Docker环境下Nginx+FastAPI中X-Real-IP/X-Forwarded-For无法返回真实IP求助

问题根源 #

本地运行Docker容器时，默认采用bridge网络模式，请求从宿主机发往容器会经过Docker网桥网关（即你看到的192.xxx.xxx.1），因此Nginx的$remote_addr会被设为网关IP，而非真实客户端IP。

解决方案 #

方案1：使用Docker Host网络模式（本地测试推荐） #

让容器直接复用宿主机的网络栈，这样Nginx能直接获取到宿主机/客户端的真实IP：

• 用docker run启动容器时添加参数：--network host
• 若用docker-compose，配置如下：

services:
  nginx:
    network_mode: host
  fastapi:
    network_mode: host

注：此模式无需端口映射，容器直接使用宿主机端口，需避免端口冲突。

方案2：配置Nginx RealIP模块（bridge网络模式适用） #

1. 先确认Nginx已安装ngx_http_realip_module模块，执行nginx -V查看输出，确保包含--with-http_realip_module。
2. 在Nginx的http块或对应server块中添加以下配置，指定Docker网桥IP段为可信代理：

# 替换为你的Docker网桥实际IP段，比如192.168.0.0/16或172.17.0.0/16
set_real_ip_from 192.xxx.0.0/16;
set_real_ip_from 172.17.0.0/16;
real_ip_header X-Forwarded-For;
real_ip_recursive on;

3. 重启Nginx容器使配置生效。

方案3：确保FastAPI/Uvicorn的代理头配置正确 #

• 启动Uvicorn时添加--proxy-headers参数：

uvicorn main:app --host 0.0.0.0 --port 8000 --proxy-headers

• 或在代码中添加中间件时指定可信代理IP段：

from fastapi import FastAPI
from fastapi.middleware.proxy_headers import ProxyHeadersMiddleware

app = FastAPI()

# 添加Docker网桥IP段作为可信代理
app.add_middleware(ProxyHeadersMiddleware, trusted_proxies=["192.xxx.0.0/16", "172.17.0.0/16"])

验证方法 #

在FastAPI中添加测试接口，查看返回的IP信息：

from fastapi import Request, FastAPI

app = FastAPI()

@app.get("/ip")
async def get_client_ip(request: Request):
    return {
        "client_ip": request.client.host,
        "X-Real-IP": request.headers.get("X-Real-IP"),
        "X-Forwarded-For": request.headers.get("X-Forwarded-For")
    }

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