#如何使用 S3 备份和恢复 ClickHouse

#概述

本文档介绍如何通过使用 S3 存储来备份和恢复 observability 数据库中的 ClickHouse 表。此操作适用于使用 ReplicatedMergeTree 表引擎的集群。

本文档提供以下指导：

• 创建全量备份。
• 基于全量备份创建增量备份。
• 将备份数据存储到指定的 S3 路径。
• 从 S3 备份恢复数据。
• 验证备份和恢复结果。

本文档以 observability.audit 表为例。你可以将相同的操作步骤应用到其他表。

常见示例表如下：

• audit：存储审计数据。
• event：存储事件数据。
• log_kubernetes：存储 Kubernetes 日志。
• log_platform：存储平台服务日志。
• log_system：存储节点级系统日志。
• log_workload：存储原生应用和工作负载日志。

#前提条件

开始之前，请确保满足以下条件。

#环境要求

#访问要求

本文档中的所有 SQL 语句均使用 ClickHouse 内置管理员账户 default。

你可以在任意健康的 ClickHouse 实例上执行这些 SQL 语句。为保持一致性，本文档以单个 ClickHouse Pod 为例。

在执行 SQL 语句之前，请先连接到目标 Pod：

kubectl exec -ti -n cpaas-system chi-cpaas-clickhouse-replicated-0-0-0 -- bash

然后连接到容器中的 ClickHouse：

clickhouse-client

default 用户已经具备执行此操作所需的权限，包括 BACKUP、RESTORE、SELECT 和 ALTER。

#S3 权限

S3 凭证必须具有以下权限：

• PutObject
• GetObject
• ListBucket
• DeleteObject，如果需要清理过期备份

#备份策略

建议采用以下备份策略：

• 仅在任意健康副本上执行一次备份操作。
• 使用 BACKUP TABLE 在不中断服务的情况下创建一致性快照。
• 在增量备份中使用 base_backup 实现文件级去重。
• 在恢复增量备份时，保持基础全量备份可访问。
• 每周保留一个全量备份、每天保留一个增量备份，以平衡恢复复杂度和存储成本。

#操作步骤

以下示例使用初始全量备份和每日增量备份。

#创建全量备份

全量备份会为后续增量备份创建基线。

在任意健康的 ClickHouse 实例上运行以下命令：

BACKUP TABLE observability.audit
TO S3(
  'http://<s3_endpoint>/<bucket>/clickhouse-backup/audit/full_20260423',
  '<access_key_id>',
  '<secret_access_key>'
)
SETTINGS compression_method = 'zstd';

按如下方式替换变量：

说明：

• S3(...) 会将备份写入指定的对象存储路径。
• compression_method = 'zstd' 使用 zstd 压缩备份内容，以减少存储占用和网络传输量。

#验证备份是否成功

备份完成后，请验证结果。

#检查备份任务状态

在执行备份命令的 ClickHouse 实例上运行以下查询：

SELECT
    id,
    name,
    status,
    error,
    start_time,
    end_time,
    num_files,
    total_size
FROM system.backups
ORDER BY start_time DESC
LIMIT 10
FORMAT Vertical;

预期结果：

通过 name 字段找到 observability.audit 的备份记录。如果满足以下条件，则说明备份成功：

• status = 'BACKUP_CREATED'
• error 为空
• end_time 有值
• num_files > 0
• total_size > 0

#检查 S3 路径

在可以访问目标 S3 bucket 的环境中运行以下命令：

mc ls <s3_alias>/<bucket>/clickhouse-backup/audit/

按如下方式替换变量：

预期结果：

• 目标路径存在。
• 路径中包含由此次备份生成的文件。
• 文件数量和总大小大于 0。

#创建增量备份

增量备份会使用 base_backup，并且只上传新增或变更的数据文件。

在任意健康的 ClickHouse 实例上运行以下命令：

BACKUP TABLE observability.audit
TO S3(
  'http://<s3_endpoint>/<bucket>/clickhouse-backup/audit/incr_20260424',
  '<access_key_id>',
  '<secret_access_key>'
)
SETTINGS
  base_backup = S3(
    'http://<s3_endpoint>/<bucket>/clickhouse-backup/audit/full_20260423',
    '<access_key_id>',
    '<secret_access_key>'
  ),
  compression_method = 'zstd';

说明：

• 增量备份依赖 base_backup 指定的备份。
• 建议每个每日增量备份都使用最新的全量备份作为 base_backup，而不要使用上一个增量备份作为基线。这样可以简化恢复依赖：恢复每日增量备份时，只需要该增量备份及其对应的全量备份。
• 在恢复增量备份时，请保留其依赖的全量备份。
• 请定期创建新的全量备份，以避免长期依赖同一个基线。

#恢复

当表数据损坏、数据目录被删除或表状态异常时，请使用此操作步骤。

#恢复前提条件

开始恢复操作之前，请确保满足以下条件：

• 你拥有有效的全量备份或增量备份。
• 如果从增量备份恢复，相应的全量备份仍然可访问。
• 你已确认 S3 endpoint、bucket、备份路径、access key 和 secret key。
• 你可以访问 Kubernetes 集群以及部署 ClickHouse 实例的宿主机节点。

#恢复操作步骤

此操作步骤按表恢复 ClickHouse 数据。请根据故障范围选择准备步骤，然后对每个需要恢复的表执行相同的恢复操作步骤。

#停止写入

首先停止 razor，以防恢复期间写入新数据。

登录到集群主节点，并创建一个 ResourcePatch 来停止 razor：

cat <<EOF > /tmp/rp-stop-razor.yaml
apiVersion: operator.alauda.io/v1alpha1
kind: ResourcePatch
metadata:
  generateName: rp-
  name: rp-stop-razor
spec:
  jsonPatch:
  - op: replace
    path: /spec/replicas
    value: 0
  release: cpaas-system/logclickhouse
  target:
    apiVersion: apps/v1
    kind: StatefulSet
    name: razor
    namespace: cpaas-system
EOF

kubectl apply -f /tmp/rp-stop-razor.yaml

#根据故障范围准备 ClickHouse

请根据故障范围选择以下其中一种准备路径。准备完成后，继续执行相同的按表恢复步骤。

#场景 A：表数据损坏，但数据目录正常

当一个或多个表损坏、被误删或数据异常，但 ClickHouse 数据目录和 Keeper 状态仍然正常时，请使用此场景。

在这种情况下，不要停止 ClickHouse，也不要清理 /cpaas/data/clickhouse/*。直接继续执行表恢复步骤。

#场景 B：数据目录或 Keeper 元数据损坏

仅当 ClickHouse 数据目录损坏、节点已重建或 Keeper 元数据不可用时，才使用此场景。

在此部署中，ClickHouse Keeper 与 ClickHouse 集成，并且其数据也存储在 ClickHouse 数据目录下。因此，清理 /cpaas/data/clickhouse/* 也会删除本地 ClickHouse Keeper 数据。

警告： 清理数据目录会删除目标节点上的本地 ClickHouse 数据。继续之前，请确认备份可用。

请在每个 ClickHouse 宿主机节点上运行 rm -rf /cpaas/data/clickhouse/* 命令，而不是在 ClickHouse 容器内执行。

登录到集群主节点，并创建一个 ResourcePatch 来停止 ClickHouse：

cat <<EOF > /tmp/rp-stop-ck.yaml
apiVersion: operator.alauda.io/v1alpha1
kind: ResourcePatch
metadata:
  generateName: rp-
  name: rp-stop-ck
spec:
  jsonPatch:
  - op: add
    path: /spec/stop
    value: "true"
  release: cpaas-system/logclickhouse
  target:
    apiVersion: clickhouse.altinity.com/v1
    kind: ClickHouseInstallation
    name: cpaas-clickhouse
    namespace: cpaas-system
EOF

kubectl apply -f /tmp/rp-stop-ck.yaml

确认所有 ClickHouse Pod 都已停止：

kubectl get pod -n cpaas-system | grep -i "chi-cpaas-clickhouse-replicated"

在部署了 ClickHouse 实例的每个宿主机节点上，清理本地 ClickHouse 数据目录：

rm -rf /cpaas/data/clickhouse/*

通过删除 ClickHouse ResourcePatch 仅启动 ClickHouse 组件。此时不要启动 razor。

kubectl delete -f /tmp/rp-stop-ck.yaml

确认所有 ClickHouse Pod 都已运行：

kubectl get pod -n cpaas-system | grep -i "chi-cpaas-clickhouse-replicated"

#检查集群就绪状态

在执行恢复命令之前，请确认 ClickHouse 集群配置和宏可用。

检查 replicated 集群配置：

SELECT *
FROM system.clusters
WHERE cluster = 'replicated';

检查本地 ClickHouse 宏：

SELECT *
FROM system.macros;

确保集群包含预期的 ClickHouse 从节点，并且 shard 和 replica 等宏可用。

#逐表恢复

对每个需要恢复的表执行以下恢复操作步骤。

在 ClickHouse 集群上删除目标表：

DROP TABLE observability.audit ON CLUSTER 'replicated' SYNC;

从 S3 恢复表：

RESTORE TABLE observability.audit
ON CLUSTER 'replicated'
FROM S3(
  'http://<S3_ENDPOINT>/<bucket>/clickhouse-backup/audit/incr_20260424',
  '<access_key_id>',
  '<secret_access_key>'
);

说明：

• 对于这个 3 从节点部署中的 ReplicatedMergeTree 表，请使用 ON CLUSTER 'replicated'，这样恢复操作会分发到集群中的所有 ClickHouse 从节点。
• 如果从增量备份恢复，ClickHouse 会自动读取其依赖的基础备份。
• 在恢复期间，请保持相应的全量备份路径可访问。
• 请将 observability.audit 和 S3 路径替换为你要恢复的实际表和备份路径。
• 对每个需要恢复的表重复相同的操作步骤。表列表由客户决定。

#检查恢复任务状态

执行每个恢复命令后，在启动任何相关组件之前检查恢复任务状态：

SELECT
    id,
    name,
    status,
    error,
    start_time,
    end_time,
    num_files,
    total_size
FROM system.backups
ORDER BY start_time DESC
LIMIT 10
FORMAT Vertical;

预期结果：

如果满足以下条件，则说明恢复成功：

• status 表示恢复操作已成功完成。
• error 为空。
• end_time 有值。

#验证恢复是否成功

恢复完成后，请从数据、分区和从节点三个角度验证结果。

#验证总行数

在每个 ClickHouse 实例上运行以下查询：

SELECT count(*) AS total_rows
FROM observability.audit;

预期结果：

所有 ClickHouse 实例上的 total_rows 值都相同。

#验证分区级数据

在每个 ClickHouse 实例上运行以下查询：

SELECT
    partition,
    sum(rows) AS rows,
    count() AS active_parts
FROM system.parts
WHERE active
  AND database = 'observability'
  AND table = 'audit'
GROUP BY partition
ORDER BY partition;

预期结果：

• 所有 ClickHouse 实例上的 partition 列表都相同。
• 所有 ClickHouse 实例上每个分区的 rows 值都相同。

active_parts 仅用于观察物理 part 布局。part 数量不同并不一定表示恢复失败。

#验证从节点状态

在任意 ClickHouse 实例上运行以下查询：

SELECT
    database,
    table,
    total_replicas,
    active_replicas,
    queue_size,
    absolute_delay
FROM system.replicas
WHERE database = 'observability'
  AND table = 'audit';

预期结果：

对于 3 从节点集群，如果满足以下条件，则说明恢复成功：

• total_replicas = 3
• active_replicas = 3
• queue_size = 0
• absolute_delay 接近 0

#启动相关组件

在恢复成功验证完成后，通过删除 ResourcePatch 重新启动 razor：

kubectl delete -f /tmp/rp-stop-razor.yaml

#建议

在生产环境中建议采用以下做法：

• 维护备份链，每周保留一个全量备份、每天保留一个增量备份。
• 为 S3 备份目录使用统一的命名规范，例如 full_YYYYMMDD 和 incr_YYYYMMDD。
• 定期在测试环境中执行恢复演练。