FastAPI + 前端（Vue/React）Docker 部署全流程

适用于 Ubuntu 服务器 | Nginx 反向代理 | 独立前后端容器

---

📁 一、项目结构（推荐）

bash

编辑

~/app/
├── backend/                # FastAPI 后端
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py
│   │   ├── routers/
│   │   │   ├── __init__.py
│   │   │   ├── note.py
│   │   │   └── health.py
│   │   └── database.py
│   ├── requirements.txt
│   └── Dockerfile
│
├── frontend/               # Vue/React 前端
│   ├── src/
│   ├── dist/               # 构建输出目录
│   ├── package.json
│   └── Dockerfile
│
└── docker-compose.yml      # （可选）一键编排

---

⚙️ 二、后端（FastAPI）关键配置

1. backend/app/routers/__init__.py

python

编辑

from fastapi import APIRouter
from . import note, health

api_router = APIRouter()

# ❗注意：prefix 不能以 / 结尾！
api_router.include_router(note.router, prefix="/notes")     # ✅ 正确
api_router.include_router(health.router, tags=["health"])

2. backend/app/main.py

python

编辑

from fastapi import FastAPI
from app.routers import api_router

app = FastAPI()

# 注册路由，带 API 版本前缀
app.include_router(api_router, prefix="/api/v1")

✅ 最终路径：POST /api/v1/notes/

3. backend/Dockerfile

dockerfile

编辑

FROM python:3.10-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

# ✅ 关键：模块路径是 app.main
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

4. 构建并运行后端

bash

编辑

cd ~/app/backend
docker build --no-cache -t fastapi-backend .
docker run -d --name backend --network app-network fastapi-backend

🔍 验证：docker logs backend 应看到 Uvicorn 启动成功

---

🌐 三、Nginx 配置（反向代理）

nginx.conf 或站点配置

nginx

编辑

server {
    listen 80;
    server_name your-domain.com;

    # 前端静态资源
    location / {
        root /usr/share/nginx/html;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    # 后端 API 代理
    location /api/ {
        proxy_pass http://backend:8000;   # ❗结尾不能有 /api/
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

✅ 请求 /api/v1/notes/ → 转发到 http://backend:8000/api/v1/notes/

---

🖥️ 四、前端（Vue/React）部署

1. 构建前端

bash

编辑

cd ~/app/frontend
npm install
npm run build   # 输出到 dist/ 目录

2. frontend/Dockerfile

dockerfile

编辑

FROM nginx:alpine
COPY ./dist /usr/share/nginx/html
EXPOSE 80

3. 构建并运行前端（含 Nginx）

bash

编辑

cd ~/app/frontend
docker build --no-cache -t frontend .

docker rm -f nginx
docker run -d \
  --name nginx \
  --network app-network \
  -p 80:80 \
  frontend

✅ 前端请求 /api/v1/notes/ 会自动被 Nginx 代理到后端

---

🧪 五、验证部署是否成功

1. 检查容器状态

bash

编辑

docker ps
# 应看到 backend (Up) 和 nginx (Up)

2. 测试 API（绕过 Nginx）

bash

编辑

curl http://localhost:8000/api/v1/health
# 应返回 {"status": "ok"}

3. 测试前端访问

• 浏览器打开 http://your-server-ip
• 打开开发者工具 → Network → 查看 /api/v1/... 请求是否 200

4. 查看日志

bash

编辑

docker logs backend    # 看 API 请求日志
docker logs nginx      # 看前端访问日志

---

🚫 六、常见错误 & 解决方案（你踩过的坑）

问题现象	根本原因	解决方法
容器启动后立即退出 (Exited (1))	uvicorn main:app 路径错误	改为 uvicorn app.main:app
路由变成 /api/notes/（无 /v1）	Nginx proxy_pass 写成 .../api/	改为 proxy_pass http://backend:8000;
404 on /api/v1/notes/	prefix="/notes/" 多了 /	改为 prefix="/notes"
导入失败（ModuleNotFoundError）	构建时不在 backend/ 目录	cd backend && docker build .
数据库连接失败	容器内 localhost ≠ 宿主机	使用 Docker 网络 + 服务名（如 db:5432）

---

🧰 七、推荐优化（后续可做）

1. 使用 docker-compose.yml 统一管理

   yaml

   编辑

   version: '3'
   services:
     backend:
       build: ./backend
       networks: [app-net]
     nginx:
       build: ./frontend
       ports: ["80:80"]
       networks: [app-net]
   networks:
     app-net:

2. 添加 .dockerignore

   txt

   编辑

   __pycache__
   *.pyc
   node_modules
   .git

3. 前端 API 地址写相对路径

   js

   编辑

   // 前端代码中
   fetch("/api/v1/notes")  // 自动走 Nginx 代理，无跨域

4. 加健康检查接口

   python

   编辑

   @router.get("/health")
   def health(): return {"status": "ok"}

---

🎉 总结

你完成了一套 生产级 Web 应用部署流程：

• ✅ 模块化 FastAPI 路由（带版本）
• ✅ Docker 容器化前后端
• ✅ Nginx 反向代理 + 静态资源托管
• ✅ 网络隔离与服务通信

这份文档不仅记录了你的成果，更是未来快速部署新项目的标准模板。