简介面向需要掌握 Python 后端服务上线技能的初中级开发者这份围绕 FastAPI 部署的实战资源包提供了从零开始构建 API 服务的完整路径。其核心优势在于不仅讲解框架本身还特别关注与 JavaScript 前端的协作通过 Type Hint 定义接口、利用 OpenAPI 自动生成交互式文档、以 AJAX 完成跨语言联调极大降低了前后端对接成本。资源以 zip 压缩包形式提供大小约 6.87MB页面未显示具体文件数但内容涉及 main.py 示例代码、Uvicorn/Gunicorn 启动配置、Nginx 反向代理参考配置及部署流程说明等方便对照实践。内容依次覆盖环境准备、路由编写、本地热重载开发、生产环境 GunicornNginx 部署并延伸至 Jenkins、GitHub Actions 等 CI/CD 集成形成一套可落地到真实项目的完整链路。目前已有 987 人学习下载步骤清晰、体系性强对希望快速打通 FastAPI 与 JavaScript 前后端联调、并掌握生产部署要点的开发者很有帮助。 我从一个FastAPI测试项目走到正式部署整个过程踩了不少坑也把一些平时文档里写得不清楚的地方彻底搞明白了。这篇博文就拿“fastapi-test”这个项目当例子把FastAPI部署这件事从头到尾讲透从部署方案选型、项目结构整理到Docker构建、Nginx反向代理再到高频故障排查都是一线实操经验不掺杂理论空谈。无论你是刚接触FastAPI的新手还是已经写过几个接口、想把它真正丢到服务器上跑起来的开发者这篇都值得收藏。1. 部署方案选型与整体思路1.1 为什么FastAPI适合做后端接口服务先说一个基本认知FastAPI不是一个Web服务器它是一个Web框架。这意味着你说“FastAPI部署”本质上是“如何把一个基于FastAPI的应用稳定地跑在服务器上对外提供服务”。FastAPI这几年热度很高核心优势就三个异步原生支持、Pydantic模型校验、自动生成OpenAPI文档。这三个特性放到部署场景里意味着你的服务天然适合高并发I/O密集型任务也方便前端或者第三方团队对联调。但框架好不代表部署简单。实际生产环境里我见过太多人本地跑uvicorn main:app --reload一切正常一到服务器就各种问题端口起不来、请求卡死、静态文件404、数据库连接池爆掉。这篇文章要解决的就是这些真实环境里会撞上的问题。1.2 部署方式横向对比部署FastAPI的方案不少我按实战中用过的顺序给你捋一遍部署方式适合场景优点缺点裸跑uvicorn本地调试、临时接口最简单一条命令启动无守护进程进程挂了不会自动拉起systemd uvicorn单机小项目随系统自启、崩溃自动重启环境迁移麻烦依赖本机Python环境Docker docker-compose中小型项目主力方案环境隔离、一键迁移、扩展方便需要理解容器网络和镜像构建Kubernetes大规模微服务弹性伸缩、自愈能力强运维成本高小项目杀鸡用牛刀我的建议是个人项目、小团队内部工具直接Docker Compose。这个方案在可维护性和上手难度之间平衡得最好。公司有K8s集群就另说但思路也是先把镜像打好再往上丢。这篇博文后面所有的实操内容都以Docker Compose为主线配合Nginx反向代理。这套组合在社区里是标准解法你在很多开源项目里都能看到类似的目录结构和配置文件。2. 部署前的项目整理与配置2.1 目录结构和依赖管理很多人的FastAPI项目是“一个main.py走天下”开发时没问题部署时就会很难受。我建议在部署前把项目整理成下面这样这也是我实际在用的结构fastapi-test/ ├── app/ │ ├── __init__.py │ ├── main.py # 应用入口 │ ├── core/ │ │ ├── config.py # 配置项读环境变量 │ │ └── logging.py # 日志配置 │ ├── routers/ │ │ └── api_v1.py # 业务路由 │ └── models/ # 业务模型 ├── docker/ │ └── Dockerfile ├── docker-compose.yml ├── requirements.txt └── .env.example依赖管理必须做到“可复现”。我强烈建议你锁定版本而不是用fastapi这种宽泛写法。实测下来FastAPI的小版本升级偶尔会有破坏性变更Pydantic从v1升到v2更是一个大坎。锁定版本是成本最低的避坑方式fastapi0.115.12 uvicorn[standard]0.34.2 pydantic2.11.2 pydantic-settings2.8.1 sqlalchemy2.0.40 psycopg2-binary2.9.10uvicorn[standard]这个写法很多人不注意。它比裸uvicorn多装了uvloop、httptools、websockets这几个关键依赖。尤其websockets如果你之后要支持WebSocket长连接只装裸uvicorn会直接导入失败。这种细节文档里写得含蓄但报错的时候很致命。2.2 环境变量配置与敏感信息隔离配置管理上别再把数据库密码、密钥写在代码里了。部署时你会接触多个环境本地、测试、正式每个环境的数据库地址、日志级别都不一样。我的做法是用pydantic-settings统一管理配置所有可变项都从环境变量读取。# app/core/config.py from pydantic_settings import BaseSettings class Settings(BaseSettings): app_name: str fastapi-test debug: bool False database_url: str sqlite:///./test.db secret_key: str change-me class Config: env_file .env env_file_encoding utf-8 settings Settings()这样做的收益很大项目里没有硬编码的敏感信息部署时只需要维护一套.env文件即可。容器化部署时把环境变量通过Compose文件传进去既不污染镜像也方便不同环境复用同一个镜像。注意.env文件一定放进.gitignore只提交.env.example作为模板。这些都是小事但真的很重要——GitHub上每天都有大量因为密钥泄露被恶意挖矿的惨案。2.3 健康检查接口是部署的第一步部署前请务必在应用里加一个健康检查接口。这不是为了好看而是为了后续的容器编排、负载均衡、监控告警都有的放矢。# app/main.py from fastapi import FastAPI from app.core.config import settings app FastAPI(titlesettings.app_name) app.get(/health) def health_check(): return {status: ok, app: settings.app_name}有了这个接口Docker Compose可以配置healthcheckNginx可以拿它做被动健康检查云平台的负载均衡也能直接监听这个路径。别等部署到K8s才想起来加这个那时候你连Pod起没起来都说不清楚。3. Docker化部署实操3.1 多阶段构建Dockerfile先上一份我实际在用的Dockerfile然后逐段讲为什么这么写# 阶段一构建依赖 FROM python:3.12-slim AS builder WORKDIR /build COPY requirements.txt . RUN pip install --prefix/install -r requirements.txt # 阶段二运行镜像 FROM python:3.12-slim RUN groupadd -r app useradd -r -g app app WORKDIR /app COPY --frombuilder /install /usr/local COPY app ./app USER app EXPOSE 8000 CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000, --workers, 4, --proxy-headers, --forwarded-allow-ips, *]这里有几个关键点单独说一下。第一多阶段构建。第一阶段用pip --prefix/install把依赖装到一个指定目录第二阶段只拷贝安装结果。最终镜像里没有构建缓存和中间文件体积能小不少。我实测装完FastAPI全家桶用多阶段构建的镜像比直接一条RUN pip install的方式小了将近200MB。这在服务器磁盘紧张的时候非常有用。第二非root用户运行。容器默认是root权限一旦应用被攻破攻击者就直接拿到容器root了。创建低权限用户运行服务是基本的安全习惯花两行省心一大截。第三启动命令里的--proxy-headers和--forwarded-allow-ips。这两个参数是给Nginx反向代理场景用的。当你用Nginx转发请求时真实客户端IP在X-Forwarded-For头里FastAPI默认不会信任这个头导致你看到的客户端来源永远是Nginx的地址。加了这两个参数uvicorn会解析反向代理传来的头部信息拿到真实IP。如果你不做这一层后面做访问日志分析、限流、IP黑名单都会出问题。3.2 docker-compose编排服务有了镜像接下来就用Compose把应用和依赖服务编排起来。一个典型的FastAPI服务通常还需要数据库、缓存之类的配套我拿PostgreSQL和Redis举例version: 3.8 services: api: build: context: . dockerfile: docker/Dockerfile container_name: fastapi-test-api restart: always env_file: - .env ports: - 127.0.0.1:8000:8000 depends_on: - db - redis healthcheck: test: [CMD, python, -c, import urllib.request; urllib.request.urlopen(http://localhost:8000/health)] interval: 30s timeout: 5s retries: 3 start_period: 10s db: image: postgres:16-alpine restart: always env_file: - .env volumes: - pg_data:/var/lib/postgresql/data redis: image: redis:7-alpine restart: always volumes: pg_data:端口这里我用了127.0.0.1:8000:8000意思是只把8000端口暴露在宿主机本机不对外网开放。对外流量统一从Nginx进。这比直接- 8000:8000安全得多因为Nginx在前面统一做TLS终止和请求过滤应用本身就不该直接暴露在公网。restart: always是生产环境的标配进程挂了Docker会自动拉起来。healthcheck配置会让Docker周期性检查/health接口这个状态在docker ps里能看到也能被其他自动化工具消费。3.3 容器内的进程管理和并发参数很多人在容器里只用单worker跑FastAPI这在正式环境是不够的。单worker意味着同一时刻只能处理一个请求的CPU密集操作虽然async能扛住I/O等待但并发量一上来CPU密集任务会阻塞事件循环表现为接口响应时间暴涨。worker数量不是越多越好太多会消耗内存而且每个worker会创建独立的数据库连接池连爆数据库就是一瞬间的事。我的经验是worker数 CPU核心数 * 2 1这是Gunicorn文档里给的经验公式适合大部分场景。你也可以用--limit-max-requests让worker处理一定数量请求后自动重启避免内存泄漏积累CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000, --workers, 3, --limit-max-requests, 2048]如果你用的是带lifespan的FastAPI应用比如在启动时创建数据库连接池要注意worker进程和异步资源释放的问题。多worker模式下每个worker是独立进程都会执行lifespan的启动和关闭逻辑。像Redis连接池这种在lifespan里创建是没问题的但要注意连接池大小别配得过大一个worker一个池三个worker就是三倍连接数。4. Nginx反向代理与域名接入4.1 Nginx核心配置说明Nginx在整套部署里的角色是“流量入口”HTTP请求先进NginxTLS终止在这里做然后明文HTTP转发给后端FastAPI容器。这样后端不用处理证书也不用暴露公网端口链路更清晰。一份完整可用的/etc/nginx/conf.d/fastapi-test.conf大概长这样server { listen 80; server_name api.example.com; client_max_body_size 50m; 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; proxy_connect_timeout 60s; proxy_read_timeout 120s; proxy_send_timeout 120s; } location /static { alias /var/www/fastapi-test/static; expires 30d; add_header Cache-Control public, immutable; } }client_max_body_size必须显式配置。FastAPI后端如果不接收大文件上传默认的1MB可能会挡住业务就算要限制大小也应该是在Nginx这一层统一限制而不是让请求进到应用层才发现超限。proxy_read_timeout这个参数特别容易踩坑。FastAPI如果处理的是耗时任务响应时间超过Nginx默认的60秒Nginx会直接断开连接客户端看到的就是504。我的建议是先设120秒根据你最长接口的响应时间再调。4.2 WebSocket和流式接口的特殊处理如果你的FastAPI接了WebSocket或者SSEServer-Sent EventsNginx需要额外配置。WebSocket是长连接HTTP超时在这里不适用需要显式加上Upgrade相关的Headerlocation /ws/ { proxy_pass http://127.0.0.1:8000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 3600s; }SSE也是常踩的坑点。SSE是持续不断的HTTP流式响应Nginx默认会缓冲响应内容导致前端收到的SSE事件不是实时的。要在location里关闭缓冲location /sse/ { proxy_pass http://127.0.0.1:8000; proxy_buffering off; proxy_cache off; proxy_read_timeout 86400s; }这两个配置都是经历过生产事故才记住的。第一次联调WebSocket时前端一直报连接失败查了半天才意识到Nginx压根没转发Upgrade请求。后来就把这套配置沉淀成了模板新项目直接用。4.3 HTTPS证书配置现在部署任何服务没有HTTPS基本说不过去。用Certbot配Lets Encrypt证书是最省事的方式一条命令就能自动申请、续期certbot --nginx -d api.example.com证书配好后Nginx会自动改配置把80端口的请求跳转到443。注意证书续期问题Lets Encrypt证书90天过期用Certbot的话记得确认定时任务在跑systemctl status certbot.timer如果不做自动续期证书过期后客户端会直接报安全错误到时候排查起来又是一顿折腾。5. 常见问题与排查技巧实录5.1 “热更新”不生效先澄清一个概念--reload这个热更新参数设计初衷是给开发环境用的在容器化和Nginx部署的场景里完全不适用。你改了代码容器里的文件没变进程也没重启热更新当然不生效。如果你就是想在服务器上快速调试代码有两个思路。一是用docker compose up --build重新构建镜像适合代码稳定后重新发布二是开发阶段用bind mount把宿主机代码挂载进容器配合--reload改代码后容器内会自动重载services: api: volumes: - ./app:/app/app注意bind mount只建议在开发环境用。生产环境滥用bind mount会让容器失去“环境一致”的意义代码更新也依赖宿主机文件状态这不叫容器化部署。5.2 数据库连接数被打满FastAPI多worker模式下每个worker都会创建自己的数据库连接池。假设配了4个worker每个池10个连接那应用启动后就直接吃掉40个数据库连接。如果你的数据库连接上限比较低比如PostgreSQL默认的100其他服务再来凑个热闹很容易就报“too many connections”。排查思路很简单到数据库里看当前连接数和来源SELECT pid, usename, application_name, client_addr, state FROM pg_stat_activity WHERE datname your_db;解决方案通常有两种调小每个worker的连接池上限比如pool_size3、max_overflow2或者引入PgBouncer之类的连接池代理。绝大多数中小项目把池调小就够用了没必要一上来就上代理那是加复杂度。5.3 Docker容器内无法访问宿主机服务开发环境里代码里写的localhost:3306在容器里是不通的因为容器有独立的网络命名空间。这个问题新手必踩。解决方案是用host.docker.internal这个特殊域名替代localhostDocker DesktopMac/Windows直接支持Linux服务器上需要在Compose文件里加services: api: extra_hosts: - host.docker.internal:host-gateway但更推荐的思路是应用和依赖服务都放到同一个Compose网络里通过服务名互访。比如FastAPI连MySQL连接地址直接写db:3306Docker的内置DNS会解析到db容器。这样整个集群内部通信更干净也符合微服务的架构习惯。5.4 常见问题速查表症状可能原因解决思路访问502FastAPI容器挂了或端口不对docker ps -a看容器状态docker logs看应用日志504网关超时接口耗时超过Nginx超时调大proxy_read_timeout优化慢接口静态资源404FastAPI默认不处理Static文件参考4.1节用Nginxalias或挂到对象存储请求体超过1MBNginx默认限制调大client_max_body_size客户端IP全是127.0.0.1没开--proxy-headers启动命令加--proxy-headers日志没有时间戳容器默认UTC时区Compose里加TZAsia/Shanghai环境变量排查问题一定讲究顺序先看容器状态再看应用日志然后抓网络请求。别一上来就怀疑代码逻辑先确认数据链路通不通。docker logs --tail100 -f fastapi-test-api是我在服务器上输得最多的命令。部署这件事光看文档是学不会的。我自己第一次把FastAPI部署到生成环境光调试WebSocket就花了整个下午后面把这些配置沉淀成模板新项目基本十分钟就能把整套环境拉起来。这套方案的核心就三个关键词环境隔离、进程守护、统一入口。把这三个问题想清楚不论以后换K8s还是上云平台思路都是一脉相承的。最后再分享一个小技巧Docker部署完之后先用docker compose logs扫一遍启动日志确认没有报错再手动curl -i http://127.0.0.1:8000/health看一眼响应头和状态码。这一步能筛掉大部分配置低级错误别急着上域名和证书。服务起得来、健康检查通了再去做反向代理问题就容易定位了。本文还有配套的精品资源点击获取 FastAPI生产级部署全攻略：Docker Compose + Nginx反向代理实践
简介面向需要掌握 Python 后端服务上线技能的初中级开发者这份围绕 FastAPI 部署的实战资源包提供了从零开始构建 API 服务的完整路径。其核心优势在于不仅讲解框架本身还特别关注与 JavaScript 前端的协作通过 Type Hint 定义接口、利用 OpenAPI 自动生成交互式文档、以 AJAX 完成跨语言联调极大降低了前后端对接成本。资源以 zip 压缩包形式提供大小约 6.87MB页面未显示具体文件数但内容涉及 main.py 示例代码、Uvicorn/Gunicorn 启动配置、Nginx 反向代理参考配置及部署流程说明等方便对照实践。内容依次覆盖环境准备、路由编写、本地热重载开发、生产环境 GunicornNginx 部署并延伸至 Jenkins、GitHub Actions 等 CI/CD 集成形成一套可落地到真实项目的完整链路。目前已有 987 人学习下载步骤清晰、体系性强对希望快速打通 FastAPI 与 JavaScript 前后端联调、并掌握生产部署要点的开发者很有帮助。 我从一个FastAPI测试项目走到正式部署整个过程踩了不少坑也把一些平时文档里写得不清楚的地方彻底搞明白了。这篇博文就拿“fastapi-test”这个项目当例子把FastAPI部署这件事从头到尾讲透从部署方案选型、项目结构整理到Docker构建、Nginx反向代理再到高频故障排查都是一线实操经验不掺杂理论空谈。无论你是刚接触FastAPI的新手还是已经写过几个接口、想把它真正丢到服务器上跑起来的开发者这篇都值得收藏。1. 部署方案选型与整体思路1.1 为什么FastAPI适合做后端接口服务先说一个基本认知FastAPI不是一个Web服务器它是一个Web框架。这意味着你说“FastAPI部署”本质上是“如何把一个基于FastAPI的应用稳定地跑在服务器上对外提供服务”。FastAPI这几年热度很高核心优势就三个异步原生支持、Pydantic模型校验、自动生成OpenAPI文档。这三个特性放到部署场景里意味着你的服务天然适合高并发I/O密集型任务也方便前端或者第三方团队对联调。但框架好不代表部署简单。实际生产环境里我见过太多人本地跑uvicorn main:app --reload一切正常一到服务器就各种问题端口起不来、请求卡死、静态文件404、数据库连接池爆掉。这篇文章要解决的就是这些真实环境里会撞上的问题。1.2 部署方式横向对比部署FastAPI的方案不少我按实战中用过的顺序给你捋一遍部署方式适合场景优点缺点裸跑uvicorn本地调试、临时接口最简单一条命令启动无守护进程进程挂了不会自动拉起systemd uvicorn单机小项目随系统自启、崩溃自动重启环境迁移麻烦依赖本机Python环境Docker docker-compose中小型项目主力方案环境隔离、一键迁移、扩展方便需要理解容器网络和镜像构建Kubernetes大规模微服务弹性伸缩、自愈能力强运维成本高小项目杀鸡用牛刀我的建议是个人项目、小团队内部工具直接Docker Compose。这个方案在可维护性和上手难度之间平衡得最好。公司有K8s集群就另说但思路也是先把镜像打好再往上丢。这篇博文后面所有的实操内容都以Docker Compose为主线配合Nginx反向代理。这套组合在社区里是标准解法你在很多开源项目里都能看到类似的目录结构和配置文件。2. 部署前的项目整理与配置2.1 目录结构和依赖管理很多人的FastAPI项目是“一个main.py走天下”开发时没问题部署时就会很难受。我建议在部署前把项目整理成下面这样这也是我实际在用的结构fastapi-test/ ├── app/ │ ├── __init__.py │ ├── main.py # 应用入口 │ ├── core/ │ │ ├── config.py # 配置项读环境变量 │ │ └── logging.py # 日志配置 │ ├── routers/ │ │ └── api_v1.py # 业务路由 │ └── models/ # 业务模型 ├── docker/ │ └── Dockerfile ├── docker-compose.yml ├── requirements.txt └── .env.example依赖管理必须做到“可复现”。我强烈建议你锁定版本而不是用fastapi这种宽泛写法。实测下来FastAPI的小版本升级偶尔会有破坏性变更Pydantic从v1升到v2更是一个大坎。锁定版本是成本最低的避坑方式fastapi0.115.12 uvicorn[standard]0.34.2 pydantic2.11.2 pydantic-settings2.8.1 sqlalchemy2.0.40 psycopg2-binary2.9.10uvicorn[standard]这个写法很多人不注意。它比裸uvicorn多装了uvloop、httptools、websockets这几个关键依赖。尤其websockets如果你之后要支持WebSocket长连接只装裸uvicorn会直接导入失败。这种细节文档里写得含蓄但报错的时候很致命。2.2 环境变量配置与敏感信息隔离配置管理上别再把数据库密码、密钥写在代码里了。部署时你会接触多个环境本地、测试、正式每个环境的数据库地址、日志级别都不一样。我的做法是用pydantic-settings统一管理配置所有可变项都从环境变量读取。# app/core/config.py from pydantic_settings import BaseSettings class Settings(BaseSettings): app_name: str fastapi-test debug: bool False database_url: str sqlite:///./test.db secret_key: str change-me class Config: env_file .env env_file_encoding utf-8 settings Settings()这样做的收益很大项目里没有硬编码的敏感信息部署时只需要维护一套.env文件即可。容器化部署时把环境变量通过Compose文件传进去既不污染镜像也方便不同环境复用同一个镜像。注意.env文件一定放进.gitignore只提交.env.example作为模板。这些都是小事但真的很重要——GitHub上每天都有大量因为密钥泄露被恶意挖矿的惨案。2.3 健康检查接口是部署的第一步部署前请务必在应用里加一个健康检查接口。这不是为了好看而是为了后续的容器编排、负载均衡、监控告警都有的放矢。# app/main.py from fastapi import FastAPI from app.core.config import settings app FastAPI(titlesettings.app_name) app.get(/health) def health_check(): return {status: ok, app: settings.app_name}有了这个接口Docker Compose可以配置healthcheckNginx可以拿它做被动健康检查云平台的负载均衡也能直接监听这个路径。别等部署到K8s才想起来加这个那时候你连Pod起没起来都说不清楚。3. Docker化部署实操3.1 多阶段构建Dockerfile先上一份我实际在用的Dockerfile然后逐段讲为什么这么写# 阶段一构建依赖 FROM python:3.12-slim AS builder WORKDIR /build COPY requirements.txt . RUN pip install --prefix/install -r requirements.txt # 阶段二运行镜像 FROM python:3.12-slim RUN groupadd -r app useradd -r -g app app WORKDIR /app COPY --frombuilder /install /usr/local COPY app ./app USER app EXPOSE 8000 CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000, --workers, 4, --proxy-headers, --forwarded-allow-ips, *]这里有几个关键点单独说一下。第一多阶段构建。第一阶段用pip --prefix/install把依赖装到一个指定目录第二阶段只拷贝安装结果。最终镜像里没有构建缓存和中间文件体积能小不少。我实测装完FastAPI全家桶用多阶段构建的镜像比直接一条RUN pip install的方式小了将近200MB。这在服务器磁盘紧张的时候非常有用。第二非root用户运行。容器默认是root权限一旦应用被攻破攻击者就直接拿到容器root了。创建低权限用户运行服务是基本的安全习惯花两行省心一大截。第三启动命令里的--proxy-headers和--forwarded-allow-ips。这两个参数是给Nginx反向代理场景用的。当你用Nginx转发请求时真实客户端IP在X-Forwarded-For头里FastAPI默认不会信任这个头导致你看到的客户端来源永远是Nginx的地址。加了这两个参数uvicorn会解析反向代理传来的头部信息拿到真实IP。如果你不做这一层后面做访问日志分析、限流、IP黑名单都会出问题。3.2 docker-compose编排服务有了镜像接下来就用Compose把应用和依赖服务编排起来。一个典型的FastAPI服务通常还需要数据库、缓存之类的配套我拿PostgreSQL和Redis举例version: 3.8 services: api: build: context: . dockerfile: docker/Dockerfile container_name: fastapi-test-api restart: always env_file: - .env ports: - 127.0.0.1:8000:8000 depends_on: - db - redis healthcheck: test: [CMD, python, -c, import urllib.request; urllib.request.urlopen(http://localhost:8000/health)] interval: 30s timeout: 5s retries: 3 start_period: 10s db: image: postgres:16-alpine restart: always env_file: - .env volumes: - pg_data:/var/lib/postgresql/data redis: image: redis:7-alpine restart: always volumes: pg_data:端口这里我用了127.0.0.1:8000:8000意思是只把8000端口暴露在宿主机本机不对外网开放。对外流量统一从Nginx进。这比直接- 8000:8000安全得多因为Nginx在前面统一做TLS终止和请求过滤应用本身就不该直接暴露在公网。restart: always是生产环境的标配进程挂了Docker会自动拉起来。healthcheck配置会让Docker周期性检查/health接口这个状态在docker ps里能看到也能被其他自动化工具消费。3.3 容器内的进程管理和并发参数很多人在容器里只用单worker跑FastAPI这在正式环境是不够的。单worker意味着同一时刻只能处理一个请求的CPU密集操作虽然async能扛住I/O等待但并发量一上来CPU密集任务会阻塞事件循环表现为接口响应时间暴涨。worker数量不是越多越好太多会消耗内存而且每个worker会创建独立的数据库连接池连爆数据库就是一瞬间的事。我的经验是worker数 CPU核心数 * 2 1这是Gunicorn文档里给的经验公式适合大部分场景。你也可以用--limit-max-requests让worker处理一定数量请求后自动重启避免内存泄漏积累CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000, --workers, 3, --limit-max-requests, 2048]如果你用的是带lifespan的FastAPI应用比如在启动时创建数据库连接池要注意worker进程和异步资源释放的问题。多worker模式下每个worker是独立进程都会执行lifespan的启动和关闭逻辑。像Redis连接池这种在lifespan里创建是没问题的但要注意连接池大小别配得过大一个worker一个池三个worker就是三倍连接数。4. Nginx反向代理与域名接入4.1 Nginx核心配置说明Nginx在整套部署里的角色是“流量入口”HTTP请求先进NginxTLS终止在这里做然后明文HTTP转发给后端FastAPI容器。这样后端不用处理证书也不用暴露公网端口链路更清晰。一份完整可用的/etc/nginx/conf.d/fastapi-test.conf大概长这样server { listen 80; server_name api.example.com; client_max_body_size 50m; 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; proxy_connect_timeout 60s; proxy_read_timeout 120s; proxy_send_timeout 120s; } location /static { alias /var/www/fastapi-test/static; expires 30d; add_header Cache-Control public, immutable; } }client_max_body_size必须显式配置。FastAPI后端如果不接收大文件上传默认的1MB可能会挡住业务就算要限制大小也应该是在Nginx这一层统一限制而不是让请求进到应用层才发现超限。proxy_read_timeout这个参数特别容易踩坑。FastAPI如果处理的是耗时任务响应时间超过Nginx默认的60秒Nginx会直接断开连接客户端看到的就是504。我的建议是先设120秒根据你最长接口的响应时间再调。4.2 WebSocket和流式接口的特殊处理如果你的FastAPI接了WebSocket或者SSEServer-Sent EventsNginx需要额外配置。WebSocket是长连接HTTP超时在这里不适用需要显式加上Upgrade相关的Headerlocation /ws/ { proxy_pass http://127.0.0.1:8000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 3600s; }SSE也是常踩的坑点。SSE是持续不断的HTTP流式响应Nginx默认会缓冲响应内容导致前端收到的SSE事件不是实时的。要在location里关闭缓冲location /sse/ { proxy_pass http://127.0.0.1:8000; proxy_buffering off; proxy_cache off; proxy_read_timeout 86400s; }这两个配置都是经历过生产事故才记住的。第一次联调WebSocket时前端一直报连接失败查了半天才意识到Nginx压根没转发Upgrade请求。后来就把这套配置沉淀成了模板新项目直接用。4.3 HTTPS证书配置现在部署任何服务没有HTTPS基本说不过去。用Certbot配Lets Encrypt证书是最省事的方式一条命令就能自动申请、续期certbot --nginx -d api.example.com证书配好后Nginx会自动改配置把80端口的请求跳转到443。注意证书续期问题Lets Encrypt证书90天过期用Certbot的话记得确认定时任务在跑systemctl status certbot.timer如果不做自动续期证书过期后客户端会直接报安全错误到时候排查起来又是一顿折腾。5. 常见问题与排查技巧实录5.1 “热更新”不生效先澄清一个概念--reload这个热更新参数设计初衷是给开发环境用的在容器化和Nginx部署的场景里完全不适用。你改了代码容器里的文件没变进程也没重启热更新当然不生效。如果你就是想在服务器上快速调试代码有两个思路。一是用docker compose up --build重新构建镜像适合代码稳定后重新发布二是开发阶段用bind mount把宿主机代码挂载进容器配合--reload改代码后容器内会自动重载services: api: volumes: - ./app:/app/app注意bind mount只建议在开发环境用。生产环境滥用bind mount会让容器失去“环境一致”的意义代码更新也依赖宿主机文件状态这不叫容器化部署。5.2 数据库连接数被打满FastAPI多worker模式下每个worker都会创建自己的数据库连接池。假设配了4个worker每个池10个连接那应用启动后就直接吃掉40个数据库连接。如果你的数据库连接上限比较低比如PostgreSQL默认的100其他服务再来凑个热闹很容易就报“too many connections”。排查思路很简单到数据库里看当前连接数和来源SELECT pid, usename, application_name, client_addr, state FROM pg_stat_activity WHERE datname your_db;解决方案通常有两种调小每个worker的连接池上限比如pool_size3、max_overflow2或者引入PgBouncer之类的连接池代理。绝大多数中小项目把池调小就够用了没必要一上来就上代理那是加复杂度。5.3 Docker容器内无法访问宿主机服务开发环境里代码里写的localhost:3306在容器里是不通的因为容器有独立的网络命名空间。这个问题新手必踩。解决方案是用host.docker.internal这个特殊域名替代localhostDocker DesktopMac/Windows直接支持Linux服务器上需要在Compose文件里加services: api: extra_hosts: - host.docker.internal:host-gateway但更推荐的思路是应用和依赖服务都放到同一个Compose网络里通过服务名互访。比如FastAPI连MySQL连接地址直接写db:3306Docker的内置DNS会解析到db容器。这样整个集群内部通信更干净也符合微服务的架构习惯。5.4 常见问题速查表症状可能原因解决思路访问502FastAPI容器挂了或端口不对docker ps -a看容器状态docker logs看应用日志504网关超时接口耗时超过Nginx超时调大proxy_read_timeout优化慢接口静态资源404FastAPI默认不处理Static文件参考4.1节用Nginxalias或挂到对象存储请求体超过1MBNginx默认限制调大client_max_body_size客户端IP全是127.0.0.1没开--proxy-headers启动命令加--proxy-headers日志没有时间戳容器默认UTC时区Compose里加TZAsia/Shanghai环境变量排查问题一定讲究顺序先看容器状态再看应用日志然后抓网络请求。别一上来就怀疑代码逻辑先确认数据链路通不通。docker logs --tail100 -f fastapi-test-api是我在服务器上输得最多的命令。部署这件事光看文档是学不会的。我自己第一次把FastAPI部署到生成环境光调试WebSocket就花了整个下午后面把这些配置沉淀成模板新项目基本十分钟就能把整套环境拉起来。这套方案的核心就三个关键词环境隔离、进程守护、统一入口。把这三个问题想清楚不论以后换K8s还是上云平台思路都是一脉相承的。最后再分享一个小技巧Docker部署完之后先用docker compose logs扫一遍启动日志确认没有报错再手动curl -i http://127.0.0.1:8000/health看一眼响应头和状态码。这一步能筛掉大部分配置低级错误别急着上域名和证书。服务起得来、健康检查通了再去做反向代理问题就容易定位了。本文还有配套的精品资源点击获取