本文旨在帮助管理员解决在配置或使用“飞书数据源同步”功能时遇到的各类问题，包括组织架构同步失败、部分人员缺失、人员离职未同步以及实时更新失效等。

排查前建议 #

请先阅读数据源同步常见问题，确认您遇到的问题是否已有对应的快速解决方案。若上述文档未能解决您的问题，请遵循本文提供的排查步骤进行深度诊断。

排查前置核心逻辑 #

• 依赖关系：必须先完成一次“全量同步”并确认成功，后续的“实时同步”才能正常生效。
• 增量机制：飞连采用增量同步，若飞书侧账号数据无变化，同步任务会显示“忽略”。

第一阶段：飞书侧权限与可见性校验 #

大部分同步失败（尤其是“读不到人”）源于飞书开放平台侧的配置不当。请先确认已参考配置文档配置无误后，按照以下步骤进行排查：

1. 核心 API 权限核对 #

请登录飞书开放平台，在应用的权限管理中点击批量导入，使用以下 JSON 脚本进行权限一键对齐。

{
  "scopes": {
    "tenant": [
      "admin:admin_dept_stat:readonly",
      "admin:admin_user_stat:readonly",
      "admin:app.user_usable:readonly",
      "application:application.contacts_range:write",
      "contact:contact",
      "contact:contact.base:readonly",
      "contact:department.base:readonly",
      "contact:department.organize:readonly",
      "contact:group:readonly",
      "contact:role:readonly",
      "contact:user.base:readonly",
      "contact:user.department:readonly",
      "contact:user.email:readonly",
      "contact:user.employee:readonly",
      "contact:user.employee_id:readonly",
      "contact:user.gender:readonly",
      "contact:user.id:readonly",
      "contact:user.phone:readonly",
      "corehr:authorization:read",
      "corehr:department.cost_center_id:read",
      "corehr:department.custom_fields:read",
      "corehr:department.manager:read",
      "corehr:department.operation_log:read",
      "corehr:department.organize:read",
      "corehr:department:read",
      "corehr:security_group:read",
      "directory:department.idconvert:read",
      "directory:department:list",
      "directory:department:read",
      "directory:employee.work.staff_status:read",
      "directory:employee:read",
      "passport:session_mask:readonly"
    ],
    "user": [
      "contact:user:search"
    ]
  }
}

2. 应用可用范围核对 #

如果出现部分员工或部门无法同步的情况，可能是由于应用对他们不可见。

1. 在应用详情页，进入版本管理与发布。
2. 检查应用的“可用范围”设置。请确保所有需要被同步到飞连的部门和员工，都包含在可用人员范围之内。
   
3. 检查用户状态：确认同步失败的用户在飞书侧状态为“在职”。

第二阶段：实时同步专项校验 #

若手动同步正常，但飞书侧变动（如新员工入职）无法立即同步至飞连，请检查：

1. 密钥与令牌匹配 #

核对飞连管理后台与飞书开放平台事件与回调页面的 Verification Token（校验令牌）和 Encrypt Key（加密密钥）是否严格一致。

• 飞连侧：
  
• 飞书侧：
  

2. 事件订阅检查 #

在飞书后台确认是否已订阅以下核心通讯录事件，实时同步依赖于这些事件的触发。：

• 员工入职、员工离职、员工信息变更。
• 部门新增、部门删除、部门信息变更。

第三阶段：任务日志审计与业务报错处理 #

飞连提供了详细的“上游 vs 下游”数据对比日志，这是定位问题的关键。

1. 如何查询日志 #

1. 登录飞连管理后台。

2. 导航至身份 ＞ 账号配置 ＞ 数据源同步 ＞ 飞书数据源 ＞ 同步任务。

3. 通过点击左侧历史同步任务查看每次任务下的对象变更情况。
   

4. 点击详情，可以查看该对象上游同步至飞连数据源信息对比。通过左右对比视图可查看员工在上游（飞书）和下游（飞连）的字段映射情况，审计是否有非法字符或映射漏配。
   

2. 常见报错及处理对策 #

仍无法解决？ #

若以上步骤均未奏效，请收集以下材料。企业客户请通过火山引擎提交工单处理；飞连渠道认证工程师请通过飞书搜索飞连 FOC 提交工单处理：

1. 问题描述：
   • 明确同步问题的现象，提供相关的再现步骤和报错截图（如有）；
   • 出问题的账户名称；是个别账户/部门发生问题还是多个账户/部门共同具有相同问题；
   • 问题是否能够稳定复现还是几率偶发；
   • 问题第一次出现的时间，在出现之前是否有系统配置更改？
   • 这是一个新部署的功能么？如果不是的话，该部署最后一次正常工作的时间。
2. 飞书侧服务日志：提供同步失败时间段内，飞书开放平台应用后台的运行日志。
   
3. 飞连服务端后台日志（针对私有化部署）：
   • 手动同步故障：/opt/corplink/log/admin.*.log
   • 定时自动同步故障：/opt/corplink/log/cron.*.log
   • 实时同步故障：/opt/corplink/log/portal.*.log
     以上日志文件也可登录飞连运维平台，定位至集群管理 ＞ 服务列表 ＞ 管理后台 ＞ 查看详情 ＞ 服务日志，下载 admin.*.log 获取。