研发平台完成LDAP或AD集成后出现用户无法登录，排查时先分清问题落在哪一层：账号尚未同步到平台、目录侧认证未通过、平台与目录之间的连接或证书异常，还是认证已通过但账号未被放行。本文按“同步—认证—连接—授权”四层顺序给出验证证据、处置动作和风险边界，适用于LDAP与Microsoft AD目录场景，访问授权策略与文档权限不在讨论范围。
要点总览（TL;DR）
- 先按“账号是否已同步—目录能否认证—平台能否建立会话—授权是否放行”四层顺序排查，每层用可观察证据确认后再改配置。
- 最常见的原因是账号未同步、用户名属性映射错位、绑定账号读取权限不足、TLS证书或连接异常四类。
- 个别用户失败优先查账号状态与属性映射；全员失败优先查连接、证书与绑定账号密码变更。
- 修改绑定账号密码、重建同步映射、批量重同步前先备份认证配置并选低峰期，大面积失败时先回退最近变更。
- 修复后用受影响账号和正常账号分别登录，核对同步记录与登录日志时间戳，并把配置沉淀为集成记录。
症状与范围：先分清登录失败还是账号未同步
“无法登录”是一句笼统描述，不同提示对应完全不同的排查起点。开始操作前，先把用户看到的原始报错、输入的用户名格式、发生时间、影响范围记录下来，再判断属于哪一类症状。
| 症状表现 | 常见指向 | 需要记录的信息 |
|---|---|---|
| 提示用户名或密码错误 | 目录认证未通过，或用户名属性映射错位 | 报错原文、输入格式（是否带域后缀）、是否仅个别用户 |
| 提示账号不存在或用户未找到 | 账号未同步到平台，或同步任务失败 | 该用户在目录中的DN、同步任务最近一次执行结果 |
| 能登录但看不到任何项目或内容 | 认证已通过，属于授权或成员配置问题 | 账号所属角色、项目成员记录 |
| 同步任务报错或长时间未完成 | 连接、绑定账号权限或过滤器配置异常 | 任务报错信息、失败时间点、影响的用户范围 |
需要特别区分认证失败与授权缺失。用户输入正确凭据后进入平台却看不到内容，说明目录认证已经通过，问题出在角色分配或项目成员配置上，属于权限治理范畴，不应继续在LDAP配置里找原因。反过来，登录页直接拒绝凭据，才应进入认证与同步排查。
同时确认影响范围：只有一名用户失败、某个用户组集体失败，还是全员无法登录。个别用户失败通常指向账号状态、属性映射或目录中的对象位置；全员失败更可能是连接中断、证书过期、绑定账号密码变更或平台认证配置被改动。范围判断直接决定后续从哪一层切入。
原因假设与排除证据：四层定位顺序
排查按从账号到会话的顺序推进，每一层都用可观察的证据确认或排除，避免在未验证的情况下直接修改配置。下表列出四层假设、验证方式和排除依据。
| 层级 | 原因假设 | 验证证据 | 排除依据 |
|---|---|---|---|
| 第一层：账号同步 | 用户对象未从目录同步到平台；同步任务失败；增量同步遗漏新增或变更用户 | 平台用户列表中检索该账号；查看同步任务执行记录与失败条目 | 账号存在且状态正常，同步记录显示成功 |
| 第二层：目录认证 | 绑定账号权限不足；Base DN 范围未覆盖目标用户；用户过滤器写错；用户名属性（uid、sAMAccountName、mail）映射不一致 | 用绑定账号执行目录查询，确认能否读到目标用户；用该用户凭据单独测试绑定 | 绑定账号可读目标OU，过滤器能命中该用户，属性值与登录输入一致 |
| 第三层：连接与安全 | LDAP/LDAPS 端口不通；防火墙拦截；TLS 证书链不完整、主机名不匹配或证书过期 | 从平台服务器侧测试端口连通性；检查证书有效期与颁发链；查看平台连接报错 | 端口可达，证书有效且主机名匹配，连接无报错 |
| 第四层：会话与授权 | 认证成功但账号被禁用或锁定；未分配角色或项目成员 | 查看平台登录日志中该账号的认证结果；核对账号状态与成员配置 | 登录日志显示认证成功，账号状态正常且已加入对应项目 |
第一层优先验证，因为账号不存在时后续所有认证测试都失去意义。在平台用户管理中按用户名、邮箱或工号检索，若查无此人，直接检查同步任务：最近一次执行是否成功、失败条目是否包含该用户、增量同步是否因时间窗口或过滤条件漏掉新入职或刚调整部门的人员。目录侧可用 ldapsearch 或 AD 管理工具按同一条件查询，对比两边结果，差异即为同步环节的问题点。
第二层验证绑定账号的实际读取能力。绑定账号（Bind DN）需要在目录中具备读取目标OU的权限，权限不足时同步任务可能部分成功、部分失败，表现为某些部门用户缺失。Base DN 设置过窄会把新设组织单元排除在外；用户过滤器条件过严会漏掉属性不完整的账号。用户名属性映射是高频问题：目录中以 sAMAccountName 存储登录名，平台却按 mail 匹配，用户输入工号或邮箱时就会提示密码错误。用同一账号在目录侧完成一次绑定测试，能快速区分是密码问题还是映射问题。
第三层关注连接本身。LDAPS 场景下证书链不完整、证书过期或证书主机名与配置地址不一致，都会导致平台无法建立安全连接，表现为同步任务整体失败或登录时统一报错。这类问题通常影响全员，且往往发生在证书到期、目录服务器迁移或网络策略调整之后。从平台服务器侧测试端口连通性，并核对证书有效期，可以快速确认。
第四层在认证通过后检查。登录日志能区分“认证失败”和“认证成功但无权限”两种结果。若日志显示认证成功而用户仍反馈无法使用，应转向账号状态（是否被禁用、是否被锁定）和成员配置，而不是继续调整LDAP参数。
按顺序处置：从同步到登录的修复动作
定位到具体层级后，按下表对应处置。涉及配置变更的操作，先备份现有认证配置，再在低峰期执行。
同步侧处置
- 个别用户缺失：对该用户触发指定同步或重跑一次增量同步，确认账号出现在平台用户列表。
- 属性映射错位：核对目录属性与平台字段的对应关系，修正用户名、邮箱、姓名等映射后重新同步受影响用户。
- 必填字段缺失：目录中部分账号缺少平台要求的必填属性，补齐目录数据或调整映射规则，避免同步时被跳过。
- 批量重同步：仅在确认映射规则正确后执行，执行前备份现有账号与组织关系，选择业务低峰期，并准备回退方案。
目录侧处置
- 绑定账号权限不足：为绑定账号授予目标OU的读取权限，或调整 Base DN 覆盖实际组织范围。
- 过滤器问题：放宽或修正用户过滤器，确认能命中目标用户，同时避免把服务账号、离职账号纳入同步范围。
- 用户名格式：核对大小写、域后缀与登录输入是否一致，必要时在平台侧统一登录名格式。
连接侧处置
- 端口与防火墙：确认平台到目录服务器的 LDAP/LDAPS 端口可达，网络策略变更后重新验证。
- 证书问题：更新过期证书、补全证书链、确保证书主机名与配置地址一致；切换 LDAPS 前先在测试环境验证连接。
- 变更前备份现有认证配置，记录原服务器地址、端口、绑定账号与证书路径，便于快速回退。
风险边界与停止点
修改绑定账号密码、重建同步映射、批量重同步属于有破坏风险的操作。执行前需备份现有认证配置与账号数据，选择低峰期，并明确回退步骤。若出现大面积登录失败，优先回退最近一次配置变更，恢复可用状态后再定位具体原因，避免在故障扩大时继续叠加修改。个别用户失败可以单点处置，全员失败应先检查连接与证书，再考虑同步与映射。
在ONES中，LDAP/AD集成用于自动同步组织架构并验证登录，账号同步结果与登录状态可以在账号管理相关界面中核对，便于把上述四层判断落到具体账号记录上。具体配置项与日志呈现以实际产品文档和实施支持为准。
验证恢复与复发预防
修复完成后，用受影响账号和一个此前正常的账号分别登录，确认两者都能进入平台并看到应有内容。同时核对同步记录与登录日志的时间戳，确认本次操作后产生了新的成功记录，而不是仅凭用户口头反馈判断恢复。
| 验证场景 | 确认方式 |
|---|---|
| 个别用户 | 该用户登录成功，平台用户列表中存在其账号，登录日志显示认证通过 |
| 某个用户组 | 组内抽取多名用户登录验证，同步记录中该组账号完整 |
| 全员 | 不同部门各抽取账号验证，同步任务整体成功，连接与证书检查无异常 |
恢复后把本次结论沉淀为集成配置记录：目录地址与端口、Base DN、绑定账号用途、用户过滤器、属性映射关系、证书有效期、最近一次变更时间与变更人。这份记录在下次故障时能直接缩小排查范围。
复发预防围绕四个检查项展开：为TLS证书设置到期提醒，提前安排更新；为绑定账号制定密码轮换计划，轮换后同步更新平台配置并验证；为同步任务失败配置告警，避免账号缺失长时间无人发现；属性映射与过滤器变更纳入评审，变更前在测试环境验证同步结果。把这些检查项纳入日常运维节奏，多数“集成后无法登录”的问题可以在影响用户之前被发现。
常见问题
用户能登录但看不到任何项目，还需要继续查LDAP配置吗？
不需要。这种情况说明目录认证已经通过，问题出在角色分配或项目成员配置上，属于授权范围。可以先查看该账号在平台中的状态是否正常、是否被加入对应项目或团队，再按权限治理的思路处理。继续调整LDAP参数不会改变用户看到的内容。
只有新入职员工无法登录，老员工都正常，应该从哪里入手？
优先检查同步环节。常见原因是增量同步的时间窗口没有覆盖新账号，或者新员工所在的组织单元不在Base DN范围内，也可能是用户过滤器条件过严导致属性不完整的账号被跳过。可以在平台用户列表中检索该员工，若查无此人，再对照目录侧查询结果确认差异，然后对该用户触发一次指定同步或重跑增量同步。
LDAP集成一直正常，某天全员突然无法登录，最可能是什么原因？
全员失败通常指向连接与安全层：绑定账号密码被修改或过期、LDAPS证书到期或证书链变化、目录服务器迁移后地址或端口改变、网络策略调整导致端口不通。建议先回退最近一次配置变更恢复可用状态，再从平台服务器侧测试端口连通性、核对证书有效期，并确认绑定账号仍能正常读取目标OU。
在ONES中核对LDAP同步和登录状态，可以看哪些信息？
ONES支持对接LDAP协议服务和Microsoft AD服务，实现组织架构自动同步与登录验证，账号同步结果与登录状态可以在账号管理相关界面中核对。具体可查看的字段、日志呈现方式和配置项以实际产品文档和实施支持为准。
修改LDAP认证配置前需要做哪些准备？
先备份现有认证配置，记录服务器地址、端口、Base DN、绑定账号、用户过滤器、属性映射和证书路径，明确回退步骤。批量重同步或重建映射应选择业务低峰期执行，并提前确认映射规则在测试环境验证通过。若变更后出现大面积登录失败，优先回退配置，恢复可用后再定位原因。
