FastAPI结合Docker生产部署必须用生产级ASGI服务器（Uvicorn或Gunicorn+UvicornWorker）、显式绑定0.0.0.0:8000、正确暴露端口，禁用--reload；否则因只读文件系统导致热重载失效、单worker并发不足、监听localhost致外部无法访问，引发502或connection refused。
FastAPI 结合 Docker 打包部署，核心就一条：不能直接用开发命令跑进容器，必须用生产级 ASGI 服务器 + 显式绑定地址端口 + 正确暴露端口。否则本地能 curl 通，上线就 502。
为什么 uvicorn --reload 不能进生产容器
开发时常用 uvicorn main:app --reload --host 0.0.0.0 --port 8000，但 --reload 依赖文件监听，在只读的容器文件系统里根本不起作用，还会报 Watchdog not available 或静默失败。更关键的是，它默认只启一个 worker，扛不住并发。
- 容器内无需热重载——代码已打包进镜像，改了就得重建镜像
-
--reload会启动额外进程监控，干扰容器健康检查和信号传递 - 单 worker 在 CPU 多核机器上严重浪费资源，容易成为瓶颈
Dockerfile 里该用 uvicorn 还是 gunicorn + uvicorn worker
两者都行，但选择取决于负载预期：
- 轻量服务（QPS < 100）、快速验证：直接用
uvicorn，启动快、配置少
示例 CMD：["uvicorn", "main:app", "--host", "0.0.0.0:8000", "--workers", "4"] - 中高流量（需平滑重启、连接池管理、请求限流）：用
gunicorn做进程管理器，配uvicorn.workers.UvicornWorker
示例 CMD：["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "4", "--worker-class", "uvicorn.workers.UvicornWorker", "main:app"]
注意：--workers 数建议设为 2 * CPU核心数 + 1，但容器里要确认实际可分配核数（比如 Kubernetes 中限制了 resources.limits.cpu: "2"，就别设 8 个 worker）。
EXPOSE 和 -p 的关系经常被搞反
EXPOSE 8000 只是文档性声明，不打开端口；真正映射靠 docker run -p 8000:8000 或编排工具里的端口配置。常见错误：
- FastAPI 应用代码里写了
uvicorn.run(..., port=80)，但 Dockerfile 写EXPOSE 8000→ 容器内端口和外部映射不一致，连不上 - 没在 CMD 中显式指定
--host 0.0.0.0，导致只监听 localhost → 外部请求进不来，返回 connection refused - 用
python:3.9-slim镜像但忘了装gcc或build-essential→ 某些依赖（如pydantic-core）编译失败，镜像构建卡在 pip install
Nginx 反向代理不是可选项，而是线上必经一环
单独跑 FastAPI 容器对外提供服务，等于把 ASGI 服务器直接暴露在公网——没有静态文件托管、无 TLS 终止、无请求缓冲、无限速熔断。真实部署中，Nginx 是事实标准入口：
- 必须转发
Upgrade: websocket头，否则FastAPI的 SSE 或 WebSocket 接口会断连 - 需设置
proxy_buffering off和proxy_http_version 1.1，避免流式响应（如 AI 生成文本）被缓存截断 - 若上游是
http://fastapi-container:8000，Nginx 配置里proxy_pass末尾带不带/，会影响路径重写逻辑，极易导致 404
最常被忽略的一点：Docker 网络模式。用 bridge 网络时，Nginx 容器和 FastAPI 容器必须在同一个自定义网络里，且用服务名（如 fastapi）而非 localhost 通信——否则 Nginx 根本找不到后端。
