研发平台完成AD域集成后出现组织架构同步不完整，排查时容易一上来就重跑全量同步，结果既没定位原因，还可能覆盖本地已调整的部门数据。更稳妥的做法是按“范围—数据—映射—权限—执行”五层依次验证：先确认缺失的是全部还是局部部门与人员，再核对AD侧对象是否落在同步范围内、必填属性与唯一标识是否可用，随后检查字段映射、同步账号读取权限和任务执行日志。每层都用可观察的证据支持判断，定位到具体层后再做针对性修复，最后通过一次全量比对确认恢复。
要点总览（TL;DR）
- 先界定缺失范围：区分全部部门缺失、局部OU缺失、人员缺失、层级错乱和离职未同步，统计缺失部门数与人数占比，能快速缩小排查方向。
- 按“范围—数据—映射—权限—执行”五层逐层验证：每层先找可观察证据，再决定是否调整配置或重跑同步，避免一上来就全量覆盖。
- 常见根因集中在四类：OU或安全组过滤过窄、必填属性为空或唯一标识冲突、同步账号读取权限不足与分页中断、增量标记异常导致变更未被识别。
- 处置涉及删除或覆盖本地组织数据前，先导出组织架构与账号清单做比对备份；全量同步后逐项复核本地有意调整的部门与账号。
- 恢复验证要同时覆盖数量、层级和登录表现，并把同步日志巡检、失败告警和定期全量校准固化为日常检查项。
同步不完整的典型症状与影响范围
同步不完整的表现差异很大，先归类症状能大幅缩小排查方向。建议从“缺什么、缺多少、缺在哪一层”三个角度记录现象，形成一份范围界定清单，再进入原因分析。
四类常见症状
- 全部部门缺失：平台侧几乎看不到AD中的组织树，通常指向连接失败、同步账号无权限或同步任务整体未执行，属于集成层面的问题。
- 局部部门缺失：部分OU或部分安全组下的对象没有进来，其余部门正常。这类问题多与同步范围过滤、对象启用状态或对象类型有关。
- 人员缺失：部门存在但成员不全，常见于必填属性为空、唯一标识冲突或分页拉取中断。
- 层级错乱：人员都在，但部门父子关系与AD不一致，或人员被挂到了错误的上级部门，通常与部门父子关系来源字段的映射有关。
- 离职未同步：AD中已禁用或移出范围的账号，在平台侧仍处于启用状态，需要检查增量同步标记与禁用状态的处理规则。
如何界定影响范围
范围界定要落到可核对的数字上，避免“感觉少了一些人”这类模糊描述。可以从三个维度统计：缺失部门数占AD侧部门总数的比例；缺失人数占应同步人数的比例；缺失集中在第几层部门（顶层、二级还是末级）。如果缺失集中在某一棵子树，优先怀疑该OU的范围配置；如果缺失分散在各层，优先怀疑属性、权限或分页问题。
与登录失败的区别
“账号存在但无法登录”和“账号未同步”是两类问题。前者说明同步已把账号写入平台，问题出在认证环节，例如登录验证配置、账号状态或密码校验；后者说明对象根本没有进入平台，属于同步链路问题。排查时先在平台侧搜索该账号是否存在，这一步就能把两类问题分开，避免在认证配置上做无效排查。
按层排查：从同步范围到执行日志的原因假设与验证证据
分层排查的核心是把“可能的原因”与“能看到的证据”一一对应。下表按五层列出常见假设和验证方式，实际排查时建议从范围层开始，逐层向下，前一层未排除前不急于重跑同步。
| 层级 | 原因假设 | 可观察证据 |
|---|---|---|
| 同步范围 | 目标OU未被纳入同步范围；安全组过滤条件过窄；对象处于禁用状态；对象类型为联系人而非用户 | 缺失对象集中在特定OU或组；AD中该对象已启用且类型正确；调整范围后对象可被拉取 |
| 数据质量 | 必填属性为空；存在重名；名称含特殊字符；唯一标识（如objectGUID、sAMAccountName、mail）冲突或为空 | 同步日志出现属性校验失败或写入冲突记录；缺失对象在AD侧属性明显不全 |
| 映射配置 | 字段对应关系错误；部门父子关系来源字段选错；多值属性取值规则不符合预期 | 人员同步成功但部门归属错误；部门层级与AD不一致；某类属性整体未写入 |
| 权限与连接 | 同步账号缺少目录读取权限；分页大小限制导致只拉到前若干条；网络或端口不可达 | 同步在固定数量处中断；日志出现权限拒绝或连接超时；部分OU完全读不到 |
| 执行层 | 增量同步标记异常导致变更未被识别；失败任务未重试；任务超时中断 | 日志显示任务失败或超时；AD侧新增对象在多次同步后仍未出现；增量同步后变更不生效 |
范围层与数据层的验证要点
范围层验证最直接的方法是挑一个缺失对象，确认它在AD中的位置、启用状态和对象类型，再对照同步配置的OU与组过滤条件，看它是否满足进入条件。数据层则要打开同步日志，区分“未拉取”和“拉取后写入失败”：前者指向范围或权限，后者指向属性与唯一标识。若日志中反复出现同一属性校验错误，基本可以锁定数据质量问题。
映射层与权限层的验证要点
映射层的问题往往表现为“人进来了但结构不对”。此时核对部门父子关系的来源字段，确认它取的是AD中的上级部门属性还是某个自定义属性，并检查多值属性（如一个用户属于多个组）的取值规则是否符合预期。权限层则要确认同步账号是否具备读取目标OU及属性的权限，同时留意分页限制：当目录对象数量超过单次分页上限时，若分页处理不当，会出现“只同步了一部分”的典型现象。
执行层的验证要点
执行层要看任务日志中的开始时间、结束状态、处理数量和错误条目。增量同步依赖变更标记，若标记异常，AD侧的修改不会被识别，表现为“新增人员一直不出现”。失败重试与超时记录同样重要：一次超时中断可能只完成了部分对象的写入，造成看似随机的缺失。把日志中的处理数量与AD侧应同步数量对照，能快速判断是整体失败还是部分失败。
按排查结果处置：分场景修复步骤
处置动作要与已定位的层级对应，避免用“重跑全量”覆盖所有问题。以下按场景给出步骤，涉及删除或覆盖本地组织数据的操作，执行前先导出当前组织架构与账号清单做比对备份。
场景一：范围配置错误
- 在AD侧确认缺失对象所属的OU与安全组，记录其完整路径。
- 对照同步配置，调整OU范围或组过滤条件，使其覆盖目标对象。
- 先对单个部门做小范围验证，确认对象可被拉取后，再重跑同步。
- 重跑后核对新增部门与人员数量是否与预期一致。
场景二：属性缺失或唯一标识冲突
- 在AD侧补齐必填属性，处理重名与特殊字符问题。
- 对无法修改AD数据的对象，建立映射例外规则，指定替代的唯一标识字段。
- 重新同步后抽查此前失败的对象是否已写入，并确认其部门归属正确。
场景三：同步账号权限不足
- 为同步账号补充目标OU及所需属性的读取权限。
- 用该账号单独验证能否读取缺失对象，确认权限生效。
- 再执行同步，观察日志中的权限错误是否消失。
场景四：增量标记异常
当确认增量同步无法识别AD侧变更时，需要触发一次全量同步。执行前先导出平台侧现有组织架构与账号清单，与AD侧做一次比对，明确哪些差异是本次要修复的、哪些是本地有意调整的。全量同步可能覆盖本地修改，因此比对结果要留存，同步完成后逐项复核。若全量同步仍无法拉全，回到范围层与权限层重新验证，而不是反复重跑。
处置中的停止点
出现以下情况时应暂停操作：本地组织架构中存在AD侧没有的手工创建部门或账号；同步操作将触发批量删除；比对结果显示差异规模远超预期。这些情况下先完成备份与差异确认，再决定是否继续，避免一次同步造成大范围数据丢失。
在ONES中，AD/LDAP对接用于自动同步组织架构并验证登录，同步结果最终体现在平台的团队与成员结构中。处置完成后，可在ONES侧核对部门层级与成员归属是否与AD一致；对于多团队划分等本地配置，需与同步结果分开核对，避免把本地调整误判为同步缺失。具体的同步范围配置项、日志位置与全量同步入口，以对应版本文档或技术支持说明为准。
恢复验证与复发预防
同步任务显示成功不等于数据已经完整，恢复验证要同时覆盖数量、层级和登录表现三个层面。
全量比对验证
- 数量比对：将AD侧应同步的用户数与部门数，与平台侧实际数量对照，差异应能逐条解释。
- 层级抽样：抽取顶层、中间层和末级部门各若干，核对父子关系与AD一致。
- 人员抽样：抽取新增、变更部门、离职三类账号，确认其状态与归属正确。
登录验证
分别用新增账号、部门变更账号和已离职账号做登录测试：新增账号应能正常登录并看到所属部门；变更账号的权限范围应随部门调整；离职账号应处于停用状态且无法登录。三类结果都符合预期，才能认为同步链路与认证链路均已恢复。
复发预防与日常巡检
- 将同步任务日志纳入日常巡检，重点关注失败条目、处理数量异常和超时记录。
- 为同步失败配置告警，确保任务中断能被及时发现，而不是等到用户反馈登录异常。
- 定期执行全量校准，与AD侧做数量与层级比对，及早发现增量同步遗漏。
- 建立变更通知机制：AD侧进行组织调整、OU迁移或账号批量停用时，同步通知平台管理员，便于在同步后主动核对结果。
把上述检查固化为一份巡检清单，每次AD侧组织调整后按清单执行一遍，可以将同步不完整从“事后排查”转为“变更后即验证”，减少对日常研发协作的影响。
常见问题
同步任务日志显示成功，但平台侧仍缺人，应该先查哪里？
任务成功只代表本次执行没有报错，不代表所有应同步对象都被处理。先对照日志中的处理数量与AD侧应同步数量：数量明显偏少，优先查范围层（OU、安全组过滤、对象启用状态）和权限层（读取权限、分页限制）；数量接近但个别对象缺失，优先查数据层，看这些对象是否存在必填属性为空、重名或唯一标识冲突。区分“未拉取”和“拉取后写入失败”，能直接指向不同层级。
AD侧调整了部门层级，平台侧人员都在但归属没变，是什么原因？
人员都在而层级不对，通常不是同步链路中断，而是部门父子关系的来源字段或映射规则没有覆盖这次调整。先核对映射配置中部门上级关系取自AD的哪个属性，再确认该属性在AD侧是否已更新、同步任务是否识别到这次变更。如果增量同步没有捕获变更，可先做一次小范围验证，确认映射生效后再考虑全量同步，并在同步前导出本地组织架构用于比对。
重跑全量同步会不会覆盖本地手工创建的部门和账号？
存在这个风险，因此全量同步前要先导出平台侧现有组织架构与账号清单，与AD侧做一次比对，明确哪些差异是本次要修复的、哪些是本地有意保留的。若比对结果显示本地存在AD侧没有的部门或账号，或同步将触发批量删除，应先暂停操作，完成备份与差异确认后再决定是否继续。同步完成后按比对清单逐项复核，避免一次同步造成大范围数据丢失。
账号已同步到平台但登录失败，还需要继续排查同步吗？
不需要把重点放在同步链路上。先在平台侧确认该账号是否存在：存在但无法登录，问题通常在认证环节，例如登录验证配置、账号状态或密码校验；账号根本搜不到，才属于同步链路问题。两类问题分开排查，可以避免在认证配置上做无效操作。ONES支持对接LDAP协议服务与Microsoft AD服务，实现自动同步组织架构与验证登录，具体登录验证配置项以对应版本文档或技术支持说明为准。
如何减少AD组织调整后反复出现同步不完整？
把验证动作前移到变更之后：AD侧进行组织调整、OU迁移或账号批量停用时，同步通知平台管理员，调整完成后按巡检清单核对数量、层级和登录表现。日常将同步任务日志纳入巡检，关注失败条目、处理数量异常和超时记录，并为同步失败配置告警。定期执行全量校准，与AD侧做数量与层级比对，可以及早发现增量同步遗漏，把问题从事后排查转为变更后即验证。
