操作场景
用户的企业组织架构和成员信息通常维护在 AI 网关外部的身份源中，AI 网关支持将外部目录中的组织与成员同步到控制台，作为消费者、凭证、模型授权、配额和审计数据的组织基础，从而无需在网关侧手工维护组织架构。
通过该功能，您可以：
配置外部组织同步源（目前支持 Windows AD / LDAP），并通过连通性与凭证校验确保可连接。
手动发起增量同步（日常同步新增、修改、删除）或全量校准（首次同步默认全量、整体校准）。
在同步过程中对外部已删除的消费者、组织节点进行人工处理（立即删除或暂时保留），避免误删线上仍在使用的对象影响业务。
查看同步任务的执行阶段、进度与结果，以及成员、部门的变更详情。
说明：
从外部同步的组织与成员由外部身份源维护，网关侧统一只读。如需调整组织架构，请在 Windows AD / LDAP 中修改后重新发起同步。
前提条件
已开通并使用 AI 网关。
已准备外部目录服务（Windows AD 或 LDAP）的连接信息，包括服务器地址、端口、管理员账户、管理员密码与 BaseDN 等。
操作步骤
步骤1：进入同步组织架构
1. 登录腾讯云控制台，选择目标网关实例进入详情页。
2. 在左侧导航栏，单击消费者管理。
3. 在组织架构区域，切换到同步组织架构页签（与自定义组织架构页签并列，手动创建的消费者（组）均归为自定义组织架构），页面上将展示同步源状态卡与外部同步组织树（若已同步），状态卡随同步源配置与任务状态变化，若已发起同步任务，可通过该状态卡跟踪任务进度。
步骤2：新建并配置同步源
在同步源状态卡单击管理同步源，在弹出的抽屉中单击新建同步源，进入新建组织同步源弹窗，当前支持 Windows AD / LDAP 两种类型的同步源导入，根据所选类型，完成同步源配置。
注意：
单租户当前最多配置一个同步源，若已存在同步源，需先删除后才能重新创建。
配置 Windows AD 同步源
字段 | 必填 | 说明 |
组织架构类型 | 是 | Windows AD / LDAP，选择 Windows AD。 |
同步源名称 | 是 | 可对同步的组织架构自定义名称。 |
协议类型 | 是 | LDAP（明文连接）/ LDAPS（TLS 加密）。 |
服务器地址 | 是 | 支持合法域名或 IP。 |
服务器端口 | 是 | LDAP 默认 389，LDAPS 默认 636。 |
证书主机名 | 协议类型为 LDAPS 时必填 | 用于证书主机名校验。 |
CA 证书 PEM | 协议类型为 LDAPS 时必填 | 填写 PEM 正文。 |
管理员账户 | 是 | 支持 UPN、域前置、DN 三种格式。 |
管理员密码 | 是 | - |
BaseDN | 是 | 每行一个，最多 32 个，不重复且不重叠；AD 须属于同一 Naming Context。 |
配置 LDAP 同步源
字段 | 必填 | 说明 |
组织架构类型 | 是 | Windows AD / LDAP，选择 LDAP。 |
同步源名称 | 是 | 可对同步的组织架构自定义名称。 |
协议类型 | 是 | LDAP（明文连接）/ LDAPS（TLS 加密）。 |
服务器地址 | 是 | 支持合法域名或 IP。 |
服务器端口 | 是 | LDAP 默认 389，LDAPS 默认 636。 |
证书主机名 | 协议类型为 LDAPS 时必填 | 用于证书主机名校验。 |
CA 证书 PEM | 协议类型为 LDAPS 时必填 | 填写 PEM 正文。 |
管理员账户 | 是 | 仅支持 DN 格式。 |
管理员密码 | 是 | - |
BaseDN | 是 | 至少填写一条，支持添加多条。 |
部门查询过滤器（filter） | 是（默认配置） | 默认 (objectClass=organizationalUnit)，满足条件的部门数据才会同步。 |
用户查询过滤器（filter） | 是（默认配置） | 默认 (objectClass=inetOrgPerson)，满足条件的成员数据才会同步。 |
步骤3：校验并保存同步源
1. 完成配置填写后，在凭证校验区域，单击开始校验。
系统先执行基础格式检查，再执行连接与凭证检查。
2. 校验结果展示在凭证校验区域：
校验通过：单击创建，该同步源即创建成功。
校验失败：展示失败字段、失败原因及修正建议，修改配置后可重新校验。
注意：
1. 凭证校验失败会累计重试次数，达到数量限制（10次）后将禁止提交校验，请尽量确保配置项正确填写。
2. 创建同步源后不会自动发起同步任务，保存与执行同步为两个独立步骤，需手动发起首次同步。
步骤4：发起同步任务
1. 通过以下任一入口均可发起同步：
同步源状态卡 > 同步任务。
管理同步源列表 > 发起同步。
同步任务抽屉 > 新建同步任务。
2. 在新建同步任务面板中，选择同步模式：
增量同步：用于日常同步外部身份源的新增、修改和删除数据。
全量校准：用于首次同步、组织数据整体校准、修复增量同步遗漏或外部数据大范围调整后的重新对齐。
3. 单击同步，创建任务。
说明：
首次同步默认仅支持全量校准。
同一时间仅允许一个同步任务处于进行中状态；若已有执行中或待确认任务，入口置灰并提示"当前已有同步任务执行中，暂不可重复发起"。
全量校准预计处理数据量较大，系统会给出风险提示。
步骤5：处理删除对象
同步任务按以下五个阶段执行：连接并拉取 → 数据校验与转换 → 计算变更 → 应用变更 → 完成同步。当系统在“计算变更”阶段发现外部数据源已删除消费者或组织节点时，任务暂停并进入“待确认”状态，等待您确认删除处理策略。
1. 在同步源状态卡单击前往确认，或在任务详情单击确认删除处理策略，打开确认删除对象的处理策略弹窗。
2. 弹窗按两类对象展示删除项：
数据源中直接删除的消费者：成员在外部身份源中被直接删除。
因组织节点删除而连带影响的对象：外部组织节点被删除，其下属组织和消费者受连带影响；组织子树支持展开、折叠、级联勾选，并可查看根组织、组织路径、下属部门与下属消费者。
3. 对每个删除对象，执行资源删除依赖关系检查并选择处理策略：
立即删除：系统先检查资源依赖（消费者的配额、MCP Server ACL 授权、MCP Tool ACL 授权、直接授权资源等；组织节点的下属消费者组、下属消费者、已授权模型 API、MCP ACL 授权等）。依赖未解除时按钮置灰，需先解除依赖；检查通过后进入二次确认弹窗，确认后立即删除。
暂时保留：对象继续保留在网关，标记为只读，支持后续在详情页手动删除。
4. 支持对多个对象批量处理（全选、批量暂时保留、批量立即删除）。批量立即删除时，选中对象中存在依赖未解除项则整体禁止执行，且仍需二次确认。
5. 全部删除对象确认完成后，单击确认以上处理策略，继续执行同步。系统校验是否存在未确认或仍待重新检查的对象，全部通过后任务恢复为“进行中”，进入“应用变更”阶段继续执行。
步骤6：查看同步结果与变更详情
查看同步结果
同步完成后，任务状态为以下之一：
任务状态 | 说明 |
成功 | 应用组织与成员变更，更新同步源最近同步时间与组织、用户数量。 |
部分成功 | 已成功处理的对象正常生效，未成功对象记录失败原因，更新问题数量。 |
失败 | 展示失败原因，保留上一份稳定组织数据，不应用本次未完成的变更，可重新发起同步。 |
任务详情展示执行阶段、当前阶段、进度、已处理/总处理数量、任务状态、开始与完成时间，以及同步前数据预览（组织节点总数、用户总数、最大组织层级等）。
查看变更详情
成功或部分成功的任务支持查看变更详情，失败任务主要展示失败阶段、失败进度、错误码与错误原因。
1. 在任务详情中打开变更详情。
2. 通过成员 / 部门页签切换，列表展示名称、ID、所属组织路径、操作类型（新建、同步、删除、更改）、处理结果与详情。
3. 支持按名称/ID 搜索、操作类型筛选、结果筛选与分页。
4. 若变更对象当前仍存在于网关，可单击成员名称或 ID 跳转至消费者详情；已删除对象以普通文本展示，不支持跳转。
相关操作
管理同步源
在同步源状态卡单击管理同步源，打开管理抽屉。抽屉列表展示：同步源名称、来源类型、状态、最近同步时间，并提供查看、发起同步、删除操作。
查看同步源
1. 单击目标同步源的 查看，打开 当前同步源详情 弹窗。
2. 弹窗展示基本信息（组织名称、来源类型、最近同步时间）与组织架构数据（组织层级数、部门总数、用户总数、各级部门数量等）。
发起同步
删除同步源
1. 单击目标同步源的删除，打开删除确认弹窗。
2. 弹窗展示风险提示：“删除后该同步源下相关数据、配置将全部删除且不可恢复，请谨慎操作。”
3. 输入完整同步源名称进行确认，单击确认删除，完成删除。
注意：
同步任务执行中不可删除同步源。
