将飞书文档同步到知识库

适用范围

开始操作前，请确保已准备以下资源：

• 一个已创建的PolarDB知识库。创建方法请参见使用企业知识空间。

• 飞书企业管理员或应用管理员权限，用于审批应用权限和发布应用。

• 待同步文件夹或知识库的管理权限，用于将资源授权给应用。

流程概述

1. 创建飞书企业自建应用，获取App ID和App Secret。

2. 为应用开通云文档读取、下载和导出权限。如果同步飞书知识库，还需开通知识库读取权限。

   说明

   • 如果目标知识空间在创建时开启了文档 ACL，还需开通用户、部门、群组和知识库成员读取权限。

   • 同步到已开启文档 ACL的权限感知空间时，飞书文档的源端访问权限会随文档进入知识库。飞书侧的用户、用户组和部门会映射为规范化权限主体并同步至检索索引，检索时用于执行文档级 ACL 过滤。创建同步链路时无需额外配置权限主体。本文其他步骤中的权限指飞书企业自建应用的 API 权限（Scope），与知识空间的文档级 ACL 不是同一概念。

3. 将待同步的文件夹或知识库授权给该应用。

4. 在PolarDB中创建飞书同步链路，填写应用凭证、飞书资源链接和同步周期。

5. 等待下一个同步周期，在目标知识库中检查文件。

步骤一：创建飞书企业自建应用

1. 登录飞书开放平台，在右上角单击开发者后台。

2. 单击创建企业自建应用，填写应用名称、描述和图标。建议使用容易识别的名称，例如PolarDB 文档同步助手。

3. 进入应用的凭证与基础信息页面，复制并妥善保存以下信息：

   • App ID

   • App Secret

4. 进入应用能力 > 添加应用能力，添加机器人能力，以便后续在飞书中搜索应用并授权资源。

步骤二：开通API权限

1. 在飞书应用管理后台进入权限管理页面。

2. 开通下表中的应用身份权限。

   手动开通

   权限	Scope	适用场景
   查看云空间中文件元数据	drive:drive.metadata:readonly	飞书云盘和知识库
   查看和下载云空间中的文件	drive:file:readonly	飞书云盘和知识库
   导出云文档	docs:document:export	飞书云盘和知识库
   获取云空间文件夹下的云文档清单	space:document:retrieve	飞书云盘文件夹，用于遍历目标文件夹及其子文件夹
   查看知识库	wiki:wiki:readonly	仅同步飞书知识库时需要

   如果目标知识空间在创建时开启了文档 ACL，还需在上述权限基础上开通以下应用身份权限：

   权限	Scope	用途
   获取企业基本信息	tenant:tenant:readonly	获取飞书租户标识，建立 ACL 用户身份命名空间。
   查看云文档协作者	docs:permission.member:retrieve	读取文档、文件夹的协作者及其权限。
   获取通讯录基本信息	contact:contact.base:readonly	查询文档协作者对应的通讯录用户。
   获取用户工号	contact:user.employee_id:readonly	将协作者身份转换为租户内稳定的user_id。
   获取群成员	im:chat.members:read	当文档授权给群组或群聊时，读取群成员并同步有效 ACL。
   获取知识空间成员	wiki:member:retrieve	当知识库空间作为文档权限主体时，读取空间成员；仅同步飞书知识库时需要。

   批量导入

   您可在中导入以下内容：

   {
     "scopes": {
       "tenant": [
         "docs:document:export",
         "drive:drive.metadata:readonly",
         "drive:file:readonly",
         "space:document:retrieve",
         "wiki:wiki:readonly"
       ]
     }
   }

   如果目标知识空间在创建时开启了文档 ACL，可导入以下完整权限清单：

   {
     "scopes": {
       "tenant": [
         "contact:contact.base:readonly",
         "contact:user.employee_id:readonly",
         "docs:document:export",
         "docs:permission.member:retrieve",
         "drive:drive.metadata:readonly",
         "drive:file:readonly",
         "im:chat.members:read",
         "space:document:retrieve",
         "tenant:tenant:readonly",
         "wiki:member:retrieve",
         "wiki:wiki:readonly"
       ]
     }
   }

   说明

   对于获取通讯录基本信息（contact:contact.base:readonly）和获取用户工号（contact:user.employee_id:readonly），建议将应用的可访问数据范围配置为组织全体成员。如果数据范围不包含文档协作者，系统可能无法获取对应用户信息，导致该用户的文档 ACL 信息缺失。

3. 创建应用版本，提交管理员审核并发布。新增权限只有在应用版本发布后才会生效。

步骤三：授权待同步资源

开通API权限后，应用不会自动获得租户内所有文档的访问权限，还需要将待同步的具体资源授权给该应用。

步骤四：创建飞书同步链路

您可以通过控制台或CreateKBSyncLink OpenAPI创建飞书同步链路。

创建成功后，系统返回pkbl-开头的同步链路ID。请妥善记录该ID，后续查询链路、调整同步周期或删除链路时需要使用。

步骤五：验证同步结果

1. 确认同步链路已创建，并且链路状态无异常。

2. 等待至少一个同步周期。飞书文档完成下载、入库和索引处理还需要一定时间，大量文档首次同步时可能需要更长时间。

3. 进入目标知识库的文件列表，确认已出现来自飞书的文件。

4. 修改一篇已同步的飞书文档，等待下一个同步周期后检查知识库中的文件是否已更新。

支持的文件类型

当前同步链路支持以下飞书文件类型：

注意事项

• 一条同步链路仅支持配置一个飞书文件夹、一个知识库空间或一个知识库节点。如需同步多个目录，必须分别创建同步链路。

• 文件夹或知识库中的子节点如果设置了独立的访问限制，应用可能无法读取该节点。请确保应用至少拥有目标节点的阅读权限。

• 当前版本会同步新增和更新的文件，但不会因为飞书源端删除文件而自动删除知识库中的对应文件。如需删除，请在知识库中单独处理。

• 飞书侧的文档权限变更（例如调整协作者或更改文件夹权限）由同步任务增量传播到知识库。传播完成前，系统遵循拒绝优先策略，暂时排除权限状态尚未更新的文档，避免返回潜在越权内容；权限放开后，相关文档可能需要等待下一个同步周期和索引处理完成后才能被召回。

常见问题

• Q：只同步了部分文件。

  A：常见原因包括：

  • 部分子文件夹或子节点没有向应用开放阅读权限。

  • 目标目录中包含当前链路不支持的飞书文件类型。

  • 普通上传文件的格式不在知识库的可解析范围内。

• Q：修改文档后没有立即更新

  A：同步任务按设置的SyncIntervalMinutes参数的周期执行，完成源文档下载后还需要进行后续入库和索引处理。请等待下一个同步周期并预留文档处理时间。

• Q：启用文档 ACL 后，部分用户在知识库中看不到已同步的文档。

  A：常见原因包括：

  • 应用未开通步骤二中的 ACL 增量权限。

  • 应用的通讯录可访问数据范围不包含该协作者。

  • 该用户在飞书源文档上本来就没有阅读权限。

  • 文档授权主体是群组或知识空间，而应用未开通im:chat.members:read或wiki:member:retrieve权限。