很多团队在做微服务或内网程序时习惯把 Nginx 放在最前面统一处理 HTTPS、域名转发、负载均衡等“脏活”。怎么说呢，后面挂着的才是真正跑业务逻辑的 FastAPI 应用。这个架构本身没什么特殊，但细节处往往藏着坑：你的应用怎么知道自己是被 HTTPS 访问的？如果 Nginx 把 /api/ 前缀吃掉再转发给后端，FastAPI 生成的文档链接和 OpenAPI schema 会不会跟着乱掉？按理说，

这篇文章按官方思路拆解两大典型场景——代理转发请求头 和 代理剥离方法前缀并附上可直接抄用的 Nginx 配置。

🧭 反向代理到底做了什么

先建立直观印象：客户端请求先到 Nginx，再由 Nginx 转给 Uvicorn 运行的 FastAPI。Nginx 通常会加一些特殊头信息，告诉后端“这个请求原本长什么样”。按理说，

关键是 FastAPI 本身跑在内网。Uvicorn 收到的是 Nginx 转发过来的普通 HTTP 请求，它完全不知道外部客户端使用的是 HTTPS，也不知道真实域名。这些信息全靠 Nginx 塞进 X-Forwarded-* 系列头里应用侧必须主动去读取。其实，

🔐 场景一：只转发头信息

这是最常见情况——Nginx 直接把 example.com 的所有请求原样转发给后端。方法不裁剪，

需要读取哪些头

• X-Forwarded-For: 记录客户端真实 IP
• X-Forwarded-Proto: 记录客户端原始协议 http/https
• X-Forwarded-Host: 记录客户端请求时用的域名

但出于安全考虑，Uvicorn 默认不会信任这些头——任何客户端都可以伪造 X‑Forwarded‑Proto: https 来骗你。所以必须显式告诉服务器我这台机器只接受来自可信代理的转发头。

启用转发头的方式

If you use FastAPI CLI to start:

fastapi run --forwarded-allow-ips="*"

* 表示信任所有来源 IP 的转发头。生产环境更严谨，可只信任 Nginx 所在内网 IP，例如写成 ".". 如果直接用 Uvicorn 跑，则使用 --proxy-headers --forwarded-allow-ips=....

HTTPS 重定向不生效的坑

A typical failure: your route uses slash auto‑redirect . If forwarded headers aren't enabled,Uvicorn thinks client is always HTTP。so it redirects to http://example.com/items/. Browser n jumps from HTTPS page to an HTTP link—eir blocked or outright error.

Once forwarded headers are enabled,Uvicorn reads X‑Forwarded‑Proto,generates correct HTTPS redirect URLs.

Nginx 配置示例

server {
listen ssl;server_name example.com;location / {
proxy_pass http://127.0.0.1:8000;怎么说呢，# 或者 http://.:;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_set_header X-Forwarded-Host $host;}
}

This set of {proxy_set_header}s tells Uvicorn that externally it was seen as HTTPS and domain example.com.

✂️ 场景二：代理剥离了方法前缀

This scenario is trickier and common when a single domain hosts multiple services. You want,but keep internal routes clean .

root_path 到底解决什么问题？

Nginx strips /api prefix before forwarding,sending only /users to backend. The app never knows it's mounted under /api—route matching works fine locally,but generated OpenAPI docs。Swagger UI request URLs miss that prefix and break.

The solution is FastAPI’s root_path which tells application “you’re actually mounted at this prefix.” It adjusts generated links accordingly.

设置 root_path 有几种方式：

• 方式一：启动参数— decouples deployment from code.

fastapi run --root-path /api
# 或者如果使用 Uvicorn
uvicorn main:app --proxy-hosts ... --root-path=/api

方式二：代码硬编码 — 用于确定永远挂在固定前缀下。其实，
from fastapi import FastAPI
app = FastAPI # 只需要改一次即可

方式三：让代理传递前缀信息 — 设置自定义 header。如 X‑Forwarded‑Prefix，某些新版本服务器会自动解析并设置 root_path。

X‑Forwarded‑Prefix 可通过 Nginx 配置：
{proxy_set_header X‑Forwarded‑Prefix /api;话说回来，}
接下来让 ASGI 框架读取该 header 并设置 root_path。
这使得部署更灵活，无需在命令行或代码中硬编码方法。



T三种方式效果等价：让应用内部知道完整访问方法前缀。路由匹配逻辑保持不变，只影响文档、Swagger UI 等生成链接时的行为。
server {
listen ssl;
server_name example.com;
说起来，location /api/ {
# 关键：末尾斜杠让 Nginx 剥离 /api 前缀再转发
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_set_header X-Foward-Prefix /api;# 可选，用于框架自动解析
}
}
---

✅ 如何验证配置是否生效？


检查当前 root_path 是否被正确读取
 ) 

打开 Swagger UI 检查文档链接
 

查看 openapi.json 的 servers 字段
 


---

💡 常见踩坑汇总表格 

---

🎯 小结 

#1: Telling app what protocol & domain were used:
– Forward headers + enable via `<--forwardable-Allow-Ips>` or `<--proxy-Headers>` on Uvicorn/FastAPI CLI.
– Guarantees correct redirects & URLs when proxied over HTTPS.
#2: Telling app what path prefix it's mounted on:
– Use `<--root-path>` command line flag OR set `FastAPI` OR let framework read custom header like `X-Foward-Prefix`.   – Fixes broken OpenAPI docs and Swagger UI links when frontends strip prefixes.
The two lines of logic are independent—you can mix m as needed:


If you only forward protocol info and don't strip paths → just handle #1.

If you also want subpath mounting → add #2 on top of it.


其他框架的相同概念也能照搬过来一旦理解此模型，其它技术栈同理排查。


参考资料 



​ – 官方关于反向代理常用方法。




​ – 常见问答与实例代码。



​ – 社区讨论与经验。



​ – 获取真实客户 IP 的技巧与代码片段。






请根据您的环境自行调整 ip、port 与证书配置，并进行充分测试后再上线


现象 | 大概率原因 | 解决方向 


a) HTTPS站点出现HTTP跳转
原因：转发头未启用、Uvicorn 未信任X‑Forwarded‑Proto；默认协议为http导致重定向错误。解决方向：- 在启动参数中加入--forwarded-Allow-Ips=* 或仅限内部IP。而且确认 nginx 设置了X‐Forwarded‐Proto=$scheme。


b) Swagger UI 请求地址缺少前缀
原因：未设置root_path 或者 nginx 剥除前缀与 root_path 不匹配。其实，解决方向：- 使用--root-path 参数或在 app 初始化中设置 root_path="/api"；- 确认 nginx location 后面的 proxy_pass 中最终有斜杠，而且两边保持一致。


 日志中客户端IP 全部显示为 nginx 内网IP
原因：未读取 X‑Forwarded‐For；或者应用未信任此 header。解决方向：- 在 nginx 中加入 `proxy_set_header X-forward-for …`，- 在启动参数中开启 `--forwardable-Allow-Ips` 并指定可信 IP；


d) 本地调试时代理 header 看起来没生效。原因：Traefik 与 nginx 行为略有差异；官方文档提供专门章节演示如何在本地测试。解决方向：- 阅读官方“Behind a Proxy”章节中的 Traefik 示例；- 若使用 Traefik，请确保其配置了 `extra_hosts` 或 `headers` 部分以传递正确 header。