rclone-obs-migrator

English

将任意 rclone 远端文件可靠、可恢复地迁移到华为云 OBS。

rclone-obs-migrator（ROM）是一个 Linux 命令行工具。它先将文件下载到本地私有任务工作区，再通过 obsutil 上传，并保留恢复中断任务或重试失败文件所需的状态。

功能

• 按全部文件、年份或 rclone include 模式选择范围。
• 使用结构化的 rclone lsjson 输出和 jq 预览迁移计划。
• 支持先下载后上传、恢复中断任务和重试失败文件。
• 支持有界重试的并发上传和持久化的单文件结果。
• 保留确定性清单、任务状态、日志和摘要报告。
• 通过任务锁防止并发冲突，并且仅在全部上传成功后清理下载文件。

非目标

ROM 不是通用同步引擎、OBS 到 rclone 的反向复制工具、图形界面、常驻服务或分布式调度器。它不创建 rclone 远端、不配置 OBS 凭据、不删除源对象，也不捆绑 obsutil。

运行要求

• Linux
• Bash 4.4 或更高版本
• 已配置源远端的 rclone
• 单独安装并完成认证的 华为云 obsutil
• util-linux 提供的 flock
• iconv
• jq
• 用于 make sensitive 和贡献检查的 Git 与 ripgrep（rg）

上述命令都必须位于 PATH 中。

安装

在已检出的发布版目录执行：

install -d "$HOME/.local/bin" "$HOME/.local/lib"
install -m 0755 bin/rclone-obs-migrator "$HOME/.local/bin/rclone-obs-migrator"
install -m 0644 lib/*.sh "$HOME/.local/lib/"
export PATH="$HOME/.local/bin:$PATH"

命令会解析同一安装前缀下的 bin/ 和 lib/。上述命令会将两者都安装到 ~/.local 下；安装到其他位置时也应保持该布局。

快速开始

Dry-run 只扫描元数据并写入计划，不下载也不上传：

rclone-obs-migrator \
  --source remote:path \
  --target obs://example-bucket/archive \
  --year 2025 \
  --dry-run

执行完整迁移：

rclone-obs-migrator \
  --source remote:path \
  --target obs://example-bucket/archive \
  --year 2025

下载并在生成清单后停止：

rclone-obs-migrator \
  --source remote:path \
  --target obs://example-bucket/archive \
  --year 2025 \
  --download-only

命令会输出任务 ID。以仅上传模式恢复该已下载任务：

rclone-obs-migrator \
  --resume-task task_20260718T120000Z_1234_5678 \
  --upload-only \
  --work-dir .rom

只重试具有持久化失败结果的文件：

rclone-obs-migrator \
  --retry-task task_20260718T120000Z_1234_5678 \
  --work-dir .rom

完整迁移全部成功后删除暂存的下载文件：

rclone-obs-migrator \
  --source remote:path \
  --target obs://example-bucket/archive \
  --all \
  --clean

使用示例配置：

rclone-obs-migrator --config examples/migrator.conf

命令行参数会覆盖配置文件中的值。新任务必须在 --all、--year 和 --include 中且只选一个。

命令行参数

参数	说明
--source REMOTE	remote:path 形式的源；新任务必填。
--target OBS	obs://bucket 或 obs://bucket/prefix 形式的目标；新任务必填。
--all	选择全部源文件。
--year YYYY	选择一个四位年份范围。
--include GLOB	使用 rclone include 模式选择。
--download-only	下载并创建清单后停止。
--upload-only	上传已下载的 --resume-task。
--dry-run	扫描并报告计划，不复制数据。
--parallel N	并发上传数，范围为 1 到 128；默认为 5。
--max-retries N	首次上传失败后的重试次数，范围为 0 到 100；默认为 3。
--resume-task ID	按输出的 ID 恢复任务。
--retry-task ID	只重试任务中失败的上传。
--acl ACL	private、public-read、public-read-write 或 bucket-owner-full-control；默认为 private。
--storage-class CLASS	standard、warm 或 cold；默认为 standard。
--work-dir DIR	工作区根目录；默认为 .rom。
--clean	仅在全部上传成功后清理下载文件。
--config FILE	读取严格的 KEY=VALUE 配置。
-h, --help	显示帮助。
--version	显示版本。

配置文件

空行和以 # 开头的行会被忽略。配置键不得重复或未知，配置值不会作为 Shell 代码求值。

配置键	取值与默认值
SOURCE	remote:path；新任务必填。
TARGET	obs://bucket/prefix；新任务必填。
ALL	true 表示选择全部文件。
YEAR	四位年份范围。
INCLUDE	rclone include 模式。
DOWNLOAD_ONLY	true 或 false；默认为 false。
UPLOAD_ONLY	true 或 false；默认为 false。
DRY_RUN	true 或 false；默认为 false。
PARALLEL	1 到 128 之间的整数；默认为 5。
MAX_RETRIES	0 到 100 之间的整数；默认为 3。
ACL	支持的 OBS ACL；默认为 private。
STORAGE_CLASS	standard、warm 或 cold；默认为 standard。
WORK_DIR	工作区根目录；默认为 .rom。
CLEAN	true 或 false；默认为 false。

ALL、YEAR 和 INCLUDE 互斥。

任务工作区

每次运行都会输出任务 ID 和目录。默认布局如下：

.rom/
└── tasks/
    └── task_<timestamp>_<pid>_<random>/
        ├── config/       # 已验证的任务快照
        ├── downloads/    # 暂存的源文件
        ├── results/      # 持久化的单文件上传结果
        ├── logs/         # 单文件工具输出
        ├── lock
        ├── manifest.tsv
        ├── report.txt     # 在 dry-run 或上传报告阶段生成
        └── status

工作区目录使用私有权限。失败或中断的任务会保留下载文件，以便检查、恢复或重试。

退出码

退出码	含义
0	请求的操作成功完成，或已显示帮助/版本。
1	验证、依赖、加锁、扫描、传输、报告或清理失败。
130	收到 INT 后中断。
143	收到 TERM 后终止。

任何非零退出码都表示迁移失败或未完成，应检查任务状态和报告。

安全默认值

• OBS ACL 默认为 private；只有在评估暴露风险后才应选择公开 ACL。
• ROM 不请求或记录凭据值。rclone 和 obsutil 各自管理其凭据存储。
• 项目不捆绑 obsutil。请从华为云安装并独立校验二进制文件。
• 任务目录默认为私有权限；输入作为参数传递且不使用 eval；dry-run 通过 jq 解析结构化的 lsjson 路径数据。
• 清理默认关闭，且除非所有持久化上传结果均为成功，否则会被拒绝。
• 本地私有扫描 marker 应保存在已忽略的 .legacy-private/ 中，运行 make sensitive 时设置 ROM_PRIVATE_PATTERNS_FILE。

切勿公开 .rom/、rclone 配置、obsutil 配置、传输日志或包含凭据的命令。

故障排查

• **找不到必需命令：**安装报错中指出的依赖，并确认它位于 PATH 中。
• **源验证或扫描失败：**运行 rclone lsd remote:path，确认当前用户已配置该远端。
• **OBS 上传失败：**单独验证 obsutil 认证和目标权限；修正原因后使用 --retry-task。
• **任务已锁定：**确认没有迁移进程仍在运行。不要从正在运行的任务中删除锁状态。
• **任务中断或失败：**检查 .rom/tasks/<ID>/status；如果 report.txt 已生成则一并检查。保留 downloads/，并使用相同的 --work-dir 恢复。
• **Dry-run 结果与预期不符：**传输前检查 manifest.tsv，并调整 --year 或 --include。

使用 make check 运行项目检查。继续阅读文档索引、运维与恢复指南、安全模型或从旧脚本迁移。贡献者还应阅读 CONTRIBUTING.md 和 SECURITY.md。

商标与关联声明

本项目为独立项目，与华为云或 rclone 项目不存在隶属、认可、背书或赞助关系。各产品名称和商标归其各自权利人所有。

许可证

MIT。详见 LICENSE。