WorkBuddy2API-Hub多Key与出口绑定详解:国内外流量各走各道互不干扰
WorkBuddy2API-Hub多Key与出口绑定详解:国内外流量各走各道互不干扰
WorkBuddy2API-Hub 是一个国际/国内双区域的多账号反代网关,把 WorkBuddy 与 CodeBuddy 封装成标准 OpenAI 兼容接口。本文带你搞懂它的多 API Key 管理与出口绑定:让不同的客户端各用各的 Key、各走各的出口,国际版流量与国内版流量互不干扰。🌐🇨🇳
为什么需要"多 Key + 出口绑定"
默认情况下,所有客户端共享一个全局出口开关:你在看板顶部切到国际版,整个网关就都走国际版。这带来两个不便:
- 同事 A 想用国际版
gpt-6-astra,同事 B 想用国内版deepseek-v4-pro,无法同时满足; - 所有人共用一把 Key,用量混在一起,分不清谁花了多少。
多 Key 与出口绑定正是为了解决这两点:每个 Key 都能固定走国际版或国内版,也可以限制它能调的模型,用量还能按 Key 归属统计。
三步生成并绑定一个 Key
打开看板 http://127.0.0.1:8788/ →「设置」页:
- 填名称:给 Key 起个好认的名字,比如"我的 Codex";
- 生成随机 Key:点一下按钮,得到一把高强度随机密钥;
- 选出口:在出口下拉里选择 🌐 国际版、🇨🇳 国内版,或「跟随面板切换」。
💡 Key 只用来调用
/v1接口,和打开看板的「面板访问密码」是两回事,别混淆。
Key 的元数据(名称、出口、模型限制等)统一保存在 accounts/settings.json 里,重启后自动复用。
出口绑定规则:三种模式怎么选
每个 Key 的出口只有三种状态,源码里用一个 realm 字段区分("" / intl / cn),见 wb_settings.py:
| 模式 | 行为 | 适用场景 |
|---|---|---|
| 🌐 固定国际版 | 永远走国际版出口 | 只玩 gpt-* / gemini-* 等国际独占模型 |
| 🇨🇳 固定国内版 | 永远走国内版出口 | 只用 deepseek / kimi / glm 等国内模型 |
| 跟随面板切换 | 没绑定,走看板顶部的全局开关 | 临时用、不关心出口 |
关键点:Key 绑定的出口优先级高于全局开关。请求进来时,网关按如下顺序决定出口(见 _request_realm):
显式
?realm=参数 → Key 绑定的出口 →X-Realm头 → 全局开关
也就是说,只要 Key 绑了出口,你在面板顶部怎么切都不影响它——这就是"国内外流量各走各道、互不干扰"的底层原因。
给 Key 上"模型白名单"
绑定出口之外,还能给 Key 限定允许调用的模型:
- 支持通配符
*,逗号分隔,例如deepseek*、gpt-6-astra; - 留空表示不限制,旧 Key 升级后行为完全不变;
- 不在白名单里的请求,本机直接返回 400,不会送达上游、也不消耗任何额度。
匹配逻辑在 key_allows_model:空列表放行,其余用 fnmatch 逐条比对。
区域自检:400 报错比晦涩的 WAF 友好
如果 Key 绑定的出口和模型"对不上",网关会在本地直接拦下并给出可读错误,而不是让上游回一句莫名其妙的 403。
举个例子:用绑定国际版的 Key 去调国内独占的 deepseek-v4-pro,你会收到类似这样的提示(见 _cross_realm_error):
模型
deepseek-v4-pro只在国内版提供,但"我的 Key"绑定的是国际版出口。请改用对应出口的 Key,或把该 Key 的出口改为"跟随面板切换"。
哪些模型属于"独占"由 exclusive_realm 判定。这样你一眼就能定位问题,省去了反复试错的烦恼。
用量归因:按 Key 看花了多少
开启「数据看板」页后,可以按 Key 列出请求数、Token、缓存命中、积分与模型分布,口径和账号表一致。
- 谁用哪个模型、烧了多少积分,一屏查清;
- 用量日志按 Key 的
id记录,即使 Key 删了,历史仍能对上号。
启停与删除:软删除,历史不丢
- 单独启停:临时禁用某把 Key,不用删;
- 删除:密钥立即失效,但条目以只读形式留在「设置」页的「已删除」折叠区;
- 历史保留:因为用量按
id归属,删除后历史用量仍会显示这把 Key 的名字,不会变成"(未知 key)"。
这套"软删除"逻辑见 set_api_keys:清掉密钥明文的同时保留行,做到"删了就再也无法认证,但账本还看得懂"。
两个容易踩的坑
- 面板保存过 Key 后,启动参数
--api-key自动失效——以看板为准,避免两套 Key 打架; - 别把面板密码和 API Key 混用:
?pwd=只用来登录面板,?key=只把 Key 存给/v1用,不会自动登录面板。
常见疑问
Q:一个 Key 能同时走国际和国内吗? 不能。一个 Key 只能固定一个出口,或"跟随面板切换"。想两边都用,就生成两把 Key。
Q:同名模型(如 deepseek-v4.1-flash)会自动在国内/国际账号间轮询吗?
目前不会混合轮询。两个区域作为独立出口分别调度,请求只走当前所选网关——这是出站指纹对齐与账号防风控的取舍。
Q:Key 限制模型和账号级限额是一回事吗? 不是。Key 限制是"这把 Key 能调哪些模型"(请求级拦截);账号级限额是"这个账号今天用多少 Token / 积分"(额度护栏),两套机制各管一段。
更多协议与特性说明见 README.md,版本演进记录见 docs/CHANGELOG.md。