WorkbuddyIP 白名单在 API 调用里怎么配置，才能既不被 403 拦住又不把出口 IP 管乱？

WorkbuddyIP 白名单在 API 调用里的配置分三步走：先确定调用方的固定出口 IP，再把该 IP 以 CIDR 形式写进持有 API 密钥的账号下的 IP 白名单并保存，最后用一次最小请求验证是否放行；如果调用方是出口 IP 随实例扩缩容漂移的 Serverless 或被大量终端共享的家庭宽带，这一步应先解决固定出口，否则白名单只能写成宽网段，等于没配。 白名单校验发生在鉴权链路的前段，先判断来源 IP 是否在允许集合内，再校验密钥是否有效，这决定了报错要先看哪一层。调用方看到请求被拒时，401 通常意味着密钥本身有问题，403 更多指向来源 IP 不在白名单或密钥已绑定到别的 IP 集合；排查顺序应是先确认服务端实际看到的源 IP，再去核对白名单条目，而不是反复重签密钥。很多“配置了不生效”的案例，根因是请求经过了代理或容器出网，平台看到的源 IP 与运维以为的 IP 不是同一个。 配置之前必须先把出口 IP 固化，这是整个白名单机制成立的前提。云主机场景应让流量走绑定了弹性公网 IP 的网卡或统一的 NAT 网关出口；容器集群要让出网流量经固定出口节点，而不是随机调度到各节点直连；CI/CD 流水线里的构建机同样要登记，否则白天手工测试通过、夜间自动发布全部失败。凡是出网路径会变化的架构，白名单都是不可靠的，需要先改网络拓扑再改配置。 白名单条目按 CIDR 书写，单个固定 IP 用掩码全长的 32 位写法最安全，网段写法越宽风险越大。把一个整段地址一次性放进来虽然省事，但等价于把该网段内任何一台机器都视为可信来源，一旦同网段存在被入侵的主机，密钥就等于暴露给了它。实践里更稳妥的做法是只登记确需出口的那几个地址，并给每条白名单加上用途备注，比如“生产订单服务出口”“数据同步跳板机”，后续复核时不用靠猜。 IPv4 与 IPv6 必须分别登记，双栈环境只填一侧是常见漏配点。当主机同时具备两种协议的出口地址时，请求实际走哪一栈由系统的地址优先级和 DNS 解析结果决定，可能同一份代码在两次运行中落到不同协议上；解决办法是把两种协议的出口都加进白名单，或在客户端明确绑定只走 IPv4，避免出现“本地能通、上线就拒”的随机现象。 不同环境应使用不同的密钥与不同的白名单集合，而不是用一把生产密钥到处跑。测试环境、预发环境、本地调试三者的出口 IP 天然不同，如果共用同一把密钥，就只能把三处 IP 全塞进同一张白名单，可信边界被无限放大。正确做法是按环境拆密钥，每把密钥绑定各自允许的来源地址，本地调试用临时密钥并在调试结束后回收，这样某一处密钥泄露时，能立刻定位影响面并单独吊销。 变更顺序要遵循“先加后删、留旁路”的原则，否则极易把自己锁在门外。替换出口 IP 时，先在新地址上完成一次成功的调用验证，再把旧地址从白名单移除；如果平台支持，应在操作前确认仍有另一条可用通道——例如另一台已登记的跳板机——可以发起同样的请求。批量修改和删除条目属于高风险操作，建议放在业务低峰、有人在旁复核的时间窗内进行，并保留修改前后的条目快照，便于回滚。 移动办公与动态宽带场景不要把整个运营商地址池放进来，而应经统一跳板机或固定出口代理出网。团队成员的本地公网地址每天都在变，逐个登记既无法持续也不可控，把所有可能变化的地址段都放进来则彻底失去白名单的意义。更合理的结构是：成员访问跳板机或固定出口服务，由这台机器代理到 API，白名单里只出现这一个出口地址，人员增减只改跳板机权限，不动 API 配置。 当调用链里还叠加了反向代理、网关或第三方中转时，白名单判断依据的是与服务端建立连接那一跳的源 IP，而不是请求头里的转发信息。很多失败案例是把真实客户端 IP 写进了转发头，却在平台侧配置了该客户端 IP，而服务端实际看到的是代理机的地址。处理办法是确认代理层是否固定出口、回源时是否保留源地址，并把代理机的出口地址写进白名单；如果代理本身是共享出口，就要评估这一层是否值得单独申请固定 IP。 验证环节用最小请求就够了：一把只登记了新 IP 的密钥，加一次不带业务参数的轻量调用，能返回正常响应即说明白名单生效。此时再切真实业务流量，能避免把业务错误和网络拦截混在一起判断。验证还要覆盖三类容易遗漏的发起方：定时任务、消息队列消费者、批量导入脚本，它们往往运行在与主服务不同的机器上，主服务通了不代表它们也通；把这三类机器在部署清单里列清楚，白名单才算配完整。 白名单只是来源限制，不能替代密钥本身的权限控制与轮换机制。它能降低密钥在非授权机器上直接使用的概率，但无法防范同网段主机被控制、代理机被滥用这类情况，所以仍需要按最小权限分配密钥、定期轮换、对异常调用量设置告警，并在人员离场时同步回收密钥与跳板机账号。把白名单当作纵深的其中一层，配合密钥治理与调用日志审计，才构成可用的访问控制闭环。 把白名单当成需要维护的资产而不是一次性配置，长期看收益最大。每次网络变更、环境迁移、供应商更换出口，都应触发一次白名单复核，把不再使用的条目删掉，把没有备注的条目补上用途与责任人；对临时放行的条目设置明确的失效日期，到期自动清理。这样做的好处是白名单条目始终与真实调用方一一对应，出问题时能从一条拒绝日志迅速定位到具体机器和负责人，而不是面对一堆来历不明的地址无从下手。