🗄️ RAGFlow 完整表结构图 — 数据库存储架构报告

涵盖 MySQL 关系数据库、Elasticsearch/Infinity 文档存储、索引结构及核心代码映射

📅 2026-06-18 📦 RAGFlow v0.25.6 🗄️ MySQL + ES/Infinity 双引擎

📊 存储架构总览

28
MySQL 表
5
ES/Infinity 索引类型
3
支持的数据库引擎
2
文档存储引擎
24+
服务层文件

双引擎架构

存储层引擎用途数据特点
MySQL / OceanBase / PostgreSQL Peewee ORM 元数据、配置、用户、对话等结构化关系数据 支持事务、JOIN、外键级联
Elasticsearch / OpenSearch 自定义 DocStoreConnection Chunk 全文检索 + 向量检索 + 融合排序 HNSW 向量索引、BM25 全文、scripted_sim 相似度
Infinity 自定义 DocStoreConnection Chunk 存储 + 元数据（替代 ES 的可选方案） 支持 HNSW、BMP、全文分析器、二级索引

🏗️ 整体存储架构图

┌─────────────────────────────────────────────────────────────────────────────────┐ │ RAGFlow 数据存储架构 │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────── MySQL / OceanBase / PostgreSQL ─────────────────┐ │ │ │ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐ ┌───────────┐ │ │ │ │ │ user │ │ tenant │ │ user_tenant│ │api_token │ │invitation │ │ │ │ │ └────┬─────┘ └────┬─────┘ └──────┬─────┘ └────┬─────┘ └───────────┘ │ │ │ │ │ │ │ │ │ │ │ │ ┌────┴─────────────┴───────────────┴─────────────┴──────────────────────┐ │ │ │ │ │ knowledgebase ←→ document ←→ file2document ←→ file │ │ │ │ │ └────┬────────────────────┬─────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ │ │ ┌────┴────────────────────┴──────────────────────────────────────────────┐ │ │ │ │ │ dialog ←→ conversation ←→ api4_conversation │ │ │ │ │ │ search │ task │ connector ←→ connector2kb │ │ │ │ │ └──────────┴────────────────┴───────────────────────────────────────────┘ │ │ │ │ │ │ │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ │ │ user_canvas ←→ user_canvas_version │ canvas_template │ │ │ │ │ │ mcp_server │ memory │ system_settings │ │ │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ │ │ llm_factories ←→ llm ←→ tenant_llm ←→ tenant_langfuse │ │ │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ │ │ pipeline_operation_log │ sync_logs │ │ │ │ │ │ evaluation_datasets → evaluation_cases → evaluation_runs │ │ │ │ │ │ evaluation_results │ │ │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌────────────────── ES / Infinity 文档存储 ─────────────────────────────────┐ │ │ │ │ │ │ │ ┌─────────────────────────┐ ┌──────────────────────┐ │ │ │ │ │ ragflow_{tenant_id} │ │ ragflow_doc_meta_ │ │ │ │ │ │ (Chunk 索引, 每租户一个) │ │ {tenant_id} │ │ │ │ │ │ │ │ (文档元数据索引) │ │ │ │ │ │ • Per KB 子表(Infinity) │ │ • meta_fields: JSON │ │ │ │ │ │ • q_{dim}_vec 向量字段 │ │ • kb_id 二级索引 │ │ │ │ │ │ • HNSW/BMP 向量索引 │ └──────────────────────┘ │ │ │ │ │ • 全文分析器索引 │ │ │ │ │ └─────────────────────────┘ │ │ │ │ │ │ │ │ ┌─────────────────────────┐ ┌──────────────────────┐ │ │ │ │ │ ragflow_message_* │ │ ragflow_skill_* │ │ │ │ │ │ (Memory 消息存储) │ │ (Skill 技能存储) │ │ │ │ │ └─────────────────────────┘ └──────────────────────┘ │ │ │ │ │ │ │ └────────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌────────────────── 文件存储 ───────────────────────────────────────────────┐ │ │ │ │ │ │ │ MinIO / S3 对象存储: │ │ │ │ • 上传的原始文档文件 (PDF, DOCX, XLSX, etc.) │ │ │ │ • 解析后的图片/缩略图 │ │ │ │ │ │ │ └────────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌────────────────── 缓存 / 消息队列 ───────────────────────────────────────┐ │ │ │ Redis: │ │ │ │ • Session 缓存 • 任务队列 • 分布式锁 • Canvas DSL 状态 │ │ │ └────────────────────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘

📦 Chunk 存储结构（ES / Infinity 索引）

这是系统的核心检索数据层，所有文档解析后的 Chunk 都存储在这里。

索引命名规则

引擎命名规则示例
Elasticsearch / OpenSearchragflow_{tenant_id}（每租户一个索引，所有 KB 共享）ragflow_abc123
Infinityragflow_{tenant_id}_{kb_id}（每知识库一个子表）ragflow_abc123_kb456

完整字段列表（44 个字段）

id — varchar, Chunk 唯一标识 (xxhash)
doc_id — varchar, 所属文档 ID
kb_id — varchar, 所属知识库 ID（二级索引）
mom_id — varchar, 父 Chunk ID
mom — varchar, 父 Chunk 内容
create_time — varchar, 创建时间
create_timestamp_flt — float, 创建时间戳
img_id — varchar, 关联图片 ID
docnm — varchar, 文档名称（全文索引：rag-coarse + rag-fine）
name_kwd — varchar, 文档名关键词（whitespace-# 分析器）
tag_kwd — varchar, 标签关键词（whitespace-# 分析器）
important_kwd_empty_count — integer, 重要关键词空计数
important_keywords — varchar, 重要关键词（全文索引：rag-coarse + rag-fine）
questions — varchar, 问题列表（全文索引：rag-coarse + rag-fine）
content — varchar, 核心内容（全文索引：rag-coarse + rag-fine）
authors — varchar, 作者信息（全文索引：rag-coarse + rag-fine）
page_num_int — varchar, 页码
top_int — varchar, 页面顶部位置
position_int — varchar, 位置信息 [page, top, bottom, left, right]
weight_int — integer, 整型权重
weight_flt — float, 浮点权重
chunk_order_int — integer, Chunk 排序
rank_int — integer, 排名分数（整型）
rank_flt — float, 排名分数（浮点）
available_int — integer, 可用标志（1=可用, 0=禁用, 二级索引）
knowledge_graph_kwd — varchar, 知识图谱数据（graph/subgraph/etc）
entities_kwd — varchar, 实体关键词（whitespace-# 分析器）
pagerank_fea — integer, PageRank 分数
tag_feas — varchar, Tag 特征向量（rankfeatures 分析器）
from_entity_kwd — varchar, KG 关系源实体
to_entity_kwd — varchar, KG 关系目标实体
entity_kwd — varchar, KG 实体
entity_type_kwd — varchar, KG 实体类型
source_id — varchar, 来源 ID（数据连接器）
n_hop_with_weight — varchar, N-hop 带权重
mom_with_weight — varchar, 父 Chunk 带权重
removed_kwd — varchar, 删除标记（whitespace-# 分析器）
doc_type_kwd — varchar, 文档类型（如 "image"）
toc_kwd — varchar, 目录标记（"toc"）
raptor_kwd — varchar, RAPTOR 标记
raptor_layer_int — integer, RAPTOR 层级
extra — varchar, 扩展字段
q_{dim}_vec — vector(float), 嵌入向量（动态维度, HNSW 索引）

向量索引配置

引擎索引类型参数相似度
ElasticsearchHNSWM=16, ef_construction=50cosine
InfinityHNSW (LVQ 编码)M=16, ef_construction=50, encode=lvqcosine
OpenSearchHNSWM=16, ef_construction=50cosine

关键代码

文件功能
rag/nlp/search.pyDealer 类 — 核心检索、Chunk 增删改查
common/doc_store/doc_store_base.py文档存储抽象基类 (MatchDenseExpr, FusionExpr, OrderByExpr)
common/doc_store/es_conn_base.pyES 连接、索引创建、CRUD 操作
common/doc_store/infinity_conn_base.pyInfinity 连接、表创建、向量索引、全文索引
conf/mapping.jsonES Chunk 索引映射（动态模板：*_int, *_flt, *_tks, *_kwd）
conf/infinity_mapping.jsonInfinity Chunk 表 schema（44 字段定义）

📋 文档元数据索引（ES / Infinity）

存储用户自定义的文档级元数据字段，为检索时按元数据过滤提供数据支撑。

索引结构

字段类型索引说明
idkeyword (ES) / varchar (Infinity)✅ 二级索引文档 ID，主键
kb_idkeyword (ES) / varchar (Infinity)✅ 二级索引知识库 ID
meta_fieldsobject / JSONdynamic: true用户自定义键值对

命名规则

引擎命名示例
ESragflow_doc_meta_{tenant_id}ragflow_doc_meta_abc123
Infinityragflow_doc_meta_{tenant_id}ragflow_doc_meta_abc123

关键代码

文件功能
api/db/services/doc_metadata_service.pyDocMetadataService — 元数据 CRUD、push-down 过滤、批量更新
common/metadata_utils.pymeta_filter() 内存过滤、apply_meta_data_filter() 统一入口
conf/doc_meta_es_mapping.jsonES 元数据索引映射
conf/doc_meta_infinity_mapping.jsonInfinity 元数据表 schema

💬 Memory 消息索引（ES / Infinity）

用于 Agent 的 Memory 功能，存储对话历史消息，支持检索增强记忆。

字段列表

字段类型说明
idvarchar消息唯一 ID
message_idinteger消息序号
message_type_kwdvarchar消息类型
source_idinteger来源 Memory ID
memory_idvarcharMemory 实例 ID
user_idvarchar用户 ID
agent_idvarcharAgent ID
session_idvarchar会话 ID
valid_at / valid_at_fltvarchar/float有效期起始
invalid_at / invalid_at_fltvarchar/float有效期截止
forget_at / forget_at_fltvarchar/float遗忘时间
status_intinteger消息状态
zone_idinteger时区 ID
contentvarchar消息内容（全文索引：rag-coarse + rag-fine）

关键代码

文件功能
api/db/services/memory_service.pyMemoryService — Memory CRUD、消息管理
conf/message_infinity_mapping.jsonInfinity 消息表 schema

🧩 Skill 技能索引（ES / Infinity）

存储 Agent Canvas 中的 Skill 组件定义。

关键代码

文件功能
conf/skill_es_mapping.jsonES Skill 索引映射
conf/skill_infinity_mapping.jsonInfinity Skill 表 schema

🗃️ MySQL 关系表完整清单

1. user MySQL

db_table: user | 行号: 707-747

用途：用户账号、认证、偏好设置。

存储逻辑：标准 MySQL 表，密码为哈希存储，email 唯一约束。is_authenticated/is_active/is_anonymous 用于 Flask-Login 集成。to_safe_dict() 方法在序列化时自动脱敏（隐藏 password, access_token）。

id: CharField(32) — PK, 雪花ID
access_token: CharField(255) — I, 访问令牌
nickname: CharField(100) — I
password: CharField(255) — I, 哈希密码
email: CharField(255) — UNIQUE
avatar: TextField, base64头像
language: CharField(32) — I, 默认中文/英文
color_schema: CharField(32) — I, Bright/Dark
timezone: CharField(64) — I, 默认UTC+8
last_login_time: DateTimeField — I
is_authenticated: CharField(1), default="1"
is_active: CharField(1), default="1"
is_anonymous: CharField(1), default="0"
login_channel: CharField, 登录来源
status: CharField(1) — I, 0=无效/1=有效
is_superuser: BooleanField — I, 超级管理员

服务层：api/db/services/user_service.py — UserService (CRUD, 密码管理, 角色检查)

2. tenant MySQL

db_table: tenant | 行号: 750-771

用途：租户/工作空间，每个用户可以属于多个租户。

存储逻辑：记录租户级别的默认 LLM 模型配置（embedding、chat、ASR、img2txt、rerank、tts）。parser_ids 存储该租户可用的文档处理器列表。通过 UserTenant 表与用户多对多关联。

id: CharField(32) — PK
name: CharField(100) — I, 租户名
public_key: CharField(255) — I
llm_id: CharField(128) — I, 默认LLM
tenant_llm_id: IntegerField — I
embd_id: CharField(128) — I, 默认嵌入模型
tenant_embd_id: IntegerField — I
asr_id: CharField(128) — I, 默认ASR
img2txt_id: CharField(128) — I, 默认图转文
rerank_id: CharField(128) — I, 默认重排序
tts_id: CharField(256), 默认TTS
parser_ids: CharField(256) — I, 文档处理器列表
credit: IntegerField — I, 默认512
status: CharField(1) — I, 0=无效/1=有效

服务层：api/db/services/user_service.py — UserTenantService (租户管理), api/db/services/tenant_llm_service.py

3. user_tenant MySQL

db_table: user_tenant | 行号: 774-783

用途：用户-租户多对多关联表。

存储逻辑：每个关联记录包含角色 (role) 和邀请人 (invited_by)，支持租户内的权限控制。

id: CharField(32) — PK
user_id: CharField(32) — I
tenant_id: CharField(32) — I
role: CharField(32) — I, 角色 (normal/admin/owner)
invited_by: CharField(32) — I
status: CharField(1) — I

服务层：api/db/services/user_service.py — UserTenantService

4. invitation_code MySQL

db_table: invitation_code | 行号: 786-795

用途：租户邀请码管理。

id: CharField(32) — PK
code: CharField(32) — I, 邀请码
visit_time: DateTimeField — I
user_id: CharField(32) — I
tenant_id: CharField(32) — I
status: CharField(1) — I

5. llm_factories MySQL

db_table: llm_factories | 行号: 798-809

用途：LLM 厂商注册表（OpenAI, Qwen, DeepSeek, etc.）。

存储逻辑：系统预置数据（conf/llm_factories.json）。每个厂商下可有多个 LLM 模型。

name: CharField(128) — PK, 厂商名
logo: TextField, base64 Logo
tags: CharField(255) — I, LLM/Embedding/Image2Text/ASR
rank: IntegerField — 排序
status: CharField(1) — I

6. llm MySQL

db_table: llm | 行号: 812-828

用途：LLM 模型定义表（系统预置 + 厂商提供）。

存储逻辑：复合主键 (fid, llm_name)。每个模型归属于一个 llm_factories。tags 字段包含能力标签 (Chat, 32k, tool等)。

llm_name: CharField(128) — I, 模型名 (gpt-4o等)
model_type: CharField(128) — I, LLM/Embedding/Image2Text/ASR
fid: CharField(128) — PK, 厂商ID
max_tokens: IntegerField(0)
tags: CharField(255) — I
is_tools: BooleanField — 是否支持工具
status: CharField(1) — I

服务层：api/db/services/llm_service.py — LLMService

7. tenant_llm MySQL

db_table: tenant_llm | 行号: 831-850

用途：租户级别的 LLM 配置实例（含 API Key）。

存储逻辑：同一租户+厂商+模型名唯一。存储用户自己的 API Key、API Base URL 和 token 使用量。

id: PrimaryKeyField — 自增
tenant_id: CharField(32) — I
llm_factory: CharField(128) — I, 厂商名
model_type: CharField(128) — I
llm_name: CharField(128) — I, 模型名
api_key: TextField, API KEY
api_base: CharField(255), API Base URL
max_tokens: IntegerField — I, 最大上下文Token数
used_tokens: IntegerField — I, 已用Token数
status: CharField(1) — I

服务层：api/db/services/tenant_llm_service.py — TenantLLMService (模型CRUD, token统计)

8. tenant_langfuse MySQL

db_table: tenant_langfuse | 行号: 853-863

用途：Langfuse 观测平台集成配置。

tenant_id: CharField(32) — PK
secret_key: CharField(2048) — I
public_key: CharField(2048) — I
host: CharField(128) — I

9. knowledgebase MySQL

db_table: knowledgebase | 行号: 866-901

用途：知识库/数据集核心元数据表。

存储逻辑：记录知识库的配置参数（相似度阈值、向量权重、解析器、pipeline）、统计信息（文档数、token数、chunk数）以及图RAG/RAPTOR/思维导图的任务状态。对应的 Chunk 数据存储在 ES/Infinity 中。

id: CharField(32) — PK
avatar: TextField, base64
tenant_id: CharField(32) — I
name: CharField(128) — I, KB名
language: CharField(32) — I, 默认中文/英文
description: TextField
embd_id: CharField(128) — I, 嵌入模型ID
tenant_embd_id: IntegerField — I
permission: CharField(16) — I, me/team
created_by: CharField(32) — I
doc_num: IntegerField(0) — Chunk中的文档数
token_num: IntegerField(0) — Token总数
chunk_num: IntegerField(0) — Chunk总数
similarity_threshold: FloatField(0.2)
vector_similarity_weight: FloatField(0.3)
parser_id: CharField(32) — I, 默认naive
pipeline_id: CharField(32) — I
parser_config: JSONField — 页面范围/表格/图片上下文
pagerank: IntegerField(0)
graphrag_task_id: CharField(32) — I
graphrag_task_finish_at: DateTimeField
raptor_task_id: CharField(32) — I
raptor_task_finish_at: DateTimeField
mindmap_task_id: CharField(32) — I
mindmap_task_finish_at: DateTimeField
status: CharField(1) — I

服务层：api/db/services/knowledgebase_service.py — KnowledgebaseService (KB CRUD, 权限检查, 统计)

10. document MySQL

db_table: document | 行号: 904-931

用途：文档元数据表，记录文档的处理状态和统计。

存储逻辑：一个文档属于一个 KB。文档有处理流水线状态 (run=1/2)、进度 (progress)、耗时 (process_duration)。content_hash 用于检测文档内容变更。文档元数据 (自定义字段) 存储在 ES/Infinity 中而非此表。

id: CharField(32) — PK
thumbnail: TextField
kb_id: CharField(256) — I
parser_id: CharField(32) — I
pipeline_id: CharField(32) — I
parser_config: JSONField
source_type: CharField(128) — I, 来源(local/s3/web等)
type: CharField(32) — I, 文件后缀
created_by: CharField(32) — I
name: CharField(255) — I, 文件名
location: CharField(255) — I, 存储路径
size: BigIntegerField(0)
token_num: IntegerField(0)
chunk_num: IntegerField(0)
progress: FloatField(0), 0~1
progress_msg: TextField, 处理状态消息
process_begin_at: DateTimeField — I
process_duration: FloatField(0)
suffix: CharField(32) — I, 真实文件后缀
content_hash: CharField(32) — I, xxhash128
run: CharField(1) — I, 1=运行/2=取消
status: CharField(1) — I

服务层：api/db/services/document_service.py — DocumentService (文档CRUD、状态管理、批量操作)

11. file MySQL

db_table: file | 行号: 934-946

用途：文件管理系统中的文件和文件夹记录。

存储逻辑：树形结构通过 parent_id 实现文件夹嵌套。

id: CharField(32) — PK
parent_id: CharField(32) — I, 父文件夹
tenant_id: CharField(32) — I
created_by: CharField(32) — I
name: CharField(255) — I
location: CharField(255), MinIO路径
size: BigIntegerField(0)
type: CharField(32) — I, 后缀
source_type: CharField(128), 来源

服务层：api/db/services/file_service.py — FileService

12. file2document MySQL

db_table: file2document | 行号: 949-955

用途：文件与文档的多对多映射。

存储逻辑：一个文件可能对应多个文档（如 PDF 拆分），反之亦然。

id: CharField(32) — PK
file_id: CharField(32) — I
document_id: CharField(32) — I

服务层：api/db/services/file2document_service.py — File2DocumentService

13. task MySQL

db_table: task (自动命名) | 行号: 958-974

用途：文档处理任务队列（解析、分块、向量化等）。

存储逻辑：队列式处理，按优先级调度。from_page/to_page 指定处理页面范围。progress/progress_msg 记录实时进度。

id: CharField(32) — PK
doc_id: CharField(32) — I
from_page: IntegerField(0)
to_page: IntegerField(MAXIMUM_TASK_PAGE_NUMBER)
task_type: CharField(32)
priority: IntegerField(0)
begin_at: DateTimeField — I
process_duration: FloatField(0)
progress: FloatField(0)
progress_msg: TextField
retry_count: IntegerField(0)
digest: TextField
chunk_ids: LongTextField

服务层：api/db/services/task_service.py — TaskService (任务CRUD, 队列调度)

14. dialog MySQL

db_table: dialog | 行号: 976-1009

用途：对话应用配置（Chat/Dialog 配置）。

存储逻辑：JSON 字段存储 LLM 设置 (temperature, top_p 等)、prompt 模板（system prompt, prologue, empty_response）、知识库关联 (kb_ids)。meta_data_filter 存储元数据过滤配置。

id: CharField(32) — PK
tenant_id: CharField(32) — I
name: CharField(255) — I
description: TextField
icon: TextField, base64
language: CharField(32) — I
llm_id: CharField(128), 默认LLM
tenant_llm_id: IntegerField — I
llm_setting: JSONField — {temperature, top_p, ...}
prompt_type: CharField(16) — I, simple/advanced
prompt_config: JSONField — {system, prologue, parameters, empty_response}
meta_data_filter: JSONField — 元数据过滤配置
similarity_threshold: FloatField(0.2)
vector_similarity_weight: FloatField(0.3)
top_n: IntegerField(6)
top_k: IntegerField(1024)
do_refer: CharField(1), 是否插入引用
rerank_id: CharField(128), 重排序模型
tenant_rerank_id: IntegerField
kb_ids: JSONField(默认[])
status: CharField(1) — I

服务层：api/db/services/dialog_service.py — DialogService (对话应用CRUD、async_ask)

15. conversation MySQL

db_table: conversation | 行号: 1012-1021

用途：对话会话记录。一个 Dialog 可以有多个 Conversation。

存储逻辑：message 为 JSON 数组存储完整对话历史。reference 为 JSON 存储引用 Chunk 信息。

id: CharField(32) — PK
dialog_id: CharField(32) — I
name: CharField(255) — I
message: JSONField — 对话历史 [{role, content, ...}]
reference: JSONField(默认[]) — 引用列表
user_id: CharField(255) — I

服务层：api/db/services/conversation_service.py — ConversationService (会话管理, 消息追加)

16. api_token MySQL

db_table: api_token | 行号: 1024-1033

用途：API 授权 Token 管理。

tenant_id: CharField(32) — CPK
dialog_id: CharField(32) — I
token: CharField(255) — CPK
beta: CharField(255) — I
source: CharField(16), none/agent/dialog

服务层：api/db/services/api_service.py — APITokenService

17. api_4_conversation MySQL

db_table: api_4_conversation | 行号: 1036-1054

用途：API 方式调用的对话会话（外部 API 集成场景）。

存储逻辑：相比 conversation 多了统计字段 (tokens, duration, round, thumb_up)、dsl 状态快照和版本追踪。

id: CharField(32) — PK
name: CharField(255), 会话名
dialog_id: CharField(32) — I
user_id: CharField(255) — I
exp_user_id: CharField(255) — I, 外部用户ID
message: JSONField
reference: JSONField(默认[])
tokens: IntegerField(0), Token消耗
source: CharField(16), none/agent/dialog
dsl: JSONField(默认{}), Canvas状态
duration: FloatField(0), 响应时间
round: IntegerField(0), 对话轮次
thumb_up: IntegerField(0), 点赞数
errors: TextField
version_title: CharField(255), Canvas版本名

服务层：api/db/services/conversation_service.py — API4ConversationService

18. user_canvas MySQL

db_table: user_canvas | 行号: 1057-1072

用途：Agent Canvas 画布（可视化工作流设计）。

存储逻辑：dsl 为 JSON 存储完整的画布定义（节点、连线、组件配置）。canvas_category 区分 agent_canvas 和 dataflow_canvas。

id: CharField(32) — PK
avatar: TextField
user_id: CharField(255) — I
title: CharField(255)
permission: CharField(16) — I, me/team
release: BooleanField — I, 是否已发布
description: TextField
canvas_type: CharField(32) — I
canvas_category: CharField(32) — I, agent/dataflow
tags: CharField(512), 逗号分隔标签
dsl: JSONField(默认{}) — 画布定义

服务层：api/db/services/canvas_service.py — UserCanvasService

19. canvas_template MySQL

db_table: canvas_template | 行号: 1075-1086

用途：Canvas 模板（系统预置 + 用户自定义）。

存储逻辑：支持多语言标题/描述 (title, description 为 JSON 字典)。

id: CharField(32) — PK
avatar: TextField
title: JSONField — 多语言标题 {zh:..., en:...}
description: JSONField — 多语言描述
canvas_type: CharField(32) — I
canvas_types: ListField
canvas_category: CharField(32) — I
dsl: JSONField(默认{})

20. user_canvas_version MySQL

db_table: user_canvas_version | 行号: 1089-1099

用途：Canvas 版本管理，允许回滚到历史版本。

id: CharField(32) — PK
user_canvas_id: CharField(255) — I
title: CharField(255)
description: TextField
release: BooleanField — I
dsl: JSONField(默认{})

21. mcp_server MySQL

db_table: mcp_server | 行号: 1102-1113

用途：MCP (Model Context Protocol) 服务器配置。

id: CharField(32) — PK
name: CharField(255)
tenant_id: CharField(32) — I
url: CharField(2048)
server_type: CharField(32)
description: TextField
variables: JSONField
headers: JSONField — 额外请求头

服务层：api/db/services/mcp_server_service.py — MCPServerService

22. search MySQL

db_table: search | 行号: 1116-1158

用途：Search App 配置（纯检索型应用）。

存储逻辑：类似 Dialog 但更轻量，专注于检索配置。通过 search_config JSON 存储全部参数。

id: CharField(32) — PK
avatar: TextField
tenant_id: CharField(32) — I
name: CharField(128) — I
description: TextField
created_by: CharField(32) — I
search_config: JSONField — {kb_ids, doc_ids, similarity_threshold, vector_similarity_weight, use_kg, rerank_id, top_k, summary, chat_id, llm_setting, cross_languages, highlight, keyword, web_search, related_search, query_mindmap}
status: CharField(1) — I

服务层：api/db/services/search_service.py — SearchService

23. pipeline_operation_log MySQL

db_table: pipeline_operation_log | 行号: 1161-1184

用途：Pipeline 处理操作日志。

id: CharField(32) — PK
document_id: CharField(32) — I
tenant_id: CharField(32) — I
kb_id: CharField(32) — I
pipeline_id: CharField(32) — I
pipeline_title: CharField(32)
parser_id: CharField(32) — I
document_name: CharField(255)
document_suffix: CharField(255)
document_type: CharField(255)
source_from: CharField(255)
progress: FloatField(0)
progress_msg: TextField
process_begin_at: DateTimeField — I
process_duration: FloatField(0)
dsl: JSONField(默认{})
task_type: CharField(32)
operation_status: CharField(32)
avatar: TextField
status: CharField(1) — I

服务层：api/db/services/pipeline_operation_log_service.py

24-25. connector + connector2kb MySQL

db_table: connector / connector2kb | 行号: 1187-1214

用途：外部数据连接器（OneDrive, Google Drive, Web, IM 等）。

connector:
id: CharField(32) — PK
tenant_id: CharField(32) — I
name: CharField(128)
source: CharField(128) — I
input_type: CharField(128) — I, poll/event
config: JSONField(默认{})
refresh_freq: IntegerField(0)
prune_freq: IntegerField(0)
timeout_secs: IntegerField(3600)
indexing_start: DateTimeField — I
status: CharField(16) — I
connector2kb:
id: CharField(32) — PK
connector_id: CharField(32) — I
kb_id: CharField(32) — I
auto_parse: CharField(1), default="1"

服务层：api/db/services/connector_service.py — ConnectorService

26-29. Evaluation 评测系统 (4 表) MySQL

行号: 1259-1320

用途：RAG 评测系统，管理测试数据集、测试用例、评测运行和结果。

evaluation_datasets:
id: CharField(32) — PK
tenant_id: CharField(32) — I
name: CharField(255) — I
description: TextField
kb_ids: JSONField — 评测目标KB
created_by: CharField(32) — I
create_time: BigIntegerField
update_time: BigIntegerField
status: IntegerField(1)
evaluation_cases:
id: CharField(32) — PK
dataset_id: CharField(32) — I, FK→datasets
question: TextField — 测试问题
reference_answer: TextField — 参考答案
relevant_doc_ids: JSONField
relevant_chunk_ids: JSONField
metadata: JSONField
create_time: BigIntegerField
evaluation_runs:
id: CharField(32) — PK
dataset_id: CharField(32) — I
dialog_id: CharField(32) — I
name: CharField(255)
config_snapshot: JSONField — 评测时的配置快照
metrics_summary: JSONField — 聚合指标
status: CharField(32), PENDING/RUNNING/COMPLETED/FAILED
created_by: CharField(32) — I
create_time: BigIntegerField
complete_time: BigIntegerField
evaluation_results:
id: CharField(32) — PK
run_id: CharField(32) — I, FK→runs
case_id: CharField(32) — I, FK→cases
generated_answer: TextField
retrieved_chunks: JSONField
metrics: JSONField — 全部评测指标
execution_time: FloatField
token_usage: JSONField — prompt/completion tokens
create_time: BigIntegerField

服务层：api/db/services/evaluation_service.py — EvaluationService

30. memory MySQL

db_table: memory | 行号: 1323-1343

用途：Agent Memory 实例配置（元数据层面，消息内容存 ES/Infinity）。

存储逻辑：memory_type 为位标志（1=raw, 2=semantic, 4=episodic, 8=procedural）。forgetting_policy 支持 LRU/FIFO。memory_size 限制消息条数。

id: CharField(32) — PK
name: CharField(128)
avatar: TextField
tenant_id: CharField(32) — I
memory_type: IntegerField(1) — I, 位标志
storage_type: CharField(32) — I, table/graph
embd_id: CharField(128)
tenant_embd_id: IntegerField — I
llm_id: CharField(128)
tenant_llm_id: IntegerField — I
permissions: CharField(16) — I, me/team
description: TextField
memory_size: IntegerField(5242880), 5MB
forgetting_policy: CharField(32), LRU/FIFO
temperature: FloatField(0.5)
system_prompt: TextField
user_prompt: TextField

服务层：api/db/services/memory_service.py — MemoryService

31-32. system_settings + sync_logs MySQL

行号: 1238-1256, 1345-1351
system_settings:
name: CharField(128) — PK, 配置项名
source: CharField(32)
data_type: CharField(32), 数据类型
value: TextField — JSON/string 值
sync_logs:
id: CharField(32) — PK
connector_id: CharField(32) — I
task_type: CharField(32) — I, sync
status: CharField(128)
from_beginning: CharField(1)
new_docs_indexed: IntegerField(0)
total_docs_indexed: IntegerField(0)
docs_removed_from_index: IntegerField(0)
error_msg: TextField, default=""
error_count: IntegerField(0)
full_exception_trace: TextField
time_started: DateTimeField — I
poll_range_start: DateTimeTzField — I
poll_range_end: DateTimeTzField — I
kb_id: CharField(32) — I

服务层：api/db/services/system_settings_service.py, api/db/services/connector_service.py

🔗 核心表关系图

用户与权限

user —⟨ user_tenant ⟩— tenant —⟨ api_token
tenant —⟨ tenant_llm ⟩— llm_factories —⟨ llm
tenant —⟨ tenant_langfuse

知识库与文档处理

tenant —⟨ knowledgebase —⟨ document —⟨ task
document —⟨ pipeline_operation_log

Chunk 检索体系

knowledgebase ⟩== Chunk (ES/Infinity: ragflow_{tenant_id}) ==⟨ document
Chunk 包含 kb_id + doc_id 双向关联，ES 每个租户共享索引，Infinity 按 kb_id 分子表
document ⟩== DocMeta (ES/Infinity: ragflow_doc_meta_{tenant_id})
元数据索引通过 id=doc_id 关联文档，存储用户自定义 meta_fields

对话与会话

dialog —⟨ conversation
dialog —⟨ api4_conversation
api_token —⟨ dialog

Agent Canvas

user_canvas —⟨ user_canvas_version
user_canvas —⟨ canvas_template (参照)

数据连接器

connector —⟨ connector2kb ⟩— knowledgebase
connector —⟨ sync_logs

评测系统

evaluation_datasets —⟨ evaluation_cases
evaluation_datasets —⟨ evaluation_runs —⟨ evaluation_results
evaluation_results.case_id → evaluation_cases

Memory

memory ⟩== Messages (ES/Infinity: ragflow_message_*)

📁 服务层代码映射

MySQL 表服务类服务文件
userUserServiceapi/db/services/user_service.py
tenantUserTenantServiceapi/db/services/user_service.py
user_tenantUserTenantServiceapi/db/services/user_service.py
llm_factories, llmLLMServiceapi/db/services/llm_service.py
tenant_llmTenantLLMServiceapi/db/services/tenant_llm_service.py
tenant_langfuseTenantLangfuseServiceapi/db/services/langfuse_service.py
knowledgebaseKnowledgebaseServiceapi/db/services/knowledgebase_service.py
documentDocumentServiceapi/db/services/document_service.py
fileFileServiceapi/db/services/file_service.py
file2documentFile2DocumentServiceapi/db/services/file2document_service.py
taskTaskServiceapi/db/services/task_service.py
dialogDialogServiceapi/db/services/dialog_service.py
conversation, api_4_conversationConversationService / API4ConversationServiceapi/db/services/conversation_service.py
api_tokenAPITokenServiceapi/db/services/api_service.py
user_canvasUserCanvasServiceapi/db/services/canvas_service.py
user_canvas_versionUserCanvasVersionServiceapi/db/services/user_canvas_version.py
mcp_serverMCPServerServiceapi/db/services/mcp_server_service.py
searchSearchServiceapi/db/services/search_service.py
pipeline_operation_logPipelineOperationLogServiceapi/db/services/pipeline_operation_log_service.py
connector, connector2kbConnectorServiceapi/db/services/connector_service.py
evaluation_*EvaluationServiceapi/db/services/evaluation_service.py
memoryMemoryServiceapi/db/services/memory_service.py
system_settingsSystemSettingsServiceapi/db/services/system_settings_service.py

文档存储层

存储对象管理类/文件服务接口
Chunkrag/nlp/search.py — Dealerretrieval(), search(), chunk_list(), insert(), delete()
DocMetadataapi/db/services/doc_metadata_service.py — DocMetadataServiceget/insert/update/delete/batch_update/filter_doc_ids
Messages (Memory)api/db/services/memory_service.py消息存储与检索

🔧 BaseModel 公共字段

所有 MySQL 表通过 DataBaseModel → BaseModel 继承以下自动管理字段：

字段类型说明自动行为
create_timeBigIntegerField创建时间戳 (秒)insert() 时自动设置为 current_timestamp()
create_dateDateTimeField创建日期由 create_time 自动推导
update_timeBigIntegerField更新时间戳 (秒)每次 update/insert 自动更新为 current_timestamp()
update_dateDateTimeField更新日期由 update_time 自动推导

自定义字段类型：

类型MySQL存储说明
JSONFieldLONGTEXT / TEXT自动序列化为 JSON 字符串，读取时反序列化
ListFieldLONGTEXT / TEXTJSONField 子类，默认值为 []
SerializedFieldLONGTEXT / TEXT支持 PICKLE 或 JSON 序列化
DateTimeTzFieldVARCHAR(255)ISO 8601 带时区的日期时间字符串

⚙️ 数据库引擎配置

支持的引擎

引擎连接池类迁移器分布式锁
MySQLRetryingPooledMySQLDatabaseMySQLMigratorMysqlDatabaseLock (GET_LOCK)
OceanBaseRetryingPooledOceanBaseDatabaseMySQLMigratorMysqlDatabaseLock (GET_LOCK)
PostgreSQLRetryingPooledPostgresqlDatabasePostgresqlMigratorPostgresDatabaseLock (pg_advisory_lock)
ElasticsearchESConnection (elasticsearch-py)N/AN/A
InfinityInfinityConnection (infinity-sdk)N/AN/A

连接重试机制

所有 SQL 数据库通过 RetryingPooled*Database 自动支持连接断开重试（最多 5 次，指数退避：1s→2s→4s→8s→16s）。

所有服务层方法通过 @with_retry 装饰器和 @DB.connection_context() 管理连接生命周期。