备份和恢复

RKE2 使用 etcd 快照来备份集群信息。本页面介绍如何使用 rke2 etcd-snapshot CLI 工具来管理 etcd 快照，以及如何从 etcd 快照中恢复。快照仅适用于嵌入式 etcd，如果您使用其他数据存储，请使用 datastore-endpoint 配置，前往实验性。

RKE2 etcd 快照存储在节点的文件系统上，并可选地上传至兼容 S3 的对象存储，用于灾难恢复场景。快照可以按计划自动生成，也可以根据需要手动生成。 rke2 etcd-snapshot CLI 工具提供了一组子命令，可用于创建、删除和管理快照。

子命令	说明
delete	删除指定的快照
ls, list, l	列出快照
修剪	去除超过配置保留数量的快照
保存	触发按需 etcd 快照

子命令

说明

delete

删除指定的快照

ls, list, l

列出快照

修剪

去除超过配置保留数量的快照

保存

触发按需 etcd 快照

有关 etcd 快照子命令的更多信息，请运行 rke2 etcd-snapshot --help。

创建快照

已安排
按需

计划快照默认启用，在系统时间的 00:00 和 12:00 生成，保留 5 个快照。计划快照的名称以 etcd-snapshot 开头，后跟节点名称和时间戳。

以下选项控制计划快照的操作：

标志说明

标志	说明
`--etcd-disable-snapshots`	禁用计划快照
`--etcd-snapshot-name`	设置 etcd 计划快照的基本名称。（默认值：`etcd-snapshot`）
`--etcd-snapshot-compress`	压缩 etcd 快照
`--etcd-snapshot-dir`	保存数据库快照的目录。（默认位置：`$<data-dir>/db/snapshots`）
`--etcd-snapshot-retention`	要保留的快照数量（默认：5)
`--etcd-snapshot-schedule-cron`	快照间隔时间的 cron 规范。例如，每 5 小时 `0 /5 * `（默认：`0 /12 * * *`）

--etcd-disable-snapshots

禁用计划快照

--etcd-snapshot-name

设置 etcd 计划快照的基本名称。（默认值：etcd-snapshot）

--etcd-snapshot-compress

压缩 etcd 快照

--etcd-snapshot-dir

保存数据库快照的目录。（默认位置：$<data-dir>/db/snapshots）

--etcd-snapshot-retention

要保留的快照数量（默认：5)

--etcd-snapshot-schedule-cron

快照间隔时间的 cron 规范。例如，每 5 小时 0 */5 * * *（默认：0 */12 * * *）

data-dir 的默认值为 /var/lib/rancher/rke2，可以通过设置 --data-dir 标志来独立更改。

计划快照保存到服务器的 --etcd-snapshot-dir 值设置的路径。如果您希望它们复制到 S3 兼容的对象存储中，请参阅 S3 配置选项。

可以通过运行 rke2 etcd-snapshot save 命令手动保存快照。这些按需快照没有保留，用户需要通过使用 rke2 etcd-snapshot delete 或 rke2 etcd-snapshot prune 命令手动去除它们。按需快照的名称以 on-demand 开头，后跟节点名称和时间戳。

以下选项控制按需快照的操作：

标志说明

标志	说明
`--name`	设置 etcd 按需快照的基本名称。（默认值：`on-demand`）
`--etcd-snapshot-compress`	压缩 etcd 快照
`--etcd-snapshot-dir`	保存数据库快照的目录。（默认位置：`$<data-dir>/db/snapshots`）

--name

设置 etcd 按需快照的基本名称。（默认值：on-demand）

--etcd-snapshot-compress

压缩 etcd 快照

--etcd-snapshot-dir

保存数据库快照的目录。（默认位置：$<data-dir>/db/snapshots）

data-dir 的默认值为 /var/lib/rancher/rke2，可以通过设置 --data-dir 标志来单独更改。

只有在运行 rke2 etcd-snapshot save 命令时，才能设置 --name 标志。另外两个也可以作为 `rke2 server`配置文件的一部分。

按需快照保存到服务器的 --etcd-snapshot-dir 值设置的路径。如果您希望它们在 S3 兼容的对象存储中复制，请参阅 S3 配置选项。

删除快照

当快照数量超过配置的保留计数（默认5）时，计划快照会自动删除。最旧的快照会被优先去除。

要手动删除计划快照或按需快照，可以使用 rke2 etcd-snapshot delete 命令：

rke2 etcd-snapshot delete <SNAPSHOT-NAME-1> <SNAPSHOT-NAME-2> ...

prune 子命令会去除与名称前缀（默认 on-demand）匹配且超过配置保留计数的快照。它包括标志 --snapshot-retention 来设置保留计数。对于计划快照，它会覆盖默认的保留策略。按需快照没有保留策略，因此此标志是必需的。

将 "按需" 快照修剪到更少的数量：

rke2 etcd-snapshot prune --snapshot-retention  <NUM-OF-SNAPSHOTS-TO-RETAIN>

将 "计划" 快照修剪到更少的数量：

rke2 etcd-snapshot prune --name etcd-snapshot --etcd-snapshot-retention <NUM-OF-SNAPSHOTS-TO-RETAIN>

S3 兼容对象存储支持

RKE2 支持将 etcd 快照复制到 S3 兼容对象存储，并从中恢复 etcd 快照。S3 支持适用于按需和计划快照。

标志说明

标志	说明
`--etcd-s3`	启用备份到 S3
`--etcd-s3-endpoint`	S3 端点 URL
`--etcd-s3-endpoint-ca`	连接到 S3 端点的 S3 自定义 CA 证书
`--etcd-s3-skip-ssl-verify`	禁用 S3 SSL 证书验证
`--etcd-s3-access-key`	S3 访问密钥
`--etcd-s3-secret-key`	S3 秘密密钥
`--etcd-s3-session-token`	S3 会话令牌
`--etcd-s3-bucket`	S3 存储桶名称
`--etcd-s3-bucket-lookup-type`	S3 存储桶查找类型，选项包括 'auto'、'dns'、'path'；如果未设置，默认值为 'auto'
`--etcd-s3-region`	S3 区域/存储桶位置（可选）。默认为 us-east-1
`--etcd-s3-folder`	S3 文件夹
`--etcd-s3-retention`	S3 保留限制（默认：5)
`--etcd-s3-proxy`	连接到 S3 时使用的代理服务器，覆盖任何与代理相关的环境变量
`--etcd-s3-insecure`	禁用 S3 通过 HTTPS
`--etcd-s3-timeout`	S3 超时（默认：`5m0s`）
`--etcd-s3-config-secret`	在 kube-system 命名空间中用于配置 S3 的秘密名称，如果启用了 etcd-s3 且未设置其他 etcd-s3 选项。

--etcd-s3

启用备份到 S3

--etcd-s3-endpoint

S3 端点 URL

--etcd-s3-endpoint-ca

连接到 S3 端点的 S3 自定义 CA 证书

--etcd-s3-skip-ssl-verify

禁用 S3 SSL 证书验证

--etcd-s3-access-key

S3 访问密钥

--etcd-s3-secret-key

S3 秘密密钥

--etcd-s3-session-token

S3 会话令牌

--etcd-s3-bucket

S3 存储桶名称

--etcd-s3-bucket-lookup-type

S3 存储桶查找类型，选项包括 'auto'、'dns'、'path'；如果未设置，默认值为 'auto'

--etcd-s3-region

S3 区域/存储桶位置（可选）。默认为 us-east-1

--etcd-s3-folder

S3 文件夹

--etcd-s3-retention

S3 保留限制（默认：5)

--etcd-s3-proxy

连接到 S3 时使用的代理服务器，覆盖任何与代理相关的环境变量

--etcd-s3-insecure

禁用 S3 通过 HTTPS

--etcd-s3-timeout

S3 超时（默认：5m0s）

--etcd-s3-config-secret

在 kube-system 命名空间中用于配置 S3 的秘密名称，如果启用了 etcd-s3 且未设置其他 etcd-s3 选项。

例如，这就是如何在 S3 中创建和去除按需 etcd 快照的工作方式：

$ rke2 etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret save
INFO[0000] Snapshot on-demand-server-0-1754907117 saved.

$ rke2 etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret ls
Name                              Location                                                                          Size    Created
on-demand-server-0-1754907117     s3://test-bucket/test-folder/on-demand-server-0-1754907117                        8937504 2025-07-22T10:02:03Z
on-demand-server-0-1754907117     file:///var/lib/rancher/rke2/server/db/snapshots/on-demand-server-0-1754907117    8937504 2025-07-22T10:02:03Z

$ rke2 etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret delete on-demand-server-0-1753178523
INFO[0000] Snapshot on-demand-server-0-1754907117 deleted.

$ rke2 etcd-snapshot --s3 --s3-bucket=test-bucket --s3-access-key=test --s3-secret-key=secret ls
Name                              Location                                                                          Size    Created

S3 保留

版本门控

从版本 v1.34.0+rke2r1、v1.33.4+rke2r1、v1.32.8+rke2r1、v1.31.12+rke2r1 开始，RKE2 包含一个新的 S3 保留标志。它的默认值与本地快照保留相同。

标志说明

标志	说明
`--etcd-s3-retention`	在 S3 中保留的快照数量（默认：`5`）

--etcd-s3-retention

在 S3 中保留的快照数量（默认：5）

S3 配置秘密支持

版本门控

自 2024 年 8 月发布以来，S3 配置 Secret 支持已可用：v1.30.4+rke2r1、v1.29.8+rke2r1、v1.28.13+rke2r1。

RKE2 支持从 Kubernetes Secret 中读取 etcd S3 快照配置。出于安全考虑，当需要在不重启 RKE2 的情况下轮换凭据时，从 Kubernetes Secret 中读取 S3 快照配置可能比在 RKE2 CLI 标志或配置文件中硬编码凭据更为理想。要通过 Secret 传递 S3 快照配置，请使用 --etcd-s3 和 --etcd-s3-config-secret=<SECRET-NAME> 启动 RKE2。在启动 RKE2 时，Secret 不需要存在，但在每次执行快照保存/列出/删除/修剪操作时都会进行检查。

在恢复快照时，无法使用 S3 配置 Secret，因为在恢复期间 apiserver 不可用以提供 Secret。在恢复存储在 S3 上的快照时，必须通过 CLI 传递 S3 配置。

仅传递 --etcd-s3 和 --etcd-s3-config-secret 标志以启用 Secret。
如果设置了任何其他 S3 配置标志，则将忽略该 Secret。

Secret 中的键对应于上述 --etcd-s3-* CLI 标志。 etcd-s3-endpoint-ca 键接受 PEM 编码的 CA 包，或者可以使用 etcd-s3-endpoint-ca-name 键指定 kube-system 命名空间中包含一个或多个 PEM 编码 CA 包的 ConfigMap 的名称。

apiVersion: v1
kind: Secret
metadata:
  name: rke2-etcd-snapshot-s3-config
  namespace: kube-system
type: etcd.k3s.cattle.io/s3-config-secret
stringData:
  etcd-s3-endpoint: ""
  etcd-s3-endpoint-ca: ""
  etcd-s3-endpoint-ca-name: ""
  etcd-s3-skip-ssl-verify: "false"
  etcd-s3-access-key: "AWS_ACCESS_KEY_ID"
  etcd-s3-secret-key: "AWS_SECRET_ACCESS_KEY"
  etcd-s3-bucket: "bucket"
  etcd-s3-folder: "folder"
  etcd-s3-region: "us-east-1"
  etcd-s3-insecure: "false"
  etcd-s3-timeout: "5m"
  etcd-s3-proxy: ""

恢复快照

RKE2 在恢复快照时经过几个步骤：

如果快照存储在 S3 上，文件将下载到快照目录中。
如果快照被压缩，则会进行解压。
如果存在，当前的 etcd 数据库文件将被移动到 $<data-dir>/server/db/etcd-old-$TIMESTAMP/。
快照的内容被提取到磁盘，并验证校验和。
启动 Etcd，除了当前节点外，所有 etcd 集群成员将从集群中移除。
CA 证书和其他机密数据从数据存储中提取并写入磁盘，以备后用。
恢复完成，RKE2 可以在执行恢复的服务器上正常重启和使用。
（可选）代理和控制平面服务器可以正常启动。
（可选）在移除旧数据库文件后，可以重启 Etcd 服务器以重新加入集群。

在恢复快照时，您不需要使用创建快照的相同 RKE2 版本；更高的次要版本也是可以接受的。

快照恢复步骤

选择下面与您的集群配置匹配的选项卡。

单服务器
多台服务器

停止 RKE2 服务：
```
systemctl stop rke2-server
```
运行 rke2 server，带上 --cluster-reset 标志，并用 --cluster-reset-restore-path 指定要恢复的快照路径。如果快照存储在 S3 上，请提供 S3 配置标志（--etcd-s3、--etcd-s3-bucket 等），并仅将快照的文件名作为恢复路径。

使用 --cluster-reset 标志而不指定要恢复的快照，仅会将 etcd 集群重置为单个成员，而不恢复快照。
```
rke2 server \
  --cluster-reset \
   --cluster-reset-restore-path=<PATH-TO-SNAPSHOT>
```
*结果：*RKE2 恢复快照并重置集群成员资格，然后打印一条消息，指示它已准备好重新启动：
Managed etcd cluster membership has been reset, restart without --cluster-reset flag now.
再次启动 RKE2：
```
systemctl start rke2-server
```
如果在 RKE2 配置文件中定义了 etcd-s3 备份配置，RKE2 恢复将尝试从配置的 S3 存储桶中提取快照文件。在这种情况下，只有快照文件名应作为参数 --cluster-reset-restore-path 传递。要从本地快照文件恢复（当存在 etcd-s3 备份配置时），请添加参数 --etcd-s3=false，并在参数 --cluster-reset-restore-path 中传递本地快照文件的完整路径。

作为安全机制，当 RKE2 重置集群时，它会在 /var/lib/rancher/rke2/server/db/reset-flag 创建一个空文件，以防止用户意外连续运行多个集群重置。当 RKE2 正常启动时，此文件将被删除。

在此示例中，有 3 台服务器，S1、S2 和 S3。快照位于 S1。

在所有服务器上停止 RKE2：
```
systemctl stop rke2-server
```
在 S1 上，运行 rke2 server，并使用 --cluster-reset 选项，--cluster-reset-restore-path 指定要恢复的快照路径。如果快照存储在 S3 上，请提供 S3 配置标志（--etcd-s3、--etcd-s3-bucket 等），并仅将快照的文件名作为恢复路径。

使用 --cluster-reset 标志而不指定要恢复的快照，仅会将 etcd 集群重置为单个成员，而不恢复快照。
```
rke2 server \
  --cluster-reset \
  --cluster-reset-restore-path=<PATH-TO-SNAPSHOT>
```
*结果：*RKE2 恢复快照并重置集群成员资格，然后打印一条消息，指示它已准备好重新启动：
Managed etcd cluster membership has been reset, restart without --cluster-reset flag now.
Backup and delete $<datadir>/server/db on each peer etcd server and rejoin the nodes.
在 S1 上，再次启动 RKE2：
```
systemctl start rke2-server
```
在 S2 和 S3 上，删除数据目录 /var/lib/rancher/rke2/server/db/：
```
rm -rf /var/lib/rancher/rke2/server/db/
```
在 S2 和 S3 上，再次启动 RKE2 以加入恢复的集群：
```
systemctl start rke2-server
```

如果在 RKE2 配置文件中定义了 etcd-s3 备份配置，RKE2 恢复将尝试从配置的 S3 存储桶中提取快照文件。在这种情况下，只有快照文件名应作为参数 --cluster-reset-restore-path 传递。要从本地快照文件恢复（当存在 etcd-s3 备份配置时），请添加参数 --etcd-s3=false，并在参数 --cluster-reset-restore-path 中传递本地快照文件的完整路径。

恢复到新主机

可以将 etcd 快照恢复到与创建该快照时所在主机不同的主机上。这样做时，必须传递在创建快照时原本使用的 server 词元，因为它用于解密快照中的启动数据。该过程与上述相同，但将步骤 2 更改为：

在创建快照的节点中保存以下值：/var/lib/rancher/rke2/server/token。这就是步骤 3 中的 <BACKED-UP-TOKEN-VALUE>。
将快照复制到新节点。节点中的路径在第 3 步中为 <PATH-TO-SNAPSHOT>。
使用以下命令在第一个服务器节点上启动从快照恢复：

rke2 server \
  --cluster-reset \
  --cluster-reset-restore-path=<PATH-TO-SNAPSHOT>
  --token=<BACKED-UP-TOKEN-VALUE>

词元值也可以在 RKE2 配置文件中设置。

节点资源也包含在 etcd 快照中。如果要恢复到一组新节点，您需要手动删除集群中不再存在的旧节点。
如果在 RKE2 配置文件中设置了词元，请确保它与 <BACKED-UP-TOKEN-VALUE> 相同，否则 RKE2 将无法启动。

ETCD快照文件自定义资源

可以通过列出或描述集群范围的 ETCDSnapshotFile 资源，使用任何 Kubernetes 客户端远程查看快照。与 rke2 etcd-snapshot list 命令只显示该节点可见的快照不同，ETCDSnapshotFile 资源会跟踪集群所有成员上存在的所有快照。

$ kubectl get etcdsnapshotfile
Name                              Location                                                                           Size     Created
etcd-snapshot-server-0-1754906881 s3://test-bucket/test-folder/etcd-snapshot-server-0-1754906881                     8937504  2025-08-11T10:08:01Z
etcd-snapshot-server-0-1754906881 file:///var/lib/rancher/rke2/server/db/snapshots/etcd-snapshot-server-0-1754907185 8937504  2025-08-11T10:08:01Z
etcd-snapshot-server-0-1754907185 s3://test-bucket/test-folder/etcd-snapshot-server-0-1754907185                     9633824  2025-08-11T10:13:05Z
etcd-snapshot-server-0-1754907185 file:///var/lib/rancher/rke2/server/db/snapshots/etcd-snapshot-server-0-1754907185 9633824  2025-08-11T10:13:05Z

$ kubectl describe etcdsnapshotfile s3-etcd-snapshot-server-0-1754906881-e1e196
Name:         s3-etcd-snapshot-server-0-1754906881-e1e196
Namespace:
Labels:       etcd.rke2.cattle.io/snapshot-storage-node=s3
Annotations:  etcd.rke2.cattle.io/snapshot-token-hash: 2bb80d537b1d
API Version:  k3s.cattle.io/v1
Kind:         ETCDSnapshotFile
Metadata:
  Creation Timestamp:  2025-08-11T10:10:37Z
  Finalizers:
    wrangler.cattle.io/managed-etcd-snapshots-controller
  Generation:        1
  Resource Version:  2356
  UID:               d4fa68e7-b692-4ad8-8740-77d2bb9c062f
Spec:
  Location:   s3://test-bucket/test-folder/etcd-snapshot-server-0-1754906881
  Node Name:  server-0
  s3:
    Bucket:           test-bucket
    Endpoint:         localhost:9090
    Insecure:         true
    Prefix:           test-folder
    Region:           us-east-1
    Skip SSL Verify:  true
  Snapshot Name:      etcd-snapshot-server-0-1754906881
Status:
  Creation Time:  2025-08-11T10:08:01Z
  Ready To Use:   true
  Size:           8937504
Events:
  Type    Reason               Age    From             Message
  ----    ------               ----   ----             -------
  Normal  ETCDSnapshotCreated  6m24s  rke2-supervisor  Snapshot etcd-snapshot-server-0-1754906881 saved on server-0

$ kubectl describe etcdsnapshotfile s3-on-demand-k3s-server-1-1730308816-79b15c

外部数据库备份（实验性）

除了备份数据存储本身外，您还必须备份位于 /var/lib/rancher/rke2/server/token 的服务器词元文件。在从备份恢复时，您必须恢复此文件，或将其值传递给 token 选项。如果在恢复时不使用相同的词元值，则快照将无法使用，因为该词元用于加密存储本身的机密数据。

使用 SQLite 进行备份和恢复

备份或恢复 SQLite 存储不需要特殊命令。

要备份 SQLite 存储，请复制 /var/lib/rancher/rke2/server/db/。
要恢复 SQLite 存储，请恢复 /var/lib/rancher/rke2/server/db 的内容（以及上述讨论的词元）。

使用外部存储进行备份和恢复

当使用外部存储时，备份和恢复操作在 RKE2 之外处理。数据库管理员需要备份外部数据库，或从快照或转储中恢复它。

我们建议配置数据库以进行定期快照。

有关如何进行数据库快照和从中恢复数据库的详细信息，请参阅官方数据库文档：