[BUG] 更换供应商 API key 后仍用旧凭证发请求(401 身份验证失败),重启才生效;401 文案未提示 key/端点不匹配 #17

已关闭
由 chenjieping 于 2026-11-16 18:02:56 +08:00创建 · 5 评论

环境

  • macOS (darwin arm64),桌面端 + sidecar
  • 供应商:zai-coding-plan(端点 https://api.z.ai/api/coding/paas/v4)、zhipuai-coding-plan(端点 https://open.bigmodel.cn/api/coding/paas/v4)

现象(2026-11-16 下午,日志时间已 +8 为本地时间)

  1. 新添加的第一个 key(用于 zai-coding-plan)持续 401:
    AI_APICallError url=https://api.z.ai/api/coding/paas/v4/chat/completions
    statusCode=401 {"message":"身份验证失败。","code":"1000"}
    
  2. 第二个 key(zhipu,bigmodel.cn)添加后一开始同样 401:
    AI_APICallError url=https://open.bigmodel.cn/api/coding/paas/v4/chat/completions
    statusCode=401 {"message":"身份验证失败。","code":"1000"}
    
  3. 在供应商列表中断开 zhipu 连接 → 重启八爪鱼 → 重新连接后同一个 key 立即恢复正常(glm-5.3 / glm-5.3-flash 均正常出流,含当前会话)。key 与端点均未改动,唯一变量是重启。

日志证据(sidecar.log)

本地时间 事件
17:24 zai-coding-plan → api.z.ai 返回 401 code:1000
17:24 zhipuai-coding-plan → open.bigmodel.cn 返回 401 code:1000
17:45 重启(所有实例 dispose),断开 zhipu 后重连
17:47 起 zhipuai-coding-plan 正常出流

分析与建议

  1. 凭证热更新失效(主要问题):更换 API key 后,运行中的 sidecar 疑似仍用内存中缓存的旧凭证发起请求,直到重启才从磁盘 auth.json 重新加载。建议:key 变更后立即失效内存缓存,或在连接测试失败时主动重读凭证。
  2. key/端点不匹配无提示(次要):zai-coding-plan(api.z.ai)与 zhipuai-coding-plan(open.bigmodel.cn)的 coding plan key 互不通用。用户误把 bigmodel 申请的 key 填到 z.ai 条目(或反之)时只会得到笼统的 401"身份验证失败",没有任何引导。建议在 401 时提示检查「key 是否与该供应商对应平台匹配」。
  3. 建议连接测试(供应商保存时的验证请求)区分「key 错误」与「key 与端点不匹配」两种情况,给出可操作的错误文案。

期望行为

  • 更换 key 后无需重启即可生效;
  • 401 错误文案能指引用户排查 key/平台匹配问题。
## 环境 - macOS (darwin arm64),桌面端 + sidecar - 供应商:`zai-coding-plan`(端点 `https://api.z.ai/api/coding/paas/v4`)、`zhipuai-coding-plan`(端点 `https://open.bigmodel.cn/api/coding/paas/v4`) ## 现象(2026-11-16 下午,日志时间已 +8 为本地时间) 1. 新添加的第一个 key(用于 `zai-coding-plan`)持续 401: ``` AI_APICallError url=https://api.z.ai/api/coding/paas/v4/chat/completions statusCode=401 {"message":"身份验证失败。","code":"1000"} ``` 2. 第二个 key(zhipu,bigmodel.cn)添加后一开始同样 401: ``` AI_APICallError url=https://open.bigmodel.cn/api/coding/paas/v4/chat/completions statusCode=401 {"message":"身份验证失败。","code":"1000"} ``` 3. 在供应商列表中断开 zhipu 连接 → 重启八爪鱼 → 重新连接后同一个 key 立即恢复正常(glm-5.3 / glm-5.3-flash 均正常出流,含当前会话)。key 与端点均未改动,唯一变量是重启。 ## 日志证据(sidecar.log) | 本地时间 | 事件 | |---|---| | 17:24 | zai-coding-plan → api.z.ai 返回 401 code:1000 | | 17:24 | zhipuai-coding-plan → open.bigmodel.cn 返回 401 code:1000 | | 17:45 | 重启(所有实例 dispose),断开 zhipu 后重连 | | 17:47 起 | zhipuai-coding-plan 正常出流 | ## 分析与建议 1. **凭证热更新失效(主要问题)**:更换 API key 后,运行中的 sidecar 疑似仍用内存中缓存的旧凭证发起请求,直到重启才从磁盘 `auth.json` 重新加载。建议:key 变更后立即失效内存缓存,或在连接测试失败时主动重读凭证。 2. **key/端点不匹配无提示(次要)**:`zai-coding-plan`(api.z.ai)与 `zhipuai-coding-plan`(open.bigmodel.cn)的 coding plan key 互不通用。用户误把 bigmodel 申请的 key 填到 z.ai 条目(或反之)时只会得到笼统的 401"身份验证失败",没有任何引导。建议在 401 时提示检查「key 是否与该供应商对应平台匹配」。 3. 建议连接测试(供应商保存时的验证请求)区分「key 错误」与「key 与端点不匹配」两种情况,给出可操作的错误文案。 ## 期望行为 - 更换 key 后无需重启即可生效; - 401 错误文案能指引用户排查 key/平台匹配问题。
fourbroad 于 2026-11-16 18:08:46 +08:00 指派给自己
所有者

claim — session unspecified-session · branch workflow/bugfix/17-stale-provider-key · account fourbroad (atomic claim via script/claim.sh, #3327)

**claim** — session `unspecified-session` · branch `workflow/bugfix/17-stale-provider-key` · account `fourbroad` (atomic claim via script/claim.sh, #3327)
所有者

Triage:根因已定位(凭证热更新失效)

根因:PUT /auth/:providerID(server/routes/instance/httpapi/handlers/control.ts:20-26)的 authSet 只做两件事——auth.set()(写盘 auth.json + ProviderFailover.clearCooldown),没有任何缓存失效。而运行中的 sidecar 有三层内存结构持有旧 key 快照:

  1. InstanceState ScopedCache(effect/instance-state.ts:42-78)按 directory 缓存整个 Provider State,成功后 TTL=∞
  2. s.models Map(provider/provider.ts:1393)—— LanguageModel 实例在实例化时闭包捕获 apiKey(:1866-1870 / :2024-2030)
  3. s.sdk Map(provider/provider.ts:1400,sdkCacheKey 把 apiKey 算进哈希)+ state 构建时 auth.all() 的 key 被快照进 providers[providerID].key/keys(:1626-1638)

所以换 key 后请求仍持旧凭证 → 401 code:1000;重启后全部从盘重建 → 立即恢复。与票面时间线(17:45 重启 → 17:47 恢复)完全吻合——注意按日志,真正让 key 生效的是重启,不是断开重连本身。

修复方向(最小改动面):authSet 成功后失效对应 directory 的 InstanceState 缓存条目,让下一次模型调用重新快照新 key(models/sdk 两层 Map 以 apiKey 入键/闭包,state 重建后自然换新)。

次项(401 文案):AI_APICallError 呈现层加「key 是否与该供应商平台(api.z.ai vs open.bigmodel.cn)匹配」提示;连接测试同口径。

下一步:在 octopus 主仓开 Kind/Bug 修复票挂本结论。

### Triage:根因已定位(凭证热更新失效) **根因**:`PUT /auth/:providerID`(`server/routes/instance/httpapi/handlers/control.ts:20-26`)的 `authSet` 只做两件事——`auth.set()`(写盘 auth.json + `ProviderFailover.clearCooldown`),**没有任何缓存失效**。而运行中的 sidecar 有三层内存结构持有旧 key 快照: 1. **InstanceState ScopedCache**(`effect/instance-state.ts:42-78`)按 directory 缓存整个 Provider State,成功后 TTL=∞ 2. **s.models Map**(`provider/provider.ts:1393`)—— LanguageModel 实例在实例化时闭包捕获 apiKey(`:1866-1870` / `:2024-2030`) 3. **s.sdk Map**(`provider/provider.ts:1400`,sdkCacheKey 把 apiKey 算进哈希)+ state 构建时 `auth.all()` 的 key 被**快照**进 `providers[providerID].key/keys`(`:1626-1638`) 所以换 key 后请求仍持旧凭证 → 401 code:1000;重启后全部从盘重建 → 立即恢复。与票面时间线(17:45 重启 → 17:47 恢复)完全吻合——注意按日志,真正让 key 生效的是**重启**,不是断开重连本身。 **修复方向(最小改动面)**:`authSet` 成功后失效对应 directory 的 InstanceState 缓存条目,让下一次模型调用重新快照新 key(models/sdk 两层 Map 以 apiKey 入键/闭包,state 重建后自然换新)。 **次项(401 文案)**:AI_APICallError 呈现层加「key 是否与该供应商平台(api.z.ai vs open.bigmodel.cn)匹配」提示;连接测试同口径。 下一步:在 octopus 主仓开 Kind/Bug 修复票挂本结论。
所有者

修复票已建:Octopus/octopus#7312(Kind/Bug,挂根因分析与验收标准)。

  • AC-1~3:authSet 缓存失效(主项)
  • AC-4:401 文案 key/端点匹配提示(次项)

本票跟踪的用户侧问题到此 triage 完结,修复进度见 #7312。

修复票已建:Octopus/octopus#7312(Kind/Bug,挂根因分析与验收标准)。 - AC-1~3:authSet 缓存失效(主项) - AC-4:401 文案 key/端点匹配提示(次项) 本票跟踪的用户侧问题到此 triage 完结,修复进度见 #7312。
所有者

已定位根因并提交修复:PR Octopus/octopus#7314

根因确认(与你的分析一致):Provider 的每实例状态(凭证/模型/SDK 快照)缓存在 InstanceState 的 ScopedCache 中,TTL 无限、仅在实例 dispose 时失效。Auth.set 只写磁盘 auth.json,运行中的 sidecar 实例继续用构建时固化的旧 key 发请求——只有重启(全部实例 dispose + 重建)才重新读盘。这就是「断开重连无效、重启立即恢复」的原因(断开/重连不动实例缓存)。

修复内容:

  1. 保存/删除 key(PUT/DELETE /auth/:providerID)写盘后立即失效 Provider 状态缓存——下次请求惰性重建、从盘重读凭证,无需重启,也不杀实例不丢会话。
  2. OAuth 回调拿到新凭证后同样失效。
  3. 401 文案追加提示:key 可能无效/过期,或与该供应商端点不匹配(此前 z.ai/bigmodel 的 身份验证失败 code:1000 无任何可操作信息)。

回归测试先行(修复前确认失败)+ 全绿;CI 通过后合并发版。感谢详细的时间线日志,对定位帮助很大。

已定位根因并提交修复:PR https://eightarms.net/Octopus/octopus/pulls/7314 **根因确认**(与你的分析一致):Provider 的每实例状态(凭证/模型/SDK 快照)缓存在 `InstanceState` 的 ScopedCache 中,TTL 无限、仅在实例 dispose 时失效。`Auth.set` 只写磁盘 `auth.json`,运行中的 sidecar 实例继续用构建时固化的旧 key 发请求——只有重启(全部实例 dispose + 重建)才重新读盘。这就是「断开重连无效、重启立即恢复」的原因(断开/重连不动实例缓存)。 **修复内容**: 1. 保存/删除 key(`PUT/DELETE /auth/:providerID`)写盘后立即失效 Provider 状态缓存——下次请求惰性重建、从盘重读凭证,**无需重启**,也不杀实例不丢会话。 2. OAuth 回调拿到新凭证后同样失效。 3. 401 文案追加提示:key 可能无效/过期,或与该供应商端点不匹配(此前 z.ai/bigmodel 的 `身份验证失败 code:1000` 无任何可操作信息)。 回归测试先行(修复前确认失败)+ 全绿;CI 通过后合并发版。感谢详细的时间线日志,对定位帮助很大。
所有者

修复已合并发布:PR Octopus/octopus#7314(主仓 #7314,已合并 main)。

最终落点(评审后共 4 处 + 修订):

  1. PUT/DELETE /auth/:providerID(设置页保存/删除 key)写盘后立即失效 Provider 状态缓存——下次请求自动用新 key,无需重启,不影响进行中的会话。
  2. OAuth 回调拿到新凭证后同样失效(含失败防护,不影响已持久化凭证)。
  3. 401 文案追加提示:key 可能无效/过期,或与该供应商端点不匹配(key/端点不匹配场景显式点名)。
  4. 三条凭证写入路径(保存、删除、OAuth 回调)均有回归测试钉死,防再度退化。

评审流程:三组并行评审(正确性/测试/安全/性能/风格/追溯 9 维度)→ 0 阻断项 → 修订(防护补齐 + 3 组负测试)→ CI 全绿 → 合并。

随下个版本发布后,更新 key 即时生效。感谢反馈与详细日志!

修复已合并发布:PR https://eightarms.net/Octopus/octopus/pulls/7314(主仓 #7314,已合并 main)。 **最终落点**(评审后共 4 处 + 修订): 1. `PUT/DELETE /auth/:providerID`(设置页保存/删除 key)写盘后立即失效 Provider 状态缓存——下次请求自动用新 key,**无需重启**,不影响进行中的会话。 2. OAuth 回调拿到新凭证后同样失效(含失败防护,不影响已持久化凭证)。 3. 401 文案追加提示:key 可能无效/过期,或与该供应商端点不匹配(key/端点不匹配场景显式点名)。 4. 三条凭证写入路径(保存、删除、OAuth 回调)均有回归测试钉死,防再度退化。 评审流程:三组并行评审(正确性/测试/安全/性能/风格/追溯 9 维度)→ 0 阻断项 → 修订(防护补齐 + 3 组负测试)→ CI 全绿 → 合并。 随下个版本发布后,更新 key 即时生效。感谢反馈与详细日志!
登录 并参与到对话中。
未选择标签
2 名参与者
通知
截止日期
未设置截止日期。
依赖工单

未设置依赖工单。

引用:Octopus/release#17