Uvicorn默认不暴露真实IP,因反向代理会覆盖X-Forwarded-For;scope["client"]返回的是代理IP而非用户出口IP,需手动解析X-Forwarded-For头取第一个IP,并配合Nginx正确配置proxy_set_header与可信代理链校验。

Uvicorn 默认不暴露真实 IP,因为反向代理会覆盖 X-Forwarded-For
直接用 scope["client"] 拿到的 IP 是反向代理(比如 Nginx)的地址,不是用户真实出口 IP。Uvicorn 本身不做 IP 解析,它只把底层 socket 的 peer address 塞进 scope["client"] —— 如果你没配 Nginx 或 Cloudflare,那它确实是真实 IP;但只要中间有代理,这里就变成代理机器的内网地址了。
scope["headers"] 里找 X-Forwarded-For 才是常规做法
你需要手动从请求头里提取,并注意几个关键点:
-
X-Forwarded-For是逗号分隔的字符串,最左边是原始客户端 IP,后面是各级代理追加的,例如:"203.0.113.195, 70.41.3.18, 150.172.238.178"→ 真实 IP 是"203.0.113.195" - 必须验证代理链可信,否则攻击者可伪造该 header;只在你明确控制了上游代理(如 Nginx 配了
set_real_ip_from)时才信任 - FastAPI 中推荐封装成依赖函数,避免每个路由都重复解析
示例(FastAPI 场景):
from fastapi import Depends, Request
def get_client_ip(request: Request) -> str:
xff = request.headers.get("x-forwarded-for")
if xff:
return xff.split(",")[0].strip()
return request.client.host or "0.0.0.0"
然后在路由中使用:@app.get("/whoami") → async def whoami(ip: str = Depends(get_client_ip)):
Uvicorn 0.52.1 是 Python ASGI Web 服务器,提供异步应用服务及 WebSocket 支持,常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理所需依赖。
别忽略 Nginx 配置,否则 X-Forwarded-For 是空的
Uvicorn 不生成这个 header,它只读取。如果你用了 Nginx,必须显式配置转发逻辑,否则 header 根本不会传过来:
- 在
location块里加:proxy_set_header X-Forwarded-For $remote_addr; - 更安全的做法是用
real_ip模块(需编译支持),配合set_real_ip_from和real_ip_header X-Forwarded-For;,让 Nginx 把真实 IP 写进$remote_addr,再透传给 Uvicorn - Cloudflare、AWS ALB 等托管负载均衡器默认会设
X-Forwarded-For,但要注意它们也可能加多层,得看实际 header 值
uvicorn --forwarded-allow-ips 参数只影响 scope["client"],不自动解析 header
这个参数常被误解为“启用真实 IP 支持”,其实它只做一件事:当请求来自白名单内的代理 IP 时,Uvicorn 会尝试从 X-Forwarded-For 取第一个 IP 替换掉 scope["client"]。但它不修改或校验 header 内容,也不保证你代码里能直接用 request.client.host 拿到真实值 —— 因为 FastAPI 的 request.client 仍基于原始 scope["client"] 构建,而该字段是否被替换取决于 Uvicorn 启动时是否同时满足两个条件:
- 启用了
--forwarded-allow-ips(如--forwarded-allow-ips="127.0.0.1,10.0.0.0/8") - 且请求的
scope["client"][0](即连接来源 IP)落在白名单内
换句话说:它是个开关,不是解析器。漏配白名单或代理 IP 不在列表里,scope["client"] 就永远是代理地址。
真实 IP 获取这件事,Uvicorn 只提供基础能力,不兜底。最终逻辑得由你控制——从哪取、怎么校验、要不要 fallback,全在应用层。最容易被忽略的是:你以为 Nginx 转发了 header,结果发现它被 upstream 的 proxy_buffering 或其他模块悄悄截断了。

















