# RAGFlow v0.17.2 → v0.25.6 知识库相关表结构差异分析

> 分析日期: 2026-06-15
> 源文件: `api/db/db_models.py` (两个版本)

---

## 一、总览

v0.17.2 共 28 个 Model 类，v0.25.6 共 50 个。新增表主要涉及：
- LLM 模型管理重构（tenant_model_provider / tenant_model_instance / tenant_model）
- 新增功能模块（MCP Server、Search、Connector、Evaluation、Memory、SystemSettings 等）

知识库核心 5 张表变化如下：

---

## 二、knowledgebase 表

| # | 字段 | v0.17.2 | v0.25.6 | 差异 |
|---|------|---------|---------|------|
| 1 | id | CharField(32) PK | 同 | — |
| 2 | avatar | TextField nullable | 同 | — |
| 3 | tenant_id | CharField(32) NOT NULL | 同 | — |
| 4 | name | CharField(128) NOT NULL | 同 | — |
| 5 | language | CharField(32) nullable | 同 | — |
| 6 | description | TextField nullable | 同 | — |
| 7 | embd_id | CharField(128) NOT NULL | 同 | — |
| 8 | **tenant_embd_id** | ❌ 不存在 | IntegerField nullable | 🆕 新增。指向 tenant_llm.id 的整数外键 |
| 9 | permission | CharField(16) NOT NULL | 同 | — |
| 10 | created_by | CharField(32) NOT NULL | 同 | — |
| 11 | doc_num | IntegerField | 同 | — |
| 12 | token_num | IntegerField | 同 | — |
| 13 | chunk_num | IntegerField | 同 | — |
| 14 | similarity_threshold | FloatField | 同 | — |
| 15 | vector_similarity_weight | FloatField | 同 | — |
| 16 | parser_id | CharField(32) NOT NULL | 同 | — |
| 17 | **pipeline_id** | ❌ 不存在 | CharField(32) nullable | 🆕 新增。Agent pipeline ID |
| 18 | parser_config | JSONField, default=`{"pages":[[1,1000000]]}` | JSONField, default=`{"pages":[[1,1000000]],"table_context_size":0,"image_context_size":0}` | ⚠️ 默认值扩展 |
| 19 | pagerank | IntegerField | 同 | — |
| 20 | **graphrag_task_id** | ❌ 不存在 | CharField(32) nullable | 🆕 GraphRAG 任务 ID |
| 21 | **graphrag_task_finish_at** | ❌ 不存在 | DateTimeField nullable | 🆕 |
| 22 | **raptor_task_id** | ❌ 不存在 | CharField(32) nullable | 🆕 RAPTOR 任务 ID |
| 23 | **raptor_task_finish_at** | ❌ 不存在 | CharField nullable | 🆕 |
| 24 | **mindmap_task_id** | ❌ 不存在 | CharField(32) nullable | 🆕 思维导图任务 ID |
| 25 | **mindmap_task_finish_at** | ❌ 不存在 | CharField nullable | 🆕 |
| 26 | status | CharField(1) | 同 | — |

**迁移影响**: 新增 8 列，均为 nullable 或有默认值，自动迁移安全。若需保留 embedding 模型引用需手工填充 `tenant_embd_id`。

---

## 三、document 表

| # | 字段 | v0.17.2 | v0.25.6 | 差异 |
|---|------|---------|---------|------|
| 1 | id | CharField(32) PK | 同 | — |
| 2 | thumbnail | TextField nullable | 同 | — |
| 3 | kb_id | CharField(256) NOT NULL | 同 | — |
| 4 | parser_id | CharField(32) NOT NULL | 同 | — |
| 5 | **pipeline_id** | ❌ 不存在 | CharField(32) nullable | 🆕 |
| 6 | parser_config | JSONField, default=`{"pages":[[1,1000000]]}` | JSONField, 默认值扩展 | ⚠️ 同上 |
| 7 | source_type | CharField(128) NOT NULL | 同 | — |
| 8 | type | CharField(32) NOT NULL | 同 | — |
| 9 | created_by | CharField(32) NOT NULL | 同 | — |
| 10 | name | CharField(255) nullable | 同 | — |
| 11 | location | CharField(255) nullable | 同 | — |
| 12 | **size** | ⚠️ IntegerField | BigIntegerField | 🔄 类型变更。int→bigint |
| 13 | token_num | IntegerField | 同 | — |
| 14 | chunk_num | IntegerField | 同 | — |
| 15 | progress | FloatField | 同 | — |
| 16 | progress_msg | TextField nullable | 同 | — |
| 17 | process_begin_at | DateTimeField nullable | 同 | — |
| 18 | **process_duation** | FloatField | 🔄 **process_duration** | 🔄 列重命名 |
| 19 | **suffix** | ❌ 不存在 | CharField(32) NOT NULL, default="" | 🆕 文件真实后缀 |
| 20 | **content_hash** | ❌ 不存在 | CharField(32) nullable, default="" | 🆕 xxhash128 内容哈希 |
| 21 | **meta_fields** | ⚠️ JSONField nullable, default={} | ❌ 已移除 | 🔴 列被删除！ |
| 22 | run | CharField(1) | 同 | — |
| 23 | status | CharField(1) | 同 | — |

**迁移影响**: 
- `meta_fields` 在 v0.25.6 的 Document model 中不存在（已被独立的 `DocMetadataService` / `doc_metadata` 体系取代）。直接 SQL 迁移时该列数据会丢失。
- `process_duation` → `process_duration` 由 `migrate_db()` 自动重命名。
- `size` 类型提升由 `migrate_db()` 自动处理。

---

## 四、file 表

| # | 字段 | v0.17.2 | v0.25.6 | 差异 |
|---|------|---------|---------|------|
| 1 | id | CharField(32) PK | 同 | — |
| 2 | parent_id | CharField(32) NOT NULL | 同 | — |
| 3 | tenant_id | CharField(32) NOT NULL | 同 | — |
| 4 | created_by | CharField(32) NOT NULL | 同 | — |
| 5 | name | CharField(255) NOT NULL | 同 | — |
| 6 | location | CharField(255) nullable | 同 | — |
| 7 | **size** | ⚠️ IntegerField | BigIntegerField | 🔄 类型变更 |
| 8 | type | CharField(32) NOT NULL | 同 | — |
| 9 | source_type | CharField(128) NOT NULL, default="" | 同 | — |

**迁移影响**: 仅 `size` 列类型变更，`migrate_db()` 自动处理。

---

## 五、file2document 表

**无变化**。三个字段 id / file_id / document_id 在两个版本中完全一致。

---

## 六、task 表

| # | 字段 | v0.17.2 | v0.25.6 | 差异 |
|---|------|---------|---------|------|
| 1 | id | CharField(32) PK | 同 | — |
| 2 | doc_id | CharField(32) NOT NULL | 同 | — |
| 3 | from_page | IntegerField | 同 | — |
| 4 | to_page | IntegerField, default=100000000 | IntegerField, default=MAXIMUM_TASK_PAGE_NUMBER | 实际值相同 |
| 5 | **task_type** | ❌ 不存在 | CharField(32) NOT NULL, default="" | 🆕 |
| 6 | **priority** | ❌ 不存在 | IntegerField, default=0 | 🆕 |
| 7 | begin_at | DateTimeField nullable | 同 | — |
| 8 | **process_duation** | FloatField | 🔄 **process_duration** | 🔄 列重命名 |
| 9 | progress | FloatField | 同 | — |
| 10 | progress_msg | TextField nullable | 同 | — |
| 11 | **retry_count** | ❌ 不存在 | IntegerField, default=0 | 🆕 |
| 12 | **digest** | ❌ 不存在 | TextField nullable, default="" | 🆕 任务摘要哈希 |
| 13 | **chunk_ids** | ❌ 不存在 | LongTextField nullable, default="" | 🆕 关联 chunk ID 列表 |

**迁移影响**: 5 个新增列有默认值，列重命名自动处理。Task 表由 `queue_tasks()` 函数在文档上传时自动填充，API 迁移方式无需关心此表。

---

## 七、v0.25.6 自动迁移函数

`migrate_db()` (db_models.py:1600) 按顺序执行：

```
1.  add column: file.source_type
2.  add column: tenant.rerank_id
3.  add column: dialog.rerank_id
4.  alter type: dialog.top_k
5.  add column: tenant_llm.api_key (2048)
6.  add column: api_token.source
... (省略中间步骤)
21. add column: task.task_type, task.priority
22. RENAME: task.process_duation → process_duration
23. RENAME: document.process_duation → process_duration
24. add column: document.suffix (NOT NULL, default="")
... (省略中间步骤)
32. add column: knowledgebase.pipeline_id
33. add column: document.pipeline_id
34. add column: knowledgebase.graphrag_task_id/raptor_task_id/mindmap_task_id etc.
... (省略)
43. alter type: document.size → BigIntegerField
44. alter type: file.size → BigIntegerField
45. add column: knowledgebase.tenant_embd_id
...
```

**关键**: 所有 DDL 变更在 v0.25.6 首次启动时自动执行，无需手工干预。

---

## 八、API 导入方式的优势

采用 API 导入（而非直接 MySQL 迁移）：
1. **无需关心列差异** — v0.25.6 API 按自身 schema 创建记录
2. **自动触发解析** — 文件上传后 `queue_tasks()` 自动入队
3. **无需处理 LLM 表重构** — tenant_llm → provider/instance/model 的迁移完全绕过
4. **MinIO 文件存储共享** — 源和目标的文件路径无关，API 重新上传