History 073 Troubleshooting

历史文档：保留迁移前已公开内容，适用其正文声明的版本。当前候选说明见 Troubleshooting。

排障指南

适用于 SandIAM 0.7.3 源码候选；安装兼容性与真实操作结果须在自己的隔离环境确认。当前候选尚未形成正式发行，发行状态见版本与兼容性。

先记录 SandIAM、SandAdmin 和 PostgreSQL 版本、操作时间、页面或接口、错误码、request id、 组织/应用/环境代码和脱敏日志。不要发送密码、令牌、凭证、恢复码、私钥或数据库备份。

现象	检查	处理
菜单或页面不存在	插件版本、菜单权限、管理范围、管理端产物	重新登录并从 SandIAM 总览进入；仍失败则让管理员核对版本和权限
保存后数据不变	页面错误、接口响应、对象归属、并发修改	停止重复点击，刷新详情并用 request id 查审计
撤销委派后仍能管理应用	是否仍有客户主体委派、独立应用委派，当前账号是否为超级管理员	两种委派来源独立生效，先核对剩余有效来源；使用普通被委派账号验证撤权，不把宿主菜单可见当成操作仍被允许
登录或 MFA 失败	应用状态、身份源、锁定、时间同步、浏览器会话	从应用正式入口重试；不要用后台会话代替应用用户会话
OAuth 刷新超时后重试导致授权失效	第一次刷新是否已经提交、是否重复使用旧 refresh token	当前没有按请求号恢复已提交刷新响应的能力；重放旧令牌会撤销整条授权。网络超时不能证明回滚，结果不确定时重新发起授权登录，不循环重放旧令牌
移除用户组成员后仍能访问资源	授权审计中的 subject_source、身份直接角色、其他有效用户组及直接身份策略	移除一个组成员关系只撤销该来源。同一角色仍可由直接授权或其他有效组提供；先核对实际命中策略和来源，再撤销确需移除的授权，不以仍能访问就判断成员移除失败
验证码或认证通知未收到	应用消息服务挂载、用途、模板、服务状态、供应商响应和投递记录	“调用成功”不等于已送达。先核对供应商是否接收及收件端拦截；超时后不要连续点击重发。修复原因后从原注册、恢复或邀请入口重新申请，不手工复用旧验证码
RADIUS 会计响应成功但会话计数未更新	会计事件 outcome、是否缺少 Start、事件时间与计数器是否倒退	orphaned 和 conflict 也会收到响应。核对 NAS 事件顺序及计数器，不手工改成 applied；不要把协议响应当作会话计数更新证明
RADIUS 登录超时或相同请求重传仍无响应	UDP 连通性、NAS 来源 CIDR、共享密钥、Message-Authenticator、重放与后端异常	超时不能单独说明密码错误。当前 Access 入口不重发缓存响应，已登记的相同报文在 5 分钟指纹有效期内静默丢弃；后端恢复后原请求也可能继续无响应。先定位故障，不清空重放记录来强行重试；真实 NAS 丢包与重传兼容性尚未完成验证
SDK 调用被拒绝	organization、application、API code、audience、action、过期与撤销	对照审计中的稳定错误码修正；禁止回退到匿名或旧 API Key
跨范围数据异常	handler 前对象加载、可信范围属性、批量逐项判定	立即停止相关接口，保留审计并按安全漏洞流程报告
Webhook 持续失败	TLS、签名、超时、幂等、退避和积压	修复接收端后只重试允许重试的记录，核对无重复副作用
目录同步积压	worker 状态、游标、连接、限流、出站状态和稳定错误码	入站失败修复原因后从已记录游标重跑；出站 failed 先修复对端，再在同一连接的出站记录中对精确事件执行重试。不要批量改表或重置尝试次数
OIDC 后通道登出为 dead	OAuth 客户端、所属应用/主体、后通道地址、原会话撤销状态和最后错误码	修复 RP 后用 OAuth 客户端的登出投递列表精确选择 dead 记录并“重新签发”；不要重置原行或重发旧 token。*_DISABLED/*_CLIENT_UNAVAILABLE/*_URI_UNAVAILABLE/*_SESSION_NOT_REVOKED 分别表示功能未启用、管理范围已停用、地址已移除或会话状态不满足恢复条件
升级失败	失败阶段、候选摘要、update 摘要、恢复描述和迁移账本	不手工标记成功；只使用 SandPackage 为同一候选验证的恢复计划

Webhook 和 OIDC 后通道登出均按至少一次投递处理。接收端应能安全处理重复通知； Webhook 可使用 X-SandIAM-Event-Id 关联同一事件。delivered 表示接收端返回 HTTP 2xx， 仍需在接收端核对实际业务结果；OIDC 场景应核对相应应用会话是否已撤销。

后台每次领取一条通知后发送，不会提前占用整批通知的租约。批量结果中的 lease_lost 表示该次处理已失去领取资格，旧处理者不会覆盖新的投递结果；它不等于 dead，不要因此手工重发。 应重新读取投递记录的当前状态，检查 worker 停顿、慢请求和系统时钟。批量统计满足 claimed = delivered + retried + dead + lease_lost，不能只用 claimed 作为送达数量。 网络或进程故障仍可能造成重复通知；租约保护不提供“恰好一次”的外部业务保证。

如果问题涉及越权、身份冒用、密钥泄露或审计缺失，请停止扩大影响，撤销相关凭证或会话， 并按根目录 SECURITY.md 私下报告。

---

文档首页 · 排障