登录持久化设计

1. 目标

为管理端和员工端提供正式上线可用的登录持久化：

刷新页面、关闭后重新打开浏览器、前后端服务重启后仍可恢复登录。
会话仅保存在服务端数据库，浏览器仅保存不透明随机令牌。
员工端和管理端会话相互隔离，可在同一浏览器同时登录。
支持闲置过期、绝对过期、主动退出、停用账号立即失效和管理员撤销会话。
不在 localStorage 或 sessionStorage 中保存密码、会话令牌或完整用户资料。

2. 现有基础

当前已实现：

auth_sessions 数据库表持久化会话。
会话令牌使用高熅随机值，数据库只保存 SHA-256 摘要。
Cookie 使用 HttpOnly、Secure、SameSite=Strict 和明确的 Expires/Max-Age。
管理端与员工端使用不同 Cookie 名称。
前端启动时调用 /api/{portal}/auth/me 恢复用户状态。
退出时撤销数据库会话并清除 Cookie。

当前的 SESSION_TTL=12h 是固定过期时间，last_seen_at 尚未用于闲置过期或续期。

3. 会话策略

策略	管理端	员工端
闲置超时	12 小时	24 小时
绝对有效期	7 天	30 天
滑动续期	剩余闲置时间低于 6 小时时续期	剩余闲置时间低于 12 小时时续期
并发会话上限	每账号 5 个	每账号 10 个
超限策略	撤销最早活跃会话	撤销最早活跃会话

续期只能延长闲置截止时间，不得超过绝对有效期。超级管理员不豁免会话过期和撤销规则。

4. 数据模型

在 auth_sessions 中保留现有字段，新增：

absolute_expires_at timestamptz NOT NULL,
last_rotated_at timestamptz NOT NULL DEFAULT now(),
revoked_reason varchar(32),
device_label varchar(120) NOT NULL DEFAULT ''

索引：

保留 token_hash 唯一索引。
增加 (user_id, last_seen_at DESC) WHERE revoked_at IS NULL，用于会话列表和并发上限。
增加 (expires_at) WHERE revoked_at IS NULL，用于过期会话清理。

revoked_reason 取值：LOGOUT、ACCOUNT_DISABLED、PASSWORD_CHANGED、ADMIN_REVOKED、CONCURRENT_LIMIT、EXPIRED。

5. 请求验证与续期

每个受保护请求执行：

读取当前端对应的 HttpOnly Cookie。
对令牌做 SHA-256，查询未撤销会话。
同时校验 expires_at 和 absolute_expires_at。
校验用户仍启用且角色与当前端一致。
距上次写入超过 5 分钟时才更新 last_seen_at，避免每次 API 请求写库。
进入续期窗口时，更新 expires_at 并重发 Cookie，新时间不超过 absolute_expires_at。
会话无效时清除 Cookie 并返回统一 401 SESSION_INVALID。

第 5、6 步应使用条件更新，保证多个并发请求不会频繁写入。

6. 前端恢复流程

应用启动后保持鉴权 loading 状态，先请求 /auth/me，不提前闪现登录页。
/auth/me 成功：只将返回的用户和项目权限保存在 React 内存状态。
返回 401：清空内存状态并跳转到对应登录页。
其他网络错误：显示“无法确认登录状态”和重试入口，不直接判定为退出。
所有 API 对 401 使用统一事件通知鉴权容器，避免页面在会话过期后继续停留在受保护界面。
可持久化项目选择等非敏感偏好，但恢复后必须再与 /auth/me 返回的权限集合校验。

7. 会话管理接口

GET /api/{portal}/auth/sessions：列出当前账号的活跃会话，仅返回会话 ID、设备摘要、IP 脱敏值、创建时间和最后活跃时间。
DELETE /api/{portal}/auth/sessions/{id}：撤销指定会话。
POST /api/{portal}/auth/logout-all：撤销当前账号全部会话。

管理员修改普通账号密码、角色或停用账号时，必须在同一数据库事务中撤销该账号的所有会话。

8. 清理与运维

API 实例每小时尝试清理一次，或由部署平台定时任务执行。
已过期或撤销会话保留 30 天供安全审计，然后物理删除。
监控指标：登录成功/失败数、限流数、活跃会话数、续期数、无效会话数和会话查询耗时。
不记录原始 Cookie、令牌、密码或完整 IP。

9. 上线迁移

新增字段允许短暂为空，对存量会话使用当前 expires_at 回填绝对过期时间。
部署兼容新旧会话的 API，完成回填后再加 NOT NULL 约束。
部署前端统一 401 处理和会话状态页。
启用过期会话清理任务和监控。

迁移不需要强制所有用户重新登录。

10. 验收标准

登录后刷新页面、关闭并重开浏览器、重启 API 均能恢复登录。
管理端和员工端会话同时存在且互不覆盖。
闲置期内活动能续期，但不能突破绝对有效期。
停用账号、改密码、改角色、主动退出或管理员撤销后，旧会话立即不可用。
Cookie 中无用户资料，前端存储中无密码和会话令牌。
网络故障不会被误判为退出，真实 401 会统一返回登录页。
并发请求不会导致每次请求更新会话表。

5.1 KiB Raw Permalink Blame History Unescape Escape