本指南旨在帮助管理员解决用户使用飞书账号登录飞连时遇到的各类异常场景（如：提示无权限、用户不存在、页面重定向异常等）。借助本文中的排查方法，管理员可快速定位并解决从“应用权限”到“网络连通性”以及“账号自动映射”等全链路问题。

适用问题 #

• 配置加载类：客户端无法加载登录图标，或点击图标后报错。
• 认证跳转类：浏览器提示 redirect_uri 不合法，或提示 Open platform return error。
• 账号准入类：飞书认证成功后，飞连提示“用户不存在”、“无登录使用权限”或“用户属性缺失”。
• 网络异常类：提示 connection reset by peer 或跳转超时。

已知限制 #

• iOS 平台：在同一台 iPhone 上同时安装了“飞书”和“Lark”时，由于 Deeplink 注册机制相同，可能导致认证跳转时唤起错误的 App，暂无系统级解决方案，建议卸载其中一个或使用浏览器登录。

排查前建议 #

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

第一阶段：飞书开放平台配置校验 #

大部分登录失败源于飞书侧应用配置不当。请先确认已参考配置文档配置无误后，按照以下步骤进行排查：

1. 核心应用权限核对 #

请登录飞书开放平台，确保您的应用已开通以下权限集。

注意：如同时需进行飞书数据源同步，权限要求将更高。此处仅针对“扫码/跳转登录”场景。

建议操作：在“权限管理”中点击“批量导入”，使用以下 JSON：

{
  "scopes": {
    "tenant": [
      "contact:contact.base:readonly",
      "contact:user.base:readonly",
      "contact:user.email:readonly",
      "contact:user.employee_id:readonly",
      "contact:user.phone:readonly"
    ],
    "user": []
  }
}

2. 应用可用范围确认 #

• 检查点：在飞书管理后台版本管理与发布中，确认当前版本的可用范围是否覆盖了尝试登录的用户或部门。若已覆盖，检查该用户在飞书中的状态是否正常。
  

3. 基础凭据匹配 #

• 报错示例：error code 20015, missing appID or appSecret。
• 排查方案：核对飞连管理后台“认证源管理”中的 App ID 与 App Secret 是否与飞书开放平台完全一致（注意去除空格）。
  • 飞连侧
    
  • 飞书侧
    

第二阶段：重定向与网络连通性排查 #

认证过程涉及三方通信：客户端 <-> 飞连 Server <-> 飞书 Server。

1. 回调地址（Redirect URL）校验 #

• 报错现象：提示 redirect_uri不合法。
• 解决步骤：
  1. 在飞连管理后台认证源管理复制“重定向 URL”。
     
  2. 前往飞书开放平台，找对对应应用，选择开发配置 > 安全设置 > 重定向 URL，添加上一步复制的内容。

2. 服务器出网权限（私有化 HA 场景特别注意） #

• 物理 IP 放行：在主备（高可用）部署环境下，飞连 Server 访问飞书接口时使用的是节点物理 IP而非虚 IP（VIP）。
• 排查逻辑：确保两台服务器的物理 IP 均已在防火墙中放行对 open.feishu.cn 和 accounts.feishu.cn 的 443 端口访问。
• 网络诊断：在服务器执行 ping open.feishu.cn 确认解析正常。

第三阶段：单位管理与多组织冲突排查 #

1. 确认子单位配置 #

• 现象：客户端看不到飞书登录图标。
• 解决建议：请检查是否开启了单位管理功能，若开启，用户必须在客户端选择已绑定飞书认证源的正确单位。管理员需检查组织架构与认证源的绑定关系。
  1. 终端用户从客户端确认所选择的单位：
     
     
  2. 管理员从管理后台确认该单位是否配置了飞书认证源:
     

2. 账号组织归属冲突 #

• 报错现象：无登录使用权限。
  
• 原因解析：终端用户可能在飞书中加入了多个组织（租户）。
• 对策：必须确保用户当前飞书 App 切换在与飞连 App ID 对应的那个企业组织下，否则会导致 OpenID 匹配失败。

第四阶段：用户准入与属性映射排查 #

当飞书侧认证成功回到飞连后，需完成“找人”的逻辑。

1. 自动创建用户逻辑 #

• 现象：提示“无法找到对应的用户”。
  
• 解决建议：需至飞连管理后台的身份 > 部门与成员中检索该登录用户是否存在。若不存在：
  • 若企业已配置并开启飞书数据源同步，请参考飞书数据源同步排障指南，检查飞书数据源同步是否运行正常。
  • 若企业未配置飞书数据源同步，并希望来自飞书的新用户在登录时自动创建，需在飞连管理后台身份 > 账号设置 > 认证源管理 > 飞书认证源 > 高级配置中开启"登录未匹配到员工时，自动创建员工账号“。
    

2. 属性缺失或冲突 #

• 报错现象 1：已开启“登录未匹配到员工时，自动创建员工账号”，但提示 用户不存在，自动创建用户缺少xx属性。
  
• 排查方案：
  • 映射核对：在飞连管理后台，检查身份 > 账号设置 > 认证源管理 > 飞书认证源 > 高级配置 > 属性映射策略，确保飞连必填字段（如手机号、邮箱）在飞书侧有对应值且已配置映射。
    
  • 在飞书管理后台，定位到组织架构 > 成员与部门 > 成员详情，检查问题用户在飞书侧，属性是否有值。
    
• 报错现象 2：已开启“登录未匹配到员工时，自动创建员工账号”，但提示用户不存在，且未提及问题属性。
  
• 排查方案：​检查飞连中是否已存在拥有相同手机号/邮箱的用户。
  若飞连已存在同手机号的本地账号，需在飞连管理后台的身份 > 账号设置 > 认证源管理 > 飞书认证源 > 高级配置 > 唯一标识优先级中配置手机号/邮箱作为匹配依据，以完成账号关联而非重复创建。

仍无法解决？ #

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

1. 基础信息：账号名、复现时间点、报错截图、操作系统及浏览器版本。
2. 前端网络日志：复现问题时，按 F12 打开开发者工具，导出 Network (HAR) 日志。
3. 服务端核心日志（针对私有化部署客户）：
   • 路径 1：/opt/corplink/log/portal.*.log（认证核心逻辑）
   • 路径 2：/opt/corplink/log/admin.*.log（管理配置逻辑）