企业官网建设流程全解析

Metapi 账号与 Token 管理完全指南：四级健康状态机与凭证自动续签机制详解

【免费下载链接】metapi把你在各处注册的 New API / One API / OneHub / DoneHub / Veloera / AnyRouter / Sub2API 等站点， 汇聚成 一个 API Key、一个入口，自动发现模型、智能路由、成本最优项目地址: https://gitcode.com/gh_mirrors/meta/metapi

如果你在用Metapi把 New API、One API、Veloera、Sub2API 等站点汇聚成一个 API Key、一个入口，那么"账号与 Token 管理"就是决定体验上限的核心模块：Metapi 为每个上游账号维护四级健康状态机（健康 / 异常 / 降级 / 禁用），并通过 60 秒级定时扫描实现凭证自动续签与失败自动重登录，让路由层只把流量发给真正可用的账号。

一、为什么账号与 Token 管理这么重要 🔑

多站点聚合场景下，你会同时面对三种麻烦：

1. 凭证会过期：Session Cookie、Access Token、refresh token 都有生命周期，手动续期根本忙不过来；
2. 故障不可见：某个账号挂了，如果路由继续把请求打过去，用户侧就是超时和报错；
3. Token 分散：上游站点的账号令牌、下游给客户端用的 API Key，两套体系混在一起容易丢。

Metapi 的解法：健康状态机负责"看"，续签调度器负责"救"，令牌服务负责"管"，三者配合让多账号长期无人值守运行。相关接入背景可参考官方文档：docs/upstream-integration.md。

二、先认识三种账号凭证模式

在谈状态机之前，先知道 Metapi 支持哪几种"上游账号的钥匙"（详见 upstream-integration.md）：

凭证模式直接决定健康状态的判定口径：比如"仅代理 + API Key"的账号，系统会依据模型探测是否成功来判定健康，而不是依赖会话登录态。

三、四级健康状态机：路由只发给健康账号 🩺

健康状态机的核心定义在 accountHealthService.ts：

判定逻辑集中在 buildRuntimeHealthForAccount()：先看禁用 → 再看是否过期 → 最后读取最近一次探测落盘的运行健康记录。

状态在界面上如何呈现

账号列表页会把每个账号的状态渲染成带呼吸动画的彩色徽标（绿色健康 / 红色异常 / 黄色降级 / 灰色禁用），映射表见 Accounts.tsx：

• 账号状态为expired时，直接展示为"已过期"，并提示"连接凭证已过期，请更新凭证"；
• 每次状态变化都会记录reason（原因）与source（来源，如auth、model-discovery），方便排查。

健康状态如何影响路由

健康信号会进入下游 Token 路由的选路依据——"P 值是硬优先级，只会在当前最高可用优先级内结合权重、成本和健康度随机选择"（见 tokenRouter.ts）。也就是说，异常账号会自动被边缘化，恢复后重新进入候选池，无需人工干预。

四、凭证自动续签机制：到期前悄悄换证 🔄

这是 Metapi 少被人注意到但极其关键的能力，由两个互补的机制组成。

1. 定时续签调度器（以 Sub2API 为例）

sub2apiRefreshScheduler.ts 定义了调度节奏：

• 每 60 秒一轮全量扫描（SUB2API_REFRESH_SCHEDULER_INTERVAL_MS = 60_000）；
• 只处理同时满足条件的账号：站点与账号均为active、持有refreshToken且tokenExpiresAt临近到期；
• 采用4 路并发（SUB2API_REFRESH_SCHEDULER_CONCURRENCY = 4）加速批量续签；
• 每次续签走 sub2apiRefreshSingleflight.ts 的单飞（singleflight）通道——同一账号即使被多个请求同时触发，也只会真正刷新一次，避免重复换证。

对用户的意义：refresh token 在到期前就被换掉，请求永远不会撞上 401。

2. 余额刷新触发的自动重登录

除了 refresh token，还有一类"Session 失效"。Metapi 在余额刷新链路（balanceService.ts）中做了兜底：

1. 发现托管会话到期 → 优先尝试 refresh token 续签；
2. refresh token 也不可用 → 若该账号配置了自动重登录（autoRelogin，存储加密的账号密码），则调用tryAutoRelogin()重新走一次完整登录，拿到新的 Access Token；
3. 续签/重登成功后，新凭证立即写回账号，后续探测从新凭证继续。

运维提示：若日志中反复出现token expired，系统会自动尝试续签；持续失败时再手动刷新 Token，详见 docs/operations.md。

五、账号 Token 管理：掩码、分组与生命周期

上游站点的"账号令牌"（区别于下游 API Key）由 accountTokenService.ts 统一管理：

• 展示掩码：maskToken() 只暴露前缀与后 4 位（如sk-ab***wxyz），界面不泄露完整密钥；
• 令牌分组：OneHub / DoneHub 等支持token_group，Metapi 自动识别并保留分组，路由可按组约束可用令牌；
• 生命周期状态：valueStatus区分ready（可直接使用）与masked_pending（仅有掩码、待补全真实值），避免把占位值发给上游。

如果你更关心下游发给客户端的 API Key 管理，可看管理后台的密钥页（见截图 api-key-management.png 对应页面），它同样支持批量创建、前缀定制与启停控制。

六、给新手的 5 条实操建议 ✅

1. 能填账密就别只填 API Key：账密模式才能解锁自动签到、余额刷新与自动重登录；
2. 善用健康状态：账号列表里红色"异常"先看reason，是"凭证过期"就去触发一次续签或重新授权；
3. Sub2API 账号保持 active：只有 active 的账号才在 60 秒续签扫描范围内，禁用账号不会自动续证；
4. 令牌别手敲：批量导入用管理 API，令牌掩码对比会防止误删已有令牌；
5. 结合代理日志验证路由：观察 proxy-logs-mapping.png 这类映射视图，确认异常账号确实被跳过。

写在最后

Metapi 的账号与 Token 管理把"多站点长期运行"拆成了两个问题：状态是否可信（四级健康状态机）和凭证是否有效（自动续签 + 自动重登）。前者让路由决策有依据，后者让凭证永不裸奔——这正是它能把一堆各自为政的中转站，变成"一个 API Key、一个入口"的底层原因。

📚 延伸阅读：

• 上游接入：docs/upstream-integration.md
• 运维排障：docs/operations.md
• 健康状态源码：src/server/services/accountHealthService.ts
• 续签调度源码：src/server/services/sub2apiRefreshScheduler.ts

【免费下载链接】metapi把你在各处注册的 New API / One API / OneHub / DoneHub / Veloera / AnyRouter / Sub2API 等站点， 汇聚成 一个 API Key、一个入口，自动发现模型、智能路由、成本最优项目地址: https://gitcode.com/gh_mirrors/meta/metapi