FastAPI+Vue项目Docker化部署：compose编排与Nginx反代实践-平芜编程栈

1. 为什么非要用Docker：Python前后端项目在裸机上跑起来有多费劲

前不久我把一个 FastAPI + Vue 的 Python 前后端分离项目正式迁到了 Docker 上部署。说实话，在动手之前我也觉得容器化无非是写几个 Dockerfile，但真正跑通之后才发现，中间隔着镜像构建、服务编排、网络互通、数据持久化四座大山。这篇文章就用这个项目当例子，把完整过程撸一遍，包括每一步为什么这么选，以及我踩过的那些文档里不会写的坑。

如果你已经会用docker run跑一些基础镜像，但还没把“前端 + 后端 + 数据库 + 缓存”这个组合完整容器化过，这篇文章可以直接照着抄。如果你是第一次摸 Docker，建议先把文中命令敲一遍，再回头理解原理，效果会好很多。项目的技术栈是 FastAPI（后端）+ Vue（前端构建产物）+ Nginx（静态服务与反向代理）+ MySQL 8.0 + Redis，把其中一个换成 Flask、Django、React 或 Postgres，思路完全不变。

1.1 三个让部署翻车的经典现场

我先说说为什么要折腾容器化。这个项目早期是传统方式部署的，也就是服务器上装 Python 环境、装 Node、装 MySQL，前端npm run build之后扔到 Nginx 目录。听起来不难，但实际维护起来全是坑。

第一个经典现场是 Python 版本。开发机上是 3.11，服务器上装的是 3.7，代码里用了 3.10 才引入的语法，一启动就SyntaxError。问题不是代码逻辑，而是环境不一致。修完这个，又发现某个依赖包在 3.7 下的行为不太一样，整个下午就耗在“本地明明是好的”这种玄学问题上。

第二个经典现场是前端构建。开发机 Node 是 18，服务器上的 Node 是 14，npm install编译原生模块直接失败，node-sass在 Node 17 以上的环境和老版本之间反复横跳。就算手工把 Node 版本对齐了，node_modules在不同机器上装出来的东西也会有细微差异，构建产物都可能在无意中发生变化。

第三个经典现场是数据库和中间件。开发环境 MySQL 5.7，线上 MySQL 8.0，排序规则和 SQL 行为有差异；Redis 要配主从，配了一下午没跑通。我之前也试过用 Tomcat 部署前后端分离项目、用 Jenkins 做发布，但每一次换机器、换网络、换版本，都等于把整个部署流程重新走一遍。

1.2 容器化之后：部署被简化成“构建镜像 + 一键启动”

容器化的核心不是“把代码打包”，而是“把运行环境也一起打包”。对我这个项目来说，部署拓扑是这样的：

浏览器请求进入 Nginx 容器，Nginx 负责托管前端静态文件；请求路径带/api/的，反向代理到 FastAPI 后端容器；后端容器连接 MySQL 容器和 Redis 容器。整个链路的五个角色全部跑在容器里，镜像里已经包含了 Python 版本、Node 构建工具、Nginx 配置、依赖包这些原来需要手工对齐的东西。

操作层面最大的变化就是启动命令。原来部署一套环境要写几千字的文档，现在一行：

docker compose up -d --build

拉代码、装环境、调配置这些步骤全部不需要了。而且因为镜像是一致的，开发环境、测试服务器、生产服务器最终跑的软件栈完全相同，以前那种“明明按照文档部署的，日志却对不上”的情况基本不会出现。

1.3 先说清楚边界：容器不是虚拟机

用 Docker 不是说把什么都塞进去就完了。容器本质上是进程级的隔离，和虚拟机不一样，容器说没就没了。所以我给这个项目划了几条边界：

API 服务、前端静态文件这类无状态服务，适合容器化，删了重建没有任何心理负担。
MySQL、Redis、用户上传文件这类需要持久化的数据，一定要挂数据卷（volume），或者干脆用托管的数据库实例。
依赖宿主机硬件的服务，比如某些需要直通 GPU 或特殊设备的功能，不建议硬塞进容器。

理解了这条边界，后面的数据卷配置和 compose 编排思路就会清晰很多：容器负责跑业务，数据交给卷来管。

2. 环境准备：Docker Desktop安装与启动失败的几种常见死法

开始写镜像之前，先确保本机的 Docker 环境是健康的。很多同学卡在这里，报错一个接一个，多数不是代码问题，而是 Docker 自己没起来。

2.1 Windows上Docker Desktop依赖WSL2：一个BIOS选项引起的血案

Windows 用户安装 Docker Desktop 后，最常见的报错就是那行英文：virtualization support not detected docker desktop failed to start。这个报错的本质是：Docker Desktop 在 Windows 上依赖 WSL2 后端，而 WSL2 的启动又依赖 CPU 虚拟化支持。如果你的 BIOS 里关闭了 Intel VT-x 或 AMD SVM，或者在 Windows 功能里没启用“虚拟机平台”，就会出现这个提示。

解决路径是这样的：

重启进 BIOS，找到 CPU 虚拟化相关的选项（Intel 叫 VT-x，AMD 叫 SVM），确保开启。
以管理员身份打开 PowerShell，执行两条命令启用 Windows 功能：

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

重启电脑，然后执行wsl --set-default-version 2。

如果你的电脑内存不大，建议在用户目录下建一个.wslconfig文件限制 WSL2 的资源占用：

[wsl2] memory=4GB processors=2

我实际测过，不限制内存的话，WSL2 可能会吃掉大半物理内存，Docker Desktop 反而跑得不稳定。

2.2 启动失败报错的自查清单

另一个高频报错是failed to connect to the docker api at npipe:////./pipe/dockerdesktoplinuxen，这串路径看起来吓人，实际含义就是：Docker 客户端连不上引擎。通常有两类原因，一是 Docker Desktop 的 engine 根本没起来，二是 WSL2 后端失联了。

我整理了一个自查清单，大部分启动失败都可以按这个表格定位：

报错信息	常见原因	处理方式
virtualization support not detected	BIOS 虚拟化未开启，或 WSL2 未安装	开启虚拟化，启用 WSL2，见 2.1
failed to connect to the docker api at npipe	Docker engine 未运行，或 WSL 后端异常	重启 Docker Desktop；执行`wsl --shutdown`后再启动；如果还不行，重启电脑
docker: error during connect: This error may also indicate that the docker daemon is not running	daemon 没有起来	检查 Docker Desktop 状态，或 Linux 下执行`systemctl status docker`
dial tcp: lookup xxx: no such host	DNS 解析问题，或镜像拉取失败	检查网络，配置 registry mirror，见 2.3

排查顺序不要乱。先确认 Docker Desktop 右上角有没有报“Engine running”，再看docker info能不能正常输出。如果 engine 都没起来，拉镜像、跑容器这些操作自然全部失败，这时候去改代码没有任何意义。

2.3 镜像加速：不配置这一步基本等于告别国内网络

默认情况下，Docker Hub 的镜像访问速度非常不稳定，拉一个几百 MB 的基础镜像可能折腾半小时。解决方式是给 Docker 配置 registry mirror，也就是镜像加速器。

Windows 上 Docker Desktop 的设置里能找到 Docker Engine 配置项，直接编辑 JSON 文件；Linux 上则修改/etc/docker/daemon.json：

{ "registry-mirrors": ["https://docker.m.daocloud.io"] }

改完重启 Docker。Linux 下的命令是：

sudo systemctl daemon-reload sudo systemctl restart docker

配置完可以用docker info确认 Registry Mirrors 字段是否生效。我有一个建议：加速器地址尽量选你实际能稳定访问的，有的是公共源，有的公司会提供内网加速器，优先用后者。配好之后拉镜像速度快很多，后面构建镜像的心情会完全不同。

3. 后端镜像：FastAPI项目的Dockerfile逐层拆解

环境准备好了，开始写后端镜像。我拿 FastAPI 项目举例，用的是应用最常见的结构：app/main.py是入口，requirements.txt管理依赖。换成 Flask、Django 也一样，区别只在启动命令。

3.1 基础镜像选型：为什么我用python:3.11-slim而不是alpine

基础镜像的选择直接影响构建速度和运行稳定性。我比较过三个方案：

镜像	体积	优点	缺点
python:3.11	较大	包含完整构建工具，编译任何包都稳	镜像臃肿，构建产物大
python:3.11-slim	中等	基于 Debian，体积可控，多数 wheel 包可直接安装	缺少部分编译工具，特殊依赖需补装
python:3.11-alpine	小	镜像极小	musl 环境与主流 Linux 有差异，很多包需要现场编译，构建慢且容易失败

最终我选了python:3.11-slim。原因很实际：alpine 虽然小，但 Python 生态里一些带原生代码的库（比如 FastAPI 底层用的 pydantic-core、处理图片的 lxml 这类包）在 alpine 上经常找不到现成的 wheel，得现场编译，一旦编译环境缺东西就报错。对部署稳定性要求高的项目，我宁愿镜像大几十 MB，也别在构建阶段折腾一上午。

还有一点必须强调：基础镜像标签一定要锁定具体版本，不要用latest。latest会漂移，今天构建的镜像和半年后构建的镜像可能基础环境都不一样了，线上行为不可控。

3.2 Dockerfile逐层拆解：缓存策略和非root运行

这是我这边的后端 Dockerfile，直接贴出来：

FROM python:3.11-slim ENV PYTHONDONTWRITEBYTECODE=1 \ PYTHONUNBUFFERED=1 \ PIP_DEFAULT_TIMEOUT=100 WORKDIR /app RUN apt-get update && apt-get install -y --no-install-recommends build-essential curl \ && rm -rf /var/lib/apt/lists/* COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple COPY . . RUN useradd -m appuser && mkdir -p /app/uploads && chown -R appuser:appuser /app/uploads USER appuser EXPOSE 8000 HEALTHCHECK CMD curl -f http://localhost:8000/health || exit 1 CMD ["gunicorn", "-k", "uvicorn.workers.UvicornWorker", "-w", "2", "-b", "0.0.0.0:8000", "app.main:app"]

逐层讲几个关键点。

ENV里两个变量很重要。PYTHONDONTWRITEBYTECODE防止 Python 写.pyc文件到容器里，减少运行时磁盘占用；PYTHONUNBUFFERED让日志直接输出，不清 buffering，否则容器里看日志会延迟。

COPY requirements.txt .和COPY . .分开写，不是形式主义，是为了利用 Docker 的 layer 缓存。构建镜像时，只要之前的层没变化，Docker 会直接复用缓存的层。如果依赖文件没改，pip install这一步就不会重新执行，整个构建过程会快非常多。

pip安装源我换成了国内源，否则在默认源下载依赖经常超时。这个细节能让构建体验好上一大截。

为什么要建一个appuser来跑？因为容器默认是 root 身份，一旦应用被攻击，攻击者拿到的就是容器 root 权限。用普通用户跑应用是部署的基本习惯。注意uploads目录要显式创建并改变属主，否则挂载卷之后可能因为权限问题写不进去。

3.3 启动命令与健康检查：让容器“活着”且有状态可查

开发阶段我一般直接uvicorn app.main:app --reload --host 0.0.0.0 --port 8000，方便热重载。但生产镜像里，我用 gunicorn 启多个 worker，并通过-k uvicorn.workers.UvicornWorker让 gunicorn 使用 uvicorn 的 worker 类型。FastAPI 的异步接口只有配合 UvicornWorker 才能发挥出性能。

HEALTHCHECK写在 Dockerfile 里，是给容器探活用的。compose 编排时，服务间的启动依赖可以用它来控制：只有后端健康检查通过，前端网关才把流量代理过来。这个/health接口在后端代码里必须存在，就是一个返回状态码 200 的最小接口。

4. 前端镜像：Vue构建产物与Nginx反向代理的设计

后端镜像写完后，前端相对简单，但简单不等于没有设计。前端的容器化我采用两阶段构建：第一阶段用 Node 构建静态文件，第二阶段用 Nginx 托管这些文件。

4.1 前端构建的分层思路：node构建层 + nginx运行层

前端 Dockerfile 长这样：

FROM node:18-alpine AS build WORKDIR /app COPY package*.json ./ RUN npm config set registry https://registry.npmmirror.com && npm install COPY . . RUN npm run build FROM nginx:1.25-alpine COPY nginx.conf /etc/nginx/conf.d/default.conf COPY --from=build /app/dist /usr/share/nginx/html EXPOSE 80

第一阶段用 Node 镜像执行npm install和npm run build，产物是dist目录。第二阶段只把dist复制进 Nginx 镜像，Node 和node_modules全部丢弃，最终镜像体积非常小。这也解释了为什么构建依赖里用node:18-alpine是可以的——它对运行镜像没有任何影响，构建阶段遇到 Alpine 的坑也有机会绕开。

有一点建议：如果项目有package-lock.json，把npm install换成npm ci，它会严格按照 lock 文件安装依赖，可复现性更好。构建缓存方面，先复制package*.json再执行安装，之后复制源码，和前面 Python 镜像的思路一致，都是尽量让依赖安装这一步少重跑。

4.2 nginx.conf：/api反代和SPA路由的写法

Nginx 配置是整个部署链路里最容易出问题的地方。我这份配置很精简，但每行都有用：

server { listen 80; server_name _; root /usr/share/nginx/html; index index.html; gzip on; gzip_types text/plain text/css application/javascript application/json image/svg+xml; gzip_min_length 1024; location /api/ { proxy_pass http://backend:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } location / { try_files $uri $uri/ /index.html; } }

两个重点。

第一，location /api/里的proxy_pass http://backend:8000;，注意这里的backend是 compose 里的服务名，后面会解释。这里有个特别容易踩的坑：如果proxy_pass后面带的 URI 带斜杠（比如http://backend:8000/），Nginx 会把请求 URI 里的/api前缀剥掉再转发；如果像我这样不带斜杠，完整 URI 会原样传给后端。两者行为完全不同，后端路由写法也必须跟着变。很多“接口 404”的故障就是这里写错导致的。

第二，try_files $uri $uri/ /index.html;是给 Vue Router 的 history 模式用的。单页应用的路由在前端代码里，直接刷新/login这个路径时，服务器并没有这个文件，Nginx 需要回退到index.html让前端路由接管。

4.3 为啥不用Node直接做静态服务

可能有人会问，前端构建完，用 Node 起一个静态服务器不也行吗？实践下来我不推荐。

Nginx 处理静态文件的开销比 Node 小得多，同样的并发量下，Nginx 的内存占用和响应速度都更稳。而且 Nginx 自带的 gzip、静态资源缓存配置，用 Node 写还得引第三方中间件。前端镜像里跑 Nginx，还可以顺便承担反向代理职责，把/api的请求转发到后端容器，前端容器成了整个站点对外的唯一入口，架构上更简洁。

我这里还顺手开了 gzip，对前端静态资源非常有用。如果项目里静态资源带 hash 文件名，可以在 location 里加expires 30d之类的缓存头，这里不再展开。

5. 一网打尽：docker-compose把前后端、MySQL、Redis编排在一起

单个镜像写好后，真正的重头戏是编排。docker-compose 会把之前零散的服务定义统一起来，一条命令管全部。

5.1 一份可跑的docker-compose.yml

这是我在项目中实际使用的 compose 文件，省略了部分与本文无关的配置：

services: backend: build: ./backend container_name: demo-backend env_file: .env volumes: - uploads:/app/uploads depends_on: mysql: condition: service_healthy redis: condition: service_started restart: unless-stopped healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000/health"] interval: 10s timeout: 5s retries: 5 frontend: build: ./frontend container_name: demo-frontend ports: - "80:80" depends_on: - backend restart: unless-stopped mysql: image: mysql:8.0 container_name: demo-mysql environment: MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD} MYSQL_DATABASE: ${MYSQL_DATABASE} MYSQL_USER: ${MYSQL_USER} MYSQL_PASSWORD: ${MYSQL_PASSWORD} volumes: - mysql-data:/var/lib/mysql ports: - "3306:3306" healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost"] interval: 10s timeout: 5s retries: 10 restart: unless-stopped redis: image: redis:7-alpine container_name: demo-redis command: ["redis-server", "--appendonly", "yes"] volumes: - redis-data:/data restart: unless-stopped volumes: mysql-data: redis-data: uploads:

新版 Compose 已经不需要version字段了，但写上也不影响。这份配置最值得注意的地方在于：depends_on不再是简单的“启动顺序”，后端依赖的 MySQL 配置了condition: service_healthy，意思是后端容器要等 MySQL 健康检查通过后才真正启动。

为什么需要这样？MySQL 容器启动到可以被连接，通常需要几十秒，第一次初始化还要建库建表。如果后端容器一启动就尝试连接数据库，连接必然失败。以前的做法是在应用代码里加循环重试，现在用 healthcheck + depends_on 就能在编排层面解决，更干净。

5.2 网络、端口、数据卷：最容易被忽略的三个点

同一份 compose 文件里的服务，默认会自动加入同一个 bridge 网络，互相之间可以直接用服务名访问。这解决了两个长期以来的问题：一是容器 IP 会变化，不能写死；二是容器间访问，IP 和服务名之间有了 Docker 内置的 DNS 解析。

端口映射上我保持了一个原则：对外只需要暴露前端 Nginx 的 80 端口。后端的 8000 不需要映射到宿主机，因为 Nginx 容器是在内部网络里通过backend:8000访问它的。MySQL 的 3306 端口我映射出来，是为了开发调试方便，用 Navicat 之类的工具直接连库里看数据。生产环境如果不需要，完全可以去掉这个端口映射，减少暴露面。

数据卷的作用容易被低估。我把 MySQL 数据、Redis 数据和用户上传文件都挂到了命名卷里，这样即使容器因为崩溃被删除重建，数据依然还在。注意docker compose down不会删除卷，但docker compose down -v会，这个命令意思是“连数据卷一起删除”，执行前务必确认是不是真的要清空数据。

5.3 环境变量与多环境切换：.env的用法

配置信息不应该硬编码在代码里。.env文件配合 compose 的环境变量替换，是我推荐的配置管理方式。项目根目录放一个.env：

MYSQL_ROOT_PASSWORD=strong_root_pwd MYSQL_DATABASE=app_db MYSQL_USER=app_user MYSQL_PASSWORD=strong_app_pwd

compose 会自动读取这个文件，${MYSQL_PASSWORD}会被替换成真值。后端应用里也用同样的变量名去读取数据库连接信息，比如：

import os DATABASE_URL = os.getenv("DATABASE_URL")

注意.env文件不要提交到 Git 仓库，生产环境的密钥不该出现在代码库里。多环境切换可以用docker compose --env-file .env.prod up -d指定不同的 env 文件，或者用 compose override 文件覆盖部分配置，刻意保持“开发环境和生产环境使用同一套镜像”的原则。

6. 跑通之后的故障排查实录：网络不通、容器互访失败、数据丢失

配置都写好之后，我第一次执行docker compose up -d --build并没有一次通过，后面两天时间基本都花在排查各种部署故障上了。这部分也是我认为最有参考价值的实操记录。

6.1 先复现一次“502 Bad Gateway”的完整排查链路

现象：浏览器能打开前端页面，但调用接口时全部返回 502 Bad Gateway。

我的排查链路是这样的，你也按这个顺序走，不要跳步。

第一步，确认所有容器是否正常运行：

docker compose ps

如果 backend 容器状态是 Restarting，那问题大概率在后端本身。查看后端日志：

docker compose logs --tail 50 backend

第二步，如果后端起来了还在 502，就说明 Nginx 在转发时连不上后端容器。进入前端容器，先验证服务名能不能解析、端口能不能通：

docker compose exec frontend wget -qO- http://backend:8000/health

如果提示wget: bad address 'backend'，说明两个容器不在同一个网络，检查 compose 文件里服务名和网络配置。如果wget能访问但返回 502，那问题在 Nginx 配置，比如proxy_pass地址写错。

第三步，验证容器网络细节：

docker network ls docker network inspect <网络名>

compose 默认会创建一个以项目目录名命名的网络，所有服务都在里面。用docker network inspect可以看到每个容器的 IP 地址和归属网络，确认没有容器被排除在外。

这类问题的大部分根因，我总结下来无非三种：

Nginx 配置里写的上游地址不对，最常见的是把服务名写成了 localhost。容器里的 localhost 指向的是这个容器自己，永远访问不到别的容器。
后端代码里连接数据库用了 localhost，同样的问题。容器内访问 MySQL 必须写服务名mysql。
端口搞混了。容器间访问要用“容器内部端口”，比如后端容器监听的是 8000，那就访问backend:8000，不是宿主机映射出来的某个端口。

还有一次更隐蔽的情况：后端容器启动了，但里面的服务绑定的是 127.0.0.1，而不是0.0.0.0。这会导致容器外部（包括 Nginx 容器）完全无法访问它，但容器内部 curl 却正常。所以启动命令我坚持用--host 0.0.0.0，不是没有原因的。

6.2 数据卷管理的正反面：备份、恢复和误删

数据卷是我反反复复强调的部分，因为它平时不显眼，一旦出事就是大事。MySQL 数据挂到了mysql-data卷里，日常管理可以这样做。

备份：

docker compose exec -T mysql sh -c 'mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --all-databases' > backup.sql

恢复：

cat backup.sql | docker compose exec -T mysql sh -c 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD"'

这里用-T是因为exec在重定向场景下不需要分配 TTY，加上去反而会报错。

数据丢失在容器化环境里绝大多数是人为误删造成的。我见过最典型的操作是先执行了docker compose down，再执行docker volume prune，把无人使用的卷全部清掉，结果 MySQL 数据跟着没了。docker volume prune这个清理命令本身没问题，但使用前必须知道有哪些卷是长期保留的。

还有一个容易忽略的点：上传文件。我给uploads卷挂到后端的同时，如果前端也需要直接访问用户上传的图片，最简单的做法是在前端 Nginx 里再挂一次同一个卷，并加一个静态路径。但更常见的方案是让后端提供一个文件访问接口，Nginx 只负责反向代理，避免多个容器写同一个目录带来的权限和数据一致性开销。

6.3 日常运维命令速查

跑稳定之后，我日常用到的命令其实就那么几条。整理成一个速查表，方便对照：

场景	命令
构建并后台启动全部服务	`docker compose up -d --build`
查看某个服务实时日志	`docker compose logs -f backend`
重启单个服务	`docker compose restart backend`
进入容器排查问题	`docker compose exec backend sh`
查看容器状态和端口映射	`docker compose ps`
停止服务但不删数据	`docker compose down`
彻底清理（删除数据，慎用）	`docker compose down -v`
查看磁盘占用分布	`docker system df`
清理悬空镜像	`docker image prune`

最后补充一个容易被忽视的运维细节：容器默认的时区是 UTC，Python 项目打印日志的时间会比北京时间慢 8 小时。如果日志里时间不对，可以在 backend 服务的 environment 里加TZ=Asia/Shanghai，然后在镜像里安装tzdata包，否则时区文件可能缺失。

整个项目跑通之后，我最大的体会是：compose 文件本身就是最好的部署文档。以前交接这类前后端项目，要写一大段“先装 Python 3.11、再装 Node 18、然后改 Nginx 配置”，现在仓库拉下来，一个命令就是一个完整环境，连数据库版本都锁死在 images 里，排查问题的时候大家看到的是同一套东西。最后再分享一个我的习惯：线上更新代码时，我用docker compose build && docker compose up -d，而不是down完再up，这样服务不会中断；有条件的话给镜像打上日期 tag，方便出问题时快速回滚到上一个可用版本。照着这套思路把前后端项目容器化，能省掉一半的部署扯皮时间。