如何在豆包控制台配置API白名单IP？

功能定位：为什么必须配置白名单

豆包开放平台的 API 按量计费，一旦 AppKey 泄露，攻击者可在数小时内刷空额度。白名单 IP 是最低成本的第一道闸门，它告诉平台「只认这些地址发来的请求」，把扫号、撞库、误调用挡在门外。

与「Token 限频」「HTTPS 强制」相比，白名单属于「网络层准入」，在 TCP 三次握手后就丢弃非法流量，不消耗业务算力，也不会触发计费。经验性观察：开启后异常调用量平均下降 90% 以上，且控制台告警条数同步减少。

功能定位：为什么必须配置白名单

前置检查：拿到真正的出口 IP

很多运维第一次配置就踩坑：把办公网 192.168.x.x 填进去，结果本地调试全 403。白名单只认「公网出口 IP」。先确认出口，再动手，能省来回改表的麻烦。

1. 服务器环境：在目标机器执行 curl ifconfig.me 或 curl ipinfo.io/ip，取返回值。
2. 本地开发：先让运维在网关做 SNAT 映射，再把映射后的固定 EIP 加入名单；否则每次拨号 IP 一变就断连。
3. 容器集群：若使用 Serverless 弹性 Pod，需把 NAT 网关的弹性 IP 段整体加入，并设置最小存活实例数，防止 Pod 重建后出口漂移。

示例：某团队把测试集群迁到 ACK Serverless，未绑定 NAT 网关，结果 Pod 一弹性伸缩就换出口，白名单瞬间失效。绑定 EIP 并整段加白后，问题消失。

控制台路径：三步完成绑定

以下路径基于豆包开放平台控制台 2026-03 界面，若后续改版，请在顶部搜索框输入「API 白名单」快速跳转。

桌面端完整路径

1. 登录 console.doubao.com → 右上角切换至「企业/团队账号」。
2. 左侧导航【开放能力】>【API 管理】>【安全设置】，找到「IP 白名单」卡片。
3. 点击「添加规则」→ 输入单 IP（如 203.0.113.42）或 CIDR（如 203.0.113.0/24）→ 选择生效范围（通用 Key 或指定 Key）→ 保存；系统提示「约 30 秒内生效」。

移动端应急操作

Android/iOS 豆包 App 暂不支持直接编辑白名单，但可打开「工作台」→「智能体管理」→右上角「…」→「API 监控」，查看实时错误码。若发现 403 激增，立即用浏览器访问桌面版控制台完成加白。

常见分支：多 Key 与多环境如何取舍

企业通常区分「测试 Key」「预发 Key」「线上 Key」。控制台允许「一条白名单绑定多 Key」，也支持「一条 Key 受多条白名单约束」。规则灵活，但越灵活越需要约定。

• 若三套环境共用同一出口 EIP，建议把 CIDR 段维护在「通用规则」里，减少重复条目。
• 若线上 Key 需要随时切换出口（例如灾备），可启用「备用 IP 组」功能：先在「高级设置」里创建命名组，再把组关联到 Key；主 IP 故障时，在组内顺序下移即可，免改 Key。

警告：白名单与「Key 级频控」是「且」关系，不是「或」。一旦 IP 正确但频控超限，仍返回 429；排查时别误判为白名单失效。

验证与观测：确保真的生效

保存后 30 秒，用未列入白名单的跳板机执行：

curl -X POST https://api.doubao.com/v1/chat \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{"msg":"ping"}' -v

预期返回 403 Forbidden，且 Response Header 带 x-reject-reason: ip_not_whitelist。同一出口再换已白名单的机器，应返回 200。若仍 403，检查公司层防火墙是否把出口 NAT 到别的地址。

验证与观测：确保真的生效

回退方案：误把自己锁门外怎么办

控制台本身走独立 SSO 域名，不受 API 白名单限制。真出现「全员 IP 填错」导致无法登录，可用以下通道：

1. 主账号在「安全设置」页面底部点击「紧急回退」，输入 MFA 后会生成一次性 Emergency Token，10 分钟内可临时清空所有白名单。
2. 若主账号也失联，提交工单时勾选「IP 白名单误封」，上传营业执照与法人身份证，官方人工审核约 30 分钟临时放行。

与智能体分身的联动：最小权限原则

很多运营把「分身 Bot」发布到抖音直播间，需要回调地址接收观众提问。此时回调服务器也必须加入白名单，否则直播互动会显示「请求失败」。

建议流程：先在「智能体管理」>【API 动作】>「回调配置」里记下域名，再 nslookup 拿到 EIP，按上文步骤加入名单；若域名解析到 CDN，需把 CDN 回源段也一并加白，或改用固定源站 EIP。

不适用场景：白名单不是万能锁

• 客户端直调：App 端把 Key 硬编码到 APK，再靠白名单保护，等于把锁匙放在门口。此种场景应改用「短期 STS」或「服务端签名校验」。
• 动态家庭宽带：个人开发者 IP 每天变，白名单维护成本高，不如启用「Key 级日限额+异常告警」。
• IPv6 双栈：豆包当前仅支持 IPv4 白名单，若服务器默认走 v6，需要关闭 v6 或强制 v4 出口，否则请求直接被丢包。

最佳实践 10 条速查表

1. 永远用 CIDR 而非单 IP，给弹性伸缩留余量。
2. 把 NAT 网关 EIP 与业务域名解耦，方便灾备切换。
3. 测试环境与线上环境分 Key，不共用白名单组。
4. 每次变更先在「预览」里核对受影响 Key 数，确认无误再保存。
5. 把白名单变更事件接入飞书群机器人，方便审计。
6. 每季度跑一次 whois，确认加白的网段仍归属本公司。
7. 出现 403 先看 x-reject-reason，再查白名单，避免盲改。
8. 不要把办公 privacy tool 出口段加入线上 Key，防止员工电脑中木马后直调 API。
9. 与财务对齐：额度告警阈值 ≤ 预算 80%，白名单只是降低误刷，不是限费。
10. 保留一条「运维跳板机」独立 IP，作为救命通道。

故障排查 FAQ（FAQPage Schema）

收尾：下一步行动清单

配置白名单只需 3 分钟，却能挡住 90% 的误调用。读完本文，你可以立刻：

1. 用 curl 确认真实出口 IP；
2. 登录豆包控制台，把 EIP 写成 /28 或 /24 段加入白名单；
3. 在跳板机与生产机分别验证 403→200 的切换；
4. 把变更事件推送到飞书群，完成审计闭环。

完成以上四步后，再把「额度告警」调到预算 80%，你就拥有了一套「网络层+业务层」双保险。API 安全没有银弹，但白名单是最便宜的那把锁——先锁门，再谈别的。