适用场景
- Product: ZCenter
- Version: 5.1.0
- Component: Base / Portal / Gateway authentication
- Trigger/Condition: 用户或自动化调用因Token在预期时间前失效，需要延长或缩短本地登录Token有效期。
问题现象
- 用户登录后，在配置的有效期到达前调用接口返回未认证，或页面提示登录状态失效。
- 浏览器或客户端重新登录后问题暂时消失；网关日志可能出现
Token expired、Token validation invalid或Token verification failed。
判断方法
- 先确认问题是否仅发生在旧Token。使用新登录获取的Token调用一个需要认证的接口，并记录返回的
expiresIn和refreshExpiresIn。 - 在数据库中查询当前有效配置：
SELECT category, name, setting
FROM sys_config
WHERE category = 'GLOBAL_SETTINGS' AND name = 'tokenExpireSeconds';- 检查
setting是否为合法JSON，并确认expireSeconds是否符合业务要求且不超过259200秒。 - 如需确认Redis中的新Token TTL，使用实际部署的Redis地址、认证信息和数据库执行只读查询，检查精确的
base:access_token:{userId}:{jti}和base:refresh_token:{userId}:{jti}键。不要使用宽泛前缀删除或清空数据库。 - 如果数据库值正确但新Token仍不符合预期，继续检查请求是否经过第三方身份提供商；第三方登录Token的有效期可能由身份提供商决定。
原因说明
本地登录Token的有效期优先读取 sys_config 中 GLOBAL_SETTINGS/tokenExpireSeconds 的 expireSeconds；数据库配置不存在或解析失败时，才回退到 Base 服务配置 jwt.token-validity-in-seconds。源码默认值为7200秒，最大值为259200秒。5.1.0迁移脚本将初始数据库值调整为43200秒，但具体环境是否执行过该迁移必须以目标数据库查询结果为准。
Refresh Token在本地Token流程中按Access Token有效期的2倍计算，因此当Access Token为43200秒时，Refresh Token通常为86400秒。不要仅依据其他服务配置文件中的同名属性判断实际生效值。
解决方案
1. 执行前准备
- 确认操作账号具备平台全局设置修改权限，并记录当前
tokenExpireSeconds配置。 - 在生产环境变更前完成数据库备份或至少保留原始配置值；先在测试环境验证。
- 确认Redis连接信息来自实际运行时配置，不要直接套用源码中的
127.0.0.1:6379或示例密码。 - 评估已有登录会话的影响。已签发Token的JWT过期时间和Redis TTL不会因修改配置而自动延长。
2. 处理步骤
- 通过平台全局设置接口或对应管理页面读取并修改
tokenExpireSeconds。Portal保存全局设置的接口为POST /api/portal/v4/global-setting/SaveSetting，请求内容应保持为合法JSON，例如：
[{"name":"tokenExpireSeconds","setting":"{\"expireSeconds\":43200}"}]- 将
expireSeconds设置为业务要求的正数，并确保不超过259200秒。只修改该配置项，不要修改Token签名密钥。 - 让用户重新登录或通过刷新流程获取新Token。仅修改数据库配置通常不需要重启，因为有效期在签发Token时读取；若修改的是打包在
application.yml中的默认配置，则必须重新部署Base服务后才会生效。 - 如果业务使用第三方身份提供商，按身份提供商的Token策略处理，不要将本地Token配置直接套用于第三方Token。
验证方法
- 配置验证：重新查询
sys_config，确认GLOBAL_SETTINGS/tokenExpireSeconds的expireSeconds为目标值。 - Token验证：重新登录，确认响应中的
expiresIn和refreshExpiresIn与目标配置一致。 - Redis验证：检查新签发Token对应键的TTL，Access Token应接近
expiresIn，Refresh Token应接近其实际有效期。 - 功能验证：使用新Token连续调用原本失败的认证接口，直到目标有效期内均能正常访问。
- 旧Token验证：确认旧Token不会被错误地延长；如需让所有用户重新建立会话，应通过正常的退出登录或会话失效流程处理。
风险与回滚
- 风险：有效期过长会延长Token泄露后的可用窗口；有效期过短会增加重新登录和刷新请求频率。
- 风险：直接修改配置文件、Token签名密钥或批量删除Redis键可能导致现有会话失效或平台认证异常。
- 回滚：将
tokenExpireSeconds恢复为变更前记录的合法JSON值，并重新登录验证新Token。不要通过FLUSHDB或删除整个Token前缀回滚。