Olares CLI `backups backup` 实战指南：将数据备份到 COS、S3、本地文件系统与 Olares Space

• 云原生
• 后端
• 运维

olares-cli backups backup是 Olares 命令行工具中用于执行数据备份的核心子命令，它基于 Restic 备份引擎，可将指定目录（如/data）备份到腾讯云对象存储（COS）、Amazon S3、本地文件系统以及 Olares Space 四种存储后端。本文将以 backups-backup.md 为骨架，完整讲解命令语法、全部参数选项、四种后端的配置方法，并结合仓库源码剖析其依赖安装与底层实现，帮助你在 Olares 主机上独立完成一次可靠、可验证的数据备份。

前置条件：必须先安装 Restic 备份引擎

backups backup依赖 Restic 执行实际的备份任务。运行前必须先通过olares-cli backups download命令安装 Restic，否则直接运行backup将返回错误。

# 默认下载并安装 Restic（系统默认 CDN 地址） olares-cli backups download # 通过自定义 CDN 地址下载 olares-cli backups download --download-cdn-url https://custom-cdn.example.com/restic

Restic 的安装逻辑可在 cli/pkg/files/file.go 中看到：CLI 会将下载的 Restic 二进制解压（bzip2），然后执行cp <target> /usr/local/bin/restic && chmod +x /usr/local/bin/restic将其安装到系统可执行路径。因此安装完成后可直接在命令行调用restic。

注意：该命令需要 root 权限。请使用 root 用户执行，或在命令前加上sudo（参见 命令参考）。如果你通过 WSL 方式安装 Olares，请在 WSL 环境中运行olares-cli，而非 PowerShell。

命令语法与通用选项

backups backup的完整语法如下：

olares-cli backups backup <存储后端> --path <备份路径> --repo-name <仓库名称> [选项]

其中<存储后端>是必填位置参数，用于指定目标存储类型；backups命令族支持的后端及简要说明见 backups.md：

以下通用选项适用于所有后端：

--repo-name是备份仓库的唯一标识：同一仓库的多次备份会累积为快照历史，恢复时可选择任意快照。建议按业务语义命名，例如my_repo、data_2026，并保持backup与后续restore、snapshots命令中的仓库名称一致。

四种存储后端配置详解

腾讯云对象存储（cos）

要点说明：

• --endpoint由区域（region）、存储桶（bucket）和可选前缀（prefix）三段构成，例如https://cos.ap-guangzhou.myqcloud.com/my-bucket/backup/，请替换为你的实际值；
• --access-key/--secret-access-key对应腾讯云 API 密钥（SecretId / SecretKey），可在腾讯云控制台「访问管理 → API 密钥管理」中获取；
• --limit-upload-rate用于限制上传带宽，单位为 KiB/s，适合在共享带宽场景下避免备份占用全部上行流量；不设置时默认不限速。

本地文件系统（fs）

fs后端无需任何凭据，--endpoint直接指向本机（或挂载的 NAS、USB 磁盘等）的一个目录，例如/backup_repo。Olares 支持挂载本地磁盘与共享目录（见 mount-local-disk.md），可以将备份仓库放到独立磁盘上，实现数据与系统盘分离。

Amazon S3（s3）

--endpoint示例：https://my-bucket.s3.us-east-1.amazonaws.com/backup/。与 COS 类似，需要提供访问密钥、密钥；S3 兼容的第三方对象存储（如 MinIO、R2 等）通常也可通过--endpoint指定其 API 地址来使用该后端。

Olares Space（space）

space后端需要准备四类身份信息：

1. 访问令牌与 Olares DID：登录 Olares Space 后，检查页面网络请求的负载（Payload），其中token字段对应访问令牌（--access-token），userid字段对应 Olares DID（--olares-did）。

2. 集群 ID：在 Olares 主机上运行以下命令获取：

   kubectl get terminus -o jsonpath='{.items[*].metadata.labels.bytetrade\.io/cluster-id}'

3. 云名称与区域 ID：可先运行olares-cli backups region space查询：

   olares-cli backups region space \ --access-token YOUR_ACCESS_TOKEN \ --cloud-api-mirror https://api-mirror.example.com \ --olares-did did:xyz123

   region命令会返回云名称（--cloud-name）和区域 ID（--region-id），将其填入 backup 命令即可。

完整使用示例

# 备份到腾讯云对象存储（COS） olares-cli backups backup cos --path /data --repo-name my_repo \ --access-key YOUR_KEY \ --secret-access-key YOUR_SECRET \ --endpoint https://cos.region.myqcloud.com/bucket/prefix # 备份到 Olares Space olares-cli backups backup space --path /data --repo-name my_repo \ --access-token YOUR_ACCESS_TOKEN \ --cloud-api-mirror https://api-mirror.example.com \ --cloud-name my_cloud \ --region-id region_1 \ --cluster-id cluster_12345 \ --olares-did did:xyz123

执行成功后，备份数据将以快照形式保存在指定仓库中。可以通过snapshots子命令验证备份结果：

# 查看本地文件系统仓库中的全部快照 olares-cli backups snapshots fs --repo-name my_repo --endpoint /backup_repo # 查看 COS 仓库中的全部快照 olares-cli backups snapshots cos --repo-name my_repo \ --access-key YOUR_KEY \ --secret-access-key YOUR_SECRET \ --endpoint https://cos.region.myqcloud.com/bucket/prefix

备份链路完整可追溯：backup写入 →snapshots验证 →restore恢复。需要恢复数据时，使用restore子命令并指定--snapshot-id即可，详见 backups-restore.md。

源码剖析：backups 命令从何而来

在仓库源码中，backups命令位于 Olares CLI 的 os 命令组下：

• cli/cmd/ctl/os/backup.go 中，NewCmdBackup()直接返回backupssdk.NewBackupCommands()；
• 该命令由 cli/cmd/ctl/os/root.go 通过NewCmdBackup()挂载进 os 命令组；
• backups-sdk是一个独立 SDK 依赖，见 cli/go.mod：olares.com/backups-sdk => github.com/Above-Os/backups-sdk v0.1.40，backup、restore、snapshots、download、region等子命令的具体选项解析与 Restic 调用均封装在该 SDK 中。

也就是说，backups命令族的命令结构、参数表和默认值由 SDK 统一提供，而 CLI 侧通过依赖注入将其接入整体命令树。如果你想查看某个参数（如--limit-upload-rate）在 SDK 内部如何映射为 Restic 的--limit-upload等底层参数，可以从 go.mod 中声明的 SDK 版本出发追踪其实现。

与settings backup命令的区分

需要留意的是，仓库中还另有一棵与备份相关的命令树：olares-cli settings backup（见 cli/cmd/ctl/settings/backup/root.go），它面向「备份计划（Backup Plan）」管理，与图形界面 Settings → Backup 页面对应：

• 其 API 路径为 BFL 的 backup-server 提供的/apis/backup/v1/plans/backup/...，响应为 BFL 风格的{code, message, data}信封结构（相关处理逻辑见 cli/cmd/ctl/settings/backup/common.go 中的doGetEnvelope/doMutateEnvelope）；
• 目前提供plans list、snapshots list <backup-id>、密码管理等读与轻量写操作，而计划的创建 / 更新（完整 BackupPolicy + LocationConfig 载荷）尚不在范围内；
• 输出格式支持--output table|json（见 common.go）。

而本文的backups backup是面向底层执行的一次性备份操作，两者定位不同：前者管理「计划」，后者直接执行「备份」。

注意事项与最佳实践

• 先下载后备份：未执行olares-cli backups download时，backup、restore、snapshots命令都会直接报错，这是最常遇到的失败原因。
• 仓库名称保持一致：--repo-name是备份与恢复之间的关键关联字段，跨命令必须一致；改名后旧快照将无法通过原名称查询。
• 带宽限制按需开启：在公网上行带宽有限的场景（如普通家庭宽带），建议为--limit-upload-rate设置一个合理的 KiB/s 上限，避免备份拖垮日常业务流量；内网或空闲时段可不设。
• 身份凭据妥善保管：COS / S3 的密钥对、Olares Space 的访问令牌都属于敏感信息，不要写入脚本明文或提交到版本库；集群 ID 需在 Olares 主机上通过kubectl获取。
• 备份后可随时验证：通过snapshots列出快照、通过restore做一次恢复演练，是确认备份链路可靠性的最低成本方式。

• 云原生
• 后端
• 运维