董超华FastAPI性能与部署实战五：Uvicorn/Gunicorn、多环境配置、监控与日志，这期是整套系列里最“摸得着”的一篇。前面几期我们把接口设计、参数校验、中间件优化都过了一遍，但代码写得再漂亮，最后还是要落到一个能扛住线上流量的部署方案上。这一篇要解决的无非是三个事：用Uvicorn和Gunicorn把服务稳定跑起来、把开发测试生产的环境配置隔离开、把监控和日志这两个“眼睛”装上。适合刚把FastAPI项目写完准备部署的朋友，也适合那些服务已经上线、但遇到问题只能靠猜、靠翻终端的人。
先说一个我踩了不知道多少次的认知误区：很多新手直接uvicorn main:app --workers 4就跑生产了，然后过阵子发现某个worker莫名其妙僵死，请求超时，CPU飙到100%。这不是Uvicorn不行，而是你没搞清楚谁该管进程、谁该管协议。把这层关系理清楚，部署的很多问题都能提前避免。
1. 部署方案选型：为什么是Uvicorn+Gunicorn
1.1 Uvicorn与Gunicorn的分工关系
先看最本质的区别：Uvicorn是个ASGI服务器，它实现了ASGI协议，能直接和FastAPI应用通信，异步能力强；Gunicorn本来是个WSGI服务器，主要服务Django、Flask这类同步框架，但从20.1版本开始，Gunicorn支持了Uvicorn的worker类型，官方文档里也把gunicorn -k uvicorn.workers.UvicornWorker作为生产部署的标准方案。
你完全可以把这两者理解成“包工头”和“施工队”的关系。Gunicorn是包工头，负责从工地上拉来一堆工人（worker进程），管他们的入场、离场、健康状态，哪个工人干不动了就换一个；Uvicorn是施工队，真正执行砌墙、抹灰这些活计，也就是处理HTTP/ASGI协议、解析请求、再把任务丢给FastAPI的业务代码。包工头不亲自砌墙，所以他管进程管理特别在行，比如worker重启、pre-load、优雅停机；施工队如果自己又拉人又干活，很容易忙乱。
这里有个关键原因要说明白：为什么不直接uvicorn --workers 4？Uvicorn确实支持多worker，而且自带进程管理器，但它的进程管理能力比Gunicorn弱，例如没有--preload这种预热机制，也没有那么细致的worker超时和优雅重启策略。生产环境里，Gunicorn的--timeout、--graceful-timeout、--max-requests这一套配置，能让服务在异常情况下“自我抢救”，而不是整个瘫掉。实测下来，用Gunicorn管理进程、用Uvicorn worker处理协议，稳定性明显强于一上来就裸跑Uvicorn多进程。
1.2 性能参数与worker数量计算
worker数量不是拍脑袋定的，一般从CPU核心数出发。最常见的经验公式是2 * CPU核心数 + 1，这是基于大量同步worker场景的经验值，但FastAPI是异步应用，worker进程内部已经用事件循环处理了大量并发，并不需要开太多进程。更合适的做法是先把服务压测一遍，然后结合核心数来定。
举个例子，一台4核的云服务器，如果接口里大部分是异步IO（查数据库、调外部API），我会从4个worker开始跑，让事件循环去吸收并发，而不是开8个进程去抢占CPU。如果接口里面有严重依赖CPU计算的同步代码，比如图像处理、加密解密，那worker数量可以适当增多，避免一个计算任务阻塞事件循环。
内存也要算进去。每个Uvicorn worker大概会占50~150MB内存，取决于应用加载的依赖和缓存。4G内存的机器，跑4个worker通常已经比较紧张了，要监控着点，别把系统内存全吃光。
还有几个参数要配套设置：
--timeout：默认30秒。如果某个接口处理时间超过30秒，Gunicorn会认为worker卡死，直接把它杀掉重启。FastAPI里如果确实有长耗时任务，要把timeout调大，或者干脆丢到后台任务队列里，别让HTTP请求扛着。--graceful-timeout：默认也是30秒。优雅停机时等待worker处理完当前请求的时间，建议给足，不然正在处理中的请求会被强杀。--keep-alive：默认2秒。保持HTTP长连接的时间，面向WebSocket或大量复用连接的场景可以调大点，一般2~5秒够用。--max-requests：让worker处理完一定数量的请求后主动重启，能有效解决内存泄漏问题。我通常设成1000~2000，配合--max-requests-jitter加一点随机量，避免所有worker同时重启。
配置文件写成这样，放production.conf.py里：
python复制import multiprocessing
workers = multiprocessing.cpu_count() * 2 + 1
worker_class = "uvicorn.workers.UvicornWorker"
bind = "0.0.0.0:8000"
timeout = 60
graceful_timeout = 30
keepalive = 5
max_requests = 1500
max_requests_jitter = 300
accesslog = "-"
errorlog = "-"
accesslog = "-"是把访问日志打到标准输出，方便容器环境统一采集日志。如果你用Docker部署，这个设置几乎是必须的，别把日志写进容器里的文件，容器一销毁日志就全没了。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 多环境配置：从开发到生产的一次到位
2.1 为什么需要多环境配置
我见过很多项目把数据库连接串直接写在config.py里，然后部署时靠手动修改代码来切换环境。这种方式在项目刚起步时还能忍，一旦团队人多起来，你根本不知道线上跑的是哪个版本，一个不小心就把测试环境的数据库连接发上去了。
多环境配置要解决三个问题：第一，不同环境下的参数值不同，比如数据库地址、Redis地址、日志级别、调试开关；第二，敏感信息不能进代码仓库，比如密码、密钥；第三，切换环境不需要改代码，只需要改变量。
FastAPI生态里最顺手的方案是pydantic-settings，它能把环境变量自动解析成带类型校验的配置对象，而pydantic本来就是FastAPI的底层依赖，不用额外引入一整套新的配置框架。
2.2 基于pydantic-settings的配置体系
先装依赖：
bash复制pip install pyd