RuoYi-Vue3-FastAPI 全栈项目 Docker 容器化实战指南

1. 为什么你需要这份 Docker 容器化实战指南如果你正在使用或者打算使用 RuoYi-Vue3-FastAPI 这个全栈框架来开发项目那么部署上线这件事迟早会摆在你面前。传统的部署方式是什么你得在服务器上装好 Python 环境、Node.js 环境、PostgreSQL 数据库、Redis 缓存然后一个个去配置、启动服务。这个过程我踩过的坑可太多了环境变量配错一个字母服务起不来服务器系统版本不同依赖包安装报错前端打包后的文件路径不对页面一片空白……每次部署都像是一次冒险更别提多台服务器之间保持环境一致有多痛苦了。直到我把整个项目用 Docker 容器化这些问题才迎刃而解。Docker 就像一个标准化的“软件集装箱”它把我们的应用代码、运行环境、系统工具、系统库全部打包在一起。这意味着你在自己电脑上测试好的服务可以原封不动地、一键部署到任何安装了 Docker 的服务器上无论是阿里云、腾讯云还是你自己的本地机器运行效果完全一致。这不仅仅是“方便”更是现代软件开发和运维的“标配”。这份指南就是把我从零开始把一个完整的 RuoYi-Vue3-FastAPI 项目包含 Vue3 前端、FastAPI 后端、PostgreSQL 数据库和 Redis进行 Docker 容器化的全过程掰开揉碎了讲给你听。我不会只给你几个冷冰冰的配置文件而是会告诉你每个配置项为什么这么写过程中可能会遇到哪些“坑”以及如何优化让它在生产环境跑得更稳。无论你是刚接触 Docker 的新手还是想寻求更优雅部署方案的老手这篇实战指南都能让你跟着步骤稳稳当当地完成项目的一键部署。2. 项目结构与核心文件全景预览在动手写任何一行 Docker 命令之前我们先像建筑师看蓝图一样把整个容器化项目的结构看清楚。理解这个结构后面配置起来才不会迷糊。我建议你直接在项目根目录下创建一个叫docker-project的文件夹所有和容器相关的配置都放在这里和你的源代码分开这样结构清晰也方便管理。整个docker-project目录的结构是这样的docker-project/ ├── docker-compose.yml # 总指挥文件定义所有服务 ├── backend/ # 后端服务目录 │ ├── Dockerfile # 后端镜像构建说明书 │ ├── .env.prod # 后端生产环境变量数据库连接等 │ ├── requirements-pg.txt # Python 依赖包列表 │ ├── app/ # 你的 FastAPI 源代码目录从这里复制 │ └── sql/ # 数据库初始化脚本 └── frontend/ # 前端服务目录 ├── Dockerfile # 前端镜像构建说明书 ├── dist/ # Vue3 打包后的静态文件从这里复制 └── nginx.conf # Nginx 服务器配置我来解释一下几个核心文件是干什么的。docker-compose.yml是核心中的核心你可以把它理解为一个乐队的指挥它定义了前端、后端、数据库、缓存这四个“乐手”服务各自怎么运行以及它们之间如何配合。Dockerfile则是给每个“乐手”的专属乐谱告诉 Docker 如何把这个服务打包成一个独立的镜像。比如后端的Dockerfile会说“请用一个干净的 Python 3.10 环境把我的代码和依赖装进去然后这样启动。”这里有个非常关键的细节注意backend/app/和frontend/dist/这两个目录。它们不是让你在这个docker-project文件夹里重新写代码而是从你的 RuoYi-Vue3-FastAPI 项目源代码目录里复制过来的。app/目录就是你的 FastAPI 后端主程序所在目录dist/目录则是你运行npm run build:prod之后生成的静态文件包。这种结构分离了“开发源码”和“部署配置”非常干净。3. 编写 Docker Compose定义你的服务乐团好了蓝图看完了我们现在来写最重要的总指挥文件——docker-compose.yml。我会逐段解释你完全可以对照着修改。version: 3.8 services: frontend: build: context: ./frontend ports: - 8080:80 depends_on: - backend backend: build: context: ./backend ports: - 8001:9099 depends_on: db: condition: service_healthy redis: condition: service_started db: image: postgres:15 restart: always environment: POSTGRES_USER: postgre POSTGRES_PASSWORD: your_strong_password_here POSTGRES_DB: ruoyi-fastapi volumes: - pgdata:/var/lib/postgresql/data - ./backend/sql:/docker-entrypoint-initdb.d healthcheck: test: [CMD-SHELL, pg_isready -U postgre] interval: 5s timeout: 5s retries: 5 redis: image: redis:7 restart: always ports: - 6379:6379 volumes: pgdata:逐项解读前端服务 (frontend)它基于./frontend目录下的Dockerfile构建镜像。ports: “8080:80”意思是把容器内部的 80 端口Nginx 默认端口映射到宿主机的 8080 端口。这样你访问http://localhost:8080就能看到页面。depends_on: - backend告诉 Docker Compose启动前端之前先确保后端服务启动了这是一种启动顺序的依赖。后端服务 (backend)同样基于自己的Dockerfile构建。映射端口8001:9099因为 RuoYi-FastAPI 默认在生产环境跑在 9099 端口。它的depends_on更精细依赖数据库 (db) 并且要求数据库通过健康检查 (healthy)依赖 Redis 则只需要它启动 (started) 就行。这个配置能有效避免后端启动时连不上数据库的报错。数据库服务 (db)我们直接使用官方的postgres:15镜像省去自己安装的麻烦。environment部分设置了数据库的用户名、密码和库名请务必把POSTGRES_PASSWORD替换成一个强密码。volumes挂载了两处一是pgdata这个命名卷用于持久化存储数据库数据即使容器删除数据也不会丢失二是把本地的./backend/sql目录挂载到容器的/docker-entrypoint-initdb.d这样容器第一次启动时会自动执行该目录下的所有.sql脚本完成表结构的初始化。缓存服务 (redis)使用redis:7镜像并将默认的 6379 端口映射出来方便我们如果需要的话用工具连接管理。数据卷 (volumes)在文件底部定义了pgdata这个卷Docker 会管理它的存储位置实现数据持久化。4. 构建后端镜像打造 Python 运行环境后端的Dockerfile决定了 FastAPI 应用运行在什么样的环境中。我们的目标是构建一个既包含必要依赖又尽可能精简的镜像。# backend/Dockerfile FROM python:3.10-slim WORKDIR /app COPY ./app /app COPY ./requirements-pg.txt /app COPY ./.env.prod /app/.env.prod RUN pip install --no-cache-dir -r requirements-pg.txt CMD [python, app.py, --envprod]基础镜像选择python:3.10-slim是一个非常好的选择。它比完整的python:3.10镜像小很多只包含了运行 Python 必需的最小系统库非常适合生产环境。我实测下来构建出的镜像体积能减少好几百兆。工作目录与文件复制WORKDIR /app设置了容器内的工作目录。接着我们把本地的源代码 (app)、依赖列表 (requirements-pg.txt) 和生产环境配置 (.env.prod) 复制到镜像的/app目录下。安装依赖RUN pip install这一行是构建过程中最耗时的步骤。--no-cache-dir参数告诉 pip 不要缓存下载的包这能稍微减小最终镜像的体积。这里有个小技巧你可以先在你的开发环境中使用pip freeze requirements-pg.txt生成精确的依赖列表确保容器内安装的版本和开发环境一致。启动命令CMD指定了容器启动时执行的命令。这里我们启动app.py并传入--envprod参数告诉 RuoYi-FastAPI 应用使用生产环境配置。关键文件.env.prod这个文件包含了后端连接数据库和 Redis 的所有关键信息绝对不要把它提交到公开的代码仓库。它的内容大致如下# backend/.env.prod DB_HOSTdb DB_PORT5432 DB_USERpostgre DB_PASSWORDyour_strong_password_here DB_NAMEruoyi-fastapi REDIS_HOSTredis REDIS_PORT6379 REDIS_PASSWORD注意看这里的DB_HOST不是localhost而是db这正是我们在docker-compose.yml里定义的数据库服务名。在 Docker 的网络中容器之间可以通过服务名直接通信这是 Docker Compose 提供的一大便利。5. 构建前端镜像用 Nginx 高效托管静态资源前端是 Vue3 构建的纯静态文件我们需要一个 Web 服务器来托管它们。Nginx 以其高性能和低资源消耗成为不二之选。# frontend/Dockerfile FROM nginx:stable-alpine RUN rm -rf /usr/share/nginx/html/* COPY ./dist /usr/share/nginx/html COPY ./nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80 CMD [nginx, -g, daemon off;]基础镜像nginx:stable-alpine是基于 Alpine Linux 的 Nginx 镜像体积极小通常只有几十兆非常适合分发静态资源。清理与复制先删除 Nginx 默认的欢迎页面然后将我们打包好的dist目录整个复制到 Nginx 的默认网站根目录。配置与启动用我们自定义的nginx.conf覆盖默认配置。最后CMD命令以前台模式启动 Nginxdaemon off;这是 Docker 容器运行的必要条件因为容器需要有一个持续运行的前台进程。核心配置nginx.conf这个配置文件解决了前端部署中最常见的问题路由和 API 代理。# frontend/nginx.conf server { listen 80; server_name localhost; location / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; } location /prod-api/ { proxy_pass http://backend:9099/; rewrite ^/prod-api/?(.*)$ /$1 break; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }根路径处理 (location /)try_files $uri $uri/ /index.html;这一行是实现 Vue Router 的 history 模式的关键。当用户直接访问一个前端路由如/system/user时Nginx 会先尝试查找对应的文件找不到就返回index.html由 Vue 应用自己来处理路由完美解决了刷新页面 404 的问题。API 请求代理 (location /prod-api/)这是连接前后端的桥梁。所有以/prod-api/开头的请求这是 RuoYi-Vue3 前端默认的配置都会被转发到名为backend的容器也就是我们的 FastAPI 服务的 9099 端口。rewrite指令会去掉请求路径中的/prod-api前缀让后端收到干净的路径。proxy_set_header则传递了客户端的真实 IP 等信息对日志记录很有帮助。6. 一键启动与运维让部署变得简单所有配置文件准备就绪后部署就变得异常简单。你可以在项目根目录创建一个start.batWindows或start.shLinux/Mac脚本。对于 Windows 用户 (start.bat):echo off chcp 65001 nul echo [1/3] 构建镜像中... docker compose build echo [2/3] 启动服务中... docker compose up -d echo [3/3] 成功 echo 前端页面http://localhost:8080 echo 后端接口文档http://localhost:8001/docs pause对于 Linux/Mac 用户 (start.sh):#!/bin/bash echo [1/3] 构建镜像中... docker compose build echo [2/3] 启动服务中... docker compose up -d echo [3/3] 成功 echo 前端页面http://localhost:8080 echo 后端接口文档http://localhost:8001/docs双击运行脚本Linux/Mac 需要先chmod x start.shDocker 就会自动完成所有工作拉取基础镜像、构建你的自定义镜像、按顺序启动所有容器并建立网络连接。第一次运行可能会花几分钟时间构建镜像之后启动都是秒级。常用的运维命令查看运行状态docker compose ps查看所有容器的实时日志docker compose logs -f查看某个特定服务的日志如后端docker compose logs -f backend停止所有服务docker compose down停止服务并删除镜像、数据卷谨慎使用docker compose down -v --rmi all进入某个容器内部例如数据库docker compose exec db bash7. 踩坑记录与进阶优化按照上面的步骤你的项目应该已经成功跑起来了。但根据我的经验有几个地方容易出问题也是你可以进一步优化的方向。坑点一前端打包路径问题有时候前端打包后访问页面出现空白打开浏览器开发者工具看到 JS/CSS 文件 404。这多半是 Vue 项目的公共路径 (publicPath) 设置不对。检查你的vue.config.js或vite.config.ts确保生产环境配置正确。在我们的 Nginx 配置下如果前端应用部署在根路径通常不需要特殊设置。坑点二后端时区与数据库连接容器内的默认时区可能是 UTC这会导致日志时间和数据库时间戳与本地时间不符。可以在后端的Dockerfile中增加一行来设置时区RUN ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime echo Asia/Shanghai /etc/timezone另外确保backend/.env.prod中的数据库密码和docker-compose.yml里db服务的POSTGRES_PASSWORD完全一致一个字符都不能差。进阶优化一使用 .dockerignore 文件在backend和frontend目录下创建.dockerignore文件忽略那些不需要打包进镜像的文件比如.git、__pycache__、node_modules、测试文件等。这能显著减少构建上下文大小加快镜像构建速度。进阶优化二编写数据库初始化脚本./backend/sql/目录下的 SQL 脚本是初始化数据库的关键。RuoYi-Vue3-FastAPI 项目一般会提供初始的 SQL 文件。你需要确保这个脚本除了创建表结构还能初始化必要的系统数据如管理员账号、菜单权限等。把这个文件放在这里Docker 会在 PostgreSQL 容器首次启动时自动执行它。进阶优化三考虑多阶段构建对于后端镜像我们可以使用多阶段构建来打造更小的镜像。原理是第一个阶段builder安装所有编译依赖和工具构建应用第二个阶段只复制第一阶段的构建结果到一个小体积的基础镜像中。这能去掉编译环境让生产镜像更精简。不过对于纯 Python 项目使用slim镜像优化效果已经很明显多阶段构建的收益相对较小你可以根据项目复杂度决定是否采用。把项目 Docker 容器化一开始可能会觉得配置繁琐但一旦完成你会发现它为开发、测试、部署带来的效率提升是巨大的。尤其是在团队协作或需要频繁部署的场景下这套标准化流程能帮你节省大量排查环境问题的时间。我自己的项目在用了这套方案后新成员上手开发、测试环境搭建、生产发布都变得顺畅无比。