vm2api OAuth 凭证生命周期:换票、刷新与 fail closed 网络不变量

原创2026-10-15 10:03:191,747 阅读

vm2api OAuth 凭证生命周期:换票、刷新与 fail closed 网络不变量

vm2api 是一套虚拟机完全拟真的 AI 订阅转 API 网关,它把 Claude / Codex 订阅变成标准 API 供生产调用。整套系统能否长期稳定,关键藏在 OAuth 凭证的生命周期里:换票(import/exchange-code)→ 到期前刷新(refresh)→ 网络出口 fail closed 兜底。本文用最少术语讲清这三环如何配合,让你不再为「凭证突然失效」「槽位莫名其妙出池」而困惑。

vm2api 请求链路总览:用户请求经协议清洗、槽位内 Claude Code 处理后回到 API 端点

一、凭证从哪来:3 条换票入口

vm2api 里每个槽位(VM/容器)的"活票"只写在一个地方:槽内 ~/.claude/credentials.json。拿到它有 3 条入口,全部由面板触发(详见 docs/OAUTH.md):

入口 触发方式 特点
Setup Token(默认) 导入 sk-ant-sid* 会话密钥 经槽位出口换取完整 OAuth scope,落盘后以 Setup Token 模式运行
已有 OAuth 转换 面板「转 Setup Token」 只切换运行模式,不增删权限,保留真实过期时间
授权链接 生成带 PKCE 的 30 分钟授权 URL 手动粘贴授权码,code 与该 VM 的会话绑定

三条入口有同一个前提:槽位必须已绑定可用出口(远程 SOCKS5 或本地出口 px-local),否则一律返回 proxy_required。换出的 access token / refresh token 只进 credentials.json;vm.json 和数据库只存脱敏元数据(是否有票、过期时间、generation),绝不落明文。

vm2api 控制台凭证模式示意:Setup Token 模式下上游只看到 Console API,OAuth 换票通道关闭

二、刷新机制:只有 1 个"写票人",且绝不盲刷

刷新是凭证生命周期里最容易出事故的一环,vm2api 为此立了几条硬规则(控制面实现见 src/server.mjs,槽内换票见 worker/internal/oauth/refresher.go):

  1. 单一写票人:只有控制面的 RefreshIfNeeded 会换票,槽内进程一律只读。推理临期或面板点「刷新凭证」才会触发,不存在第二套后台定时器。
  2. 5 分钟刷新窗口:access token 到期前 5 分钟才进入刷新窗口;窗口外只读现票,不做任何换票动作。
  3. 并发安全:先进程内 singleflight 合并重复请求,再加文件锁;锁内重读凭证和 generation 二次确认,避免两个请求把同一个 refresh token 刷废。
  4. 失败分类(见 src/lib/oauth/oauth-credentials.mjs):
    • retryable:429、5xx、超时、网络抖动 —— 稍后自动重试;
    • fatal:invalid_grant、refresh_token_missing、token has been revoked —— 重试无意义,槽位立即出池、容器暂停,面板显示"无效凭证"。
  5. 401 不强制换票:端点拒绝票据 ≠ 票据过期。硬刷会把还能用的 grant 烧成 invalid_grant,所以 401 只触发重读现票。
  6. 定期兜底:控制面每 5 分钟(默认)巡检所有带 refresh token 的槽位,只对临期的发起 Ensure,保证即使没有推理流量,票也不会悄悄过期(src/lib/oauth/credential-refresh-monitor.mjs)。

三、fail closed 网络不变量:没出口,就停摆

这是 vm2api 区别于普通反代方案的核心设计,规则只有一句话:所有出槽请求必须走该槽绑定的出口,出口不可用就整体失败,绝不 VPS 直连。

  • 共用槽位 SOCKS5 出口的请求包括:/v1/messages 推理、/api/oauth/usage 额度查询、/v1/models、健康探测、换票本身;
  • 槽位未绑定出口 → 直接拒绝(proxy_required),连授权 URL 都不生成;
  • 代理缺失或连接失败 → 槽位 fail closed:请求失败、槽位出池,而不是"退而求其次"走 VPS 本机 IP 直连 Anthropic——那会立刻暴露 VPS 身份,毁掉整个拟真方案。

vm2api 隔离虚拟机与独立网络出口:每个 VM 节点经专属 SOCKS5 隧道连接外部网络

四、面板怎么管理换票与刷新

操作 接口 说明
手动刷新 POST /api/panel/vms/:id/oauth/refresh 控制面只转发该槽 Ensure,成功返回 refreshed、ttl_seconds、generation 等脱敏状态,永不回显 token
查看状态 GET /api/panel/oauth worker + 脱敏凭证状态一览
出入池 POST /api/panel/vms/:id/schedulable 只改调度资格,不改容器状态

调度资格与面板"网页可用"是同一套判定:过期且无 refresh token 的槽不入池,死凭证自动出池并拆掉会话粘性。

五、给新手的关键结论

  • 换票:3 条入口统一经槽位出口完成,活票只落 credentials.json,元数据脱敏;
  • 刷新:单一写票人 + 5 分钟窗口 + 失败二分法(可重试 / 致命),401 绝不硬刷;
  • fail closed:出口即命脉,代理不可用宁可失败也不直连,这是拟真方案的底线不变量。

理解这三环,你就能看懂面板里每一种凭证状态背后的逻辑。更多细节可查阅官方文档 docs/OAUTH.md 与 docs/API.md。

登录后查看全文
vm2api