---
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) — 同类扩展开发模式