用户同步

1. 概述

1.1 功能概述

当企业无法通过标准协议（如安全提供程序/单点登录）集成时，Wyn系统（版本≥8.0）提供用户同步解决方案，通过直连数据集，将用户、组织、角色及其关联关系全量同步至Wyn内置库，支持手动/定时同步与失败监控，实现异构系统的用户统一管理。

• 功能原理： 通过直连原始业务系统数据库（如CRM/OA），建立源数据表与Wyn内置表的字段映射，以全量同步策略将数据写入Wyn用户体系，过程中遵循以下规则：

  • 数据隔离： 同步数据来源标记为Synchronizer，与Ul创建/单点登录等来源互不影响

  • 容错机制： 部分失败不影响整体同步，未映射字段保留原值

  • 增量逻辑： 以ID为唯一标识，自动识别新增/更新/删除操作

• 核心能力

  模块	功能描述
  同步范围	用户、组织、角色、用户-组织关系、用户-角色关系(可选配置)
  同步模式	手动触发或定时任务
  运维支持	失败通知、同步历史追溯

• 操作流程

  1. 连接数据源： 配置原始业务系统数据连接（创建数据源）

  2. 建立字段映射： 通过直连数据集关联源表与Wyn内置表字段

  3. 执行同步： 运行服务完成数据同步

     
     

• 同步策略说明： 采用全量同步，数据操作逻辑如下：

  上次同步状态	本次同步状态	执行动作
  存在	存在	更新
  不存在	存在	新增
  存在	不存在	删除

2. 操作步骤

用户同步功能通过连接客户系统的数据源（创建数据源）和数据集（创建直连数据集），获取现有用户数据实现同步。

2.1 前提条件

1. 权限要求： 仅系统管理员可以执行用户同步操作。

2.2 操作步骤

步骤一：连接客户既有系统的用户数据

1. 根据业务系统实际的数据存储形式（数据库/文件/API等），Wyn提供全类型数据源支持（数据连接），确保各类用户同步需求都能得到满足。

2. 本文以Excel数据源为例演示完整用户同步设置流程，您也可使用数据库系统进行同步体验。

   示例文件：用户同步.xlsx

3. 使用上面提供的示例文件，创建Excel数据源。

   
   

步骤二：使用直连数据集建立信息映射

由于各业务系统用户数据格式存在差异，需为每类同步内容（用户/组织/角色/用户组织/用户角色）创建独立的直连数据集（以示例文件为例，需创建5个直连数据集），下文将以组织同步为例进行说明，其他类型操作相同。

1. 创建直连数据集，在数据集中勾选源字段后，需在别名列准确填写Wyn标准字段名（如username→name）完成映射，且必须满足用户同步功能对直连数据集的输出字段要求（部分为必填字段）。

   
   

• 用户同步功能对直连数据集的输出字段要求如下：

  • 用户数据集字段要求

    字段名	是否必须	描述	约束
    id	是	用户id	不能为空
    name	是	用户名	不能为空
    password	否	内置属性：用户密码	将会被用于明文密码，并按照Wyn加密方式进行存储。 更多有关同步密码的内容可以查阅密码同步与应用密钥章节
    email	否	内置属性：用户邮箱
    mobile	否	内置属性：手机号码
    avatar	否	内置属性：头像	只支持URL，不支持二进制数据和base64格式的字符串
    full_name	否	内置属性：用户全名
    first_name	否	内置属性：用户姓氏
    last_name	否	内置属性：用户名字
    enabled	否	内置属性：用户禁用状态
    xxx	否	用户扩展属性	用户同步支持同步用户扩展属性，字段设置需与用户扩展属性名称严格一致，建议统一采用字符串类型，避免格式兼容性问题。 特殊情况： 多值属性处理：在数据集中使用逗号分隔的字符串格式（如"销售,市场,研发"），系统将自动拆分为多个独立值进行同步。 未创建属性处理：若同步字段对应的扩展属性未预先定义，系统会出现警告提示（用户扩展属性未创建），但不会影响用户数据的正常同步。

  • 组织数据集字段要求

    字段名	是否必须	描述	约束
    id	是	内置属性：组织id	不能为空
    parent_id	是	内置属性：父组织id； 为空时表示父组织设置为全局组织。	父组织id不能指定为其他来源的组织的id，全局组织除外
    name	是	内置属性：组织名	不能为空
    xxx	否	组织模型属性	用户同步支持同步组织模型属性，字段设置需与组织模型属性名称严格一致，建议统一采用字符串类型，避免格式兼容性问题。 特殊情况： 在数据集中使用逗号分隔的字符串格式（如"总部,分公司,事业部"），系统将自动解析为多个独立组织模型属性进行同步。 未创建属性处理：若同步字段对应的组织模型属性未预先定义，系统会出现警告提示（组织模型属性未创建），但不会影响组织数据的正常同步。

  • 角色数据集字段要求

    字段名	是否必须	描述	约束
    id	是	角色id	不能为空
    name	是	角色名	不能为空
    org_id	是	角色所属组织id 为空表示全局组织	角色所属组织id不能指定为其他来源的组织id，全局组织除外

  • 用户-组织关系数据集字段要求

    字段名	是否必须	描述	约束
    user_id	是	用户id	不能为空
    org_id	是	用户所属的组织id； 为空时表示全局组织	用户所属组织id值不能为其他来源的组织id，全局组织除外
    is_admin	否	是否要指定该用户为所属组织的组织管理员； 默认：否	字段类型必须是布尔类型

  • 用户-角色关系数据集字段要求

    字段名	是否必须	描述	约束
    user_id	是	用户id	不能为空
    role_id	是	用户所属角色id	不能为空

3. 按要求创建完成后，保存直连数据集。

步骤三：用户同步配置

1. 在文档门户，依次单击「系统管理>账户管理>同步设置」，进入用户同步界面。

   
   

2. 在用户同步界面，同步设置包含开启/关闭同步、同步数据集配置、调度计划、超时控制及失败通知机制这几项。

   
   

• 开启/关闭： 启用或禁用用户同步

  
  

• 选择数据集： 根据同步需求选择数据集类型并关联对应数据集（已创建的对应类型的直连数据集），保存时将自动校验字段完整性，若校验失败会明确提示问题数据集及具体字段。

  
  

• 定时同步设置与手动同步

  • 手动同步： 单击手动同步按钮后，右侧工作区会轮询用户同步任务的状态，当用户同步完成以后，右侧工作区会显示本次同步的结果。用户同步成功后，可在组织管理/角色管理/用户管理界面查看同步成功的组织，角色，用户及其之间的关系。

    
    

  • 用户同步任务的状态说明：

    状态	说明
    成功	成功状态下，所有用户数据同步成功
    警告	警告状态下，部分数据同步成功，同步失败的数据条目包括失败和警告两种类型，在任务结果中可以查看和过滤
    失败	同步任务失败，所有数据都同步失败

  • 定时同步设置： 通过开启自动定时同步功能，可配置详细的执行计划（与Wyn其他任务类型一致），保存后工作区将显示下次执行时间，从而确保Wyn与业务系统的用户数据持续同步更新。

    
    

    type=info

    由于用户同步的日志量较大，建议生产环境中不要将同步频率设置太高。

• 超时设置： 超时设置支持最低1分钟阈值，若任务执行超时则自动终止且不会同步任何数据。

  
  

• 失败通知： 用户同步支持部分数据失败时的容错处理，失败通知将通过Wyn通知中心（除API外）所有已配置的渠道发送，且通知发送状态不影响同步任务结果。

  
  

  失败通知的内容包含：失败通知包含同步时间戳及各维度（用户/组织/角色/用户-角色关系/用户-组织关系）的成功/失败/警告统计数（注：具体失败条目及原因不包含在内），示例如下：

  
  

步骤四：密码同步与应用密钥

1. 由于业务系统密码通常采用不可逆加密存储，Wyn用户同步仅支持明文密码同步；若无法获取明文，可通过应用密钥方案实现安全集成。

   
   

• 应用密钥

  • 用途： 仅限被同步的用户使用，只能用于生成令牌，不可用于系统登录。

  • 注意： 所有通过同步导入的用户均可使用应用密钥生成访问令牌（无论是否设置密码），该密钥专为集成场景设计，须严格保密并定期更新。

  • 使用方法： 通过API使用应用密钥和已同步的用户来生成令牌

    
    

    type=info

    注意： 更改应用密钥不会影响之前生成的token的有效性

3. 用户同步错误码分类与说明

用户同步错误码分为三类：严重错误（导致全部同步失败）、单条错误（影响个别用户数据）和警告（仅导致属性同步失败），具体说明如下表所示。