需在网络链路各环节协同配置：反向代理透传X-Forwarded-For头，应用启用信任代理机制，必要时调整Docker网络模式，并逐层验证。
在 Docker 容器中，应用常只能拿到反向代理（如 Nginx、Traefik、Cloudflare）或负载均衡器的 IP，而非用户真实 IP。根本原因在于：容器网络默认经过多层转发，原始 TCP 连接的源 IP 在到达应用时已被覆盖为上一跳地址（如宿主机或代理 IP）。要还原真实 IP，需在**网络链路各环节协同配置**，而非仅改应用代码。
确保反向代理正确透传 X-Forwarded-For
这是最常见也是最关键的一步。如果前端是 Nginx、Apache 或 Traefik，必须显式配置其将客户端真实 IP 注入 HTTP 请求头。
- Nginx 示例（在 server 或 location 块中）：
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; - Traefik v2+ 默认已透传，但需确认中间件未覆盖；若用 IngressRoute，请检查 entryPoints 中是否启用 forwardedHeaders。
- 使用 Cloudflare 时，务必开启 “Always Use HTTPS” 并在源站 Nginx 中信任 Cloudflare 的 IP 段（通过 set_real_ip_from），否则 $remote_addr 会被误判为 CF 节点 IP。
容器内应用需主动读取 X-Forwarded-For 头
Docker 容器本身不自动解析代理头，应用必须明确启用“信任代理”机制，否则框架（如 Express、Spring Boot、Django）会忽略 X-Forwarded-* 头，仍返回 172.x 或 127.0.0.1。
- Node.js（Express）：
app.set('trust proxy', true); // 或指定可信代理网段，如 '172.16.0.0/12' - Spring Boot：
server.forward-headers-strategy=framework（推荐）
或显式配置：
server.tomcat.remote-ip-header=x-forwarded-for
server.tomcat.protocol-header=x-forwarded-proto
server.tomcat.internal-proxies=172\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|10\.\d{1,3}\.\d{1,3}\.\d{1,3} - Python（Flask）：
from werkzeug.middleware.proxy_fix import ProxyFix
app.wsgi_app = ProxyFix(app.wsgi_app, x_for=1, x_proto=1)
避免 Docker 网络层掩盖原始 IP（可选但重要）
当容器直接暴露端口（如 -p 8080:80）且无外部代理时，$remote_addr 应为真实客户端 IP。但若使用默认 bridge 网络 + NAT，部分场景下可能被宿主机 iptables 修改。此时可考虑：
- 改用 host 网络模式（docker run --network host）：容器共享宿主机网络命名空间，TCP 连接直接可见，$remote_addr 即真实 IP（适合单容器、无端口冲突场景）。
- 启用 IPv6 + SLIRP4NETNS（Podman 场景） 或使用 CNI 插件（如 Calico）配合 HostNetwork，绕过 Docker 默认 NAT。
- 若必须用 bridge 网络，确保宿主机 iptables FORWARD 链未做 SNAT，并在 docker daemon.json 中设置 "iptables": false（需自行管理防火墙，慎用）。
验证与调试方法
不要只信日志，要逐层抓包确认：
- 在代理层（如 Nginx 容器）加日志：
log_format full '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$http_x_forwarded_for"';
查看 $http_x_forwarded_for 是否含多级 IP（如 203.0.113.5, 198.51.100.2）。 - 进入应用容器执行：
curl -H "X-Forwarded-For: 192.0.2.100" http://localhost:3000/ip，测试应用是否解析该头。 - 用 tcpdump 抓容器 eth0 流量：
tcpdump -i eth0 -nn port 80 -A | grep "X-Forwarded-For"，确认请求头确实到达容器。
