WorkbuddyIP 白名单在 API 调用里怎么配置，应该填服务器公网 IP 还是 CIDR 网段？

WorkbuddyIP 白名单在 API 调用里配置的核心动作，是在 WorkbuddyIP 控制台找到对应 API 密钥的安全设置，把调用方的公网出口 IP 或 CIDR 网段加入允许列表并保存；保存后只有来源地址命中白名单的请求才能用该密钥调用，未命中的请求通常返回 401 或 403。它不适用于出口 IP 每天变化的家用宽带、默认不固定出口的 Serverless 函数，除非先把出口地址固定下来。 白名单是网络层校验，和 API Key 鉴权是两道独立闸门。WorkbuddyIP 先看请求来自哪个源 IP，再看密钥是否有效、额度是否足够；因此白名单不能代替密钥保密，密钥泄露但攻击者不在白名单内仍可能被挡，反过来白名单内的主机被入侵也会被利用。配置时要把这两个边界分开看。 配置前必须先确认调用方的真实公网出口 IP，而不是服务器内网 IP 或本机 127.0.0.1。做法是从实际发起 API 调用的机器上，通过公网回显服务或云厂商控制台的弹性公网 IP 页面查看出口地址，再复制到 WorkbuddyIP 白名单。若经过 NAT 网关、负载均衡、容器出网，填的应该是最终访问 WorkbuddyIP 的那个出口地址。 填写格式上，单个地址写点分十进制 IPv4，连续网段写 CIDR，例如单个 IP 用 /32，连续网段用类似 198.51.100.0/24 的写法；多个地址用逗号或换行分隔。能精确到单个 IP 时不要为了省事填 0.0.0.0/0，因为那等于关闭来源限制。若调用方使用 IPv6，要先确认 WorkbuddyIP 当前密钥是否支持 IPv6 白名单，不支持时需通过 IPv4 出口代理转发。 白名单保存后通常秒级到分钟级生效，但已有长连接、连接池或网关缓存可能继续沿用旧状态。改完配置后不要只看旧连接是否报错，而应新开一次 API 调用测试，并分别记录成功响应与 401、403 的差异。401 多与密钥无效或缺失有关，403 更常见于来源 IP 未命中白名单，可据此缩小排查范围。 经过反向代理或 CDN 回源时，WorkbuddyIP 看到的是 TCP 层的源 IP，不是请求头里的 X-Forwarded-For。也就是说，在请求头里手写 X-Forwarded-For 不会让白名单放行，把代理服务器的出口 IP 加进去才是正确做法。若架构里有多层代理，要逐层确认最后一跳访问 WorkbuddyIP 的地址。 云函数、容器平台和 CI/CD 默认出口地址经常不固定，这是白名单配置失败的高发场景。部分函数计算、容器平台、持续集成环境，如果没有绑定固定公网 IP 或 NAT 网关，每次调用的出口地址都可能变化。解决方式是为这些环境配置固定出口，例如绑定弹性 IP 的 NAT 网关、静态代理或自建转发网关，再把固定地址加入 WorkbuddyIP 白名单。 多环境共用密钥会让白名单边界变得模糊，正确做法是按开发、测试、生产分别创建 API 密钥并绑定不同白名单。开发机 IP 变动频繁，可以只允许办公网固定出口；生产环境则只允许业务服务器的固定出口，不把个人电脑和临时测试机混进去。这样即使某个环境的密钥外泄，影响范围也被限制在对应来源内。 白名单不是万能防护，它主要降低密钥被盗后从陌生 IP 直接调用的风险。内网横向移动、SSRF 漏洞、被入侵的白名单主机、代理服务被滥用，都可能绕过来源限制。因此还要配合密钥轮换、最小权限、调用额度限制和审计日志，把异常来源、异常频率、异常模型调用记录下来，定期回看。 排查 WorkbuddyIP 白名单问题时，可以按来源地址、密钥、协议、时间四个维度核对。先确认调用方出口 IP 是否与白名单完全一致，再确认请求是否走了代理或 VPN，然后检查 IPv4 与 IPv6 是否混用，最后确认配置保存后是否等过了生效时间。若仍然失败，用同一密钥从白名单内机器和外部机器各调一次，对比结果就能定位是来源问题还是密钥问题。 对于出口 IP 无法固定的个人开发者或临时环境，不建议直接关闭白名单，而应增加一个固定出口的轻量网关。把 API 调用统一收口到该网关，由网关持有密钥并绑定白名单，本地只访问网关；这样既保留来源限制，又避免每次 IP 变化都要改配置。是否采用该方案，取决于调用频率、安全要求和运维成本，若只是偶发测试可短期使用临时白名单，以官方说明为准。 总结起来，WorkbuddyIP 白名单配置的关键不是代码，而是控制台里对公网出口地址的准确登记。先固定出口，再填 IP 或 CIDR，最后用新连接验证生效，并配合密钥分环境管理，才能让 API 调用既稳定又不把安全边界放得太宽。动态 IP 环境若不先解决出口固定问题，白名单会表现为时好时坏，而不是持续拦截。