apisix透传客户端真实IP（real-ip插件）

apisix透传客户端真实IP

需求和背景

当 APISIX 前端有其他反向代理（如 Nginx、HAProxy、云厂商的 LB）时，如何正确获取到真实的客户端 IP 地址。

默认情况下，APISIX 会将直接连接到它的那个代理服务器的 IP 视为客户端 IP ($remote_addr)。但真实的客户端 IP 通常被放在 X-Forwarded-For (XFF) 请求头中。

当 APISIX 位于反向代理（如负载均衡器、CDN）之后时，客户端的真实 IP 会被代理服务器的 IP 覆盖（例如，APISIX 看到的 remote_addr 是负载均衡器的 IP，而非用户的真实 IP）。

k8s 集群入口一般都需要过负载均衡，然后再到 apisix。
这时如果后台业务需要获取客户端 ip，可能拿到的是 lb 或者相关的内网 ip。

这里一般要获取真实 ip 需要做几个处理。

1. 负载均衡上，一般支持配置获取真实 ip 参数，需要配置上。然后 lb 会把客户真实 ip 写入 x-forwarded-for 参数。
2. apisix 上配置 real-ip 插件。作用和 nginx 的 realip 插件相同。

apisix real-ip插件

官方文档: https://apisix.apache.org/zh/docs/apisix/plugins/real-ip/

real-ip 插件是 Apache APISIX 的一个功能模块，用于通过 HTTP 请求头或查询字符串中的 IP 地址设置客户端的真实 IP，特别适用于 APISIX 位于反向代理后的场景。该插件类似于 NGINX 的 ngx_http_realip_module，但提供了更多灵活性，支持从 URI 参数、请求头或多层代理中获取真实 IP，并可通过配置可信地址和递归选项来精确控制 IP 替换逻辑。

• 插件支持从 URI 参数（如 arg_realip）或请求头（如 X-Forwarded-For）中提取真实 IP。
• 可配置 trusted_addresses 指定可信代理 IP 范围（支持 CIDR 表示法）：
  • 只有请求的 remote_addr（直接连接的客户端 IP）在 trusted_addresses 列表中时，插件才会处理 IP 替换。
  • 避免恶意用户伪造 X-Forwarded-For 头篡改 IP，确保只有可信代理的请求能触发 IP 替换。
  • 确保只有受信任的代理（如负载均衡器、CDN）能触发 IP 替换，防止伪造攻击。
  • 不配置 trusted_addresses 或留空会完全禁用 IP 替换功能。
  • 支持单个 IP、CIDR 范围或多层代理递归处理

为什么需要 trusted_addresses？

在 Apache APISIX 的官方文档中，trusted_addresses 是 real-ip 插件的一个可选参数

当 APISIX 位于反向代理（如负载均衡器、CDN）之后时，客户端的真实 IP 会被代理服务器的 IP 覆盖（例如，APISIX 看到的 remote_addr 是负载均衡器的 IP，而非用户的真实 IP）。为了解决这个问题，代理服务器通常会在请求头（如 X-Forwarded-For）中附加用户的真实 IP。

风险：如果任何客户端都能直接访问 APISIX，并随意伪造 X-Forwarded-For 头，恶意用户可以通过篡改该头字段伪装成任意 IP，绕过安全策略（如 IP 黑名单或速率限制）。

攻击场景（无 trusted_addresses）
恶意用户直接访问 APISIX，伪造请求头

GET /api/data HTTP/1.1
Host: apisix.example.com
X-Forwarded-For: 6.6.6.6  # 伪造的 IP

APISIX 错误地将客户端 IP 识别为 6.6.6.6（实际是恶意用户的真实 IP）。

防御机制（启用 trusted_addresses）

1. 配置只信任负载均衡器的 IP（如 203.0.113.10）

"trusted_addresses": ["203.0.113.10"]

2. 只有通过负载均衡器的请求才会触发 IP 替换：
   负载均衡器转发请求时，remote_addr 是 203.0.113.10（可信）。
   插件读取 X-Forwarded-For 中的真实用户 IP（如 1.2.3.4）。

在理想的生产环境部署中，APISIX 的 IP 确实不应该直接暴露在公网，而是应该隐藏在反向代理（如负载均衡器、CDN、API 网关）之后，并通过安全组/防火墙严格限制访问来源。

因此，感觉这个配置不是很需要。APISIX 原本设计为内网服务，但被错误地绑定到公网 IP 或未启用认证。

防止内部威胁：

• 攻击者可能通过内网横向移动（如入侵其他服务器后访问 APISIX）。
• 恶意内部人员可能直接发送伪造请求。

安全架构的最佳实践

1. 网络层隔离
   仅允许代理 IP 访问 APISIX：

# 示例：AWS Security Group 规则
允许入站 80/443 → 源IP: 负载均衡器（203.0.113.10）
拒绝其他所有流量

禁用公网绑定

# APISIX 配置中仅监听内网
listen 192.168.1.100:9080;

2. 应用层防御（trusted_addresses）

{"real-ip": {"source": "header","header": "X-Forwarded-For","trusted_addresses": ["203.0.113.10", "192.168.1.0/24"]}
}

3. 监控与告警
   检测异常请求（如直接访问 APISIX 的非代理 IP）。
   定期审计防火墙和代理配置。

总结
1…“APISIX 不暴露”是目标，但 trusted_addresses 是最后一道防线。
2. 安全 = 预防 + 检测 + 容错：即使你相信网络层万无一失，应用层仍需冗余保护。
3. 类比：就像你家有门锁（防火墙），但保险箱（trusted_addresses）仍需要密码。

示例场景

假设你的架构如下：

用户 → 负载均衡器（IP: 203.0.113.10） → APISIX（IP: 192.168.1.100） → 后端服务

负载均衡器会将用户真实 IP 放在 X-Forwarded-For 头中，例如：X-Forwarded-For: 1.2.3.4

配置 real-ip 插件

为了让 APISIX 信任负载均衡器的 IP（203.0.113.10），并替换客户端 IP 为 X-Forwarded-For 中的值（1.2.3.4），配置如下：

{"plugins": {"real-ip": {"source": "header",           // 从请求头获取 IP"header": "X-Forwarded-For",   // 指定头字段"trusted_addresses": ["203.0.113.10/32"]  // 只信任负载均衡器的 IP}}
}

递归查找（多层代理）
如果 X-Forwarded-For 包含多个 IP（如 1.2.3.4, 203.0.113.10），启用 recursive 会从右向左找到第一个非可信 IP：

{"source": "header","header": "X-Forwarded-For","trusted_addresses": ["203.0.113.10"],"recursive": true  // 递归查找
}

结果：客户端 IP 替换为 1.2.3.4（跳过可信的 203.0.113.10）。

apisix界面配置

• source指，写入那个参数，一般是http_x_forwarded_for。
• trusted_addresses指，set_real_ip_from，一般需要设置的内网ip地址。比如lb的内网地址，或者有内网转发的话，集群内网的ip地址。