> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 配置 IP 白名单
> 将账户 API Key 的使用限制在已批准的公网 IP 地址范围内。
IP 白名单可限制使用您 YCloud 账户 API Key 发起的请求来源。启用该功能后，YCloud 仅接受来自白名单中 IP 地址的 API 调用。
YCloud 建议所有从已知服务器环境调用 API 的账户都启用 IP 白名单。它增加了一层重要的安全防护：即使 API Key 泄露，来自未获批准 IP 地址的请求也会被拦截。
在启用白名单之前，请添加所有生产、测试、备用以及故障转移环境的出站 IP。如果活跃系统从不在白名单中的地址发送请求，其发起的 YCloud API 调用将会失败。
## 准备工作
请确保：
* 您的角色可以在 YCloud 控制台中访问 **开发者** > **IP 白名单** 。
* 您清楚每个调用 YCloud API 的系统所使用的公网出站 IP 地址。
* 您的基础设施使用的是静态出站 IP 地址，或者您具备在地址发生变更时更新白名单的流程。
* 您已包含可能发送请求的备用网关、NAT 网关、代理以及故障转移环境。
请添加 YCloud 接收到的出站流量公网 IP 地址。切勿添加私网内部地址，例如 `10.0.0.0/8`、`172.16.0.0/12` 或 `192.168.0.0/16` 网段中的地址。
## 添加批准的 IP 地址
1. 登录 [YCloud 控制台](https://www.ycloud.com/console/)。
2. 前往 **开发者** > **IP 白名单**。
3. 点击 **添加白名单 IP**。
4. 输入调用 YCloud API 的系统公网出站 IP 地址。
5. 保存该地址。
6. 对所有生产、测试、备用以及故障转移源重复上述步骤。
列表中会显示每个已批准的 IP 地址及其添加日期。
## 启用 IP 白名单
添加完所有必需地址后：
1. 与您的基础设施或网络团队核对白名单。
2. 开启 **启用 IP 白名单功能**。
3. 从每个预期环境中发送测试请求。
4. 确认定时任务、Webhook 相关服务以及故障转移系统仍能正常调用 YCloud API。
白名单针对的是出站 API 请求的源 IP 地址。如果请求经过 NAT 网关或代理，请添加该网关或代理的公网出站 IP，而不是应用程序的内部 IP。
## 安全更新白名单
基础设施变更可能会改变您的公网出站 IP。请按以下顺序操作以避免服务中断：
1. 将新的公网 IP 地址添加到白名单中。
2. 通过新地址发送测试请求并确保成功。
3. 将生产流量切换至新路由。
4. 确认不再有流量使用旧地址。
5. 从白名单中删除旧 IP 地址。
在依赖某个地址的所有服务完成迁移之前，切勿删除该地址。
## 安全建议
* 即使您的 API Key 存储在密钥管理系统中，也建议启用 IP 白名单。
* 仅向受信任的账户成员授予白名单设置的访问权限。
* 定期审查列表并移除不再使用的地址。
* 在网络或基础设施发生变更后，监控失败的身份验证尝试。
* 如果您怀疑密钥泄露，请立即轮换账户 API Key。参见 [管理 API Key](/zh/documentation/developer/manage-api-keys)。
IP 白名单是对安全使用 API Key 的有效补充；它不能替代密钥轮换、最小权限访问或密钥管理机制。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.