使用代理网关进行身份同步

本文面向身份集成管理员，说明如何将身份数据跨系统流转目标拆成可配置、可测试、可回退的实施阶段。完成后应能证明数据从来源进入目标系统，并能定位失败对象。

适用版本与验收边界

本文按 6.7.1 系列固定源码基线整理。由于当前仓库没有独立的 6.7.1.1 Tag，正式发布前还需核对实际构建版本，并在目标租户完成运行验证。

场景与目标

以一个可追踪的身份数据对象完成跨系统闭环：明确来源、转换、目标、失败处置和成功证据。

适用条件

当前环境开放对应连接流或代理网关能力。

管理员具备创建、测试和查看日志的最小权限。

已获得目标系统接口、网络、鉴权、字段与错误响应资料。

方案设计

将连接流拆为触发、读取、转换、写入、返回和完成阶段。每个阶段只承担一个明确职责，并保留对象唯一键、任务 ID 和错误信息，便于幂等重试和审计。

实施阶段

先使用单个测试用户和部门完成节点级测试，再执行整流测试；只有返回结构、关系和日志均符合预期后才扩大范围。

概述

在混合云或网络隔离的企业环境中，专属集成平台部署在 SaaS 环境，而下游目标系统（如 Windows AD、LDAP、数据库等）位于企业内网，二者之间存在网络隔离，无法直接通信。代理网关功能通过在企业内网部署轻量级网关组件，建立 SaaS 平台与内网系统之间的安全加密通道，实现稳定的通讯录同步。

应用场景

场景	说明
混合云架构	专属集成平台部署在公有云，需要同步数据到企业私有化部署的内网系统
安全隔离网络	企业内网与外部网络严格隔离，但需要身份数据同步
多区域部署	企业在不同网络区域部署了多个系统，需要通过代理网关统一打通
合规要求	因数据安全合规要求，核心系统部署在内网，但需要与 SaaS 服务集成

解决方案优势

优势	说明
网络穿透	无需更改企业网络安全策略，通过代理网关实现内外网安全连接
统一管理	在专属集成平台上集中管理所有通讯录同步配置，包括内网应用
安全可控	所有通信加密传输，支持访问控制和审计，确保数据安全
灵活部署	支持多种代理网关部署模式，适应不同网络环境需求

准备工作

前提条件	说明
网关部署	已完成代理网关的部署，并确认网关状态正常
网关连接	代理网关已成功连接到专属集成平台，并显示在平台的网关管理列表中
目标系统信息	获取内网目标系统（如 AD）的必要连接信息：服务器地址和端口、管理员账号和密码、BaseDN 等系统特定配置
管理员权限	拥有专属集成平台的管理员权限，以及目标系统的管理员权限

操作步骤

步骤 1：创建通讯录同步连接器

登录专属集成平台管理控制台

在左侧导航栏选择「用户中心 → 通讯录同步」

点击「新建连接器」按钮

选择需要同步的目标系统类型（如 AD、LDAP、数据库等）

按目标系统类型选择连接器后，记录连接器名称和目标网络区域，供后续选择网关。

确认查看通讯录同步连接器列表中的关键配置

步骤 2：配置网关代理

在连接器配置页面中，找到「代理网关」配置项，根据网络环境选择对应的代理方式：

在连接器配置页的代理网关区域选择“不使用”、默认网关或指定网关，并保存当前选择。

代理方式	说明	适用场景
不使用	目标系统可直接通过公网访问，无需代理	目标系统部署在公网或与平台在同一网络环境
默认网关	使用系统指定的默认代理网关访问内网系统	仅部署了单个代理网关的简单环境，无需额外选择
自定义网关	从已部署的多个代理网关中选择特定网关或网关组	部署了多个代理网关的复杂环境，可根据目标系统所在网络区域选择

最佳实践：在有多个网络区域或多个目标系统的环境中，建议部署多个代理网关并进行合理分组，然后在同步配置中选择对应的自定义网关或网关组，实现负载均衡和高可用。

步骤 3：网关连接测试

配置完网关代理后，建议进行连接测试以确认代理网关能够正常访问目标系统：

在连接配置页面底部，找到「测试连接」按钮

输入有效的测试账号（该账号必须存在于目标系统中）

点击「测试连接」按钮

系统将通过配置的代理网关尝试连接目标系统

检查测试结果：

测试成功：显示绿色成功提示，可继续下一步配置

测试失败：显示红色错误信息，需根据下表排查修正

常见测试失败原因及解决方法：

错误信息	可能原因	解决方法
网关连接超时	代理网关未正常运行或网络连接中断	检查代理网关服务状态，确认网关与专属集成平台之间网络畅通
目标系统连接失败	内网地址或端口配置错误，或目标系统未运行	验证内网系统地址和端口是否正确，确认目标系统服务正常运行
认证失败	管理员账号或密码错误	核对并更正管理员账号和密码，确认账号未被锁定或禁用
网关未找到	所选网关不存在或已离线	检查网关部署状态，必要时重新部署或选择其他可用网关

步骤 4：完成其他配置项

代理网关配置验证通过后，继续完成其余通讯录同步配置：

配置同步策略：设置同步周期、同步范围、筛选条件等

设置属性映射：定义平台字段与目标系统字段的对应关系

配置高级选项：根据目标系统类型设置特定参数（如有需要）

保存并激活：保存所有配置并激活同步连接器

网关管理与维护

查看网关状态

定期检查代理网关的运行状态，确保同步任务能够正常执行：

导航至「系统管理 → 网关管理」

查看所有已部署网关的状态信息：

状态	说明
在线	网关正常运行，可以正常使用
离线	网关未连接到平台，需检查网关服务
异常	网关连接异常，可能无法正常使用

分组管理

对于复杂环境，建议通过网关分组实现更灵活的管理：

在「网关管理」页面，点击「网关分组」选项卡

创建新的网关分组，为其指定有意义的名称（如按区域或业务系统分组）

将相关网关添加到分组中

在通讯录同步配置中，可选择特定网关分组作为代理

故障排除

当通过代理网关的同步出现问题时，按以下步骤进行故障排除：

步骤	操作	说明
第一步	检查网关日志	查看网关服务器上的日志文件，识别可能的连接问题
第二步	验证网络连接	确认网关服务器能够正常访问目标内网系统
第三步	检查同步日志	在专属集成平台的同步日志中查找具体错误信息
第四步	更新网关版本	确保使用最新版本的代理网关软件，获取最新功能和修复

最佳实践

网关部署策略

策略	说明
靠近目标系统	将代理网关部署在尽可能接近目标系统的服务器上，减少网络延迟
资源分配	根据同步数据量和频率，为代理网关分配足够的 CPU、内存等系统资源
高可用部署	关键业务场景下，建议部署多个网关并进行分组，实现高可用

安全建议

建议	说明
网关认证	使用强认证方式保护网关与专属集成平台之间的通信
最小权限	为代理网关访问目标系统配置最小必要权限
网络隔离	确保代理网关服务器只能访问必要的内网系统
定期更新	保持代理网关软件的及时更新，修复潜在安全漏洞

性能优化

优化项	说明
同步频率	根据业务需求设置合理的同步频率，避免过于频繁导致系统负载过高
增量同步	优先使用增量同步方式，减少数据传输量
网关扩容	当单个网关处理能力不足时，考虑部署多个网关分担负载

常见问题

Q1：配置了代理网关后同步仍然超时失败，如何处理？

可能原因：

网关服务未正常运行

内网防火墙阻止了网关访问目标系统

目标系统负载过高响应缓慢

解决方法：

检查网关服务状态，确认网关进程正常运行

检查内网防火墙配置，确认网关服务器到目标系统的端口已放行

检查目标系统状态，确认其响应正常

Q2：在有多个网关可用时，如何选择最合适的网关？

选择网关时综合考虑以下因素：

因素	说明
网络距离和延迟	优先选择与目标系统网络延迟最低的网关
性能和负载	选择当前负载较低的网关服务器
稳定性和可用性	优先选择在线时间长、故障率低的网关
业务重要性	重要业务建议使用专用网关，避免共享影响

Q3：网关突然离线，会影响正在进行的同步任务吗？

会。正在进行的同步任务将因网关离线而失败。系统会根据配置的重试策略尝试重新同步，当网关恢复在线状态后，同步任务将在下一次触发时继续执行。建议为关键同步任务配置网关分组以实现高可用。

Q4：如何处理目标系统地址变更的情况？

当内网目标系统地址变更时：

编辑同步连接器配置，更新服务器地址信息

保存配置并进行连接测试，确认新地址可通过代理网关正常访问

必要时调整网关配置以适应新的网络环境

Q5：不同类型的目标系统（AD、LDAP、数据库等）对代理网关配置有区别吗？

代理网关的基本配置流程相同，但不同系统可能需要特定的端口和连接参数。代理网关作为透明代理，不关心上层协议类型，仅负责建立网络通道。具体的目标系统连接参数请参考各系统类型的详细配置文档。

端到端验收

正常对象在目标系统形成预期用户、部门和关系。

重复执行不会生成重复账号或重复关系。

失败对象可在日志或待处理列表中定位，并能安全重试。

删除、停用和恢复分别使用测试对象验证，不从创建成功推断其行为。

风险与限制

外部接口限流、超时、字段约束和部分成功会造成两端状态不一致。批量上线前应设置范围、停止条件和观察窗口；凭据与敏感字段只在受控配置中保存。

回滚与恢复

停止触发和调度，保留任务日志与失败对象清单，恢复上一版连接流配置后用测试对象验证。对已经写入或删除的外部数据，按目标系统备份和恢复机制处理，不能仅通过回滚连接流配置恢复。

使用代理网关进行身份同步

场景与目标#

适用条件#

方案设计#

实施阶段#

概述#

应用场景#

解决方案优势#

准备工作#

操作步骤#

步骤 1：创建通讯录同步连接器#

步骤 2：配置网关代理#

步骤 3：网关连接测试#

步骤 4：完成其他配置项#

网关管理与维护#

查看网关状态#

分组管理#

故障排除#

最佳实践#

网关部署策略#

安全建议#

性能优化#

常见问题#

Q1：配置了代理网关后同步仍然超时失败，如何处理？#

Q2：在有多个网关可用时，如何选择最合适的网关？#

Q3：网关突然离线，会影响正在进行的同步任务吗？#

Q4：如何处理目标系统地址变更的情况？#

Q5：不同类型的目标系统（AD、LDAP、数据库等）对代理网关配置有区别吗？#

端到端验收#

风险与限制#

回滚与恢复#

场景与目标

适用条件

方案设计

实施阶段

概述

应用场景

解决方案优势

准备工作

操作步骤

步骤 1：创建通讯录同步连接器

步骤 2：配置网关代理

步骤 3：网关连接测试

步骤 4：完成其他配置项

网关管理与维护

查看网关状态

分组管理

故障排除

最佳实践

网关部署策略

安全建议

性能优化

常见问题

Q1：配置了代理网关后同步仍然超时失败，如何处理？

Q2：在有多个网关可用时，如何选择最合适的网关？

Q3：网关突然离线，会影响正在进行的同步任务吗？

Q4：如何处理目标系统地址变更的情况？

Q5：不同类型的目标系统（AD、LDAP、数据库等）对代理网关配置有区别吗？

端到端验收

风险与限制

回滚与恢复