Workbuddy 的 IP 白名单在 API 调用里怎么配置？出网 IP、CIDR 网段与代理转发该先确认哪一项？

Workbuddy 的 IP 白名单要在调用方的出网地址固定之后再配置：先在控制台找到对应 API Key 的白名单入口，把服务器或 NAT 网关的出口 IP、CIDR 网段写入并保存，未列入的地址发起调用会被拒绝；本机公网 IP、请求头里携带的客户端地址都不算数，具体入口位置与字段名称以官方文档为准。顺序反了就会反复出现「配置了还是不通」的情况，因为改的是错误的地址。 白名单校验的是 Workbuddy 服务端看到的对端源地址，也就是请求链路上最外层那一跳的 IP，而不是 X-Forwarded-For 头里写的客户端 IP。请求如果经过 NAT 网关、反向代理、CDN 或企业出口防火墙，做源地址转换的是这些设备，最终到达平台的只有它们的出网地址。因此先要确认调用链路里有几层转发，再决定往白名单里填哪一段地址，否则填业务服务器的内网 IP 一定无效。 确认出口地址最直接的办法是在调用机上执行一次查询自身公网 IP 的请求，得到的返回值就是平台侧看到的源地址；容器和代理环境要在宿主或网关侧查，不能在业务容器里查。记录时要连协议栈一起记，IPv4 与 IPv6 是两套地址，双栈环境下只加 IPv4 会导致部分请求被拒。可以把结果写进部署文档，作为后续变更的基线。 白名单的粒度用 CIDR 表达，单个固定公网地址填 /32 最安全，只有整段地址确实归属自己时才用更大的网段。云主机共享地址池、办公网共用出口这类场景，整段放行等于把白名单放开给同网段的其他用户，风险与不加白名单接近。原则是能精确到单个地址就不放大到网段，必须放大时要配合配额限制与用量告警一起使用。 配置顺序建议是先加后删：把新地址加入白名单并保存，用新地址发起一次真实调用确认成功，再移除旧地址。反过来先删后加会有一段请求全部失败的窗口，对生产流量来说就是一次人为故障。多地址并存期间可以观察日志里各地址的调用量，确认流量已经迁移干净再收口，这比凭印象删除可靠。 容器与 Serverless 环境的出口地址默认不固定，Pod 重建、函数扩容都可能换地址，直接把临时地址写进白名单会周期性失效。可行做法是让出网流量统一走 NAT 网关或专用出口代理，把网关的地址加入白名单；不具备固定出口条件时，改用独立 Key 加额度控制，而不是频繁改白名单。这一点在弹性扩缩容的业务上尤其明显。 测试、生产、持续集成要各用各的 Key，各自维护白名单，不要把生产 Key 借给本地调试。共用 Key 的结果是白名单被迫放大到办公网甚至家庭宽带，等于把生产凭证的可调用来源扩散到不可控范围。拆开之后，CI 环境可以只放行构建机的出口地址，本地调试用一个低额度 Key，出问题时影响范围也可控。 排错时先分清状态码含义：401 一般是凭证无效或缺失，403 更可能是来源地址不在白名单或权限不足，两者处理路径完全不同。看到 403 不要急着重发请求，先取响应里的请求标识去查平台侧记录，再比对调用方实际出口地址与白名单里写的是否一致。很多所谓「白名单不生效」其实是走了另一条出口线路。 白名单只收窄可用来源，不能替代鉴权与配额管理，Key 仍然要定期轮换、设置用量上限并开启异常告警。地址限制解决的是「谁能用这把 Key」，解决不了「Key 泄露后怎么止损」。两者叠加才有意义：白名单把可用范围压到几台机器，配额和告警负责在异常放量时第一时间发现，轮换负责在泄露后切断旧凭证。 有几类场景不适合硬性绑定固定白名单：本地开发调试、临时外包协作、移动办公与动态宽带接入。这些环境出口地址随时变化，硬绑会不断打断工作。可行做法是单独签发一个额度受限的 Key，在平台支持的前提下临时加白并在任务结束后立即删除，同时把这类 Key 的调用单独打标签，便于事后审计。 上线前至少做两条验证用例：在白名单内的机器调用应返回成功，在白名单外的机器调用应被明确拒绝并给出可读的错误信息。只测通过路径不测拒绝路径，等于没有验证白名单是否真的生效，配置写错网段或写成内网地址都不会被发现。两条用例都跑通，再把这套检查加入发布清单。 日常维护要盯住地址变更：运营商动态地址、办公网出口切换、云上网关重建都会让旧白名单失效。把出口地址当作配置项纳入变更管理，迁移前先把新地址加入、观察通过后再移除旧地址，并在变更记录里写清时间与影响范围。这样即使半年后有人问起某个地址为什么在白名单里，也能查到依据。