104 lines
5.0 KiB
Markdown
104 lines
5.0 KiB
Markdown
|
---
|
|||
|
|
title: 数据源导入开发
|
|||
|
|
tags: [集成扩展, 数据源, 飞书, 同步, 连接器]
|
|||
|
|
aliases: [数据源导入, DataSource, 数据同步]
|
|||
|
|
source: 数据源导入开发文档.md
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 数据源导入开发
|
|||
|
|
|
|||
|
|
WeKnora 的数据源导入模块支持从外部平台（飞书、企业微信、Notion、Confluence 等）自动导入和同步内容到知识库。用户可配置数据源连接，选择需要同步的资源，并通过手动触发或定时调度自动完成内容的增量/全量同步。
|
|||
|
|
|
|||
|
|
数据源绑定到知识库，一个知识库可接入多个数据源。凭证使用 AES-256-GCM 加密存储。
|
|||
|
|
|
|||
|
|
> 数据源导入与 [IM集成开发](../集成扩展/IM集成开发.md) 都涉及飞书集成，可考虑共享飞书应用凭证
|
|||
|
|
|
|||
|
|
## 当前支持的连接器
|
|||
|
|
|
|||
|
|
| 连接器 | 认证方式 | 增量同步 | 删除同步 |
|
|||
|
|
|--------|---------|:-:|:-:|
|
|||
|
|
| 飞书 (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 服务生效。详见 [飞书云盘数据源接入说明](飞书云盘数据源接入说明.md#6-docx-解析模式与环境变量)。
|
|||
|
|
|
|||
|
|
## 架构设计
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
外部平台 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. 前端添加配置
|
|||
|
|
|
|||
|
|
> 扩展开发模式与 [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md) 和 [集成向量数据库](../集成扩展/集成向量数据库.md) 类似
|
|||
|
|
|
|||
|
|
## 相关主题
|
|||
|
|
|
|||
|
|
- [IM集成开发](../集成扩展/IM集成开发.md) — IM 渠道中的飞书集成
|
|||
|
|
- [共享空间说明](../安全认证/共享空间说明.md) — 知识库共享机制
|
|||
|
|
- [常见问题](../运维排障/常见问题.md) — 数据源同步相关故障排查
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 反向链接
|
|||
|
|
|
|||
|
|
- [Home](../Home.md) — Wiki 首页导航
|
|||
|
|
- [IM集成开发](../集成扩展/IM集成开发.md) — 同样涉及飞书集成，可共享应用凭证
|
|||
|
|
- [共享空间说明](../安全认证/共享空间说明.md) — 知识库共享与数据源导入互补
|
|||
|
|
- [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md) — 同类扩展开发模式
|