vm2api OAuth 凭证生命周期:换票、刷新与 fail closed 网络不变量
vm2api OAuth 凭证生命周期:换票、刷新与 fail closed 网络不变量
vm2api 是一套虚拟机完全拟真的 AI 订阅转 API 网关,它把 Claude / Codex 订阅变成标准 API 供生产调用。整套系统能否长期稳定,关键藏在 OAuth 凭证的生命周期里:换票(import/exchange-code)→ 到期前刷新(refresh)→ 网络出口 fail closed 兜底。本文用最少术语讲清这三环如何配合,让你不再为「凭证突然失效」「槽位莫名其妙出池」而困惑。
一、凭证从哪来: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),绝不落明文。
二、刷新机制:只有 1 个"写票人",且绝不盲刷
刷新是凭证生命周期里最容易出事故的一环,vm2api 为此立了几条硬规则(控制面实现见 src/server.mjs,槽内换票见 worker/internal/oauth/refresher.go):
- 单一写票人:只有控制面的
RefreshIfNeeded会换票,槽内进程一律只读。推理临期或面板点「刷新凭证」才会触发,不存在第二套后台定时器。 - 5 分钟刷新窗口:access token 到期前 5 分钟才进入刷新窗口;窗口外只读现票,不做任何换票动作。
- 并发安全:先进程内 singleflight 合并重复请求,再加文件锁;锁内重读凭证和 generation 二次确认,避免两个请求把同一个 refresh token 刷废。
- 失败分类(见 src/lib/oauth/oauth-credentials.mjs):
retryable:429、5xx、超时、网络抖动 —— 稍后自动重试;fatal:invalid_grant、refresh_token_missing、token has been revoked—— 重试无意义,槽位立即出池、容器暂停,面板显示"无效凭证"。
- 401 不强制换票:端点拒绝票据 ≠ 票据过期。硬刷会把还能用的 grant 烧成
invalid_grant,所以 401 只触发重读现票。 - 定期兜底:控制面每 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 身份,毁掉整个拟真方案。
四、面板怎么管理换票与刷新
| 操作 | 接口 | 说明 |
|---|---|---|
| 手动刷新 | 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。


