研发平台与 AD 域集成，核心是打通两条链路：登录时由 AD 校验账号凭据，运行中把 AD 的组织与账号属性同步到平台侧。本文按数据方向、接入前提、认证与映射配置、异常处置、验收验证五个环节展开，适用于负责研发平台部署或 IT 集成的读者。具体支持哪些协议、字段和同步方式，需以所选研发平台的官方文档和实际版本为准。
要点总览（TL;DR）
- AD 域集成要打通两条链路：登录时由 AD 实时校验凭据，运行中把 AD 的组织、账号属性和账号状态同步到平台侧；角色与文档权限属于平台内授权策略，不在集成范围内。
- 接入前先落实 AD 只读服务账号的最小权限、389/636 端口与防火墙、LDAPS 证书信任、Base DN 与用户/组织 OU 范围，以及平台侧集成配置的管理员权限。
- 账号唯一标识（sAMAccountName 或 userPrincipalName）需在配置前确定并保持稳定；先执行一次全量同步，确认无误后再开启增量同步。
- 运行中重点处理同名或同邮箱账号冲突、AD 账号禁用与删除、同步失败重试和 AD 不可用时的登录降级，并保留不依赖 AD 的本地管理员应急入口。
- 验收用测试账号覆盖正确密码、错误密码、禁用账号三类登录场景，抽查属性映射与 AD 变更后的同步时效，并把同步成功率、冲突数量、证书到期纳入日常监控。
研发平台与 AD 域之间要打通哪些数据和方向
AD 域集成的典型结构是：AD 作为身份源，研发平台作为依赖方。用户在平台登录页输入域账号，平台把凭据交给 AD 校验，校验通过后放行；同时平台按计划从 AD 读取组织与账号信息，写入自己的账号体系。这两件事触发方式不同，配置入口也往往不同，需要分开设计。
认证发生在每次登录时，属于实时校验，平台本身不保存 AD 密码；账号同步则是批量或增量的数据搬运，把 AD 中的用户、部门、邮箱等写入平台。认证解决“这个人能不能进来”，同步解决“进来的人挂在哪个部门、属性对不对”。只做认证不做同步，平台里仍需手工建账号；只做同步不做认证，账号密码仍是两套。
需要打通的数据大致分三类：组织与部门结构，决定账号在平台内的归属层级；账号属性，包括登录名、邮箱、姓名、工号等；账号状态，即启用、禁用、离职等标记。三类数据的同步范围和频率可以不同，例如组织架构按天同步、账号状态按小时同步，具体取决于平台能力与业务对时效的要求。
| 数据项 | 方向 | 触发方式 | 是否本文范围 |
|---|---|---|---|
| 登录凭据校验 | 平台 → AD | 用户每次登录实时发起 | 是 |
| 组织/部门结构 | AD → 平台 | 定时全量或增量同步 | 是 |
| 账号属性（登录名、邮箱、姓名等） | AD → 平台 | 随账号同步写入 | 是 |
| 账号状态（启用/禁用） | AD → 平台 | 随账号同步更新 | 是 |
| 平台账号回写 AD | 平台 → AD | 需单独评估 | 仅作方向说明 |
| 角色、项目权限、文档可见范围 | 平台内部 | 平台内配置 | 否，属访问授权策略 |
平台向 AD 回写账号属于反向操作，涉及 AD 写权限和变更审计，通常只在有明确管理要求时评估，本文不展开。角色分配、项目成员权限、知识文档的可见范围属于平台内的访问授权策略，与身份集成是两件事，本文同样不涉及。
接入前需要准备哪些权限和前提
集成配置卡住的原因多数不在平台侧，而在 AD 侧的权限和网络没有提前落实。建议在动手配置前，把下面几项逐条确认并记录责任人，避免配置到一半回头补权限。
- AD 只读服务账号：为集成单独建一个服务账号，只授予读取用户与组织对象的权限，限定可查询的 OU 范围。不要复用域管理员账号，也不要授予写权限，除非明确要做回写。
- 端口与防火墙：LDAP 常用 389 端口，LDAPS 常用 636 端口。确认研发平台服务器到域控制器的网络可达，防火墙策略已放通对应端口，多台域控制器时逐一确认。
- 证书信任：使用 LDAPS 时，需要把域控制器证书的签发 CA 根证书导入平台服务器的信任库，并确认证书中的主机名与连接地址一致，否则加密连接会因证书校验失败而中断。
- 平台侧管理员权限：确认操作账号具备账号目录或集成配置的管理权限，部分平台把该配置放在系统管理而非项目设置中。
- 域名、Base DN 与 OU 范围：记录 AD 域名、用于查询的 Base DN，以及用户 OU 与组织 OU 的具体路径。用户和组织可能分属不同 OU，需要分别确认。
- 版本与域功能级别：核对研发平台版本文档中列出的 AD/LDAP 支持范围，以及 AD 域功能级别是否在支持列表内。这一项以官方文档为准，配置前查证，不凭经验假设。
| 核对项 | 责任人 | 确认结果 |
|---|---|---|
| 只读服务账号已创建并限定查询范围 | ||
| 389/636 端口网络连通性已验证 | ||
| LDAPS 根证书已导入平台服务器 | ||
| 平台集成配置管理员权限已确认 | ||
| 域名、Base DN、用户 OU、组织 OU 已记录 | ||
| 平台版本与 AD 域功能级别兼容性已查证 |
认证与账号同步怎么配置和映射
认证方式上，LDAP 简单绑定配置简单，但凭据在网络上以明文传输；LDAPS 在 TLS 通道内完成绑定，适合跨网段或对传输安全有要求的场景。选择时先看网络环境：平台与域控制器在同一受控网段且已有其他管控手段，可先用简单绑定验证连通；正式运行建议启用 LDAPS。若平台还提供基于 SAML 或 CAS 的单点登录，那属于另一条认证路径，与 LDAP 绑定可以并存，按登录体验需求选择。
账号唯一标识必须在配置前定下来。常见候选是 sAMAccountName（域登录名）和 userPrincipalName（形如 name@domain 的登录名）。选择依据是用户在平台上的登录习惯，以及 AD 中这两个属性是否稳定唯一。一旦确定，后续同步和登录校验都按同一字段匹配，中途更换会导致账号重复。
| 平台字段 | AD 属性（示例） | 说明 |
|---|---|---|
| 登录名 | sAMAccountName 或 userPrincipalName | 二选一作为唯一匹配键，配置后不随意更换 |
| 邮箱 | 用于通知与找回，需确认 AD 中已填充 | |
| 姓名 | displayName 或 cn | 展示用，允许重名 |
| 部门 | department 或按 OU 路径映射 | 属性为空时可按 OU 层级推导 |
| 工号/员工编号 | employeeID | 按需映射，AD 中未必统一填充 |
| 账号状态 | userAccountControl 中的禁用位 | 用于同步禁用状态 |
同步范围通过 OU 或用户组过滤来限定，只把研发相关人员所在的分支纳入同步，避免把全公司账号灌入平台。同步频率按组织变动节奏设置：人员流动频繁可设为小时级，组织调整较少可按天。首次配置时先执行一次全量同步，把存量账号和组织写入平台，确认结果无误后再开启增量同步，顺序颠倒容易出现增量覆盖不全或重复创建。
在 ONES 侧，账号目录能力支持对接 LDAP 协议服务与 Microsoft AD 服务，实现组织架构自动同步与登录验证；对于非标准目录服务，也可通过标准接口更新组织架构。具体字段映射范围、同步周期与增量机制以所选版本的官方文档为准，配置时按文档逐项核对。
账号重复、属性冲突和 AD 不可用时怎么处理
集成运行后，最常遇到的是账号匹配不上或匹配到多个。处理原则是：以配置阶段确定的唯一标识为准，匹配成功则更新属性，匹配失败则按策略新建或挂起，匹配到多个则进入人工确认队列，不自动合并。同名同邮箱的账号在 AD 中本应唯一，若出现重复，先回 AD 侧清理，再重跑同步。
| 异常场景 | 处置方式 | 观察点 |
|---|---|---|
| 平台已有账号与 AD 账号同名 | 按唯一标识匹配；无法匹配时标记冲突，人工确认后绑定或停用旧账号 | 冲突账号清单与处理记录 |
| 同邮箱对应多个 AD 账号 | 暂停自动同步该批数据，回 AD 侧核实 | 同步日志中的重复告警 |
| AD 账号被禁用 | 同步后平台侧账号同步禁用，禁止登录 | 禁用状态同步延迟 |
| AD 账号被删除 | 平台侧账号转为停用或保留历史数据，不物理删除关联工作项 | 离职人员账号清理记录 |
| 同步任务失败 | 按配置的重试次数自动重试，连续失败触发告警 | 任务执行日志与失败原因 |
| AD 不可用 | 登录请求无法校验，按平台策略降级；本地管理员账号保留应急入口 | 登录失败率与域控可用性监控 |
AD 不可用时的登录降级需要在集成设计阶段就明确：是拒绝所有域账号登录并提示稍后重试，还是允许已同步账号凭平台侧缓存凭据登录。两种策略安全性与可用性取舍不同，需与安全负责人确认后写入运行手册。无论哪种，都应保留至少一个不依赖 AD 的本地管理员账号，用于故障期间恢复配置。
日志与告警建议覆盖四个观察点：同步任务的开始、结束与失败原因；账号新建、更新、禁用的数量统计；登录校验失败的类型分布；域控制器连接状态。这些指标能帮助在用户报障之前发现同步中断或证书过期。
如何验证集成结果并确认可长期运行
验证要用专门的测试账号，覆盖正常与异常两类路径，逐项记录结果和证据，形成可复核的验收记录。
- 登录验证：用测试账号以正确密码登录，应成功进入；输入错误密码，应被拒绝且提示明确；使用 AD 中已禁用的账号登录，应被拒绝。三类结果都符合预期才算认证链路通过。
- 属性抽查：在平台中随机抽取若干账号，与 AD 中的姓名、邮箱、部门逐项比对，确认映射字段与配置表一致，空值字段的处理方式符合预期。
- 冲突处理验证：构造一个平台已存在、AD 中也存在的同名账号，观察系统是否按唯一标识正确匹配，冲突时是否进入待确认状态而非自动合并。
- 同步时效验证：在 AD 中修改一个测试账号的部门或禁用状态，记录变更时间，等待一个同步周期后检查平台侧是否更新，得出实际同步延迟。
- 故障演练：在测试环境模拟域控制器不可达，确认登录降级行为与告警触发符合运行手册的约定。
| 检查项 | 预期结果 | 证据 |
|---|---|---|
| 正确密码登录 | 成功进入平台 | 登录截图与时间 |
| 错误密码登录 | 拒绝并提示 | 失败提示截图 |
| 禁用账号登录 | 拒绝并提示账号不可用 | 失败提示截图 |
| 属性映射抽查 | 与 AD 一致 | 比对记录表 |
| 重复账号处理 | 按规则匹配或进入待确认 | 冲突处理日志 |
| AD 变更同步时效 | 在一个同步周期内生效 | 变更与同步时间记录 |
| AD 不可用降级 | 符合运行手册约定 | 演练记录与告警截图 |
上线后持续观察的指标包括：同步任务成功率与平均耗时、账号冲突数量趋势、登录失败率、证书到期时间、域控制器连接可用性。把这些指标纳入日常监控，并在组织架构调整、域控升级、证书更换等变更前后各做一次抽查，集成就能长期稳定运行。
常见问题
研发平台与 AD 域集成，只做登录认证不做账号同步可以吗？
可以，但平台内仍需手工维护账号。认证只解决登录时凭据校验，平台侧没有从 AD 同步来的组织和属性，新员工入职后要人工建号、调岗后要人工改部门。如果研发人员规模小、组织变动少，先做认证再补同步是可行的过渡方式；人员流动频繁时，建议认证与同步一并规划，减少手工维护带来的账号不一致。
LDAP 简单绑定和 LDAPS 应该怎么选？
简单绑定配置快，但凭据在网络上以明文传输，适合在受控网段内做连通性验证。正式运行建议启用 LDAPS，把绑定过程放进 TLS 通道。启用 LDAPS 前需要把域控制器证书的签发 CA 根证书导入平台服务器信任库，并确认证书主机名与连接地址一致，否则会因证书校验失败导致连接中断。若平台还提供 SAML 或 CAS 单点登录，那是另一条认证路径，可与 LDAP 绑定并存，按登录体验需求选择。
AD 中账号被禁用或删除后，平台侧会怎么处理？
通常的做法是：AD 账号被禁用后，同步任务把禁用状态写入平台，该账号无法再登录；AD 账号被删除后，平台侧账号转为停用或保留历史数据，不物理删除其关联的工作项和记录，避免项目数据出现空缺。具体行为取决于平台的同步策略配置，建议在测试环境先验证一遍禁用与删除的实际表现，再写入运行手册。离职人员账号的清理节奏也应与 HR 流程对齐。
域控制器故障导致 AD 不可用时，用户还能登录研发平台吗？
这取决于集成设计阶段确定的降级策略。一种做法是拒绝所有域账号登录并提示稍后重试，安全性高但可用性受影响；另一种是允许已同步账号凭平台侧缓存凭据登录，可用性好但需要评估缓存凭据的安全边界。两种策略的取舍应与安全负责人确认后写入运行手册。无论选哪种，都应保留至少一个不依赖 AD 的本地管理员账号，用于故障期间恢复配置和排查问题。
集成上线后，怎么判断同步是否还在正常工作？
建议持续观察四类指标：同步任务的开始、结束时间与失败原因；账号新建、更新、禁用的数量统计；登录校验失败的类型分布；域控制器连接状态与 LDAPS 证书到期时间。在组织架构调整、域控升级、证书更换等变更前后各做一次账号抽查，比对平台与 AD 的姓名、邮箱、部门是否一致。这样能在用户报障之前发现同步中断或证书过期。
