存储与卷 - ClickHouse Documentation

本指南介绍 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。

dataVolumeClaimSpec 与数据路径上的自定义卷互斥。如果设置了 dataVolumeClaimSpec，则在 /var/lib/clickhouse 挂载自定义卷会被拒绝。保留卷名称 clickhouse-storage-volume、 clickhouse-server-tls-volume 和 clickhouse-server-custom-ca-volume 不能在 podTemplate.volumes 中使用。

扩展存储

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

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

只有在底层 StorageClass 设置了 allowVolumeExpansion: true 时，才能进行扩容。Kubernetes 不支持缩小 PVC，因此新容量必须大于或等于当前容量。

多磁盘 (JBOD) 存储

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.* 表——都会使用这一组合。

挂载路径会原样保留模板名称，但 storage_configuration 中的磁盘标识符会将连字符替换为下划线。名为 cold-disk 的模板会挂载到 /var/lib/clickhouse/disks/cold-disk，并在生成的配置中显示为 cold_disk。

自定义存储策略

对于上面的 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 设置为使用其他策略名称。

这会使用 AES-128-CTR 对通过加密策略写入的 MergeTree 数据分区片段进行加密。位于数据根目录的 ClickHouse server 元数据和日志不在此范围内——对于这些内容，请使用磁盘级加密，例如 LUKS 或 CSI driver。在运行中的 cluster 上启用加密会触发一次性滚动重启以注入密钥；在重启完成之前，副本可能会短暂报告配置重新加载错误。密钥存储在由 operator 管理的 cluster Secret 中，该 Secret 由 Custom Resource 拥有，并会随其一同删除。没有密钥时，加密的 parts 将无法读取：如果删除 CR 后仍需保留加密数据 (PVC 会被保留) ，请通过 externalSecret 提供密钥，或在删除前备份 disk-encryption-key 条目。不要删除受管 Secret——operator 会生成新的密钥，而现有加密 parts 将变得无法读取。

创建后不可更改的内容

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

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

校验参考

条件	结果
未设置 `dataVolumeClaimSpec`，且 `/var/lib/clickhouse` 下也没有自定义卷	警告 — 重启时可能会导致数据丢失
在 `/var/lib/clickhouse` 挂载了自定义卷，同时又设置了 `dataVolumeClaimSpec`	拒绝
设置了 `additionalVolumeClaimTemplates`，但缺少 `dataVolumeClaimSpec`	拒绝
附加磁盘命名为 `default`	拒绝 — 该名称被 ClickHouse 默认磁盘保留
附加磁盘名称以 `-encrypted` 结尾	拒绝 — 与生成的加密磁盘名称冲突
附加磁盘命名为 `clickhouse-storage-volume`	拒绝 — 与主数据卷名称冲突
附加磁盘名称重复	拒绝
名称不匹配 `^[a-z]([-a-z0-9]*[a-z0-9])?$` 或长度超过 63 个字符	被 CRD schema 拒绝
创建后添加或删除 `dataVolumeClaimSpec`	拒绝
创建后添加、删除或重命名 `additionalVolumeClaimTemplates`	拒绝
在 `podTemplate.volumes` 中使用保留卷名称	拒绝
将 `encryption.policyName` 设置为 `default`	被 CRD schema 拒绝 — 加密策略不得替换默认策略
创建后禁用 `encryption` 或重命名其策略	被 CRD schema 拒绝

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

​主数据卷

​在没有持久数据卷的情况下运行

​扩展存储

​多磁盘 (JBOD) 存储

​自定义存储策略

​静态数据加密

​创建后不可更改的内容

​校验参考

​相关指南

主数据卷

在没有持久数据卷的情况下运行

扩展存储

多磁盘 (JBOD) 存储

自定义存储策略

静态数据加密

创建后不可更改的内容

校验参考

相关指南