如何通过Nginx反向代理将客户端IP传递给FastAPI

你的Nginx配置已经正确设置了X-Real-IP和X-Forwarded-For头，但FastAPI默认不会自动解析这些头来替换客户端IP——因为它不知道自己运行在反向代理之后。需要给FastAPI添加ForwardedHeadersMiddleware中间件来实现这个功能。

步骤1：添加FastAPI中间件 #

在你的FastAPI项目中，导入并添加ForwardedHeadersMiddleware，同时指定可信的代理IP（即Nginx所在的IP或网段）：

from fastapi import FastAPI, Request, Response
from starlette.middleware.forwarded import ForwardedHeadersMiddleware
# 保留你已有的CORS中间件导入
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# 先配置你的CORS中间件（示例）
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # 根据实际需求调整
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# 添加ForwardedHeadersMiddleware，指定可信代理
app.add_middleware(
    ForwardedHeadersMiddleware,
    # 这里替换为你的Nginx所在IP/网段，比如本地部署用127.0.0.1，Docker容器常用172.17.0.0/16
    trusted_proxies=["127.0.0.1", "172.17.0.0/16"]
)

# 你的原有端点代码无需修改
@app.post('/api/example')
def send_order(data: SomeDataType, request: Request, response: Response):
    print(request.client.host)  # 现在会输出真实客户端IP

关键说明 #

• ForwardedHeadersMiddleware会从可信代理发来的请求中，解析X-Forwarded-For、X-Forwarded-Proto等头，自动更新request.client的信息，让request.client.host返回真实客户端IP。
• trusted_proxies必须设置为Nginx的IP或所在网段，避免恶意请求伪造X-Forwarded-For头进行攻击。如果Nginx和FastAPI在同一服务器，填127.0.0.1；如果是Docker环境，通常容器内网网段是172.17.0.0/16，可以根据实际情况调整。
• 你的Nginx配置已经正确，无需修改——proxy_add_x_forwarded_for会将客户端IP追加到请求头中，X-Real-IP则直接记录客户端IP。

验证 #

重启FastAPI和Nginx服务后，发送请求测试，request.client.host应该显示真实的客户端公网IP，而非Nginx的本地内网IP。

内容的提问来源于stack exchange，提问作者user2138149