问题说明
本文用于排查ZCenter因Redis不可达、认证失败、连接超时或Redis服务异常引起的登录认证、权限读取和资源同步异常。不同服务对Redis异常的最终返回结果可能不同，应以连接测试和服务日志为准。
现象
- 登录、刷新Token或访问需要认证的接口失败，可能返回401，日志中出现
Token expired、Token validation failed、Token verification failed或Auth error。 - 云环境资源同步未执行、同步任务重试或单个资源同步超时，日志中可能出现
resource sync get lock timeout!、Failed to acquire lock during resource sync等关键字。 - 角色权限读取异常、页面提示无权限，或登录锁定相关行为异常。
- 服务启动或运行日志中出现Redis connection refused、timeout、authentication failure等客户端异常。具体异常文本以实际客户端日志为准。
适用环境
- 产品：ZCenter
- 版本：5.1.0
- 组件：Base、Gateway及使用Redis/Redisson的资源同步服务
- 部署形态：单节点或多服务部署；Redis地址和密码以实际运行时配置为准
可能原因
- Redis进程未运行，监听地址或端口不可达。
- 服务配置中的Redis地址、端口、密码、数据库或TLS模式与实际部署不一致。
- Redis连接数、资源或网络状态异常，导致Redisson连接超时或重试失败。
- Redis故障导致Access Token键、Refresh Token键或分布式锁无法读写；资源同步可能无法获取锁。
- 仅有权限异常时，也可能是权限配置、缓存刷新或调用服务本身的问题，不能仅凭页面现象判定为Redis故障。
排查步骤
1. 确认影响范围和时间
- 记录首次发生时间、受影响用户、云环境、资源和具体接口。
- 区分是所有请求失败、单个服务失败，还是只有资源同步或权限显示异常。
- 如果只有单个用户或单个资源异常，先保留对应用户ID、cloudAccountId、resourceId和请求时间，避免直接执行全局恢复操作。
2. 检查应用和Redis连通性
- 检查项：从受影响服务所在网络命名空间访问实际Redis地址。
- 命令：
redis-cli -h <redis-host> -p <redis-port> --askpass PING- 预期结果：返回
PONG，且连接使用的地址、端口、密码和数据库与运行时配置一致。 - 异常处理：分别确认Redis进程状态、监听端口、防火墙/安全组、网络路由和认证信息。不要直接使用源码中的示例地址或密码。
3. 检查服务健康状态和日志
- 命令/UI路径：访问受影响服务的
/actuator/health，并查看Base、Gateway及对应业务服务日志。 - 建议搜索：
Token validation failed、Token expired、Token verification failed、Auth error、resource sync get lock timeout、Failed to acquire lock during resource sync、tryLock fail。 - 预期结果：服务健康检查正常，日志不再持续出现Redis连接异常或锁获取超时。
- 异常处理：结合异常发生时间检查Redis服务日志、连接数和资源使用情况；不要仅依据健康接口判断所有Redis操作均正常。
4. 按功能分支确认
- 如果登录和认证同时失败：检查新登录产生的
base:access_token:{userId}:{jti}、base:refresh_token:{userId}:{jti}是否可以写入和读取，并用新Token访问一个受保护接口。 - 如果只有资源同步失败：确认云账号同步请求已发起，再检查对应服务是否持续出现分布式锁超时。不要在同步仍运行时手动删除锁键。
- 如果只有权限异常：检查角色权限配置和缓存刷新情况，同时验证Base服务及Redis读写；源码显示角色权限缓存有定时刷新和数据库回退逻辑，不能直接断言所有权限请求都会失败。
- 如果只有登录锁定异常：检查测试用户对应的
base:loginFailCount:{userId}和base:loginLock:{userId}键及其TTL，不要使用全库清理方式解锁。
5. 收集支持信息
- Redis运行状态、部署拓扑、实际连接地址、端口、数据库和是否启用高可用。
- 受影响服务的日志及Redis日志，覆盖故障前后至少一个完整时间窗口。
- 受影响用户、cloudAccountId、resourceId、请求URL、HTTP状态码和准确时间戳。
- 变更记录，包括Redis重启、故障转移、密码变更、网络策略变更和ZCenter服务重启。
处理方式
- Redis服务停止时，按部署规范恢复Redis服务或执行已批准的主备切换；确认服务端口和认证可用后再恢复ZCenter业务操作。
- 配置不一致时，修正实际运行时的Redis地址、端口、密码、数据库和TLS配置，并按部署方式重启受影响服务。不要修改源码文件代替运行时配置变更。
- 网络或防火墙阻断时，放通受影响服务到Redis的必要访问路径，并保留变更前后的连通性结果。
- Redis恢复后，先验证登录和受保护接口，再执行一个受控的云账号资源同步。不要直接删除全部Token或分布式锁键。
验证方法
- Redis验证：从每个实际使用Redis的服务所在网络位置执行只读连接测试，确认返回
PONG。 - 认证验证：重新登录、访问受保护接口、刷新Token并验证退出登录后的Token不可继续使用。
- 权限验证：使用测试用户访问一个已知需要角色权限的接口，确认权限结果符合配置。
- 同步验证：对一个受控云账号触发同步，确认任务完成、资源状态更新，且日志不再出现锁超时。
- 告警和日志验证：持续观察一个完整业务周期，确认连接超时、认证失败和锁获取失败不再重复出现。
风险与回滚
- Redis重启或故障切换可能造成短时认证、缓存和同步中断；应在维护窗口执行并提前通知用户。
- 不要使用
FLUSHDB、删除全量Token前缀或批量删除Redisson锁作为常规恢复手段，这可能导致所有会话失效或破坏正在运行的同步任务。 - 配置变更失败时恢复到变更前的运行时配置，并按部署方式重启受影响服务；保留Redis和应用日志用于回溯。
补充信息
- Token键：
base:access_token:{userId}:{jti}、base:refresh_token:{userId}:{jti}。 - 登录锁定键：
base:loginFailCount:{userId}、base:loginLock:{userId}。 - 资源同步锁的具体键格式和等待时间由业务服务实现决定，排障时应优先使用日志中的cloudAccountId/resourceId定位。
- 关联KB：ZCenter Token 过期时间不满足业务要求，如何安全调整？。