tako 文档 GitHub

81 · 刷新失败不误判登出

性质:方案(已落地)。把 /api/auth/refresh 拿到响应后的判定从「非 2xx 即登出」改成三态:只有「HTTP 401 且响应是引擎信封」才清登录态;5xx、dev 下 Vite 代理在重启窗口回的 500、非信封的 401 都是暂时性故障,静默保留 token 等下一拍。 状态:✅ 2026-11-14 落地(未 commit,等验收)。客户端判定:npm test 35/35 绿(含本方案新增 8 条)、npm run typecheck / npm run build 通过;两个 check 脚本退出 0。端到端「重启后仍保持登录」与反向「伪造 refresh 值后确实回登录页」是人工浏览器走查项,由用户验收时跑(见 §4)。 代码落点:web/src/auth.ts(RefreshOutcome / readRefreshOutcome / isEnvelope、doRefresh 按三态分支)、web/test/authrefresh.test.ts(新增回归网)。无后端改动、无契约字节变化。 前置真源:doc/40(响应信封 {code,message,data} 固定序与业务码表)、doc/46(SSE 事件流,是这次刷新请求的触发方)、doc/36 §34(登录态统一在 auth.ts)。 边界:不改后端 Go 代码;不改 scripts/acceptance/、vite.config.ts;不改 SSE 重连节奏;不把 token 从 sessionStorage 挪到 localStorage;不放宽真失效判定(真 401 + 信封仍必须登出)。

1 病灶:把「拿到非 2xx」等同于「登录失效」

1.1 一场真实发生的戏

dev 环境里把引擎重启一次(改了后端代码要让新二进制生效)。浏览器上开着的那个标签页——一直挂在 http://127.0.0.1:5173/,没换地址、没换标签页、没退出——自己退回了登录页,表单上写着「登录已过期,请重新登录」。用户什么都没做。

这不是「登录真的过期了」。服务端从没拒绝过这个人:dev 的 TAKO_JWT_SECRET 是固定默认值、重启前后一致;refresh token 存在 Postgres 的 refresh_tokens 表里、重启不丢;重启窗口前后的 refresh 请求没有一条 401。

1.2 链条在哪一步断了(四步,全部可复核)

  1. 重启窗口里,引擎还没 bound,Vite 还在。 dev.sh 日志:[vite] http proxy error: /api/auth/refresh → Error: connect ECONNREFUSED 127.0.0.1:8901。引擎晚约 44 秒才 Listening and serving,中间是「前端在、引擎不在」。
  2. Vite 对普通 HTTP 请求代理出错,写死回 500(web/node_modules/vite/dist/node/chunks/config.js:res.writeHead(500, { "Content-Type": "text/plain" }).end())。
  3. 前端把这个 500 当成登录失效。 旧 doRefresh():
    if (!res.ok || !body || body.code !== 0 || !body.data?.accessToken) {
      clearAuth('expired')
      return false
    }
    fetch 没有抛异常(拿到的是一个正常的 500 响应),所以「网络错误保留 token」的分支根本没走到,直接落到 !res.ok → clearAuth('expired') → 登录表单。
  4. 这个 refresh 是谁打的:SSE 重连。 web/src/mutation.ts 里引擎一停,事件流断开 → es.onerror → 重连前先自己 refreshAccessToken() → 打到 Vite → 代理到已停的引擎 → 500。

1.3 严重性

确定性、每次必现:只要重启引擎时浏览器有标签页开着,这个标签页就会被登出一次。同类误判的后果不止重启——引擎内部错误(codeInternal)回 500 时,同样会把一个合法的登录清掉。

1.4 这不是「设计错了」,是同一条规则漏写了一处

同一份文件里另外三处判定其实是对的:switchTenant / settleSwitch 只有 res.status === 401 才 clearAuth();authFetch 只在「连 refresh token 都没有」时才 clearAuth('expired');loginWithPassword 失败只返回错误、不动登录态。漏的就是 doRefresh 这一处。

2 完整业务链路(谁 → 谁 → 谁)

用户在页面登录
→ saveAuth 把 access/refresh 写进 sessionStorage
→ 页面静止(没人调 api)时,只有 SSE 事件流在维持
→ 引擎重启 → SSE 断开 → es.onerror
→ 重连前先 refreshAccessToken():POST /api/auth/refresh   ← 本方案动的是这一环的判定
→ 引擎回什么决定走哪条路:
     200 信封 code=0   → updateTokens(新 token 对) → 重建 SSE,用户无感
     401 + 引擎信封     → 真的失效 → clearAuth('expired') → 登录表单(应该保留)
     5xx / 代理 500     → 暂时性故障 → 保留 token,下一拍再试(今天错走成了「失效」)

本方案动的唯一一环:/api/auth/refresh 拿到响应之后的三态判定。上游是引擎的响应,下游是 clearAuth 与 SSE 重建。不改谁去刷新、不改刷新节奏、不改任何后端。

3 判定口径:必须是引擎信封形状才判失效

POST /api/auth/refresh 的响应口径(后端真源 internal/runengine/auth.go):

情形 HTTP 业务码 该不该登出
成功 200 0 + data.accessToken 不登出,换 token
refresh token 无效 / 用户被停用 / 无可用租户 401 111105 登出
请求体格式不对(不该发生) 400 111101 不登出
内部错误(DB 抖动等) 500 codeInternal 不登出
引擎没起(dev 下 Vite 代理兜底) 500 无(text/plain) 不登出

三态判定(导出为纯函数 readRefreshOutcome(status, body)):

export type RefreshOutcome = 'ok' | 'expired' | 'transient'

// ok        = 2xx 且响应是引擎信封、code=0、data.accessToken 是字符串
// expired   = HTTP 401 且响应是引擎信封且 code≠0   ← 唯一会清登录态的一态
// transient = 其余全部(5xx、代理 500、400、非 JSON 的 HTML、401 但非信封……)

「是引擎信封」的判据(isEnvelope):body 是非 null 对象、typeof body.code === 'number'、typeof body.message === 'string'。

为什么 expired 还要 code≠0:401 却自称 code=0(成功)是矛盾体,无法确证是引擎在拒绝,按保守处理归 transient、不登出——「引擎明确拒绝」必须是「信封 + 非零业务码」,不是光看 HTTP 状态。

没这么做会怎样:只按 HTTP 状态分(例如「401 就登出」)在今天也能跑,但把判断绑在了「引擎恰好用 401 表达失效」这个巧合上——信封规则(doc/40)才是真源,业务码才是页面分叉的依据。

transient 这一态静默保留 token:只 return false,不改 authState、不弹提示、不打日志(重启期每几秒一次,打日志会刷屏);下一次调用自然会重试。这不等于绕过鉴权——服务端该 401 还是 401,下一次带旧 access token 的请求仍会被拒并再触发刷新。

4 测试与验收

4.1 机器测试(已入库,cd yk-tako-eino/web && npm test)

web/test/authrefresh.test.ts,逐条用例与期望:

# 输入(status, body) 期望 readRefreshOutcome 为什么
1 200, {code:0,message:'',data:{accessToken:'a',refreshToken:'b'}} ok 正常续期
2 401, {code:111105,message:'登录已失效,请重新登录',data:null} expired 真失效
3 500, null(Vite 代理 500,text/plain 解析失败) transient 本次病灶
4 500, {code:111408,message:'服务暂时不可用,请再试一次',data:null} transient 引擎内部错误
5 400, {code:111101,message:'请求格式不对',data:null} transient 客户端 bug,不该踢人
6 401, null(网关 HTML 401) transient 非信封不判失效
7 401, {code:0,message:'',data:null} transient 矛盾体,保守
8 200, '<!doctype html>'(被代理到别的服务) transient 非信封

用例 1 与 2 是「既有行为不许破」的守卫;3、4、5、6、7、8 是本次修复的新网。

4.2 活体验收(人工浏览器走查,由用户执行)

  1. 正向:重启引擎 → 浏览器 http://127.0.0.1:5173/ 保持登录(不出现登录页);引擎回来后事件流自动重连、任务/会话列表恢复。
  2. 反向(证明真失效仍然会登出):浏览器控制台把 sessionStorage['tako.configure.refresh'] 改成一个垃圾值 → 触发一次刷新(等 SSE 重连,或切一次工作区)→ 应回到登录页并显示「登录已过期,请重新登录」。

机器能验的是判定函数(§4.1);「重启不再踢人」这条端到端行为需要真浏览器,登记为人工项,不写成「已自动验证」。

5 顺带记录:一处与本方案无关的独立盲区

scripts/check-master-plan.sh 的 awk 只认 | N | 形式的表格行,而 doc/README.md §1 现行真源是 - **NN** [标题](...) 的列表 → 该检查目前对任何编号都匹配不到、恒返回 OK(空跑)。也就是说它今天并不真守卫「doc/16 有没有漏引 docs/README §1 的现行真源」。

本方案不修它(不在范围内),只留记录给后续接手:以后改动 doc/README.md §1 之后,不能只靠这条脚本判定 doc/16 有没有跟上,得人工核。