hzhub/hzhub-portal-employee/TIMEOUT_CONFIG.md

员工门户登录超时配置说明

问题需求

修改员工门户(hzhub-portal-employee)的登录超时时间为1小时，超时后自动退出。

配置原理

Token超时机制

HZHub使用Sa-Token进行认证管理，token超时时间由 sys_client 表的 active_timeout 字段控制：

字段	说明	单位	默认值
active_timeout	token活跃超时时间	秒	1800 (30分钟)
timeout	token固定超时时间	秒	604800 (7天)

区别说明：

• active_timeout: 用户活跃超时，用户在指定时间内无操作则token失效
• timeout: token绝对超时，从登录开始计时，无论是否活跃都将在该时间后失效

客户端配置

员工门户使用的客户端ID: e5cd7e4891bf95d1d19206ce24a7b32e（来自 .env.development）

修改方案

方法1：执行SQL更新（推荐）

执行以下SQL脚本将员工门户的超时时间修改为1小时：

# 连接数据库
mysql -u root -phzhub123

# 执行更新SQL
source /tmp/update_employee_timeout.sql

或手动执行SQL：

-- 查询当前配置
SELECT id, client_id, client_key, active_timeout, timeout, status 
FROM sys_client 
WHERE client_id = 'e5cd7e4891bf95d1d19206ce24a7b32e';

-- 更新为1小时超时
UPDATE sys_client 
SET active_timeout = 3600 
WHERE client_id = 'e5cd7e4891bf95d1d19206ce24a7b32e';

-- 验证结果
SELECT id, client_id, client_key, active_timeout, timeout, status 
FROM sys_client 
WHERE client_id = 'e5cd7e4891bf95d1d19206ce24a7b32e';

方法2：通过管理后台修改

1. 登录管理后台: http://localhost:5666
2. 进入 "系统管理" -> "客户端管理"
3. 找到 client_id = e5cd7e4891bf95d1d19206ce24a7b32e 的记录
4. 编辑该记录，将 活跃超时时间 修改为 3600
5. 保存

超时时间建议

根据不同场景，建议的超时时间配置：

场景	active_timeout	timeout	说明
内部员工	3600 (1小时)	604800 (7天)	平衡安全性和便利性
移动端APP	7200 (2小时)	604800 (7天)	移动端使用频率高
公共终端	1800 (30分钟)	86400 (1天)	安全性优先
超级管理员	1800 (30分钟)	86400 (1天)	高安全性要求

验证配置生效

修改后需要重新登录才能生效：

1. 清除浏览器缓存或使用隐身模式
2. 访问员工门户登录页面
3. 登录后等待1小时不操作
4. 再次访问应自动跳转到登录页面

技术实现

后端实现

登录时通过 SaLoginParameter.setActiveTimeout() 设置：

// PasswordAuthStrategy.java
SaLoginParameter model = new SaLoginParameter();
model.setActiveTimeout(client.getActiveTimeout()); // 从sys_client表读取
LoginHelper.login(loginUser, model);

前端响应

前端通过以下方式检测token过期：

1. API响应401: 拦截器检测到401状态码，自动跳转登录页
2. 路由守卫: 访问页面时检查token是否有效
3. 本地存储: Pinia持久化存储token，过期后自动清除

相关配置文件

• 后端配置: /data/hzhub/hzhub-ai/hzhub-common/hzhub-common-satoken/src/main/resources/common-satoken.yml

  • dynamic-active-timeout: true - 允许动态设置token有效期

• 前端配置: /data/hzhub/hzhub-portal-employee/.env.development

  • VITE_CLIENT_ID=e5cd7e4891bf95d1d19206ce24a7b32e - 客户端ID

• 数据库表: sys_client

  • active_timeout - 活跃超时时间（秒）
  • timeout - 固定超时时间（秒）

常见问题

Q: 修改后没有生效？

A: 需要重新登录。已登录的token不会立即失效，只有新登录的token才会使用新的超时时间。

Q: 如何测试超时是否正确？

A:

1. 登录系统
2. 等待设定的超时时间（如1小时）
3. 不进行任何操作
4. 刷新页面或访问API，应自动跳转到登录页

Q: 可以设置为永不过期吗？

A: 不建议。为了安全考虑，应该设置合理的超时时间。如需延长，可以设置为更大的值：

-- 设置为8小时
UPDATE sys_client SET active_timeout = 28800 WHERE client_id = 'e5cd7e4891bf95d1d19206ce24a7b32e';

-- 设置为12小时
UPDATE sys_client SET active_timeout = 43200 WHERE client_id = 'e5cd7e4891bf95d1d19206ce24a7b32e';

相关文档

• Sa-Token官方文档
• HZHub认证流程
• 服务管理脚本