Workbuddy 调用 API 时 IP 白名单该配在哪一侧?固定出口 IP、CIDR 网段和代理头分别怎么处理

IP 白名单要配在接收请求的 API 平台控制台或网关上,登记的是 Workbuddy 出站流量的出口 IP;只有 Workbuddy 自己对外提供接口时,才由你在它的接入层登记调用方地址。出口 IP 不固定时得先加固定 NAT 或固定代理,否则白名单会时好时坏,甚至等于没有生效。

IP 白名单要填在接收请求的一方,不在 Workbuddy 的本地配置文件里。当 Workbuddy 作为调用方去请求别人的 API 时,白名单条目属于 API 平台的控制台、网关或防火墙,登记的是 Workbuddy 出站流量的出口 IP;只有当 Workbuddy 自己对外暴露接口、需要限定谁能调用它时,才由你在它的接入层登记调用方的 IP。若出口 IP 本身不固定,例如跑在共享出口的 Serverless 环境里,单靠白名单无法长期生效,必须先把出口固定下来再登记。 API 侧看到的源地址通常是统一出口网关的地址,而不是使用者所在办公网的地址。原因是请求要经过负载均衡、NAT 网关或正向代理才落到公网,链路上任何一跳都可能改变源地址。做法是在 API 平台侧打开调用日志,查看失败请求里记录的 source IP,再把这个地址和运维记录中的出口地址核对一遍,确认是哪一个网关在出流量。 白名单能写成单个地址就不要写成大网段,一个 /32 条目比一段 /24 安全得多。云上的 NAT 网关通常分配的是一组弹性 IP 而不是单个地址,这种情况下必须把整组都登记进去,否则请求会在不同出口之间轮转,表现为时好时坏。IPv4 和 IPv6 双栈环境要分别登记,只加 IPv4 的条目在 IPv6 优先的链路上会直接失效。 白名单是第二道锁,不能替代密钥和签名。IP 在应用层可以被伪造,X-Forwarded-For 这类头部由客户端随意填写,平台如果把代理头当作真实源地址,白名单就达不到任何实际保护作用。正确的做法是让服务端校验 TCP 连接的真实源 IP,代理头只用于日志排查;密钥、签名、IP 白名单三层同时开,任何一层失效都还有下一层兜底。 多个环境要分开登记,不能把测试环境的出口一次性加进生产白名单。开发、预发、生产的出站链路往往不同,共用一条白名单等于给测试流量开了生产权限。做法是按环境建不同的密钥,每个密钥绑定自己那组 IP,项目下线时按组回收,比在一条长名单里逐个删条目可靠得多。 白名单改完不等于立刻生效,同步有延迟,旧连接还会继续沿用原有映射。网关侧的白名单通常秒级到分钟级下发,如果链路层是长连接或 NAT 映射有保活,改动前建立的连接不会主动断开。验证时要新建连接,换一个进程或重新发起握手,拿旧会话测出来的结果没有意义。 401 和 403 要分开看,前者是身份问题,后者才多半是白名单或权限问题。401 说明密钥没带上或已经失效,403 说明服务端认出了请求但拒绝了来源。排错时先用 curl 的输出详情看返回码和响应头,再对照 API 平台的拒绝日志,日志里通常会写明命中哪条规则,比两端各猜一遍要快。 出口 IP 会变的场景,正确解法是加固定出口,而不是关掉白名单。Serverless、容器弹性扩缩、办公网动态拨号都会导致出口漂移,可行的手段是给出站流量挂一个带固定 IP 的 NAT 网关,或让请求统一走一台带固定地址的代理。反过来把白名单改成 0.0.0.0/0,等于把这道锁彻底拆掉。 白名单条目数有上限,超限时要靠合并网段和分组管理,而不是继续往里堆条目。多数平台对单密钥或单账号的条目数有配额,堆到上限后新增会被直接拒绝。可行的做法是先把同一机房的地址合并成最小可覆盖的网段,再按业务线拆成不同密钥分组,最后定期清理已经不存在的条目。 白名单变更是权限变更,要有审批和留痕。加一条 0.0.0.0/0 和加一个具体地址,风险完全不是一个量级,但操作上只差几个字符。落地做法是把白名单变更纳入变更单,记录申请人、用途和到期时间,项目结束或人员离场时同步回收,避免名单越滚越长最后没人敢动。 联调阶段最常见的坑是把域名解析结果当成源 IP。API 平台侧看到的永远是发起连接那一端的地址,域名解析出来的是目标地址,两者不是一回事。真要确认,在 Workbuddy 侧执行一次出站探测,请求一个会回显来源 IP 的服务,再把这个结果和平台日志对齐,通常一轮就能定位到是哪条链路没有加白。