redis

.env.docker.example

@@ -19,5 +19,9 @@ PUBLIC_SITE_HERO_HIGHLIGHT=贯穿每一次考试。
 PUBLIC_SITE_HERO_DESCRIPTION=使用学校下发的报名号登录，完成密码更新和个人信息核验后，即可办理所有考试事项。
 PUBLIC_SITE_FOOTER_NOTICE=本平台展示数据仅用于系统演示
 
-# 可选 Redis 缓存；容器外的 Redis 不应填写 127.0.0.1。
+# 可选 Redis；容器外的 Redis 不应填写 127.0.0.1。
+# 普通接口缓存使用 DB 0，认证状态会自动使用独立 DB 1。
 # REDIS_URL=redis://redis-host:6379/0
+# REDIS_SESSION_DB=1
+# 也可让认证状态使用另一台 Redis（此时 URL 中可指定自己的逻辑 DB）。
+# REDIS_SESSION_URL=rediss://session-redis-host:6379/1

.env.example

@@ -5,12 +5,18 @@ SQLITE_PATH=./data/exam.sqlite
 HOST=127.0.0.1
 PORT=4173
 
-# 可选 Redis 公开接口缓存；未设置 REDIS_URL 时自动禁用并直接读取数据库。
+# 可选 Redis。普通接口缓存使用 DB 0；配置 REDIS_URL 后，登录状态默认自动使用独立的 DB 1。
+# 未设置任何 Redis 地址时，接口缓存和认证状态均使用本机内存模式。
 # REDIS_URL=redis://127.0.0.1:6379/0
 # REDIS_CACHE_PREFIX=exam-information
 # REDIS_CACHE_TTL_SECONDS=60
 # REDIS_RESULTS_CACHE_TTL_SECONDS=86400
 # REDIS_CONNECT_TIMEOUT_MS=1500
+# REDIS_SESSION_DB=1
+# REDIS_SESSION_PREFIX=exam-information:auth
+# AUTH_SESSION_TTL_SECONDS=28800
+# 如需让认证状态使用另一台 Redis，可设置独立地址；URL 中可直接指定逻辑 DB。
+# REDIS_SESSION_URL=rediss://session-redis.example.com:6379/1
 
 # 仅在首次创建空数据库时使用。部署前务必修改初始密码。
 INITIAL_ADMIN_USERNAME=admin

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