本指南旨在为飞连私有化部署环境下的 IT 管理员和运维工程师，提供一套标准的深度排障流程，用于解决在配置或使用数据源同步（如飞书、钉钉、AD 等）时遇到的各类问题。

在开始通用的排障流程前，我们建议您首先查阅针对特定身份源的常见问题和排障指南。这些文档可能包含了针对您所遇问题的快速解决方案。

• 飞书数据源同步排障指南
• 数据源同步常见问题

如果上述文档未能解决您的问题，请继续遵循下文的排障步骤进行深度排查。

数据源同步失败问题，通常可以从网络连通性和服务日志两个层面进行排查。

步骤一：网络连通性检查

此步骤旨在确认飞连服务器与第三方数据源平台之间的网络是否通畅。

1. 通过 SSH 登录到您的飞连服务器后台。
2. 使用 ping 命令测试网络可达性，以飞书为例：ping open.feishu.cn。
3. 检查是否可以正常请求。如果命令失败或超时，表明存在基础的网络问题。请重点检查您的服务器 DNS 配置、出向防火墙策略以及网络路由。

步骤二：服务日志定位与分析

飞连的同步任务由不同的服务模块负责。排查问题的第一步，是根据同步方式，找到正确的日志文件。

重点关注日志中输出的error级别信息。

• 方法一：通过错误码（err_code）直接定位
  • 日志中的err_code通常能直接揭示问题原因。例如，权限相关的错误、IP 白名单限制、或第三方平台返回的特定业务错误码。
  • 根据错误码的提示，前往对应的第三方平台或飞连后台进行配置修正。

  说明

  如果该err_code表示一个您已知晓且可接受的业务状态（非系统性故障），您可以考虑在飞连的监控告警系统中调整相关规则，以避免不必要的告警。

• 方法二：通过关键词进行深度搜索
  • 如果日志中没有err_code或其含义不明确，您可以在日志文件中搜索以下关键词，以缩小排查范围。
    • 通用关键词：sync_full、sync
    • 平台名称：lark、feishu、weixin、wechat、ding_talk 等
    • 实时同步事件：contact.user.updated_v3、sync_event
  • 通过分析包含这些关键词的错误日志上下文，通常可以定位到具体的失败环节（如“获取部门列表失败”、“更新用户信息失败”等）。

• 飞连认证渠道工程师：请通过飞书搜索飞连 FOC，提交工单处理。
• 企业用户：请通过火山引擎官网提交工单处理。