跳到主要内容

数据库架构与迁移 (Database schema and migration)

使用 RAGFlow 官方脚本同步数据库架构（Schema）并迁移数据。

RAGFlow 在启动时会自动处理数据库架构的更新与迁移。但是，对于诸如 Kubernetes 之类的高并发或大规模数据环境，庞大的数据集可能导致初始化时间超过 10 分钟，从而触发容器超时或健康检查失败。为避免这种情况，您可以禁用内置的自动初始化，并在启动服务之前手动运行以下提供的脚本来完成数据库升级：

mysql_migration.py

mysql_migration.py 脚本是一个用于重新组织 RAGFlow 模型相关数据的专用工具。它将数据从旧的统一数据表转换到现代的多表结构中，以支持更高级的模型管理。

核心功能

  • 顺序迁移：数据迁移分为三个不同的阶段（模型商 Provider、实例 Instance 和模型 Model），以维护数据库完整性并满足依赖关系。
  • 灵活的设置：支持使用 YAML 配置文件或直接通过命令行参数连接到 MySQL。
  • 执行控制：提供三种特定模式：dry-run（预览）、table-only（仅结构设置）和 execute（完整数据搬迁）。
  • 自动映射：生成唯一 ID，并处理遗留记录与新表结构之间的复杂关联（Join）。
  • 批量日志记录：以 100 条记录为一组进行分批处理，并在最后提供包含总耗时和行数的摘要。

何时使用

  • 版本升级：在升级到 RAGFlow v0.25 或更高版本时，此工具至关重要，它可以确保您的模型在新架构中被正确分类。
  • 数据规范化：当您需要将多个 API 密钥或 LLM（大语言模型）提供商整合到更新后的系统格式中时需要使用。
  • Kubernetes 部署：在主服务启动之前，使用 --create-table-only 标志独立设置数据库结构非常有用。
  • 迁移验证：在 dry-run 模式下运行，用于识别所有仍需移动到新表中的遗留记录。

db_schema_sync.py

db_schema_sync.py 脚本是一个同步实用工具，用于确保您的 MySQL 数据库结构与 RAGFlow 源码中定义的 Peewee ORM 模型相匹配。

核心功能

  • 变更检测：将 api/db/db_models.py 中的 Python 模型定义与正在运行的数据库进行比较，以识别新表、新增字段或类型不匹配。
  • 迁移文件生成：在特定版本的目录下（例如 tools/migrate/v0_25_0/）自动创建 Python 迁移文件（包含 migrate() 和 rollback() 逻辑）。
  • 架构审计：提供 --diff 命令以查看结构差异，而不应用任何实际更改。
  • 执行管理：将未决（Pending）迁移应用到数据库中，使其与当前软件版本保持最新。
  • 安全控制：通过要求显式的 --drop 标志来生成针对已移除字段的 DROP COLUMN 语句，从而防止意外的数据丢失。

何时使用

  • 版本升级：当迁移到引入了数据库结构性变更的新版 RAGFlow 时。
  • 开发环境：在修改了 db_models.py 后，需要更新本地数据库而不想手动编写 SQL 时。
  • CI/CD 流水线：用于在部署过程中自动准备或应用数据库更新。
  • 问题排查：当应用程序因“未知列（Unknown column）”或“找不到表（Table not found）”错误而失败（这表明架构未同步）时使用。