RAGFlow源码解析-1、从源码启动并切换引擎和关系数据库为seekdb

RAGFlow 0.25 在 MacBook 2019 16寸上从源码启动完整指南（使用 SeekDB）

一、环境说明

项目	版本/配置
机型	MacBook Pro 2019 16寸
系统	macOS (Darwin)
CPU	Intel x86_64 架构
Python	3.12
RAGFlow	v0.25.0
数据库	SeekDB (OceanBase 精简版)
依赖管理	uv

二、前置准备

1. 安装 uv 和 pre-commit

pipx install uv pre-commit

2. 克隆代码

git clone https://github.com/infiniflow/ragflow.gitcd ragflow# 切换到 0.25.0 版本git checkout v0.25.0

3. 配置 /etc/hosts

sudo vim /etc/hosts

添加以下内容：

127.0.0.1       es01 infinity mysql minio redis sandbox-executor-manager seekdb

三、安装依赖

1. 修复 macOS x86_64 兼容性问题

由于 llvmlite 0.46.0+ 版本没有 macOS x86_64 的预编译包，需要固定版本：

# 编辑 pyproject.toml，在 dependencies 中添加：vim pyproject.toml

找到 dependencies 部分，添加：

"llvmlite==0.45.0",

2. 安装 Python 依赖

uv sync --python 3.12 --all-extrasuv run python3 download_deps.pypre-commit install

四、启动 Docker 依赖服务

1. 启动基础服务

docker compose -f docker/docker-compose-base.yml up -d

启动的服务包括：

MySQL
Redis
MinIO
Elasticsearch (可选)
SeekDB
(本文重点)

2. 验证 SeekDB 状态

# 检查 SeekDB 容器docker ps | grep seekdb# 测试连接docker exec ragflow-seekdb bash -c "mysql -h127.0.0.1 -P2881 -uroot -pinfini_rag_flow -e 'SELECT 1;'"

3. 创建 rag_flow 数据库

docker exec ragflow-seekdb bash -c "mysql -h127.0.0.1 -P2881 -uroot -pinfini_rag_flow -e 'CREATE DATABASE IF NOT EXISTS rag_flow CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;'"

五、修改配置文件

1. 修改 conf/service_conf.yaml

# 添加 seekdb 配置seekdb:  name: 'rag_flow'  user: 'root'  password: 'infini_rag_flow'  host: '127.0.0.1'  port: 2881  max_connections: 900  stale_timeout: 300# 修改 oceanbase 配置（文档引擎）oceanbase:  scheme: 'oceanbase'  config:    db_name: 'test'    user: 'root'    password: 'infini_rag_flow'    host: '127.0.0.1'    port: 2881

注意：SeekDB/OceanBase 的用户格式是 root，不需要 @tenant 格式。

六、代码修改（关键！）

1. 添加 SEEKDB 枚举支持

编辑 api/db/db_models.py：

# 1. TextFieldType 枚举class TextFieldType(Enum):    MYSQL = "LONGTEXT"    OCEANBASE = "LONGTEXT"    SEEKDB = "LONGTEXT"  # 添加这行    POSTGRES = "TEXT"# 2. PooledDatabase 枚举class PooledDatabase(Enum):    MYSQL = RetryingPooledMySQLDatabase    OCEANBASE = RetryingPooledOceanBaseDatabase    SEEKDB = RetryingPooledOceanBaseDatabase  # 添加这行    POSTGRES = RetryingPooledPostgresqlDatabase# 3. DatabaseMigrator 枚举class DatabaseMigrator(Enum):    MYSQL = MySQLMigrator    OCEANBASE = MySQLMigrator    SEEKDB = MySQLMigrator  # 添加这行    POSTGRES = PostgresqlMigrator# 4. DatabaseLock 枚举class DatabaseLock(Enum):    MYSQL = MysqlDatabaseLock    OCEANBASE = MysqlDatabaseLock    SEEKDB = MysqlDatabaseLock  # 添加这行    POSTGRES = PostgresDatabaseLock

2. 支持扁平配置结构

编辑 common/doc_store/ob_conn_pool.py，在 __init__ 方法中：

scheme = self.OB_CONFIG.get("scheme")ob_config = self.OB_CONFIG.get("config", {})# 添加以下三行，支持扁平配置if not ob_config:    ob_config = self.OB_CONFIGif scheme and scheme.lower() == "mysql":

3. 修复重试逻辑 Bug（重要！）

编辑 api/db/db_models.py，找到 RetryingPooledOceanBaseDatabase.execute_sql 方法：

# 修改前（有 Bug）：error_messages = ['', 'Lost connection', 'gone away']# 修改后：error_messages = ['Lost connection', 'gone away']

Bug 说明：原代码中的空字符串 '' 会导致所有OperationalError 都被重试 5 次，包括 “Duplicate column name” 等非连接错误，导致数据库迁移卡死。

七、启动服务

命令行启动

cd /Users/liutao/PycharmProjects/ragflow-0.25.0source .venv/bin/activateexport PYTHONPATH=$(pwd)export DB_TYPE=seekdbexport HF_ENDPOINT=https://hf-mirror.combash docker/launch_backend_service.sh

PyCharm 启动配置

配置项	值
Script path	`api/ragflow_server.py`
Working directory	项目根目录
Environment variables	见下方

环境变量：

PYTHONPATH=/Users/liutao/PycharmProjects/ragflow-0.25.0DB_TYPE=seekdbHF_ENDPOINT=https://hf-mirror.comDOC_ENGINE=seekdb

八、启动前端（可选）

cd webnpm installnpm run dev

前端运行在 http://localhost:8000

九、验证服务

1. 检查端口

lsof -i :9380# 应该看到 python3 进程在监听

2. 测试 API

curl http://localhost:9380/v1/user/login# 返回 {"code":109,"data":false,"message":"Unauthorized!"} 表示服务正常

3. 访问 Web 界面

浏览器打开 http://localhost:9380，应该能看到 RAGFlow 登录页面。

十、遇到的问题及解决方案汇总

问题	原因	解决方案
`llvmlite` 安装失败	0.46.0+ 没有 x86_64 wheel	在 pyproject.toml 中固定 `llvmlite==0.45.0`
`KeyError: 'SEEKDB'`	代码未定义 SEEKDB 枚举	在 4 个枚举类中添加 SEEKDB 支持
SeekDB 连接被拒绝	用户格式错误 (`root@ragflow`)	使用 `root` 无 tenant 格式
数据库 `rag_flow` 不存在	需手动创建	`CREATE DATABASE rag_flow`
HuggingFace 下载超时	网络问题	设置 `HF_ENDPOINT=https://hf-mirror.com`
数据库迁移卡死	重试逻辑 Bug（空字符串匹配所有错误）	移除 `error_messages` 中的空字符串

十一、启动成功标志

        ____   ___    ______ ______ __       / __ \ /   |  / ____// ____// /____  _      __      / /_/ // /| | / / __ / /_   / // __ \| | /| / /     / _, _// ___ |/ /_/ // __/  / // /_/ /| |/ |/ /    /_/ |_|/_/  |_|\____//_/    /_/ \____/ |__/|__/INFO: RAGFlow server is ready after 40.05s initialization.INFO: Running on http://0.0.0.0:9380 (CTRL + C to quit)

十二、参考链接

RAGFlow 官方文档：https://ragflow.io/docs/dev/
RAGFlow GitHub：https://github.com/infiniflow/ragflow
SeekDB GitHub：https://github.com/oceanbase/seekdb
HuggingFace 镜像：https://hf-mirror.com

十三、总结

在 MacBook 2019 (Intel) 上从源码启动 RAGFlow 0.25 并使用 SeekDB 作为数据库，主要需要：

固定依赖版本
：解决 llvmlite 兼容性问题
扩展代码支持
：添加 SEEKDB 枚举
修复关键 Bug
：数据库重试逻辑的空字符串问题
正确配置
：用户名格式、数据库创建、HuggingFace 镜像