从零到部署：用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 PORT8000 # 暴露端口 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 --frombuilder /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-app3. 使用Docker Compose编排服务实际生产环境中我们的应用通常需要与其他服务如数据库协同工作。Docker Compose可以完美解决这个问题。version: 3.8 services: web: build: . ports: - 8000:8000 environment: - DATABASE_URLpostgres://user:passworddb: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 -d4. 生产环境优化与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证书。使用Lets Encrypt可以免费获取可信证书sudo apt install certbot python3-certbot-nginx sudo certbot --nginx -d yourdomain.comNginx与Uvicorn的完整Docker Compose配置version: 3.8 services: web: build: . expose: - 8000 environment: - DATABASE_URLpostgres://user:passworddb: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核CPU1-2避免上下文切换开销2核CPU3-4充分利用CPU资源4核CPUCPU核数1通用公式启动命令示例uvicorn main:app --workers 4 --host 0.0.0.0 --port 8000监控方案内置日志Uvicorn提供详细的访问日志和错误日志Prometheus监控集成prometheus-fastapi-instrumentatorfrom 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-Alivekeepalive_timeout 65; keepalive_requests 100;在实际部署中我们发现使用Docker的--memory限制参数可以有效防止内存泄漏导致的问题docker run -d --memory512m --name myapp fastapi-app