存储与卷

本指南介绍 operator 如何为 ClickHouseCluster 配置持久存储：包括主数据卷、在多磁盘 (JBOD) 布局中挂载额外磁盘、扩展容量，以及集群创建后哪些内容可以更改、哪些不能更改的规则。

如需查看按字段划分的参考信息，请参阅 Configuration → Storage configuration 和 API 参考文档。

spec.dataVolumeClaimSpec 是标准的 Kubernetes PersistentVolumeClaimSpec。 Operator 会将其转换为 StatefulSet 的 volumeClaimTemplate，因此 StatefulSet 控制器会为每个副本创建并保留一个 PersistentVolumeClaim，并将其挂载到 ClickHouse 数据路径 /var/lib/clickhouse。

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: my-cluster
spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd   # optional; depends on the installed CSI driver
    resources:
      requests:
        storage: 100Gi

• 省略 accessModes 时，operator 会默认将其设置为 ReadWriteOnce。
• 删除 cluster 时，每个副本的 PVC 都会被保留，因此即使删除后重新创建 Custom Resource，数据也仍然存在。对于 加密策略中的数据，这还需要保留加密 key——请参阅该部分中的说明。
• KeeperCluster 上也有同样的字段，行为也完全一致。

dataVolumeClaimSpec 是可选的。如果省略它，并且未在数据路径挂载您自己的卷， ClickHouse 会写入容器的临时文件系统，准入 webhook 也会返回一条警告，提示如果集群重启，数据可能会丢失。

这仅适用于一次性或测试集群。若要提供您自己的存储来替代 dataVolumeClaimSpec —— 例如 emptyDir 或预置卷 —— 请通过 spec.podTemplate.volumes 定义它，并使用 spec.containerTemplate.volumeMounts 将其挂载到 /var/lib/clickhouse。

要扩容卷，请增大 resources.requests.storage 并应用更改。 operator 会就地更新现有的 PVC。

spec:
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 200Gi   # was 100Gi

spec.additionalVolumeClaimTemplates 会在主 dataVolumeClaimSpec 的基础上，为每个 ClickHouse 副本挂载额外磁盘。每个条目都是一个具名 PVC 模板——即一个 metadata.name 加上一个 PVC spec——其协调方式与 主数据磁盘完全相同，因此 StatefulSet 控制器会为每个 副本创建并保留一个名为 <name>-<statefulset>-0 的 PVC。

spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd
    resources:
      requests:
        storage: 100Gi
  additionalVolumeClaimTemplates:
    - metadata:
        name: disk1
      spec:
        storageClassName: fast-ssd
        resources:
          requests:
            storage: 100Gi
    - metadata:
        name: disk2
      spec:
        storageClassName: fast-ssd
        resources:
          requests:
            storage: 100Gi

operator 会将每个附加卷挂载到 /var/lib/clickhouse/disks/<name> ，并且会为你自动生成 ClickHouse 的 storage_configuration——你无需手动编写 它。它会注册每个附加磁盘，并将其添加到内置的 default 存储策略中。

主数据磁盘 (default) 和所有附加磁盘共同对应 default 策略中的同一个卷， 因此 ClickHouse 会以轮询方式将新的数据分区片段分布到这些磁盘上。 可用容量等于所有磁盘容量之和，而所有未单独设置 storage_policy 的表 ——包括 system.* 表——都会使用这一组合。

对于上面的 JBOD 布局，你不需要 extraConfig——operator 会自动生成 default 策略。只有当你需要生成的默认策略之外的存储策略时，才使用 spec.settings.extraConfig，例如带有 move_factor 和 prefer_not_to_merge 的分层冷热策略，或 S3 支持的 disk。 你在这里添加的配置会合并到生成的 storage_configuration 之上。

有关这些策略字段，请参阅 ClickHouse 存储文档。

设置 spec.settings.encryption 可启用表数据的静态数据加密。该 operator 会生成一个 16 字节的 AES 密钥——存储在托管集群的 Secret 中，或 通过 externalSecret 提供——以及一个专用的存储策略，使用 ClickHouse 的 encrypted 磁盘类型封装每个 数据磁盘。

spec:
  settings:
    encryption: {}   # enables the feature; the policy defaults to "encrypted"

加密需按表单独启用；默认存储策略仍为明文。创建表时，选择 加密策略：

CREATE TABLE secret_data (id UInt64) ENGINE = MergeTree ORDER BY id
SETTINGS storage_policy = 'encrypted';

将 encryption.policyName 设置为使用其他策略名称。

集群一旦创建，存储布局基本就固定了。会导致数据成为孤立对象 或重新绑定 PersistentVolumeClaims 的更新会在准入阶段被拒绝：

• dataVolumeClaimSpec 的存在与否是不可变的——对于创建时未配置数据 卷的集群，你不能添加数据卷；对于创建时已配置数据卷的集群，你也不能移除它。
• additionalVolumeClaimTemplates 的集合是固定的——创建后你不能添加、 移除或重命名其中的条目。
• 允许扩展现有条目的 resources.requests.storage (前提是 StorageClass 支持，参见扩展存储) 。
• 一旦启用加密，就不能将其禁用，并且 encryption.policyName 也不能 重命名——已在使用该加密策略的表将无法访问。

• 配置 — 完整的字段参考，包括 extraConfig。
• 集群扩缩容 — 介绍如何添加和移除副本与分片。