数据迁移
1. 功能概述
存储数据迁移用于在不丢失数据的前提下,把业务数据从一种存储搬到另一种存储。典型场景:
- 单机文件存储升级为数据库存储;
- 数据库更换(MySQL → PostgreSQL、SQL Server → SQLite 等);
- 生产数据导出为文件备份,或文件数据导入新环境;
- 多环境之间同步作业配置。
迁移只负责搬运数据,不会自动修改应用的存储配置。迁移完成后需要手动修改 StorageType、DatabaseProvider 与连接字符串并重启应用。

2. 支持范围
| 存储类型 | 标识 | 依赖 |
|---|---|---|
| 文件 | File | 无 |
| MySQL | MySql | Chet.QuartzNet.EFCore.MySQL |
| PostgreSQL | PostgreSql | Chet.QuartzNet.EFCore.PostgreSQL |
| SQLite | SQLite | Chet.QuartzNet.EFCore.SQLite |
| SQL Server | SqlServer | Chet.QuartzNet.EFCore.SqlServer |
五种存储任意两两互转(共 20 个方向)。同一存储类型之间不允许直接迁移;如需在同类数据库间搬运,可以先导出到文件,再从文件导入。
迁移内容
| 数据 | 业务键 | 说明 |
|---|---|---|
| 作业数据 | JobGroup + JobName | 作业定义、触发器、Cron、状态、依赖 |
| 作业日志 | LogId | 执行历史 |
| 系统设置 | Key | 键值型配置 |
| 通知消息 | NotificationId | 通知历史 |
未指定时默认四类全选。服务端按「系统设置 → 作业数据 → 通知消息 → 作业日志」的顺序写入,避免作业先于设置落库。
3. 前置条件
- 安装目标数据库对应的 NuGet 包(版本与主包一致);
- 重启应用,迁移面板会自动识别可用存储;
- 确保应用账号具备:
- 文件源:读取权限;作为目标时需要写权限;
- 数据库源:读取权限;
- 数据库目标:建表 / 改表 / 写入权限;
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. 页面操作
- 登录管理界面,进入「系统设置」页;
- 打开「数据迁移」面板,标题旁会显示当前存储类型;
- 选择迁移源与迁移目标(文件 / 附加数据库 / 当前数据库);
- 选择写入模式与迁移内容;
- 点击「预检」,在弹窗中确认源端 / 目标端数据量与预计写入量;
- 点击「开始迁移」(也可在预检弹窗中直接开始),页面轮询展示各阶段进度;
- 点击「查看摘要」打开弹窗,查看步骤明细、结果与配置建议,按提示切换存储并重启。
只有一种存储时
当前存储之外没有其他可用存储时,页面会隐藏源 / 目标选择并提示先配置 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 或使用当前文件路径 |
| 迁移已完成,无法重复迁移 | 使用「强制重新迁移」 |
| 迁移成功但作业没有变化 | 检查目标存储配置是否已切换并重启 |
更多配置项见 配置说明。