企业官网建设流程全解析

• 云原生
• 后端
• 运维

本文以 Terminus（Olares）开源项目自带的olares-cli命令行工具为对象，系统讲解backups snapshots子命令的用法：它用于列出指定备份仓库中的所有可用快照，支持腾讯云 COS、Amazon S3、本地文件系统与 Olares Space 四种存储后端。读完本文，你将掌握快照查询的完整命令语法、四种后端的认证参数配置，并能结合仓库源码理解快照数据的底层结构，从而高效完成备份仓库的巡检与恢复前的快照选择。

命令定位：备份体系中的"仓库清单查看器"

olares-cli backups命令族提供了一组数据备份、恢复和快照管理工具，官方文档 backups 将其子命令划分为五个：

从命令族的角度看，snapshots承担着"查看仓库里有什么"的职责：backup负责写入快照，snapshots负责列出这些快照，而restore则在拿到快照 ID 后执行恢复。三者形成完整的"备份 → 查看 → 恢复"闭环，snapshots输出的快照 ID 正是restore --snapshot-id参数的直接来源（参见 backups-restore）。

从源码结构看，该命令族通过backups-sdk注册到 CLI：在 cli/cmd/ctl/os/backup.go 中，NewCmdBackup()直接返回backupssdk.NewBackupCommands()（模块为olares.com/backups-sdk，声明于 cli/go.mod）。这意味着快照查询的具体参数解析与 Restic 调用逻辑封装在 SDK 层，CLI 只负责把命令挂载到olares-cli的os（即backups）命令树下。

前置条件：必须先安装 Restic

:::warning 必须先运行olares-cli backups download命令来安装 Restic，否则直接运行snapshots命令将返回错误。 :::

snapshots本质上是对 Restic 备份仓库的查询操作，因此要求宿主机上存在可执行的restic二进制。download子命令负责完成安装：

olares-cli backups download [选项]

其唯一可选参数--download-cdn-url用于指定 Restic 的 CDN 下载地址，默认为系统内置 URL（详见 backups-download）。

仓库中download的实际安装逻辑可以在 cli/pkg/files/file.go 中看到端倪：Bzip2Cmd()会识别包含restic关键字的下载包，将其从 bzip2 流解压到目标目录，最后执行cp <target> /usr/local/bin/restic && chmod +x /usr/local/bin/restic，把可执行文件安装到系统 PATH 中。也就是说，安装成功后你可以直接验证：

restic version

命令语法与通用选项

snapshots子命令的基础语法为：

olares-cli backups snapshots <存储后端> --repo-name <仓库名称> [选项]

其中<存储后端>为位置参数，取值必须是cos、s3、fs、space之一；--repo-name指定要查询的备份仓库名称，需与 backup 创建仓库时使用的名称保持一致。

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

--repo-name在表中标注为"否"是 CLI 参数解析层的惯例（其余参数均为可选、可为空），但实际查询时仓库名称是 Restic 定位仓库目录/桶下数据的关键标识，实践上应始终显式指定。

存储后端配置选项

snapshots需要与目标仓库的存储后端建立连接并完成身份认证，各后端的配置选项如下。

腾讯云对象存储（cos）

--endpoint中的{region}需替换为 COS 所在地域（如ap-guangzhou），{bucket}为存储桶名称，{prefix}为仓库所在的前缀目录。

本地文件系统（fs）

本地后端无需任何凭据，--endpoint直接指向存放备份仓库的本地目录（例如外接磁盘的挂载路径），适合离线备份或移动介质场景。

Amazon S3（s3）

Olares Space（space）

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

2. 获取集群 ID：在 Olares 集群节点上执行以下命令：

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

space后端是 Olares 官方云存储，云名称与区域 ID 可通过region子命令先行探测：

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

使用示例

以下示例完整覆盖文档给出的典型场景：

# 列出腾讯云对象存储中的快照 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 # 列出本地文件系统中的快照 olares-cli backups snapshots fs --repo-name my_repo --endpoint /backup_repo

对应的 S3 与 Olares Space 写法如下：

# 列出 Amazon S3 中的快照 olares-cli backups snapshots s3 --repo-name my_repo \ --access-key YOUR_KEY \ --secret-access-key YOUR_SECRET \ --endpoint https://bucket.region.amazonaws.com/prefix # 列出 Olares Space 中的快照 olares-cli backups snapshots space --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

查询成功后，输出中的快照 ID即可作为restore命令的--snapshot-id参数使用，例如：

olares-cli backups restore fs --path /data_restore --repo-name my_repo \ --snapshot-id snapshot_12345 --endpoint /backup_repo

快照数据的底层结构

虽然backups snapshots直接驱动 Restic 读取仓库，但 Olares 的备份体系在更高层面（备份计划、备份服务端）同样维护了一套快照元数据模型，可以帮助理解"快照"在系统中的真实构成。

在 framework/backup-server/pkg/apis/sys.bytetrade.io/v1/snapshot_types.go 中，SnapshotSpec定义了快照的核心字段：

注意其中的SnapshotId字段正是 Restic 仓库中的快照标识，而Size字段在网络传输时会被 framework/backup-server/pkg/handlers/helper.go 的ParseSnapshotSize统一格式化为十进制字符串（fmt.Sprintf("%d", *size)）。这说明在 Olares 的备份链路中，快照元数据（ID、大小、时间、状态、进度）被持久化在 Kubernetes 自定义资源中，用于支撑控制台与 CLI 的统一展示。

与之对应，CLI 的settings backup snapshots list子命令（cli/cmd/ctl/settings/backup/snapshots.go）读取的就是这套 API 数据：其backupSnapshot结构体包含ID、CreateAt、Size（字符串）、Status、Progress五个字段，并约定progress以**基点（basis points）**为单位（0–10000，10000 表示 100.00%），在渲染表格时才转换为百分比；size则通过humanBytes人性化为 KiB/MiB/GiB 等单位。这从侧面印证了快照查询输出中常见字段（ID、状态、进度、大小、时间）的数据来源与展示约定。

此外，Olares 集群的备份能力建立在 Velero 之上：安装流程见 cli/pkg/terminus/velero.go，其中以beclab/velero与beclab/velero-plugin-for-terminus镜像安装插件，并创建名为terminus-cloud的 BackupStorageLocation（--bucket terminus-cloud --prefix ''）。因此backups snapshots查询到的仓库，在云原生层面对应着 Velero 备份位置所指向的存储。

常见问题与排查要点

1. 提示需要先安装 Restic

直接运行snapshots时若返回错误，按文档要求先执行olares-cli backups download完成安装，再重新查询。可参考 backups-download 确认下载参数。

2. 无法获取 Olares Space 的云名称 / 区域 ID

--cloud-name与--region-id不是臆造的值，必须先通过olares-cli backups region space（携带--access-token与--olares-did）查询获取，详见 backups-region。

3. 访问令牌过期或无效

--access-token与--olares-did取自 Olares Space 页面网络请求负载中的token与userid字段，重新登录后需同步更新这两个参数。

4. 查询到的快照 ID 如何用于恢复

snapshots输出的快照 ID 直接对应restore的--snapshot-id选项；恢复前建议先用snapshots核对仓库中可用的快照时间点与数量，避免指定已过期或不属于该仓库的快照 ID。

小结

olares-cli backups snapshots是 Olares 备份运维中最常用的"只读巡查"命令：它不修改数据，只负责把指定仓库中的快照清单呈现出来，为restore提供准确的恢复依据。掌握四种后端（cos、s3、fs、space）的参数差异、理解--repo-name与存储位置（endpoint/目录）的对应关系，并配合download、region、backup、restore兄弟命令使用，即可在 Olares 上构建完整、可审计的数据备份与恢复工作流。

• 云原生
• 后端
• 运维