> ## Documentation Index
> Fetch the complete documentation index at: https://docs.li.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# API 密钥安全

符合条件的服务端及企业级集成可以向 LI.FI 团队申请两项额外控制：**IP 白名单**（按密钥）和 **专用实例锁定**（按后端实例）。它们是 [速率限制和 API 认证](/zh-hans-api-reference/rate-limits) 中客户端暴露防范指南之外的补充。

具体可用性和配置方式需要逐案确认。这些控制不能替代对密钥的保密、使用监控，以及在怀疑泄露时轮换密钥。

# IP 白名单

一个 API 密钥可以绑定到一份来源 IP 地址白名单。绑定是**按密钥**的，不是按集成方一次性生效。

* 条目可以是 IPv4 或 IPv6 地址，或 CIDR 网段。单独填写一个地址时，按单主机处理（IPv4 为 `/32`，IPv6 为 `/128`）。
* 只有携带 `x-lifi-api-key` 请求头的请求才会进行 IP 白名单校验。其他认证规则或实例级控制仍可能拒绝未带该请求头的请求。
* 当 LI.FI 能够确定调用方 IP 时，使用已限制密钥的请求只有在该 IP 落在白名单网段内才会被接受。来自其他来源的请求**即使密钥值正确也会被拒绝**。
* 被拒绝的请求返回 HTTP `403`，响应体为 `{ "message": "Forbidden" }`。这不是 LI.FI 常规错误信封（没有 `code` 字段）。无效密钥仍然返回 `401`。
* 如果 LI.FI 无法确定调用方 IP，此项控制不会拦截该请求。它适合作为出口 IP 固定且较少的服务端集成（例如固定的一组后端主机或 NAT 网关）的纵深防御，不能保证被盗密钥在所有网络上都无法使用。
* 由于密钥校验结果可能被缓存，白名单变更不一定立即生效。在依赖新策略之前，请先确认它已经生效。若怀疑密钥泄露，应轮换密钥；不要只靠收紧白名单来立刻切断访问。

# 专用实例锁定

对于有更严格隔离需求的集成，LI.FI 可以提供一台专用后端实例，将常规 API 流量限制为仅接受指定的集成方 ID 和/或 API 密钥。

* 这是**实例级**的部署控制，与按密钥的 IP 白名单互补。
* 在已锁定的实例上，使用未列入该实例允许名单的密钥发起的已认证请求会收到 HTTP `401 Unauthorized`，即使该密钥在共享的 LI.FI API 上仍然有效。
* 具体主机名、拓扑以及允许哪些集成方 ID 和/或 API 密钥，需要逐案约定。不要假定存在统一的专用实例契约。

# 如何配置

目前这两项控制都不是合作伙伴门户中的自助式设置。请联系 LI.FI 团队确认可用性并安排配置，可以作为入驻流程的一部分，也可以作为对现有集成的后续加固步骤。

<Card title="联系 LI.FI 团队" icon="envelope" href="https://li.fi/contact-us/">
  若需 IP 白名单，请通过团队提供的安全流程标明要限制哪些密钥，并提供允许的 IPv4/IPv6 地址或 CIDR 网段。若需专用实例，请说明必须放行哪些集成方 ID 和/或 API 密钥。切勿在不安全的支持消息中发送 API 密钥的 secret 值。
</Card>

# 上线检查清单

* 让服务端 API 流量通过少量且稳定的出口 IP，例如 NAT 网关。
* 变更网络时，先添加并验证新网段，再移除旧网段。
* 完成上线前，分别从白名单内和白名单外的来源进行测试。
* 怀疑密钥泄露时，即使同时更新了白名单，也应轮换密钥。

# 相关内容

<Note>请参阅 [速率限制和 API 认证](/zh-hans-api-reference/rate-limits) 了解 `x-lifi-api-key` 请求头的工作方式，以及为何绝不应在客户端暴露你的密钥。</Note>