Skip to content
使用指南

数据迁移

在文件、MySQL、PostgreSQL、SQLite、SQL Server 五种存储之间迁移作业、日志、设置与通知数据。

更新于 2026-11-17MIT 开源

数据迁移 ​

1. 功能概述 ​

存储数据迁移用于在不丢失数据的前提下,把业务数据从一种存储搬到另一种存储。典型场景:

  • 单机文件存储升级为数据库存储;
  • 数据库更换(MySQL → PostgreSQL、SQL Server → SQLite 等);
  • 生产数据导出为文件备份,或文件数据导入新环境;
  • 多环境之间同步作业配置。

迁移只负责搬运数据,不会自动修改应用的存储配置。迁移完成后需要手动修改 StorageType、DatabaseProvider 与连接字符串并重启应用。

数据迁移面板

2. 支持范围 ​

存储类型标识依赖
文件File无
MySQLMySqlChet.QuartzNet.EFCore.MySQL
PostgreSQLPostgreSqlChet.QuartzNet.EFCore.PostgreSQL
SQLiteSQLiteChet.QuartzNet.EFCore.SQLite
SQL ServerSqlServerChet.QuartzNet.EFCore.SqlServer

五种存储任意两两互转(共 20 个方向)。同一存储类型之间不允许直接迁移;如需在同类数据库间搬运,可以先导出到文件,再从文件导入。

迁移内容 ​

数据业务键说明
作业数据JobGroup + JobName作业定义、触发器、Cron、状态、依赖
作业日志LogId执行历史
系统设置Key键值型配置
通知消息NotificationId通知历史

未指定时默认四类全选。服务端按「系统设置 → 作业数据 → 通知消息 → 作业日志」的顺序写入,避免作业先于设置落库。

3. 前置条件 ​

  1. 安装目标数据库对应的 NuGet 包(版本与主包一致);
  2. 重启应用,迁移面板会自动识别可用存储;
  3. 确保应用账号具备:
    • 文件源:读取权限;作为目标时需要写权限;
    • 数据库源:读取权限;
    • 数据库目标:建表 / 改表 / 写入权限;Replace 模式还需要删除权限。

迁移服务由 AddQuartzUI() 自动注册,无需额外代码。

4. 配置数据库与文件来源 ​

4.1 附加数据库(可选) ​

大多数场景只需在「当前数据库」与「文件存储」之间迁移,无需配置本项。需要与另一个数据库双向迁移时,配置一个附加数据库:

json
{
  "QuartzUI": {
    "Migration": {
      "AdditionalStore": {
        "Provider": "MySQL",
        "ConnectionString": "Server=127.0.0.1;Port=3306;Database=quartzui;User=root;Password=***;"
      }
    }
  }
}
  • 页面下拉中显示为「附加数据库 · MySQL」,源和目标均可选择;
  • Provider 接受 MySQL / PostgreSQL / SQLite / SqlServer 及常见别名;
  • 连接字符串只保存在服务端,不会下发到浏览器;
  • 同一时间只配置一个附加数据库;
  • 旧版的 Migration.Profiles 命名配置档仍然兼容,但推荐改用 AdditionalStore。

4.2 文件来源白名单 ​

json
{
  "QuartzUI": {
    "Migration": {
      "FileSources": [
        {
          "Name": "历史文件数据",
          "Path": "D:\\QuartzBackup\\QuartzJobs"
        }
      ]
    }
  }
}

文件源白名单由当前 FileStoragePath 与 FileSources 组成。请求中的路径必须命中白名单,否则会被拒绝。相对路径按应用工作目录解析,建议直接写绝对路径。

5. 页面操作 ​

  1. 登录管理界面,进入「系统设置」页;
  2. 打开「数据迁移」面板,标题旁会显示当前存储类型;
  3. 选择迁移源与迁移目标(文件 / 附加数据库 / 当前数据库);
  4. 选择写入模式与迁移内容;
  5. 点击「预检」,在弹窗中确认源端 / 目标端数据量与预计写入量;
  6. 点击「开始迁移」(也可在预检弹窗中直接开始),页面轮询展示各阶段进度;
  7. 点击「查看摘要」打开弹窗,查看步骤明细、结果与配置建议,按提示切换存储并重启。

只有一种存储时

当前存储之外没有其他可用存储时,页面会隐藏源 / 目标选择并提示先配置 Migration.AdditionalStore 或 FileSources。配置后重启应用即可出现可选目标。

迁移期间可以勾选「暂停调度器」将调度器置为 Standby,避免任务执行干扰写入。

6. 三种写入模式 ​

模式语义适用场景幂等性
合并 Merge不存在则插入,存在则跳过增量同步是
覆盖 Overwrite不存在则插入,存在则更新以源为准刷新目标基本幂等
替换 Replace先清空目标中所选实体,再全量写入整体搬迁、环境重建是,但会删除目标数据

注意

Replace 会删除目标端对应数据,默认被禁用。需要显式配置 AllowReplace: true 后才可使用,执行前会要求二次确认。

7. 执行过程与校验 ​

迁移在后台任务中执行,前端通过轮询获取状态,阶段依次为:

text
参数校验 → 连通性探测 → 统计 → (可选)暂停调度器
→ 备份 → 目标建表 → 分批迁移 → 校验 → 完成

关键机制:

  • 自动备份:文件源自动备份;数据库源不自动备份,请提前自行备份;
  • 自动建表:数据库目标自动执行 EF Core 迁移;
  • 分批处理:默认每批 500 条,可在 1–2000 之间配置;
  • 流式读写:文件端日志与通知采用流式处理,避免大文件占用内存;
  • 迁移后校验:数量校验 + 首 / 中 / 尾抽样校验,差异只告警不阻断。

8. 安全与收尾 ​

  • 数据库连接字符串仅存在于服务端;
  • 文件路径必须在服务端允许列表内;
  • 迁移结果只返回存储展示名,不返回连接字符串;
  • 迁移完成后,修改 QuartzUI:StorageType、DatabaseProvider 与 ConnectionStrings:QuartzUI,重启应用生效;
  • 确认新存储工作正常后再清理旧的备份数据。

9. 常见问题 ​

现象原因 / 处理
未找到迁移配置档检查 Migration.AdditionalStore 是否配置(旧版配置检查 Profiles 名称)
未安装 xxx 包,无法使用该存储安装对应 EFCore 扩展包并重启
源与目标的存储类型相同换成不同类型,或先导出到文件
Replace 模式不可用配置 AllowReplace: true
文件路径不在允许列表中加入 FileSources 或使用当前文件路径
迁移已完成,无法重复迁移使用「强制重新迁移」
迁移成功但作业没有变化检查目标存储配置是否已切换并重启

更多配置项见 配置说明。

让 Quartz.Net 调度,从未如此简单