Genarrative/docs/technical/AUTH_REFRESH_SESSION_PERSISTENCE_HOTFIX_2026-04-24.md

Auth refresh session 持久化热修方案

日期：2026-04-24

1. 背景

当前 Rust 鉴权链路已经具备 refresh cookie 自动续签能力：access token 过期后，前端会调用 POST /api/auth/refresh，后端轮换 refresh token 并返回新的 access token。

但 module-auth 当前仍使用进程内 InMemoryAuthStore 保存账号与 refresh session。只要 server-rs 在 access token 生命周期内发生重启，浏览器侧 HttpOnly cookie 仍然存在，服务端却找不到对应账号与 session，最终表现为约 JWT_EXPIRES_IN 后需要重新登录。

2. 本次目标

本次先落一个低风险持久化闭环，解决“后端重启导致 2 小时后必须重新登录”的线上体验问题：

1. 为当前 InMemoryAuthStore 增加 UTF-8 JSON 快照文件。
2. 在账号、手机号索引、微信身份、refresh session 发生变更后自动保存快照。
3. api-server 启动时从配置路径恢复快照。
4. 保持现有 /api/auth/refresh、logout、sessions 语义不变。

3. 非目标

本次不把完整认证域一次性迁入 SpacetimeDB 表，原因是 refresh session 独立持久化不足以解决问题：refresh 成功后还需要按 user_id 读取账号快照重新签发 access token，因此账号主数据也必须同源恢复。

SpacetimeDB 正式表接管仍按以下既有文档继续推进：

1. docs/technical/SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md
2. docs/technical/SPACETIMEDB_AUTH_IDENTITY_TABLE_DESIGN_2026-04-21.md
3. docs/technical/SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md

4. 配置

新增环境变量：

变量	默认值	说明
GENARRATIVE_AUTH_STORE_PATH	server-rs/.data/auth-store.json	当前 Rust 鉴权快照文件路径。相对路径按进程工作目录解析。

5. 数据边界

快照文件保存当前 Rust 鉴权服务已经在内存中维护的最小真相：

1. next_user_id
2. users_by_username
3. phone_to_user_id
4. sessions_by_id
5. session_id_by_refresh_token_hash
6. wechat_identity_by_provider_uid
7. user_id_by_provider_union_id

短信验证码和微信 OAuth state 不持久化，原因是它们是短生命周期挑战数据，重启后失效是可接受行为。

6. 安全约束

1. refresh token 原文仍只存在浏览器 HttpOnly cookie，快照只保存 sha256(refresh_token)。
2. 快照包含 password_hash、手机号映射和 refresh token hash，部署时必须放在服务端私有目录，不允许暴露到静态资源目录。
3. 快照写入必须使用 UTF-8，并通过临时文件原子替换降低写坏风险。

7. 后续 SpacetimeDB 接管点

当 user_account、auth_identity、refresh_session 表及 reducer 全部落地后，替换策略如下：

1. 保留 module-auth 用例语义。
2. 把当前快照仓储替换为 SpacetimeDB 仓储适配器。
3. 启动时可提供一次性导入脚本，把 JSON 快照导入 SpacetimeDB 表。
4. 导入完成后禁用 GENARRATIVE_AUTH_STORE_PATH 快照写入。