从零到部署：用Uvicorn和Docker打包你的FastAPI应用（附Nginx配置）-程序员充电站

从零到部署：用Uvicorn和Docker打包你的FastAPI应用（附Nginx配置）

在当今快速迭代的Web开发领域，FastAPI凭借其卓越的性能和直观的异步支持，已成为Python开发者构建API服务的首选框架。而将本地开发的原型转化为可投入生产的稳定服务，则需要一套完整的部署工具链。本文将带你从零开始，构建一个包含Uvicorn服务器、Docker容器化和Nginx反向代理的完整部署方案。

1. 开发环境搭建与Uvicorn基础配置

在开始部署之前，我们需要确保开发环境配置正确。FastAPI与Uvicorn的组合为开发者提供了极佳的本地调试体验。

首先创建并激活虚拟环境：

python -m venv venv source venv/bin/activate # Linux/macOS venv\Scripts\activate # Windows

安装必要的依赖包：

pip install fastapi uvicorn

一个典型的FastAPI应用结构如下：

# main.py from fastapi import FastAPI app = FastAPI() @app.get("/") async def root(): return {"message": "Hello World"} @app.get("/items/{item_id}") async def read_item(item_id: int): return {"item_id": item_id}

使用Uvicorn运行开发服务器时，推荐以下参数组合：

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

提示：--reload参数会在代码变更时自动重启服务，非常适合开发阶段使用，但切勿在生产环境中启用。

2. 构建生产级Docker镜像

当应用开发完成后，我们需要将其打包为Docker镜像以便部署。以下是经过优化的Dockerfile配置：

# 使用官方Python精简镜像作为基础 FROM python:3.9-slim # 设置工作目录 WORKDIR /app # 先安装依赖，利用Docker缓存层 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # 复制应用代码 COPY . . # 设置环境变量 ENV PYTHONPATH=/app ENV PORT=8000 # 暴露端口 EXPOSE $PORT # 运行命令 CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

构建镜像时，我们可以使用多阶段构建来进一步优化镜像大小：

# 第一阶段：构建环境 FROM python:3.9 as builder WORKDIR /app COPY requirements.txt . RUN pip install --user -r requirements.txt # 第二阶段：运行环境 FROM python:3.9-slim WORKDIR /app # 从构建阶段复制已安装的包 COPY --from=builder /root/.local /root/.local COPY . . # 确保脚本可执行 ENV PATH=/root/.local/bin:$PATH ENV PYTHONPATH=/app EXPOSE 8000 CMD ["uvicorn", "main:app", "--host", "0.0.0.0"]

构建并运行镜像：

docker build -t fastapi-app . docker run -d -p 8000:8000 --name myapp fastapi-app

3. 使用Docker Compose编排服务

实际生产环境中，我们的应用通常需要与其他服务（如数据库）协同工作。Docker Compose可以完美解决这个问题。

version: '3.8' services: web: build: . ports: - "8000:8000" environment: - DATABASE_URL=postgres://user:password@db:5432/mydb depends_on: - db restart: unless-stopped db: image: postgres:13 environment: POSTGRES_USER: user POSTGRES_PASSWORD: password POSTGRES_DB: mydb volumes: - postgres_data:/var/lib/postgresql/data ports: - "5432:5432" volumes: postgres_data:

关键配置说明：

restart策略：设置为unless-stopped确保服务异常退出后自动重启
环境变量：通过环境变量配置数据库连接，避免硬编码
数据持久化：使用volume保存PostgreSQL数据，防止容器重启后数据丢失

启动整个服务栈：

docker-compose up -d

4. 生产环境优化与Nginx配置

直接暴露Uvicorn服务到公网并不是最佳实践。我们应该使用Nginx作为反向代理，它能够提供：

静态文件服务
SSL终止
请求缓冲
负载均衡

基础Nginx配置示例：

server { listen 80; server_name yourdomain.com; location / { proxy_pass http://web: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; } location /static/ { alias /app/static/; } }

对于生产环境，我们还需要配置SSL证书。使用Let's Encrypt可以免费获取可信证书：

sudo apt install certbot python3-certbot-nginx sudo certbot --nginx -d yourdomain.com

Nginx与Uvicorn的完整Docker Compose配置：

version: '3.8' services: web: build: . expose: - "8000" environment: - DATABASE_URL=postgres://user:password@db:5432/mydb depends_on: - db restart: unless-stopped nginx: image: nginx:alpine ports: - "80:80" - "443:443" volumes: - ./nginx.conf:/etc/nginx/conf.d/default.conf - ./certbot/conf:/etc/letsencrypt - ./certbot/www:/var/www/certbot depends_on: - web restart: unless-stopped db: image: postgres:13 environment: POSTGRES_USER: user POSTGRES_PASSWORD: password POSTGRES_DB: mydb volumes: - postgres_data:/var/lib/postgresql/data volumes: postgres_data:

5. 性能调优与监控

在生产环境中运行FastAPI应用时，我们需要关注几个关键性能指标：

Uvicorn工作进程配置建议：

服务器配置	推荐worker数	说明
1核CPU	1-2	避免上下文切换开销
2核CPU	3-4	充分利用CPU资源
4核CPU+	CPU核数+1	通用公式

启动命令示例：

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

监控方案：

内置日志：Uvicorn提供详细的访问日志和错误日志

Prometheus监控：集成prometheus-fastapi-instrumentator

from prometheus_fastapi_instrumentator import Instrumentator Instrumentator().instrument(app).expose(app)

健康检查端点：

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

性能优化技巧：

使用httptools和uvloop提升Uvicorn性能：

pip install httptools uvloop

启动命令：

uvicorn main:app --loop uvloop --http httptools

对于CPU密集型任务，考虑使用asyncpg替代同步的PostgreSQL驱动

合理配置Keep-Alive：

keepalive_timeout 65; keepalive_requests 100;

在实际部署中，我们发现使用Docker的--memory限制参数可以有效防止内存泄漏导致的问题：

docker run -d --memory="512m" --name myapp fastapi-app

从零到部署：用Uvicorn和Docker打包你的FastAPI应用（附Nginx配置）