飞书完全集成方案

更新时间：2026-02-28 17:35:19

概述

飞书是字节跳动旗下先进协作与管理平台。观远支持与飞书的深度集成，打通两个平台的账号体系，进行便捷的数据分析与智能决策。

集成后可实现以下功能：

• 观远 BI 成为飞书的内嵌应用；
• 观远 Web 端可用飞书扫码/免密快捷登录；
• 从飞书的应用中心访问观远 BI 可免密登录（包括飞书的移动端和 PC 端）；
• 订阅、预警消息推送至飞书，一键触达。

前提条件

在开始配置前，请确保满足以下条件：

• 部署模式： 观远 BI 私有化部署版本。 SaaS 环境由于飞书官方限制，暂不支持飞书集成。观远分析云客户不受此影响。

• 权限要求：

  1. 拥有「飞书开放平台」的企业管理员权限，用于创建和配置应用。
  2. 拥有观远「管理中心 > 系统集成 > 飞书」的编辑权限。
     
     

• 网络环境： 确保观远 BI 服务器可正常访问飞书开放平台的 API 接口。

基础集成配置

操作步骤：

1. 飞书开放平台创建应用：「飞书开放平台 > 开发者后台 > 创建企业自建应用」，填写相关信息后完成创建。在「企业自建应用」中找到已创建的应用，进入「凭证与基础信息」页面，获取「App ID」和「App Secret」。
2. 观远管理中心同步信息：观远「管理中心 > 系统集成 > 办公 OA > 飞书 > 设置配置信息」，填写获取到的飞书应用信息，测试连接成功后「启用」，获取「回调域名」、「桌面端主页」、「移动端主页」。
3. 权限授权与应用发布、配置范围：在飞书应用详情页面按需配置「应用能力」、「安全设置」、「权限管理」，完成后「发布应用」，并且配置「应用可用范围」。

飞书开放平台创建应用

1. 以管理员身份登录 飞书开放平台-开发者后台，点击「创建企业自建应用」，填写「应用名称｜、「应用描述」等信息后点击「创建」。

   
   
   应用创建完成后，系统自动跳转至应用详情页。
   
   

2. 点击「凭证与基础信息」，在此页面获取「App ID」和「App Secret」，用于观远管理后台配置。

   

观远管理中心集成应用

1. 进入观远「管理中心 > 系统集成 > 办公 OA > 飞书」页面，点击「设置配置信息」，在「飞书参数设置」弹窗中填入从飞书获取的 「App ID」和「App Secret」，「测试连接」成功后点击「确定」。
   

   

2. 连接成功后开启飞书集成按钮，系统将生成「回调域名」、「桌面端主页」与「移动端主页」链接，用于飞书应用配置。
   

   
   
   回调地址可从观远管理后台直接获取。私有化环境下，回调域名地址可在「管理中心 > 系统设置 > 通用设置 > 系统规则 > 域名配置」中进行配置，域名的初始状态是 http://localhost:3001/，需要改成企业实际域名。
   说明

   7.4 及以上版本支持子域域名修改。

   

飞书开放平台配置与发布

可以根据实际需求，为应用开启能力。单个应用可开启多种能力，一个能力可用于一个或多个飞书场景。

配置「网页应用」

说明

SSO 登录流程基于网页能力实现，因此此能力必须开启。

1. 返回 飞书开放平台-开发者后台，在新创建的企业自建应用详情页，点击「添加应用能力」，选择「网页应用」，点击下方「添加」，系统跳转至「网页应用」配置页面，

   

2. 将在观远获取的「桌面端主页」和「移动端主页」链接填入对应字段，点击「保存」即可配置成功。

   • 桌面端应用：在桌面端飞书工作台打开应用主页。（桌面端暂不支持调用 Native 能力）
   • 移动端应用：在移动端飞书工作台打开应用主页。
   

配置「配置重定向 URL」

重定向 URL 是保证 SSO 登录流程能正常进行的基本配置，飞书接到登录请求后会重定向到 BI 系统，流程才能往下走。

在飞书应用后台的「安全设置」页面，将在观远获取的「回调域名」填入「重定向 URL」和「H5 可信域名」，完成添加。

注意

• https 与 http 协议需要与实际使用的网址一致；
• URL 末尾的 / 需要保留。

配置「权限管理」

在飞书应用后台的「权限管理」页面中，点击「开通权限」，勾选所需应用能力对应的权限后点击「确认开通权限」。

应用功能对应的权限如下：

应用功能	需开通的权限
免密登录	获取用户 user ID
账户同步	获取通讯录基本信息、获取部门基础信息、获取通讯录部门组织架构信息、获取用户基本信息、获取用户组织架构信息、获取用户邮箱信息、获取用户手机号、获取用户受雇信息
多维表格	查看、评论、编辑和管理多维表格
订阅预警	以应用的身份发消息、给一个或多个部门的成员批量发消息、给多个用户批量发消息、获取与上传图片或文件资源

发布应用并配置可见范围

应用配置完成后，需将当前配置发布后方可使用。

1. 飞书应用后台的「版本管理与发布」页面，点击「创建版本」，填写版本信息后「保存」即可创建并发布应用版本。

   

2. 在「版本详情」页配置相应信息。
   

   

   1. 填写「应用版本号」与「更新说明」，用于展示当前版本信息。

   2. 配置应用「可见范围」：应用配置完成后，需配置可见范围，在可见范围内的用户才可使用该应用。
      点击「编辑」按钮，系统跳转至「可用范围设置」页面，在该页面选择可以使用该应用的成员，支持「全部成员」与「部分成员」。

      • 全部成员：选择全部成员，则该组织架构下的所有成员均可使用此应用。
        
        
      • 部分成员：仅勾选的成员可使用应用，支持通过组织架构/名称搜索选择成员。
        
        

   3. 版本信息与可见范围配置完成后，点击「保存」，即可将应用发布上线。

   4. （可选）后续若需要修改应用可见范围，可在「飞书管理后台 > 应用管理」中进行配置。

      

观远管理中心关联飞书账户

BI 管理后台飞书集成启用后，BI 系统会在「用户基础属性」中自动添加「飞书账号」，管理员可以通过手动添加的方式关联飞书账号，也可通过同步账户数据集的方式关联。

手动关联

单个用户关联

1. 在「飞书管理后台 > 成员与部门」页面，点击想要关联的用户，复制「用户 ID」。

   

2. 在观远 BI「管理中心> 用户管理 > 用户」页面，选中想要关联的目标用户，并填写对应的飞书账号信息，完成关联。

   

批量关联

1. 在「飞书管理后台 > 成员与部门」页面，「批量导出」用户的飞书账号信息。

   

2. 在观远 BI「管理中心> 用户管理 > 用户基础属性管理 > 批量设置」页面，点击「批量上传」按钮，下载模板表格并填写用户对应的飞书账号信息，上传文件后完成批量关联。
   

   

通过账户数据集关联

账户数据集创建可参考 账户数据集。

账户数据集创建完成后，在「管理中心 > 用户管理 > 账户同步」页面，点击右上角「编辑」，在「用户同步」处导入数据集并配置「飞书账号」的匹配方式为「账号」。

效果展示

在飞书「应用中心」找到创建的应用，点击可直接进入 BI 页面。

同时，观远 BI 登录页面也可选择「飞书」作为第三方登录方式，点击「确定」可进行飞书扫码登录，已登录飞书 PC 端可通过「快捷登录」授权进行免密登录。

如需设置默认登录为飞书，则可在「管理中心 > 系统设置 > 登录设置 > 通用设置」中设置默认登录方式为飞书。

进阶配置

免密登录至数据应用

若需要从飞书工作台免密登录进入 BI 某一个具体的应用，需要对飞书应用的主页地址进行调整，将 path_url={应用地址除去BI域名部分} 内容增加上去。BI 后台默认的主页地址只能登录到应用主页面，不会进入到某一个具体的应用。

免密登录至数据应用有以下两种方式：

• 参考 移动端门户或者移动轻应用配置说明 在 BI 「企业配置 > 简易门户」页面将「企业默认页面」设置为数据应用。

• 通过在飞书「网页应用页面」配置跳转地址，详细操作如下。

免密登录至移动端应用

无需手动拼接 URL，可在观远「数据应用 > 移动端应用」页面中，点击目标应用的管理下拉框，选择「飞书集成链接」，快速获取主页地址。

免密登录至桌面端应用

需要将应用地址中的路径拼接到桌面端主页链接中，详细操作如下：

1. 在观远「管理中心 > 系统集成 > 办公 OA > 飞书」页面，获取桌面端主页链接。
   例如：https://open.feishu.cn/open-apis/authen/v1/index?redirect_uri=https%3A%2F%2Fuat.guandata.com%2Fbi-test%2F%3Fprovider%3Dfeishu%26domain%3Dtesting%26path_url%3D&app_id=cli_a3023e14602a600b&state=pc
   
2. 在观远 BI「数据应用 > 桌面端 > 应用」页面，找到目标页面点击预览，即可得到想要登录的具体应用链接。
   例如：https://uat.guandata.com/bi-test/home/web-app/a0a4e3210ca504685bac55b1
   
   
3. 将应用地址域名部分去除，得到 /bi-test/home/web-app/a0a4e4150ca504685bac55b1。
4. 将去除域名后的地址进行 URL 转码，可利用 转码工具 得到加密的地址。
   例如：%2Fbi-test%2Fhome%2Fweb-app%2Fa0a4e4150ca504685bac55b1。
5. 将加密后的地址拼接至桌面端主页地址 path_url%3D 之后，得到最终桌面端应用地址。
   例如 https://open.feishu.cn/open-apis/authen/v1/index?redirect_uri=https%3A%2F%2Fuat.guandata.com%2Fbi-test%2F%3Fprovider%3Dfeishu%26domain%3Dtesting%26path_url%3D%2Fbi-test%2Fhome%2Fweb-app%2Fa0a4e3210ca504685bac55b1&app_id=cli_a3023e14602a600b&state=pc。
6. 将桌面端应用地址填入 飞书开放平台-开发者后台「桌面端主页」即可。
   
   

免密登录至移动端门户

免密登录移动端门户与登录桌面端应用基本一致，区别在于获取目标地址方式不同，获取移动端门户地址操作如下。

在观远 BI「数据应用 > 移动端 > 门户」页面，点击预览后复制链接。

免密登录至桌面端门户

免密登录桌面端门户与登录桌面端应用基本一致，区别在于获取目标地址方式不同，获取桌面端门户地址操作如下。

在观远 BI「数据应用 > 桌面端 > 门户」页面，点击「编辑」，在编辑页面找到目标页面点击预览，即可得到想要登录的具体链接。

跨组织免密登录 BI

飞书支持关联组织共享使用自建应用，当观远 BI 应用共享到其他关联组织时，支持同步其他关联组织成员数据。

当同一用户存在于多个组织时，会有 User ID 不同的情况，为了避免用户在切换组织后导致登录账号不一致，观远 BI 支持使用手机号识别用户身份，同一用户在不同组织免密登录时，仍能以一个身份正常登录。

前提条件

客户的所有关联组织都开通了飞书共享应用，并且被关联组织审批通过，且已成功共享 BI 应用并设置了共享成员。

1. 被关联组织在飞书「管理后台 > 对外协作 > 关联组织」页面点击「分享本组织邀请码」，将二维码发送给主体组织。
   

   

2. 主体组织扫描被关联组织的二维码，选择「共享范围」后，发起关联申请。

   

3. 被关联组织在飞书「管理后台 > 关联组织 > 申请列表 > 建立关联申请」页面，「同意」主体组织的申请，成功建立组织互联关系。
   

   

4. 互联后可在「关联组织详情」页面设置共享范围。
   

   

5. 主体组织在飞书「管理后台 > 对完协作 > 应用互通 > 本企业共享的应用」页面，点击「添加共享应用」。
   

   

6. 勾选需要分享的应用，点击「下一步」。一次只能勾选一个应用。
   

   

7. 勾选需要共享的「关联组织」。
   

   

8. 「确认并发送邀请」即可完成添加，应用可同步至被关联组织的成员。
   

   

操作步骤

1. 在观远「管理中心 > 系统集成 > 办公 OA > 飞书」页面，新增「手机号」作为用户标识信息字段。

   

2. 创建账户数据集。

   1. 在观远「数据准备 > 数据集」页面，点击「新建数据集 > 账户数据集」，选择「飞书连接器」后点击「下一步」。
      
      
   2. 在「选择数据表」下方勾选「高级设置（同步关联组织成员）」。
      
      
   3. 点击「确认新建」，完成数据集创建。
      
      

3. 数据集处理：当一个用户存在于多个组织并使用手机号识别用户时，会有用户数据重复的情况，需要用户根据实际情况通过 Smart ETL 做进一步处理数据，保留一个组织下的用户数据即可（建议保留主体企业）。

4. 同步账号数据集

   1. 在观远「管理中心 > 用户管理 > 账号同步」页面，点击右上角「编辑」。
      

      

   2. 上传处理好的「数据集」。

      

   3. 配置「飞书账号」的「匹配方式」。

      

   4. 选择「手机号」作为匹配字段，成功后即可实现跨组织时通过手机号识别用户。
      

      

订阅与预警推送

将观远 BI 中配置的订阅与预警，自动推送至飞书，支持「消息通知」与「群机器人」两种方式。

说明

使用群机器人推送订阅预警时，需要在 飞书开放平台-开发者后台 完成机器人创建，详情可参考 添加飞书群机器人。

在观远 BI 中配置订阅预警任务时，「通知渠道」选择「飞书」。

效果展示

系统会自动调用已集成的飞书应用权限，将消息发送给指定的飞书用户。

多应用免密登录

多应用免密登录可参考 飞书多应用免密登录。

常见问题

• Q：飞书集成报错：请求非法,请联系应用开发者。
  A：飞书免密登陆会校验请求来源的地址是不是和后台配置的回调地址相同，如果不同则会报这个错误。请按以下步骤排查：

  1. 检查 BI 「管理员中心 > 系统管理 > 通用设置 > 域名配置」是否正确。
  2. 在 飞书开发者后台 确认该应用「开发配置 > 安全设置 > 重定向 URL」是否配置的是 BI 的域名。
  3. 如果是从飞书的工作台打开应用时报的这个错，那就看下飞书应用配置里的「应用能力 > 网页应用 > 网页应用配置」里的桌面端主页和移动端主页地址里，地址是否正确（如果 BI 上域名配置正确，那可以直接复制 BI 上飞书配置最下方的链接）。

• Q：为什么在飞书点击应用或扫码登录时，提示“redirect_uri 校验失败”？

  A： 这是最常见的配置错误。请检查飞书应用后台「安全设置」中的「重定向 URL」，是否与观远管理中心生成的「回调域名」完全一致（包括协议、域名、端口及结尾的“/”）。

• Q：飞书账号关联成功，但免密登录时提示用户不存在或登录失败？

  A： 请按以下步骤排查：

  1. 检查观远用户管理中填写的「飞书账号」是否为该用户在飞书中的唯一 User ID，而非手机号或姓名。
  2. 确保该飞书用户在飞书后台的「应用可用范围」内。
  3. 检查观远与飞书之间的网络连通性。

• Q：跨组织互联后，手机号匹配用户失败如何处理？

  A： 确保以下几点：

  1. 在两个组织的飞书通讯录中，用户的手机号信息已维护且格式一致（如均带国际区号 +86）。
  2. 在观远同步的飞书账户数据集中，包含了关联组织的成员数据，并且手机号字段已被正确抽取。
  3. 通过 ETL 对重复用户数据进行处理（如保留主体组织数据），确保手机号唯一。

• Q：消息推送不到飞书？

  A： 检查飞书应用后台的「权限管理」中，是否已开通 「以应用的身份发消息」等相关权限。同时，确认接收消息的用户或群聊在应用可见范围内。