后台会话策略（README）

本文档记录管理员后台会话策略的现状、优化建议与后续启用指引，便于根据安全与体验需求做选择或演进。

现状（已生效）

• 会话模型：滑动空闲过期（Idle Timeout）。
• 默认时长：120 分钟。
• 生效位置：api/app/base/controller/AdminBaseController::getAdmin()。
• 实现要点：
  • 读取 Env::get('app.user_expired_time', 120)（单位：分钟）。
  • 过期判断：admin_user_token.update_time + app.user_expired_time*60 < now 则会话失效。
  • 未过期时：每次请求刷新 update_time = now（滑动窗口）。
  • 失效返回：ERROR_TOKEN，前端清除 token 并跳转 /login。

建议（暂不启用）

为提升整体安全性，建议在滑动空闲过期的基础上增加“绝对最长会话时长（Absolute Max TTL）”。当前暂不启用，但建议值如下，供后续选择：

• 管理员：绝对最长 8–12 小时；空闲超时保持 120 分钟。
• 超管/高敏操作：绝对最长 4–8 小时；空闲超时 30–60 分钟。
• 内网/演示环境：可不设绝对最长或设置为 24 小时；空闲超时放宽 240–480 分钟。

引入绝对最长会话时长可避免因心跳或高频操作让会话无限续期，降低被劫持后长期存活的风险；同时需要权衡长任务被强制中断的体验影响。

启用指引（未来）

若后续需要启用“绝对最长会话时长”，建议按以下步骤：

1. 环境配置（单位：分钟）

   • 在 api/.env 或 api/env-master 增加：
     • app.user_absolute_max_time = 720（示例为 12 小时）或 1440（24 小时）。

2. 基准字段选择

   • 优先以 AdminUserToken.create_time 作为绝对过期的时间基准。
   • 若未启用模型自动时间戳，可在发放 token 时补充专用字段（如 login_time）作为基准。

3. 统一校验位置

   • 在 AdminBaseController::getAdmin() 中与空闲过期同时校验：
     • 绝对过期：(base_time + app.user_absolute_max_time*60) < now 则失效。
     • 空闲过期：沿用现有 update_time 判断。
     • 未过期：刷新 update_time = now，保持滑动窗口。

4. 前端联动

   • 后端返回 ERROR_TOKEN 或 401 时，现有逻辑会在 web/src/api/base/error-engine.js 调用 handleTokenInvalid()，清除 token 并跳转 /login。
   • 可选优化：在到期前增加提示或倒计时弹窗，降低强制中断的体验影响。

变更影响与运维建议

• 影响评估：
  • 安全性提升：限制会话上限，避免无限续期。
  • 体验影响：长任务与夜间会话可能被强制中断。
• 运维建议：
  • 按环境差异配置（开发/测试/生产）。
  • 监控会话超时次数与登录重试行为，作为调参依据。
  • 灰度启用绝对最长会话时长，并保留快速回滚方案。

参考与定位

• 后端会话校验：api/app/base/controller/AdminBaseController::getAdmin()。
• 环境变量：
  • app.user_expired_time（滑动空闲过期，分钟）。
  • app.user_absolute_max_time（绝对最长会话时长，分钟，建议后续引入）。
• 前端错误处理与跳转：web/src/api/base/error-engine.js。