客户端 IP 解析

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

准确识别 API 请求中的客户端 IP 地址对于 Apigee 中的某些功能非常重要，包括分析和 Advanced API Security 功能，例如滥用检测和安全操作。

在采用代理和负载均衡器的现代网络架构中，客户端 IP 识别流程非常具有挑战性，因为这些中间方可能会模糊真实的来源 IP 地址。

为克服这一挑战，Apigee 支持一种环境级设置，用于指定如何从 X-Forwarded-For (XFF) 标头解析客户端 IP 地址，从而识别标头中与您的网络拓扑和安全要求匹配的 IP 地址的索引。使用此设置可让您清楚了解、保持一致并控制如何确定环境中所有请求的客户端 IP 地址，并确保在环境中的 Advanced API Security、流变量和分析变量之间保持一致的客户端 IP 地址识别。

如果未按本页面所述配置环境级客户端 IP 解析，则客户端 IP 地址变量会使用默认客户端 IP 地址解析行为进行填充。

默认客户端 IP 地址解析

如果未在环境级配置客户端 IP 解析，则 ax_resolved_client_ip 维度的默认值将如 Analytics 维度所述进行计算。

如果为环境配置了客户端 IP 解析，则流和 Analytics 变量会根据客户端 IP 解析配置进行设置。请参阅为环境设置客户端 IP 解析。

何时为环境设置客户端 IP 解析

虽然无需设置客户端 IP 解析，但如果默认客户端 IP 地址解析无法满足您的需求，并且您希望替换它以提供指定的客户端 IP 地址解析，以便进行 Analytics、Advanced API Security 或执行任何其他需要有关客户端 IP 地址的一致可靠信息的功能，则可能需要设置客户端 IP 解析。

了解客户端 IP 解析配置语法

客户端 IP 解析设置的格式如下：

"clientIpResolutionConfig": {
  "headerIndexAlgorithm": {
     "ipHeaderName" : "X-Forwarded-For",
     "ipHeaderIndex": 2
  }
}
 其中
  • ipHeaderName 是用于客户端 IP 的标头。目前，支持的标头值为 X-Forwarded-For。
  • ipHeaderIndex 是 ipHeaderName 中的索引值。

    正数表示从左侧（添加到标头的第一个地址）开始选择地址，其中最左侧的位置为 0，后续每个地址的索引依次递增 1（例如 0, 1, 2）。 例如，如果列表为 192.0.2.1, 192.0.2.2, 192.0.2.3，则索引 1 会解析为 192.0.2.2。

    负数会选择从右侧（添加到标头的最后一个地址）开始的地址，其中右侧的第一个位置为 -1，后续每个地址的索引递减 1（例如 -3, -2, -1）。 例如，如果列表为 192.0.2.1, 192.0.2.2, 192.0.2.3, 192.0.2.4，则索引 -1 会解析为 192.0.2.4，而索引 -2 会解析为 192.0.2.3。

如需详细了解此设置，请参阅 organizations.environment API。

查看客户端 IP 解析配置

您可以使用 Apigee 界面或 Management API 查看环境的当前客户端 IP 解析配置。

通过界面查看客户端 IP 解析配置

如需使用 Cloud 控制台中的 Apigee 界面查看客户端 IP 解析设置，请依次选择管理 > 环境，选择相应环境，然后在关于标签页中查看客户端 IP 配置。

Apigee 界面中的客户端 IP 解析

使用 API 查看客户端 IP 解析配置

如需使用 Apigee Management API 查看客户端 IP 解析配置，请向 organizations.environments.get API 发送请求。

为环境设置客户端 IP 解析

为环境设置客户端 IP 解析配置后，client.resolved.ip 流变量会使用指定的算法填充。Resolved Client IP Analytics 维度也是如此。

为环境设置客户端 IP 解析配置后，这些更改可能会影响现有安全操作规则的 Advanced API Security 配置。查看现有规则，并根据需要重新生成这些规则，以使用新的变量和设置。

在选择用于解析客户端 IP 的索引时，请注意以下影响：

  • Apigee 到 Apigee 的调用不会作为特殊情况处理。请注意并相应地跳过 IP 数量。
  • 由于 X-Forwarded-For 标头可能会被仿冒，因此最好根据客户端与 Apigee 负载均衡器之间预期的跃点数使用正确的索引。恶意用户可以发送预填充的 X-Forwarded-For 标头。 虽然 XFF 中的第一个 IP 最接近实际的客户端 IP，但鉴于负载均衡器知道连接到它的 TCP 客户端，因此 XFF 中的最后一个 IP 最值得信赖。

如需在环境中设置客户端 IP 解析，请使用某个 Apigee API Management 在 client_ip_resolution_config 中为环境设置客户端 IP 解析。 对于新环境，请使用 organizations.environments.create。对于现有环境，请使用 updateEnvironment 或 modifyEnvironment。

测试客户端 IP 地址解析

保存新的客户端 IP 配置后，您可以按照以下说明进行测试：

  1. 保存新配置设置后，至少等待 5 分钟。
  2. 启动调试会话。启用显示所有 FlowInfo 设置。
  3. 在代理请求流已启动之前检查 FlowInfo。您应该会在该部分看到捕获的已配置客户端 IP 地址。

在 FlowInfo 中查找这些变量：

  • client_ip_resolution.resolved.ip：已解析的客户端 IP 地址。
  • client_ip_resolution.used.fallback：布尔值。除非 Apigee 因无法使用已配置的客户端 IP 解析而回退到默认客户端 IP 解析，否则此值为 false。例如，如果配置的解析指定了标头中不存在的索引。
  • client_ip_resolution.algorithm：用于确定客户端 IP 地址的算法。如果已配置，则为 "HeaderIndexAlgorithm{IpHeaderName:header_name, IpHeaderIndex: $header_index}"。 否则，系统会显示 default。

限制

以下限制适用于环境级客户端 IP 解析：

  • 对客户端 IP 解析配置的更新最多可能需要 5 分钟才能生效。
  • 避免频繁（例如每 5 分钟）更改客户端 IP 解析配置，因为这可能会导致性能下降。
  • 在 Apigee Hybrid 中，设置环境的客户端 IP 解析配置适用于 Hybrid 1.14.0 及更高版本。
  • 您可以通过 Apigee 控制台或 API 查看配置，但只能通过 API 设置配置。
  • 即使没有恶意用户，X-Forwarded-For 列表也依赖于每个代理向该列表添加正确的信息。该完整列表不在 Apigee 的监督和控制范围内，因此设置客户端 IP 解析配置并不能保证识别出正确的请求 IP 地址。