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 管理这么重要 多站点聚合场景下你会同时面对三种麻烦凭证会过期Session Cookie、Access Token、refresh token 都有生命周期手动续期根本忙不过来故障不可见某个账号挂了如果路由继续把请求打过去用户侧就是超时和报错Token 分散上游站点的账号令牌、下游给客户端用的 API Key两套体系混在一起容易丢。Metapi 的解法健康状态机负责看续签调度器负责救令牌服务负责管三者配合让多账号长期无人值守运行。相关接入背景可参考官方文档docs/upstream-integration.md。二、先认识三种账号凭证模式在谈状态机之前先知道 Metapi 支持哪几种上游账号的钥匙详见 upstream-integration.md凭证模式典型形态能力边界用户名密码credentialMode: session系统自动登录余额查询、自动签到、账号令牌管理全解锁Access Token / Session CookieJWT 或session...Cookie自动解析用户信息适合非 AnyRouter 站点API Key仅代理sk-xxxxxxxx只用于模型调用无签到/余额/令牌管理凭证模式直接决定健康状态的判定口径比如仅代理 API Key的账号系统会依据模型探测是否成功来判定健康而不是依赖会话登录态。三、四级健康状态机路由只发给健康账号 健康状态机的核心定义在 accountHealthService.ts状态前端标签含义典型触发条件healthy健康运行状态正常余额/模型探测成功、请求成功unhealthy异常最近一次检查失败认证失败、账号过期、请求持续报错degraded降级运行状态波动时好时坏、偶发失败disabled已禁用账号或站点已禁用管理员手动禁用unknown未知尚未检测新接入、从未跑过探测判定逻辑集中在 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中做了兜底发现托管会话到期 → 优先尝试 refresh token 续签refresh token 也不可用 → 若该账号配置了自动重登录autoRelogin存储加密的账号密码则调用tryAutoRelogin()重新走一次完整登录拿到新的 Access Token续签/重登成功后新凭证立即写回账号后续探测从新凭证继续。运维提示若日志中反复出现token expired系统会自动尝试续签持续失败时再手动刷新 Token详见 docs/operations.md。五、账号 Token 管理掩码、分组与生命周期上游站点的账号令牌区别于下游 API Key由 accountTokenService.ts 统一管理展示掩码maskToken() 只暴露前缀与后 4 位如sk-ab***wxyz界面不泄露完整密钥令牌分组OneHub / DoneHub 等支持token_groupMetapi 自动识别并保留分组路由可按组约束可用令牌生命周期状态valueStatus区分ready可直接使用与masked_pending仅有掩码、待补全真实值避免把占位值发给上游。如果你更关心下游发给客户端的 API Key 管理可看管理后台的密钥页见截图 api-key-management.png 对应页面它同样支持批量创建、前缀定制与启停控制。六、给新手的 5 条实操建议 ✅能填账密就别只填 API Key账密模式才能解锁自动签到、余额刷新与自动重登录善用健康状态账号列表里红色异常先看reason是凭证过期就去触发一次续签或重新授权Sub2API 账号保持 active只有 active 的账号才在 60 秒续签扫描范围内禁用账号不会自动续证令牌别手敲批量导入用管理 API令牌掩码对比会防止误删已有令牌结合代理日志验证路由观察 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考