FastAPI与Docker生产环境部署指南

1. FastAPI与Docker部署概述FastAPI作为现代Python Web框架的佼佼者凭借其异步性能和自动文档生成等特性已经成为API开发的首选工具之一。而Docker作为容器化技术的代表则彻底改变了应用部署的方式。将FastAPI应用通过Docker部署到生产环境能够实现环境隔离、快速扩展和持续交付的完美结合。在实际项目部署中我们通常会遇到环境配置复杂、依赖冲突等问题。传统部署方式需要在每台服务器上手动安装Python解释器、依赖库并配置运行环境这个过程既耗时又容易出错。而Docker通过容器技术将应用及其所有依赖打包成一个标准化的单元从根本上解决了在我机器上能跑的经典问题。提示虽然Docker Desktop在Windows/macOS上提供了便捷的GUI操作但生产环境部署更推荐使用Linux服务器原生的Docker Engine性能更好且资源占用更低。2. 部署前准备2.1 环境与工具清单在开始部署前需要确保准备好以下资源开发环境本地开发机Windows/macOS/Linux均可Python 3.7环境FastAPI项目代码已通过测试Docker Desktop开发测试用或Docker Engine生产环境服务器环境Linux服务器Ubuntu 20.04或CentOS 7推荐已安装Docker Engine开放的必要端口通常为80/443辅助工具Docker Hub账户或私有镜像仓库SSH客户端如OpenSSH代码版本控制Git2.2 Docker环境配置对于Ubuntu服务器安装Docker Engine的标准流程如下# 卸载旧版本 sudo apt-get remove docker docker-engine docker.io containerd runc # 安装依赖 sudo apt-get update sudo apt-get install \ ca-certificates \ curl \ gnupg \ lsb-release # 添加Docker官方GPG密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 设置稳定版仓库 echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装Docker Engine sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin # 验证安装 sudo docker run hello-world注意如果遇到virtualization support not detected错误说明系统未启用虚拟化支持。在BIOS中启用VT-x/AMD-V技术或考虑使用云服务器通常已预装虚拟化支持。3. FastAPI应用Docker化3.1 编写Dockerfile标准的FastAPI应用Dockerfile应包含以下核心部分# 使用官方Python精简镜像作为基础 FROM python:3.9-slim # 设置工作目录 WORKDIR /app # 先复制依赖文件利用Docker缓存层 COPY requirements.txt . # 安装依赖 RUN pip install --no-cache-dir -r requirements.txt # 复制应用代码 COPY . . # 暴露端口 EXPOSE 8000 # 启动命令 CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 8000]优化后的Dockerfile还应考虑使用多阶段构建减小镜像体积设置非root用户运行增强安全性配置适当的健康检查3.2 构建与测试镜像本地构建和测试镜像的命令流程# 构建镜像注意最后的点表示当前目录 docker build -t fastapi-app . # 运行测试容器 docker run -d --name fastapi-test -p 8000:8000 fastapi-app # 检查运行日志 docker logs fastapi-test # 测试API访问 curl http://localhost:8000/docs构建优化技巧使用.dockerignore文件排除不必要的文件如__pycache__对于生产环境推荐使用特定标签而非latest多阶段构建示例# 构建阶段 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 . . # 确保脚本在PATH中 ENV PATH/root/.local/bin:$PATH CMD [uvicorn, main:app, --host, 0.0.0.0]4. 生产环境部署策略4.1 单容器部署最简单的生产部署方式是直接运行容器docker run -d \ --name fastapi-prod \ -p 80:8000 \ -e ENVIRONMENTproduction \ --restart unless-stopped \ fastapi-app:1.0关键参数说明-d后台运行--restart设置自动重启策略-e传递环境变量-p端口映射主机端口:容器端口4.2 使用Docker Compose对于复杂应用推荐使用docker-compose.ymlversion: 3.8 services: app: image: fastapi-app:1.0 build: . ports: - 80:8000 environment: - ENVIRONMENTproduction restart: unless-stopped volumes: - ./logs:/app/logs redis: image: redis:alpine ports: - 6379:6379 volumes: - redis_data:/data volumes: redis_data:启动命令docker-compose up -d4.3 高级部署架构对于高可用需求可以考虑使用Nginx作为反向代理和负载均衡配置多个FastAPI容器实例添加数据库、缓存等支持服务示例架构客户端 → Nginx → [FastAPI容器1, FastAPI容器2] ← Redis ← PostgreSQL对应的docker-compose.prod.yml示例version: 3.8 services: nginx: image: nginx:alpine ports: - 80:80 - 443:443 volumes: - ./nginx.conf:/etc/nginx/nginx.conf depends_on: - app app: image: fastapi-app:1.0 environment: - ENVIRONMENTproduction deploy: replicas: 2 depends_on: - redis - postgres redis: image: redis:alpine volumes: - redis_data:/data postgres: image: postgres:13-alpine environment: POSTGRES_PASSWORD: example volumes: - postgres_data:/var/lib/postgresql/data volumes: redis_data: postgres_data:5. 运维与监控5.1 常用Docker命令# 查看运行中的容器 docker ps # 查看容器日志 docker logs -f container_name # 进入容器shell docker exec -it container_name /bin/bash # 查看资源使用情况 docker stats # 更新服务修改compose文件后 docker-compose up -d --no-deps --build service_name5.2 日志管理建议将应用日志挂载到主机目录volumes: - ./logs:/app/logs使用logrotate管理日志文件/app/logs/*.log { daily missingok rotate 14 compress delaycompress notifempty create 0640 root root sharedscripts postrotate docker kill -s USR1 container_name endscript }5.3 性能监控方案使用cAdvisor监控容器资源docker run \ --volume/:/rootfs:ro \ --volume/var/run:/var/run:ro \ --volume/sys:/sys:ro \ --volume/var/lib/docker/:/var/lib/docker:ro \ --volume/dev/disk/:/dev/disk:ro \ --publish8080:8080 \ --detachtrue \ --namecadvisor \ --privileged \ --device/dev/kmsg \ gcr.io/cadvisor/cadvisor:v0.47.0集成Prometheus监控 在FastAPI中添加from prometheus_fastapi_instrumentator import Instrumentator Instrumentator().instrument(app).expose(app)6. 常见问题排查6.1 容器启动失败现象容器启动后立即退出排查步骤查看容器日志docker logs container_name常见原因端口已被占用依赖项缺失requirements.txt不完整启动命令错误CMD中的路径不正确6.2 性能问题现象API响应缓慢优化方向检查UVicorn工作线程配置# 在启动命令中添加workers参数 CMD [uvicorn, main:app, --host, 0.0.0.0, --workers, 4]考虑使用Gunicorn作为进程管理器CMD [gunicorn, -k, uvicorn.workers.UvicornWorker, main:app, -b, 0.0.0.0:8000]6.3 虚拟化支持问题错误信息Docker Desktop failed to start because virtualization support wasnt detected解决方案进入BIOS启用VT-x/AMD-V确保Windows功能中启用了Hyper-VWindows Hypervisor PlatformVirtual Machine Platform对于Windows家庭版需要使用WSL2后端7. 安全最佳实践使用非root用户运行RUN useradd -m appuser chown -R appuser /app USER appuser定期更新基础镜像FROM python:3.9-slimsha256:具体哈希值扫描镜像漏洞docker scan fastapi-app限制资源使用deploy: resources: limits: cpus: 0.50 memory: 512M使用秘密管理# 创建secret echo mysecretpassword | docker secret create db_password - # 在compose中使用 services: db: image: mysql secrets: - db_password8. 持续部署流程8.1 基本的CI/CD流程开发 → 提交代码到Git仓库CI服务器如GitHub Actions运行测试构建Docker镜像推送到镜像仓库生产服务器拉取最新镜像重新部署服务8.2 GitHub Actions示例name: Build and Deploy on: push: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv2 - name: Login to Docker Hub uses: docker/login-actionv1 with: username: ${{ secrets.DOCKER_HUB_USERNAME }} password: ${{ secrets.DOCKER_HUB_TOKEN }} - name: Build and push uses: docker/build-push-actionv2 with: context: . push: true tags: username/fastapi-app:latest deploy: needs: build runs-on: ubuntu-latest steps: - name: SSH and deploy uses: appleboy/ssh-actionmaster with: host: ${{ secrets.SERVER_IP }} username: ${{ secrets.SERVER_USER }} key: ${{ secrets.SSH_PRIVATE_KEY }} script: | docker pull username/fastapi-app:latest docker-compose up -d8.3 蓝绿部署策略通过Docker标签实现无缝更新构建新版本镜像并打上v2标签启动新容器组绿色环境测试通过后将流量切换到绿色环境停用旧容器组蓝色环境实现脚本示例# 部署新版本 docker-compose -f docker-compose.prod.yml up -d --scale app3 --no-recreate # 健康检查 while ! curl -s http://localhost/health; do sleep 1 done # 切换流量通过更新Nginx配置或服务发现 docker exec nginx nginx -s reload # 停用旧版本 docker-compose -f docker-compose.prod.yml up -d --scale app3