FastAPI部署到服务器：反向代理与HTTPS证书配置详解

本节目标：理解 FastAPI 前面为何要放反向代理，搞懂 HTTPS 证书与续期机制，并了解把应用部署到云平台或自有服务器时如何处理域名、静态文件与代理头。

应用能跑起来只是第一步。要让外网用户安全访问，还需要 HTTPS 和反向代理。这一章把部署最后一块拼图补齐。

50-1 为什么需要反向代理

你的 FastAPI 由 Uvicorn 跑着，直接监听某个端口。但生产环境通常不会让 Uvicorn 直接面对公网，而是在它前面放一个「反向代理」。

反向代理（Reverse Proxy）坐在公网和用户之间，负责接收外部请求，再转发给你的应用。它常同时承担几个职责：

处理 HTTPS 加密（TLS 终止）
把请求分发给多个后端进程（负载均衡）
统一处理域名、静态文件、压缩等

常见选择有 Nginx、Traefik、Caddy、HAProxy。Traefik 和 Caddy 还能自动申请并续期证书，最省心。

50-2 HTTPS 与 TLS 终止代理

HTTPS 不是「开个开关」那么简单。服务器需要向第三方机构申请证书，证书有有效期（通常约 3 个月），到期要续期。TLS 加密位于 TCP 之上、HTTP 之下。

实践中，通常由反向代理充当「TLS 终止代理」：它监听 443 端口、握手解密 HTTPS，把明文 HTTP 转给你的 Uvicorn；Uvicorn 返回的明文响应再由代理加密发回浏览器。这就是「终止」的意思——加密在此处结束。

Note

一个 IP 的 443 端口同一时刻只能一个进程监听，这个进程就是 TLS 终止代理。它持有证书，靠 SNI 扩展能在一个 IP 上服务多个域名。你的应用只需跑在内部端口，由代理转发。

50-3 Let’s Encrypt 与自动续期

过去证书又贵又麻烦。现在 Let’s Encrypt 免费提供标准证书，自动验证域名、自动签发，生命周期约 3 个月，反而因够短更安全。Traefik、Caddy 这类工具内置了续期流程。

续期程序要证明「你控制这个域名」，常见做法：改 DNS 记录，或在公网 IP 上临时起服务。因为代理本身就监听那个端口，让「同一个代理顺带管续期」最理想——否则得先停代理再续，期间服务会中断。这也说明：HTTPS 最好交给独立的反向代理组件，而不是让 Uvicorn 直接挂证书。

50-4 让应用信任代理头

请求经过代理后，应用（Uvicorn）拿到的是明文 HTTP，它并不知道外面是 HTTPS、原始域名是什么。代理会顺手加几个头：X-Forwarded-For、X-Forwarded-Proto、X-Forwarded-Host，告诉应用真实情况。

但应用默认不信任这些头（怕被伪造）。用 FastAPI CLI 跑时，加 --forwarded-allow-ips 告诉它信任来自哪个 IP 的代理头：

fastapi run main.py --forwarded-allow-ips "*"

"*" 表示信任所有来源，适用于应用只收来自可信代理的请求时（比如同一台机器、同一容器网络）。这样应用才能正确生成自己的公开 URL、做好重定向。

如果在 Docker 里跑在代理后面，Dockerfile 的 CMD 加 --proxy-headers 即可：

CMD ["fastapi", "run", "app/main.py", "--proxy-headers", "--port", "80"]

Tip

--proxy-headers 是信任代理头的总开关；--forwarded-allow-ips 是它的配套白名单（默认只信任 127.0.0.1）。代理不在本机时两者一起用：先开 --proxy-headers，再用 --forwarded-allow-ips 扩大信任的代理 IP。单独加 --forwarded-allow-ips 不会生效。

50-5 部署到云平台

几乎任何云厂商都能部署 FastAPI。流程大致是：把代码推上去，平台构建或拉取镜像，分配一个域名和 HTTPS，启动你的应用。

几个具体例子：

Railway：官方有 FastAPI 部署指南，连仓库或镜像即可，自动给 HTTPS 和域名。
Render：同样提供 FastAPI 部署文档，支持从 Git 构建、托管服务。
FastAPI Cloud：由 FastAPI 原作者团队打造，把构建、部署、访问一体化，体验和开发时一致。

云平台的优点是把 HTTPS、开机自启、崩溃重启、扩缩容都包了，你只需关心代码。代价可能是自由度或费用上的限制。小项目、原型、个人服务用它最快。

50-6 部署到自有服务器

用一台云主机（虚拟机）自己部署，灵活但要自己管更多事：

买域名，在 DNS 配 A 记录指向服务器公网 IP
装 Docker，用上一章的 Dockerfile 构建镜像并跑容器
在容器前放 Nginx/Traefik 做 TLS 终止与转发
用 --restart 策略或 systemd 保证容器开机自启、崩溃重启
让代理用 Let’s Encrypt/Certbot 拿到证书并自动续期

Nginx 反向代理的核心配置（示意）是把 443 收到的请求转发到本地 127.0.0.1:80 的容器：

server {
    listen 443 ssl;
    server_name yourdomain.com;
    location / {
        proxy_pass http://127.0.0.1:8000;
    }
}

Note

真实 Nginx 还要配证书路径、SSL 协议等，这里只展示「监听 443 → 转发到容器内 80」的转发思路。

50-7 静态文件与域名

FastAPI 主要服务 API（JSON）。如果你的项目还有前端静态文件（HTML/JS/CSS），两种处理方式：

让反向代理（Nginx/Traefik）直接托管静态文件，只有 /api 开头的请求转发给 FastAPI
或用 FastAPI 的 StaticFiles 挂载静态目录（小项目够用，大流量还是交给专业代理）

域名方面，一个反向代理能用 SNI 服务多个域名，把不同域名或不同路径前缀转发给不同后端应用。所以一台服务器上可以同时跑多个 FastAPI 服务，各自有各自域名。

50-8 部署概念回顾

整套部署要照顾的概念就这几条，本册三章部署已分别覆盖：

安全：HTTPS（交给 TLS 终止代理）
开机自启：systemd / 容器 restart 策略 / 云平台
崩溃重启：同上外部工具负责
复制：Uvicorn --workers 或多容器/多机
内存：按进程核算，避免撑爆
启动前步骤：数据库迁移等只跑一次

容器和反向代理组合后，这些概念大多被平台默认照顾好，你只需做少量配置。

50-9 小结

生产别让 Uvicorn 直连公网，前面放 Nginx/Traefik 这类反向代理做 TLS 终止与转发。容器映射端口时也只绑本机（如 docker run -p 127.0.0.1:8000:80 ...），不要把应用端口直接暴露到公网，否则会绕过 TLS 代理被明文访问。HTTPS 证书交给 Let’s Encrypt，由代理自动续期。应用用 --proxy-headers/--forwarded-allow-ips 信任代理头。云平台（Railway/Render/FastAPI Cloud）省心，自有服务器要自己配代理、DNS、重启策略。静态文件交给代理更稳。

HTTPS、反向代理与云平台部署

50-1 为什么需要反向代理

50-2 HTTPS 与 TLS 终止代理

50-3 Let’s Encrypt 与自动续期

50-4 让应用信任代理头

50-5 部署到云平台

50-6 部署到自有服务器

50-7 静态文件与域名

50-8 部署概念回顾

50-9 小结