跳到主要内容

Remote Addr （客户侧 IP）

在输出请求日志时，会包含 remote_addr 字段，该字段记录了请求的来源地址。

Aidy 通常部署在反向代理之后，因此默认 remote_addr 字段记录的 IP 地址可能并不是真实的来源地址，需要进行配置提取规则。

备注

该地址始终提取的是外部用户连接 Aidy 的 IP 地址，而非业务等需要的「用户侧 IP」，因此相关配置仅支持在静态配置中配置。

警告

提取到的 IP 地址根据实际情况可能是 IPv4 或 IPv6 地址，请做好兼容。

IP 提取来源​

目前支持以下三种 IP 提取来源：

  • connecting_ip：连接 Aidy 的 IP 地址（默认，但通常不会使用）
  • header：某一特定 header 的值
  • xff：X-Forwarded-For 头部的 IP 地址（取第 X 个）

配置示例​

[plugins.log.remote_addr]
source = "connecting_ip" # or header or xff
header = "X-Real-IP" # 当 source=header 时取哪个 Header 的值
xff = 1 # 当 source=xff 时取第几个 IP

Connecting IP​

直接提取连接 Aidy 的 IP 地址，该策略为默认策略（尽管不常用），无需任何配置。

提取某一特定 header 的值，该策略通常用于在反向代理后部署时，提取反向代理的 IP 地址。

当使用该策略时，需要指定 header 字段，该字段指定提取的 header 的名称。提取后将校验其是否为合法的 IPv4/IPv6 字符串：

  • 若 header 缺失或值为空，则 remote_addr 为 "<not_found>"；
  • 若不是合法 IP，则 remote_addr 为 "<invalid>"（若包含端口将被忽略）。

XFF​

提取 X-Forwarded-For 头部的 IP 地址，该策略通常用于在反向代理后部署时，提取反向代理的 IP 地址。

因为 XFF 头部可能包含多个 IP 地址，因此需要指定 xff 字段（必填），该字段指定提取的 IP 地址的索引；索引支持正数与负数，正数表示从左往右数第 X 个 IP 地址，负数表示从右往左数第 X 个 IP 地址。提取逻辑：

  • 若 X-Forwarded-For 头部缺失或解析后列表为空，则 remote_addr 为 "<not_found>"；
  • 若指定索引超出范围，则 remote_addr 为 "<not_found>"；
  • 若命中但不是合法 IP，则 remote_addr 为 "<invalid>"（若包含端口将被忽略）。

错误与特殊值​

  • <not_found>：未能获取到目标值，例如目标 header 缺失/为空，或 X-Forwarded-For 缺失/索引越界。
  • <invalid>：拿到了字符串，但不是合法的 IPv4/IPv6（会忽略端口，再进行合法性校验）。

例： X-Forwarded-For 的值为 X-Forwarded-For: 192.168.1.1, 192.168.1.2, 192.168.1.3，则 xff = 1 表示提取 192.168.1.1、xff = -1 表示提取 192.168.1.3。