将 Milvus Backup 升级至 0.6.xCompatible with Milvus Backup 0.6.x
当您需要将Milvus Backup 工具从 0.5.x 升级至 0.6.x 时,请参考本指南。以下步骤以 0.6.0 作为经过验证的目标版本。此操作不会升级您的 Milvus 服务器。 如果您仍使用 0.5.x 版本,请继续参考0.5.x 版 CLI或API指南。如果是新安装,请使用CLI 指南。
V1 YAML 配置仍可通过自动转换加载。但 0.6.0 版本将拒绝已弃用的 CLI 参数,且 Milvus 3.0 中的默认备份格式已发生变更。在切换计划任务或服务之前,请务必检查配置和命令。
检查起始点
记录您的备份版本、Milvus 源版本和目标版本、配置文件、环境变量覆盖设置、备份位置,以及脚本或 API 服务使用的命令。请查阅这些服务器版本的兼容性信息。
在验证新安装时,请保留原始二进制文件、配置文件和现有备份目录。请通过“获取 Milvus Backup”将 0.6.0 下载到一个单独的目录中。以下所有命令均从该目录运行,并调用 0.6.0 二进制文件。请将您的 v1 配置文件副本放置在configs/backup-v1.yaml 路径下。
迁移配置
v1 配置文件在 0.6.0 中仍可加载。Milvus Backup 会在启动时将其转换为 v2 格式,并输出警告信息。若要将转换后的配置保存到单独的文件中:
./milvus-backup config migrate --config configs/backup-v1.yaml --output configs/backup-v2.yaml --strict
./milvus-backup config show --config configs/backup-v2.yaml
./milvus-backup check --config configs/backup-v2.yaml
--strict 会拒绝无效的迁移配置。若未指定--output ,该命令将把 v2 YAML 写入标准输出。请务必在确认新文件中的设置已正确转换后,再进行审查和使用。
| v1 设置 | v2 设置 |
|---|---|
milvus.address,milvus.port | milvus.grpc.address,milvus.grpc.port |
源存储位于minio.* | milvus.storage.* |
备份存储位于minio.backup* | backup.storage.* |
| 存储凭据 | milvus.storage.auth.* /backup.storage.auth.* ,并显式指定auth.type |
minio.crossStorage | transfer.mode |
backup.gcPause.address | milvus.management.endpoint |
请在与配置文件相同的变更中审查环境变量。V2 仅接受受支持的凭据相关环境变量,例如MILVUS_STORAGE_AUTH_SECRET_ACCESS_KEY 。旧版 v1 的名称不适用于 v2 文件。对于非凭据设置(如存储桶名称和端点),请使用 YAML 或配置键覆盖:
./milvus-backup config show --config configs/backup-v2.yaml --set milvus.storage.bucketName=my-bucket
config migrate 该命令会报告受影响的环境变量,但不会将其机密值复制到输出文件中。请参阅受支持的 v2 环境变量。config show 取代了已弃用的check config 命令。
更新 CLI 命令
在 0.5 版本中已弃用的标志在 0.6.0 版本中将被拒绝。请在升级二进制文件之前更新脚本。
| 命令 | 已移除的选项 | 替代方案 |
|---|---|---|
create | --colls /-c,--databases /-d,--database_collections /-a | --filter |
create | --force /-f | --strategy skip_flush |
create | --meta_only | --strategy meta_only |
restore | --collections /-c,--databases /-d,--database_collections /-a | --filter,使用目标名称 |
restore | --restore_index | --rebuild_index |
get | --detail /-d | 移除该标志;get 将返回备份信息 |
list | --collection /-c | 没有等效的Collection过滤器 |
例如,以下 0.5.16 版本的命令会选择源名称coll :
./milvus-backup create -c coll -n my_backup
./milvus-backup restore -c coll -n my_backup -s _bak
其 0.6.0 版本的替代命令使用目标名称进行恢复:
./milvus-backup create --filter coll -n my_backup --config configs/backup-v2.yaml
./milvus-backup restore --filter coll_bak -n my_backup -s _bak --config configs/backup-v2.yaml
如果恢复过滤器未匹配任何内容,则可成功退出而不会创建 Collection。请务必检查目标 Collection 及其数据。HTTP API 中的 `collection_names ` 仍会选择备份中的源名称;请参阅HTTP API 指南。
选择备份行为
- 在受支持的 Milvus 2.x 服务器上,
auto格式使用二进制日志。升级备份功能无需迁移至 Milvus 3.0。 - 在 Milvus 3.0 上,
auto会选择快照。官方的备份和恢复支持从 Milvus 3.0.1 开始。创建备份时,传递--format binlog参数可保留二进制日志行为。 - V1 配置兼容性不会保留已移除的命令标志,也不会覆盖新格式的默认设置。
- 用途预设可设置格式及其他选项。例如,
--for archive会强制使用二进制日志,即使同时提供了--format snapshot参数也是如此。请仔细审查格式和用途的选择。 - 备份过程中会跳过外部Collection。请检查备份元数据,而非仅凭任务成功就认为所有Collection均已被包含。
切换作业前请进行验证
以下示例保留二进制日志格式,并将数据还原到一个新的 Collection 中。请将 `coll ` 替换为一个您已记录其 Schema、数量、标量和向量值以及搜索结果的 Collection。使用新的备份名称,并确保目标名称coll_upgrade_check 不存在。
./milvus-backup check --config configs/backup-v2.yaml
./milvus-backup create --filter coll --format binlog -n upgrade_check --config configs/backup-v2.yaml
./milvus-backup get -n upgrade_check --config configs/backup-v2.yaml
./milvus-backup restore --filter coll_upgrade_check -n upgrade_check -s _upgrade_check --config configs/backup-v2.yaml
确认备份中包含coll ,且还原后coll_upgrade_check 已存在。如有必要,请创建其向量索引,加载该索引,并将还原后的数据和搜索结果与记录的基线进行比较。在此测试期间,请保持源数据不变。
在使用新工具依赖某个现有备份之前,请先对其进行测试。对于名为legacy_backup 的 0.5.16 版本备份(其中包含coll ),请使用独立的目标名称:
./milvus-backup get -n legacy_backup --config configs/backup-v2.yaml
./milvus-backup restore --filter coll_legacy_check -n legacy_backup -s _legacy_check --config configs/backup-v2.yaml
这些升级路径已在Milvus 2.6.11、备份0.5.16 → 0.6.0 以及 MinIO 中的二进制日志备份中经过验证。无论是新创建的备份还是现有备份,恢复后的实体值和向量搜索结果均与原始数据一致。 这并不意味着所有历史备份或 Milvus 2.x 到 3.0 的恢复操作均兼容。此外,这也不能证明 0.5.x 版本能够读取由 0.6.0 创建的备份。
验证成功后,请更新任务以同时使用新的二进制文件、已验证的配置、环境设置和替换标志。对于 API 部署,请使用已验证的配置启动新服务,并通过HTTP API 验证任务完成情况。若要在 Milvus 3.0.1 或更高版本中采用快照,请参阅《单实例中的快照备份与恢复》。