第十二章部署上线

本章目标：掌握 FastAPI 应用的生产部署方式，包括 Uvicorn/Gunicorn 配置、Docker 容器化和部署前的安全检查清单。
预计时长：30 分钟

12.1 生产启动方式

开发 vs 生产

对比项	开发环境	生产环境
启动命令	`fastapi dev main.py`	`uvicorn` 或 `gunicorn`
热重载	✅ 开启	❌ 关闭
工作进程	1 个	多个（利用多核 CPU）
调试模式	✅ 开启	❌ 关闭
绑定地址	`127.0.0.1`	`0.0.0.0`

Uvicorn 生产配置

bash

uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

参数	说明	推荐值
`--host 0.0.0.0`	监听所有网络接口	生产必须
`--port 8000`	监听端口	按需
`--workers 4`	工作进程数	CPU 核心数 × 2 + 1
`--no-access-log`	关闭访问日志（由 Nginx 记录）	可选
`--log-level warning`	日志级别	生产用 warning 或 error

Gunicorn + Uvicorn Worker（Linux 推荐）

Gunicorn 是成熟的进程管理器，搭配 Uvicorn Worker 可以获得最佳的生产体验：

bash

pip install gunicorn

bash

gunicorn app.main:app \
    --workers 4 \
    --worker-class uvicorn.workers.UvicornWorker \
    --bind 0.0.0.0:8000 \
    --access-logfile - \
    --error-logfile -

架构对比

方案一：Uvicorn 单独部署
┌─────────┐
│ Uvicorn  │ × 4 workers
│  (ASGI)  │
└─────────┘

方案二：Gunicorn + Uvicorn Worker（推荐）
┌────────────────────────────────┐
│ Gunicorn（主进程，管理 Worker） │
│  ┌──────────┐ ┌──────────┐    │
│  │ Uvicorn  │ │ Uvicorn  │    │
│  │ Worker 1 │ │ Worker 2 │    │
│  └──────────┘ └──────────┘    │
│  ┌──────────┐ ┌──────────┐    │
│  │ Uvicorn  │ │ Uvicorn  │    │
│  │ Worker 3 │ │ Worker 4 │    │
│  └──────────┘ └──────────┘    │
└────────────────────────────────┘

方案	优点	缺点
Uvicorn 单独	简单、跨平台（Windows 也能用）	进程管理能力弱
Gunicorn + Uvicorn	进程管理成熟、自动重启崩溃的 Worker	仅 Linux/macOS

注意：Gunicorn 不支持 Windows。Windows 上直接用 Uvicorn --workers 即可。

12.2 Docker 部署

基础 Dockerfile

dockerfile

FROM python:3.12-slim

WORKDIR /app

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

COPY ./app ./app

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]

多阶段构建（优化镜像大小）

dockerfile

# ====== 阶段一：安装依赖 ======
FROM python:3.12-slim AS builder

WORKDIR /app

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

# ====== 阶段二：运行镜像 ======
FROM python:3.12-slim

WORKDIR /app

# 只复制安装好的依赖，不带 pip 缓存
COPY --from=builder /install /usr/local
COPY ./app ./app

EXPOSE 8000

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]

镜像大小对比

方式	镜像大小
`python:3.12`（完整版）	~1.0 GB
`python:3.12-slim`	~150 MB
`python:3.12-slim` + 多阶段构建	~120 MB

构建与运行

bash

# 构建镜像
docker build -t my-fastapi-app .

# 运行容器
docker run -d \
    --name fastapi-server \
    -p 8000:8000 \
    -e DATABASE_URL=postgresql://user:pass@db:5432/mydb \
    -e SECRET_KEY=your-production-secret \
    my-fastapi-app

docker-compose 示例

yaml

# docker-compose.yml
version: "3.8"

services:
  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/app
      - SECRET_KEY=production-secret-key
    depends_on:
      - db

  db:
    image: postgres:16
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=app
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

volumes:
  postgres_data:

bash

# 启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f web

# 停止
docker-compose down

.dockerignore

__pycache__
*.pyc
.env
.git
.vscode
tests/
*.md

12.3 部署 Checklist

上线前逐项检查，避免踩坑：

① CORS 配置

前后端分离时必须配置 CORS，否则浏览器会拦截请求：

python

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=settings.allowed_origins,  # 不要用 ["*"]！
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

配置项	开发环境	生产环境
`allow_origins`	`["*"]` 或 `["http://localhost:3000"]`	明确列出前端域名
`allow_credentials`	`True`	`True`（如果用 Cookie）
`allow_methods`	`["*"]`	按需限制

安全警告：生产环境绝对不要使用 allow_origins=["*"]，这会允许任何网站跨域调用你的 API。

② 环境变量管理

✅ 正确做法：
  - 敏感信息（密钥、数据库密码）放环境变量
  - 使用 BaseSettings 读取
  - .env 文件不提交到 Git（写入 .gitignore）

❌ 错误做法：
  - 密码、密钥硬编码在代码中
  - .env 文件提交到 Git 仓库

.gitignore 中添加：

.env
.env.production

③ 日志配置

生产环境需要结构化日志，方便排查问题：

python

import logging
from fastapi import FastAPI, Request
import time

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
)
logger = logging.getLogger(__name__)

app = FastAPI()


@app.middleware("http")
async def log_requests(request: Request, call_next):
    start = time.time()
    response = await call_next(request)
    duration = time.time() - start
    logger.info(
        f"{request.method} {request.url.path} "
        f"status={response.status_code} "
        f"duration={duration:.3f}s"
    )
    return response

输出示例：

2025-01-15 10:30:00 | INFO | app.main | GET /users/ status=200 duration=0.012s
2025-01-15 10:30:01 | INFO | app.main | POST /items/ status=201 duration=0.045s

④ HTTPS（Nginx 反向代理）

生产环境必须使用 HTTPS。推荐通过 Nginx 反向代理实现：

客户端 ──HTTPS──→ Nginx（443） ──HTTP──→ Uvicorn（8000）
                    ↑
               SSL 证书在这里配置

Nginx 配置示例：

nginx

server {
    listen 80;
    server_name api.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    server_name api.example.com;

    ssl_certificate     /etc/ssl/certs/fullchain.pem;
    ssl_certificate_key /etc/ssl/certs/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1: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;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

免费 SSL 证书：使用 Let's Encrypt + certbot 工具自动申请和续期。

完整 Checklist 总表

#	检查项	状态
1	`DEBUG = False`	☐
2	`SECRET_KEY` 已更换为强随机字符串	☐
3	数据库密码等敏感信息通过环境变量传入	☐
4	`.env` 文件已加入 `.gitignore`	☐
5	CORS `allow_origins` 已设置为具体域名	☐
6	使用 Uvicorn 多 Worker 或 Gunicorn 启动	☐
7	已配置 HTTPS（Nginx + SSL 证书）	☐
8	日志已配置，输出到文件或日志服务	☐
9	数据库已配置连接池（`pool_size`）	☐
10	所有测试通过	☐
11	Dockerfile 已优化（slim 基础镜像 + 多阶段构建）	☐
12	健康检查接口 `GET /health` 已添加	☐

健康检查接口示例：

python

@app.get("/health")
async def health_check():
    return {"status": "ok"}

12.4 动手练习

练习 1：编写 Dockerfile

为你在前几章开发的 FastAPI 项目编写 Dockerfile，要求：

使用 python:3.12-slim 基础镜像
使用多阶段构建
暴露 8000 端口
启动 4 个 Worker

练习 2：docker-compose 完整栈

编写 docker-compose.yml，包含：

FastAPI 应用容器
PostgreSQL 数据库容器
通过环境变量传递数据库连接信息

练习 3：部署自查

按照 Checklist 总表，逐项检查你的项目，确保所有项目都已完成。特别注意：

检查代码中是否有硬编码的密码或密钥
确认 .env 是否已加入 .gitignore
添加 GET /health 健康检查接口

本章小结

概念	要点
Uvicorn 生产配置	`--host 0.0.0.0 --workers 4`，关闭热重载
Gunicorn + Uvicorn	`--worker-class uvicorn.workers.UvicornWorker`，仅 Linux
Docker 基础	`python:3.12-slim`，分层构建，`.dockerignore`
多阶段构建	builder 阶段装依赖，运行阶段只复制产物，镜像更小
CORS	生产环境明确指定 `allow_origins`，不用 `["*"]`
环境变量	敏感信息走环境变量，`.env` 不提交到 Git
日志	结构化日志 + 请求耗时中间件
HTTPS	Nginx 反向代理 + Let's Encrypt 免费证书
健康检查	`GET /health` 返回 `{"status": "ok"}`

全教程总结

恭喜你完成了 FastAPI 入门教程的全部 12 章！让我们回顾整个学习路径：

章节	主题	核心知识点
第一章	初识 FastAPI	FastAPI 定位、技术架构、Hello World
第二章	路由与请求处理	路径参数、查询参数、请求体、CRUD
第三章	数据校验与序列化	Pydantic Model、Field 约束、嵌套模型
第四章	自动交互式文档	Swagger UI、ReDoc、文档优化
第五章	依赖注入系统	`Depends()`、yield 依赖、类依赖
第六章	中间件与异常处理	HTTPException、自定义中间件、CORS
第七章	异步与性能	async/await、异步 vs 同步选择
第八章	数据库集成实战	SQLAlchemy + FastAPI、CRUD、Alembic
第九章	认证与安全	JWT、OAuth2、密码哈希、角色权限
第十章	项目结构与工程化	APIRouter、BaseSettings、lifespan
第十一章	测试	TestClient、依赖覆盖、异步测试
第十二章	部署上线	Uvicorn/Gunicorn、Docker、部署清单

你已经掌握的能力

✅ 用 FastAPI 构建 RESTful API
✅ 使用 Pydantic 进行数据校验和序列化
✅ 利用依赖注入管理数据库、认证等横切关注点
✅ 实现完整的 JWT 认证和角色权限控制
✅ 组织规范的项目结构
✅ 编写自动化测试
✅ 将应用容器化并部署到生产环境

下一步学习建议

方向	推荐资源
深入 FastAPI	FastAPI 官方文档 — 质量极高，案例丰富
WebSocket 实时通信	FastAPI 原生支持 WebSocket，适合聊天、通知场景
后台任务	`BackgroundTasks`、Celery 异步任务队列
GraphQL	Strawberry + FastAPI 集成
微服务	服务发现、API 网关、消息队列（RabbitMQ/Kafka）
性能优化	Redis 缓存、数据库连接池调优、CDN

最后一句话：学编程最好的方式是动手写项目。拿一个你感兴趣的想法，用 FastAPI 把它实现出来吧！

第十二章 部署上线 ​

12.1 生产启动方式 ​

开发 vs 生产 ​

Uvicorn 生产配置 ​

Gunicorn + Uvicorn Worker（Linux 推荐） ​

架构对比 ​

12.2 Docker 部署 ​

基础 Dockerfile ​

多阶段构建（优化镜像大小） ​

镜像大小对比 ​

构建与运行 ​

docker-compose 示例 ​

.dockerignore ​

12.3 部署 Checklist ​

① CORS 配置 ​

② 环境变量管理 ​

③ 日志配置 ​

④ HTTPS（Nginx 反向代理） ​

完整 Checklist 总表 ​

12.4 动手练习 ​

练习 1：编写 Dockerfile ​

练习 2：docker-compose 完整栈 ​

练习 3：部署自查 ​

本章小结 ​

全教程总结 ​

你已经掌握的能力 ​

下一步学习建议 ​

第十二章部署上线

12.1 生产启动方式

开发 vs 生产

Uvicorn 生产配置

Gunicorn + Uvicorn Worker（Linux 推荐）

架构对比

12.2 Docker 部署

基础 Dockerfile

多阶段构建（优化镜像大小）

镜像大小对比

构建与运行

docker-compose 示例

.dockerignore

12.3 部署 Checklist

① CORS 配置

② 环境变量管理

③ 日志配置

④ HTTPS（Nginx 反向代理）

完整 Checklist 总表

12.4 动手练习

练习 1：编写 Dockerfile

练习 2：docker-compose 完整栈

练习 3：部署自查

本章小结

全教程总结

你已经掌握的能力

下一步学习建议