redis

README.md

@@ -73,6 +73,7 @@
 - 服务端角色权限校验
 - SQLite / MySQL 8.4 双数据库持久化
 - 可选 Redis 公开接口缓存，支持写后版本失效、热点请求合并和故障回源
+- Redis 登录状态存储，和普通接口缓存使用不同逻辑数据库，支持多实例共享会话
 - 规范关系模型、外键、唯一约束和业务索引
 - 业务写入与审计日志使用原子事务提交
 - 关键管理操作审计日志
@@ -130,7 +131,7 @@ docker compose logs --follow app
 docker build --tag hengzhun-exam-system:local .
 ```
 
-镜像默认监听 `0.0.0.0:4173`，以非 root 用户运行，并通过 `/api/public/home` 执行健康检查。需要连接 MySQL 或 Redis 时，用运行环境变量覆盖 `DATABASE_CLIENT`、`DATABASE_URL`/`MYSQL_*`、`REDIS_URL`；此时 SQLite 数据卷可以移除。
+镜像默认监听 `0.0.0.0:4173`，以非 root 用户运行，并通过 `/api/public/home` 执行健康检查。需要连接 MySQL 或 Redis 时，用运行环境变量覆盖 `DATABASE_CLIENT`、`DATABASE_URL`/`MYSQL_*`、`REDIS_URL`；认证状态默认使用同一 Redis 服务的独立 DB 1，也可以通过 `REDIS_SESSION_DB` 或 `REDIS_SESSION_URL` 单独配置。此时 SQLite 数据卷可以移除。
 
 #### Gitea Actions 自动发布到 Docker Hub 与 Gitea 软件包
 
@@ -233,6 +234,8 @@ npm start
 
 配置 `REDIS_URL` 后，应用会缓存公开首页、已发布公告详情和每名考生的已发布成绩查询。公开数据默认 TTL 为 60 秒，成绩默认 TTL 为 24 小时；成绩录入/发布、批量导入、考试归档和成绩复议会自动使成绩缓存失效，超级管理员也可以在成绩管理中心手动刷新全部成绩缓存。Redis 未配置或暂时不可用时，应用会自动切换到有界本机缓存（默认最多 200 条），避免热点接口反复回源；写入后的失效语义保持不变。
 
+同一个 `REDIS_URL` 还会启用 Redis 认证状态存储：登录 Session、TOTP 登录挑战和 TOTP 绑定临时状态全部写入 Redis。普通接口缓存按 `REDIS_URL` 使用 DB 0 时，认证状态默认自动选择独立 DB 1；可通过 `REDIS_SESSION_DB` 修改逻辑 DB，或通过 `REDIS_SESSION_URL` 指向另一台 Redis。应用会拒绝让认证状态与普通缓存使用同一 Redis 端点的同一逻辑 DB。认证 Redis 配置后连接失败会阻止服务启动，避免多实例之间悄悄退回本机状态而出现随机掉线。完全未配置 Redis 时，认证状态仍使用本机内存，服务重启会要求重新登录。
+
 数据库关系表会按写入版本复用进程内只读快照，避免每个请求重复扫描并转换全部业务表。应用自身写入会立即使快照失效；SQLite 还通过 `PRAGMA data_version` 检测其他连接的提交，MySQL 外部直写默认最多延迟 30 秒可见。可通过 `DATABASE_STATE_CACHE_TTL_MS` 调整 MySQL 快照时间，通过 `LOCAL_CACHE_MAX_ENTRIES` 控制本机接口缓存上限。
 
 ```powershell
@@ -240,10 +243,12 @@ $env:REDIS_URL = 'redis://127.0.0.1:6379/0'
 $env:REDIS_CACHE_PREFIX = 'exam-information'
 $env:REDIS_CACHE_TTL_SECONDS = '60'
 $env:REDIS_RESULTS_CACHE_TTL_SECONDS = '86400'
+$env:REDIS_SESSION_DB = '1'
+$env:AUTH_SESSION_TTL_SECONDS = '28800'
 npm start
 ```
 
-生产环境可使用 `redis://` 或启用 TLS 的 `rediss://` 连接地址，并通过 `REDIS_CONNECT_TIMEOUT_MS` 调整启动连接超时。
+生产环境可使用 `redis://` 或启用 TLS 的 `rediss://` 连接地址，并通过 `REDIS_CONNECT_TIMEOUT_MS` 调整启动连接超时。若 Redis Cluster 不支持非 0 逻辑 DB，请用 `REDIS_SESSION_URL` 为认证状态配置独立 Redis 实例。
 
 ### 导入服务器 MySQL 测试数据
 
@@ -341,7 +346,8 @@ src/data/base.mjs                  空业务库与系统基础配置
 src/data/seed.mjs                  手动测试数据生成器
 scripts/import-test-data.mjs       独立测试数据导入脚本
 src/http/responses.mjs             JSON、文件与请求体处理
-src/security/session.mjs           Cookie 会话与当前用户
+src/security/auth-state.mjs        Redis / 本机会话与 TOTP 临时状态
+src/security/session.mjs           Cookie 解析与当前用户
 src/security/authorization.mjs     管理层级、权限和数据范围
 src/routes/public.routes.mjs       公开 API
 src/routes/auth.routes.mjs         登录、注册与改密 API