xinmi/docs/wiki/集成扩展/数据源导入开发.md

title, tags, aliases, source

title	tags	aliases	source
数据源导入开发	集成扩展 数据源 飞书 同步 连接器	数据源导入 DataSource 数据同步	数据源导入开发文档.md

数据源导入开发

WeKnora 的数据源导入模块支持从外部平台（飞书、企业微信、Notion、Confluence 等）自动导入和同步内容到知识库。用户可配置数据源连接，选择需要同步的资源，并通过手动触发或定时调度自动完成内容的增量/全量同步。

数据源绑定到知识库，一个知识库可接入多个数据源。凭证使用 AES-256-GCM 加密存储。

数据源导入与 IM集成开发 都涉及飞书集成，可考虑共享飞书应用凭证

当前支持的连接器

连接器	认证方式	增量同步	删除同步
飞书 (Feishu)	OAuth2 (Tenant Access Token)	✅	✅

快速接入：飞书知识库

1. 创建飞书应用，获取 App ID / App Secret
2. 开通权限：wiki:wiki:readonly、drive:drive:readonly、drive:export:readonly、docx:document:readonly
3. 在知识库设置页添加数据源，选择飞书，填写凭证
4. 测试连接，选择知识库空间，配置同步策略
5. 触发首次同步验证

注意：飞书国际版（Lark）同样支持，自动适配 https://open.larksuite.com 的 API 地址

飞书 docx 解析模式与环境变量

飞书新版云文档（docx）的解析路径由环境变量 FEISHU_DOCX_PARSE_MODE 控制（作用于 app 服务，对飞书知识库和飞书云盘两个连接器同时生效）：

模式	值	解析路径	图片与文档关联	速度	docx 内附件
export（默认）	留空 / export	异步导出 -> .docx 二进制 -> docreader 解析	✅ 图片 inline 进父文档，parent_chunk_id 关联	慢	丢失
blocks	blocks	blocks API -> Markdown	❌ 图片作为独立知识条目，与文档割裂	快	保留

优缺点对比：

• export：导出 .docx 交 docreader 解析，图片 inline 进父文档（与普通 docx 上传一致），通过 parent_chunk_id 建立同知识条目父子关联，三个场景都能关联图片内容；代价是同步变慢（异步导出 + docx 解析）、docx 内附件丢失、图片 OCR/caption 依赖多模态配置。
• blocks：图片 block 渲染成空 ![图片]() 占位符，图片单独下载成独立知识条目，检索 / Wiki / 智能体无法把图片内容关联回文档；但同步快、保留 docx 内 file block 附件。

配置方法：默认即为 export，无需设置；需要 blocks 模式时在 .env 或 docker-compose.yml 的 app 服务环境变量中设置 FEISHU_DOCX_PARSE_MODE=blocks，重启 app 服务生效。详见 飞书云盘数据源接入说明。

架构设计

外部平台 API → Connector → ConnectorRegistry → DataSourceService → WeKnora Core (知识入库管道)

核心设计模式：

模式	用途
Adapter Pattern	统一不同平台的差异
Registry Pattern	按类型动态查找连接器
Strategy Pattern	SyncMode（增量/全量）、ConflictStrategy（覆盖/跳过）
Cursor-based Pagination	增量同步基于 SyncCursor 跟踪变更

关键概念

• DataSource — 数据源：外部平台连接与知识库的绑定
• Connector — 连接器：与外部平台交互的适配层
• SyncCursor — 同步游标：增量同步的状态标记
• FetchedItem — 拉取到的文档条目

API 端点

方法	路径	说明
GET	/api/v1/datasource/types	获取可用连接器类型
POST	/api/v1/datasource/validate-credentials	验证凭证
POST	/api/v1/datasource	创建数据源
GET	/api/v1/datasource?kb_id=xxx	列出数据源
POST	/api/v1/datasource/:id/sync	手动触发同步
POST	/api/v1/datasource/:id/pause	暂停
POST	/api/v1/datasource/:id/resume	恢复

扩展新连接器

1. 实现 Connector 接口（Validate、ListResources、FetchAll、FetchIncremental）
2. 注册连接器到 ConnectorRegistry
3. 前端添加配置

扩展开发模式与 添加网络搜索引擎 和 集成向量数据库 类似

相关主题

• IM集成开发 — IM 渠道中的飞书集成
• 共享空间说明 — 知识库共享机制
• 常见问题 — 数据源同步相关故障排查

---

反向链接

• Home — Wiki 首页导航
• IM集成开发 — 同样涉及飞书集成，可共享应用凭证
• 共享空间说明 — 知识库共享与数据源导入互补
• 添加网络搜索引擎 — 同类扩展开发模式