飞书云盘数据源使用说明

飞书云盘数据源(feishu_drive / lark_drive)可以把飞书/Lark 云盘某个文件夹下的文档和文件自动同步到 WeKnora 知识库,支持增量同步、定时同步和子文件夹递归。

1. 前置条件:创建飞书应用

1. 登录飞书开放平台(Lark 用户使用 Lark 开放平台),创建企业自建应用。
2. 记录应用的 App ID(cli_ 开头)和 App Secret,配置数据源时需要填写。
3. 按下节表格开通权限,并发布应用版本(权限修改后必须重新发布才生效)。

注意:飞书(open.feishu.cn)和 Lark(open.larksuite.com)是两个独立体系,应用不通用。同步飞书云盘用飞书应用,同步 Lark Drive 用 Lark 应用,凭据不能混用。

2. 所需权限(详细)

在应用后台「权限管理」中开通以下 3 个权限:

说明:

• 与「飞书知识库」连接器相比,云盘不需要 wiki:wiki:readonly,其余权限相同。
• list API 本身还接受 drive:drive(读写)或 space:document:retrieve 作为替代,但推荐只开只读的 drive:drive:readonly,最小授权。
• 权限开通后必须创建并发布新版本,否则接口仍报无权限。

3. 关键一步:把文件夹分享给应用

飞书的权限模型要求:即使应用开通了上述 API 权限,也只能访问被显式分享给它的文件。

1. 创建一个飞书（Lark）群或复用某个飞书（Lark）群
2. 将需要导入的飞书云盘管理者拉进群

PS: 不拉进群也会导致没有访问权限

3. 在飞书云盘中打开目标文件夹;
4. 点击「分享」/「··· → 添加协作者」,把文件夹分享给应用所在的群(把应用拉进一个群,再将文件夹分享给该群),权限给「可阅读」即可;
5. 子文件夹和其中的文件会随父文件夹一起获得授权,无需逐个分享;
6. 如果之后新增的文件同步报 403,检查该文件是否在这棵已分享的目录树下。

这是一次性操作,但不做的话,加载文件夹会直接报「应用无权访问该文件夹」。

4. 配置数据源(四步)

入口:知识库 → 设置 → 数据源 → 新建数据源,选择「飞书云盘」。

第 1 步:选择类型

选择「飞书云盘」(国际版选「Lark Drive」)。

第 2 步:配置凭证

填写 App ID 和 App Secret,点击下一步时系统会自动测试连接(验证 tenant_access_token 能否获取)。此步只验证应用身份,不验证文件夹权限。

第 3 步:选择范围

1. 在「云盘文件夹 Token」输入框填入目标文件夹的 folder_token,或直接粘贴文件夹的完整链接(飞书 https://xxx.feishu.cn/drive/folder/<token> 或 Lark https://xxx.larksuite.com/drive/folder/<token>,系统按路径自动提取 token,两种链接都支持);
2. 点击「加载」,列出该文件夹下的完整目录树;
3. 勾选要同步的文件/文件夹,支持逐级展开、全选/折叠分支。

注意:

• 不支持云空间根目录(根目录不分页且不返回快捷方式),必须选择具体文件夹;
• 加载失败时按提示处理:403 → 回到第 3 节分享文件夹;token 无效 → 重新从文件夹 URL 复制。

第 4 步:同步策略

保存后数据源开始按策略运行,也可在数据源卡片上手动「触发同步」。

5. 支持的文件类型

补充行为:

• docx 中的附件会作为独立知识条目同步(与父文档关联,父文档更新时自动清理已移除的附件);
• 文档内嵌图片会尝试 OCR/多模态解析,未配置对象存储或 VLM 时自动跳过,不影响正文同步。

6. docx 解析模式与环境变量

飞书新版云文档(docx)有两种解析路径,由环境变量 FEISHU_DOCX_PARSE_MODE 控制。该变量作用于 WeKnora app 服务(不是数据源配置),对飞书云盘和飞书知识库两个连接器同时生效。

模式对比

为什么图片关联有差异

• export 模式:导出 .docx 后由 docreader 解析,图片 inline 进父文档(与普通 docx 上传一致),通过 parent_chunk_id 建立同知识条目的父子关联,三个场景都能在一次检索中把图片内容与文档一起返回。
• blocks 模式:走 blocks API,图片 block 渲染成空 ![图片]() 占位符,图片单独下载成独立知识条目,与父文档只有元数据级弱关联。WeKnora 的检索、Wiki 构建、智能体问答链路都不会把图片内容关联回文档,图片和正文是割裂的。

配置方法

在 WeKnora 服务的 .env 或 docker-compose.yml 的 app 服务环境变量中设置:

FEISHU_DOCX_PARSE_MODE=blocks

不设置或设为 export 即用默认模式。修改后需重启 app 服务生效。

export 模式的代价

• 同步变慢:每个 docx 都要走异步导出(创建任务 + 轮询 + 下载)+ docreader 解析,比 blocks API 慢。
• 附件丢失:docx 内 file block 附件不随 .docx 导出下载,如需附件用 blocks 模式或单独同步。
• 图片内容依赖多模态:图片 inline 后 OCR/caption 由多模态服务异步生成,未配置对象存储或 VLM 时图片只存储不生成内容(前端展示正常,但检索层面仍弱)。

选择建议

• 需要图片内容在检索 / Wiki / 智能体中与文档关联:用默认 export。
• 只需文档正文、要保留附件、追求同步速度:用 blocks。

7. 同步行为说明

• 增量同步:以文件修改时间为游标,只拉取上次同步后变更的内容;中断后从断点续传。
• 部分失败不中断:某个子文件夹无权限或某个文件下载失败时,该条目记为失败,其余内容继续同步,失败明细可在「同步日志」中查看。
• 更新语义:内容变更的文件会先删除旧知识条目再重建,解析期间该文档短暂不可用,属正常现象。
• 安全约束:为避免误删,源端删除的文件不会自动从知识库移除(见第 4 步「同步删除」)。

8. 常见问题