代理IP API Token过期排查：时间、签名、权限与配额

代理IP API 返回“token expired”“invalid token”“signature mismatch”或 401 时，问题不一定是 Token 本身失效。常见根因包括 VPS 时钟漂移、签名使用了错误的请求路径、认证头格式不对、账号没有目标接口权限、配额耗尽，或者旧 Token 仍被应用缓存。排查时要保留一次完整请求的时间、路径、响应状态和服务端错误码，不要在日志中打印完整密钥。

先区分过期、无效和权限不足

先记录 HTTP 状态码与响应体中的错误码：

curl -i --max-time 10   -H "Authorization: Bearer REDACTED_TOKEN"   "https://api.example.test/v1/proxy/health"

过期：服务端能识别 Token，但判断 exp 或有效期已到。
无效/签名错误：Token 被截断、签名串不同、算法或密钥版本不匹配。
权限/配额：身份有效，但没有接口权限、IP 白名单不匹配或调用额度已用完。

不同平台的状态码和错误字段可能不同，不能只根据 401 或 403 猜原因，应以接口文档和服务端返回为准。

第一步：检查 VPS 时间与时区

带时间戳或 JWT 的 API 对时钟很敏感。先看本地时间、UTC 时间和同步状态：

date -u
timedatectl status
chronyc tracking 2>/dev/null || timedatectl timesync-status

如果系统时间比真实时间快或慢几分钟，短有效期 Token 可能被提前判定过期，HMAC 签名的 timestamp 也会被拒绝。先修复 chrony 或系统时间同步，再重新生成 Token；不要通过扩大时间容忍窗口掩盖长期漂移。

第二步：核对签名原文和请求头

很多 API 的签名由 HTTP 方法、路径、查询参数、时间戳、Nonce 和请求体拼接而成。以下任一变化都会导致签名不同：

把编码前的查询串签成编码后的查询串，或参数顺序不一致。
签名时使用 /v1/proxy，实际请求却是 /v1/proxy/。
请求体签名使用 JSON 原文，发送时却被客户端重新排序或改变空格。
把 Bearer Token 放进 URL，经过网关或日志脱敏后被截断。

在调试环境记录“参与签名的字段摘要”和最终请求方法/路径，不记录密钥原文。用同一份固定参数做一次 curl 和 SDK 对照，确认两者的签名输入完全一致。

第三步：排查权限、白名单和配额

Token 有效不代表可以调用所有接口。检查控制台中的项目、环境、来源 IP 白名单、接口范围、并发上限和剩余额度。若请求从 VPS 发出，白名单应登记实际出口，而不是本机内网地址；经过代理或 NAT 时还要确认服务端看到的地址。

配额不足时，重试只会增加失败请求。建议在客户端把 401/403、429 和网络超时分开处理：认证错误进入人工或密钥轮换流程，429 按服务端的 Retry-After 等待，网络超时才使用有限次数的退避重试。

安全地更换 Token

先在密钥管理或环境变量中生成新 Token，不覆盖旧值。
在一台实例或一个工作进程上做灰度请求，确认返回和出口分配正常。
更新其他实例，观察 401、403、429 和成功率。
确认没有旧进程继续使用旧 Token 后，再撤销旧 Token。

不要把 Token 写进 Git、Shell 历史、公开 issue 或普通访问日志。若怀疑已经泄露，应先撤销并重新签发，再追查调用日志。

如何做一条可复现的最小请求

把请求缩减为一个健康检查或只读接口，固定方法、路径、参数、时间戳和请求头，保存脱敏后的 curl：

curl -i --request GET   --url "https://api.example.test/v1/proxy/health?region=us"   --header "Authorization: Bearer REDACTED"   --header "X-Request-Timestamp: 1710000000"

将客户端时间、服务端响应时间、Request-ID 和错误码放在同一条记录里，便于平台客服或开发者定位。示例时间戳仅用于说明格式，不能直接照抄。