Coroot 使用指南：为 ClickHouse 配置 S3 对象存储（Tiered 与 S3-only 双模式）
【免费下载链接】corootCoroot is an open-source observability and APM tool with AI-powered Root Cause Analysis. It combines metrics, logs, traces, continuous profiling, and SLO-based alerting with predefined dashboards and inspections.项目地址: https://gitcode.com/GitHub_Trending/co/coroot
Coroot 使用 ClickHouse 存储日志（Logs）、链路（Traces）、性能剖析（Profiles）与可选指标（Metrics），默认情况下这些遥测数据全部落在本地磁盘上。本文基于 Using S3 Storage with ClickHouse 指南，完整讲解如何通过 Coroot Kubernetes Operator 为 ClickHouse 接入 S3 兼容对象存储，实现"热数据本地、冷数据上云"的分层存储架构。读完本文，你将掌握 Tiered 与 S3-only 两种模式的配置方法、凭证注入方式、底层数据隔离与缓存原理，以及一套可复用的故障排查 SQL。
为什么要把 ClickHouse 数据放到 S3
默认部署下，ClickHouse 把全部遥测数据写入本地持久卷。启用 S3 对象存储后可以带来三方面收益：
- 降低存储成本：把历史冷数据迁移到更便宜的对象存储，本地只保留高性价比的 SSD；
- 存储与计算独立伸缩：扩容存储只需扩大对象存储容量，无需反复调整 PVC 大小、迁移数据；
- 突破本地磁盘容量限制：可以保存更长周期的数据，不再受单机本地盘容量约束。
需要注意的是，S3 存储面向的是由 Operator 托管的 ClickHouse 集群（部署在 Kubernetes 上），不是 Coroot 外部连接的外部 ClickHouse（externalClickhouse）配置。
两种 S3 存储模式
Coroot Operator 支持两种 S3 存储模式，按业务对查询性能与成本的取舍进行选择：
| 模式 | 工作方式 | 适用场景 |
|---|---|---|
| Tiered（分层） | 近期数据保存在本地 SSD，本地磁盘空间不足时自动把最旧的数据移动到 S3 | 对近期数据查询性能要求高，同时希望长期数据低成本留存，官方推荐 |
| S3-only（纯 S3） | 所有数据直接写入 S3，本地磁盘仅用作读缓存与临时合并操作 | 本地存储要求极低、追求极致成本优化的场景 |
两种模式可以在同一份CorootCustom Resource（CR）中配置，只需切换mode字段并调整cacheSize与storage.size即可。
前置条件
开始之前需要确认以下条件已满足：
- Coroot 已通过 Kubernetes Operator 部署，Operator 负责创建和管理 ClickHouse StatefulSet；
- 拥有一个 S3 兼容的存储桶，例如 AWS S3、MinIO、Ceph RGW 等；
- 具备 S3 凭证（Access Key + Secret Key），或集群已配置 IAM Roles for Service Accounts（IRSA）/ Workload Identity。
Step 1：创建专用的 S3 存储桶
为 ClickHouse 数据创建专用bucket，不要与其他应用共用。ClickHouse 自己管理对象文件的生命周期，外部的生命周期策略（如自动过期删除）可能导致数据丢失。
aws s3 mb s3://my-coroot-clickhouse --region us-east-1使用 MinIO 等自建存储时，可通过其管理控制台或mc mb命令创建对应 bucket。
Step 2：创建凭证 Secret
用kubectl在 Coroot 所在命名空间创建静态凭证 Secret，字段名需要与 CR 中的引用保持一致：
kubectl create secret generic clickhouse-s3-creds \ --from-literal=access_key_id=YOUR_ACCESS_KEY \ --from-literal=secret_access_key=YOUR_SECRET_KEY \ -n coroot:::tip 如果集群使用了IAM Roles for Service Accounts（IRSA）或Workload Identity，可以完全跳过 Secret 的创建，并在 CR 中省略credentials段落。此时 ClickHouse 会自动从环境变量与实例元数据服务中解析凭证。 :::
Step 3：在 Coroot CR 中配置 S3
在 Coroot 自定义资源的spec.clickhouse下增加s3段落。下面是 Operator 支持的完整参数说明（对应 k8s-operator.md 中clickhouse段落的注释定义）：
| 参数 | 默认值 | 说明 |
|---|---|---|
endpoint | — | S3 端点 URL，若结尾缺少/会自动补齐 |
region | — | S3 区域（可选） |
credentials.accessKeyId | — | Access Key 的 Secret 引用（name + key） |
credentials.secretAccessKey | — | Secret Key 的 Secret 引用（name + key） |
cacheSize | 10Gi | 本地用于缓存 S3 读取的磁盘空间，必须小于storage.size |
mode | tiered | 存储模式：tiered或s3only |
moveFactor | 0.1 | Tiered 模式下，本地磁盘可用空间低于总容量该比例时触发数据搬迁 |
Tiered 模式（推荐）
apiVersion: coroot.com/v1 kind: Coroot metadata: name: coroot namespace: coroot spec: communityEdition: nodeAgent: clusterAgent: clickhouse: shards: 1 replicas: 2 storage: size: 100Gi # local disk per replica s3: endpoint: https://s3.us-east-1.amazonaws.com/my-coroot-clickhouse/ region: us-east-1 credentials: accessKeyId: name: clickhouse-s3-creds key: access_key_id secretAccessKey: name: clickhouse-s3-creds key: secret_access_key cacheSize: 10Gi # local cache for S3 reads mode: tiered moveFactor: "0.1" # move data to S3 when <10% free space以上面 100Gi 本地盘为例：ClickHouse 会在本地磁盘可用空间低于约 10Gi（即moveFactor = 0.1）时，自动把最旧的数据部分（parts）搬迁到 S3，从而把本地占用控制在一个稳定的水位。整个搬迁由 ClickHouse 自身透明完成，无需修改任何表的 TTL 配置，保留策略（TTL 周期）内的数据都会被完整保留在 S3 上，而不是被删除。
S3-only 模式
所有数据直接落 S3，本地磁盘只承担读缓存与临时合并（merge）工作：
s3: endpoint: https://s3.us-east-1.amazonaws.com/my-coroot-clickhouse/ region: us-east-1 credentials: accessKeyId: name: clickhouse-s3-creds key: access_key_id secretAccessKey: name: clickhouse-s3-creds key: secret_access_key cacheSize: 20Gi # larger cache recommended for s3only mode mode: s3onlyS3-only 模式下可以放心缩小storage.size（本地盘仅用于缓存与临时操作），但建议同步调大cacheSize以缓解读放大，官方示例给出 20Gi。
Step 4：应用配置
kubectl apply -f coroot.yamlOperator 会监听 CR 变更，将 S3 存储配置写入 ClickHouse StatefulSet，随后滚动重启 ClickHouse Pod 使新配置生效。变更期间 ClickHouse 会短暂不可用，属正常现象。
工作原理
数据隔离：每个 Shard / Replica 独立的 S3 路径
为避免多副本并发写同一批 S3 对象造成数据损坏，每个 ClickHouse shard 与 replica 都使用独立的 S3 路径前缀，路径遵循以下模式：
s3://my-coroot-clickhouse/{shard}/{replica}/以 2 shard × 2 replica 为例，实际路径为：
s3://my-coroot-clickhouse/shard-0/coroot-clickhouse-shard-0-0/s3://my-coroot-clickhouse/shard-0/coroot-clickhouse-shard-0-1/s3://my-coroot-clickhouse/shard-1/coroot-clickhouse-shard-1-1/s3://my-coroot-clickhouse/shard-1/coroot-clickhouse-shard-1-1/
ClickHouse 虽然提供 "zero-copy replication"（零拷贝复制）特性让副本共享 S3 对象，但该特性自22.8 版本起默认关闭且仍处于实验阶段，存在已知的数据损坏风险（见 ClickHouse 官方 issue #45346）。因此 Operator 会显式禁用该特性，坚持每副本独立路径，保证数据安全。
本地缓存层
ClickHouse 与 S3 之间有一层本地磁盘缓存：频繁访问的数据会被缓存在本地，显著降低 S3 API 调用次数与读取延迟；同时缓存支持写入时预填充（cache_on_write_operations），新写入的数据立即可从缓存命中。这也是cacheSize参数存在的意义——它决定了这个缓存层能占用的本地磁盘上限。
Space Manager 自动禁用
启用 S3 后，Coroot 的 Space Manager 会被自动禁用，逻辑可以在 clickhouse/space_manager.go 中找到：Coroot 通过system.disks读取磁盘信息，一旦检测到存在type = 'ObjectStorage'的磁盘，便打印storage manager is disabled for ClickHouse on S3并跳过清理逻辑。
原因很清晰：Space Manager 的职责是在磁盘写满时删除最旧分区来释放空间（见 space_manager.go，仅针对otel_%与profiling_%表执行ALTER TABLE ... DROP PARTITION）；而启用 S3 后，磁盘压力由 ClickHouse 通过"把数据搬到 S3"来解决，数据得以保留完整的 TTL 周期，不再需要以牺牲数据为代价换取可用空间。这与 ClickHouse Cloud 场景下 Space Manager 自动禁用的处理方式一致。
使用 MinIO 或其他 S3 兼容存储
任意 S3 兼容存储（MinIO、Ceph RGW、SeaweedFS 等）都可以接入，只需把endpoint指向你的存储服务地址：
s3: endpoint: https://minio.example.com/coroot-clickhouse/ credentials: accessKeyId: name: minio-creds key: access_key_id secretAccessKey: name: minio-creds key: secret_access_key注意endpoint需要包含 bucket 前缀路径（如https://minio.example.com/coroot-clickhouse/），凭证 Secret 的创建方式与 Step 2 完全一致。
故障排查
1. 验证 S3 磁盘已生效
进入 ClickHouse Pod 执行：
kubectl exec -it <clickhouse-pod> -- clickhouse-clientSELECT name, path, type, free_space, total_space FROM system.disks预期输出中，除了Local默认磁盘外，还应看到类型为ObjectStorage的s3_disk与s3_cache两块磁盘。其中 S3 磁盘的free_space/total_space通常是一个极大的哨兵值（math.MaxUint64），Coroot 在读取时会将其归一化为 0（见 clickhouse.go 的处理逻辑），这一点在核对输出时需要注意。
2. 验证存储策略
SELECT * FROM system.storage_policies根据mode的不同，可以看到名为s3_tiered或s3_s3only的策略。
3. 检查数据在磁盘间的分布
SELECT disk_name, sum(bytes_on_disk) as bytes FROM system.parts WHERE active = 1 GROUP BY disk_name该查询可以直观看到本地盘与 S3 上分别承载了多少活跃数据。Tiered 模式下，随着时间推移，s3_disk上的字节数应持续增长、本地磁盘占用保持在水位附近，这正是分层存储按预期工作的信号。
常见注意事项
- bucket 专用：不要为 ClickHouse 配置外部对象生命周期删除策略，ClickHouse 自行管理对象生命周期；
- cacheSize 约束：本地缓存不能超过 ClickHouse 本地盘容量（
cacheSize < storage.size），否则配置无效； - 空间回收预期：Tiered 模式下数据搬迁是渐进式的，只有本地可用空间低于
moveFactor阈值后才会触发搬迁动作，无需人工干预； - Operator 升级：调整 S3 配置后如果 ClickHouse Pod 未按预期重启，可检查 Operator 日志与 CR 状态，必要时执行
kubectl rollout status观察 StatefulSet 滚动进度。
至此，Coroot 的 ClickHouse 已经从"单机本地盘"演进为"热冷分层"的弹性存储架构：近期遥测数据以全速查询，历史数据以极低成本长期留存，而这一切只需一份 CR 配置即可完成。
【免费下载链接】corootCoroot is an open-source observability and APM tool with AI-powered Root Cause Analysis. It combines metrics, logs, traces, continuous profiling, and SLO-based alerting with predefined dashboards and inspections.项目地址: https://gitcode.com/GitHub_Trending/co/coroot
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
