配置

GreptimeDB 支持使用 Kafka 实现 Remote WAL 存储。要启用 Remote WAL，需要分别配置 Metasrv 和 Datanode。

如果你使用 Helm Chart 部署 GreptimeDB，可以参考常见 Helm Chart 配置项了解如何配置 Remote WAL。

Metasrv 配置

Metasrv 负责 Kafka topics 的管理及过期 WAL 数据的自动清理。

[wal]
provider = "kafka"
broker_endpoints = ["kafka.kafka-cluster.svc.cluster.local:9092"]

# WAL 数据清理策略
auto_prune_interval = "30m"
auto_prune_parallelism = 10
flush_trigger_size = "512MB"
checkpoint_trigger_size = "128MB"

# Topic 自动创建配置
auto_create_topics = true
num_topics = 64
replication_factor = 1
topic_name_prefix = "greptimedb_wal_topic"
create_topic_timeout = "30s"

配置

配置项	说明
provider	设置为 "kafka" 以启用 Remote WAL。
broker_endpoints	Kafka broker 的地址列表。
auto_prune_interval	自动清理过期 WAL 的间隔时间，设为 "0s" 表示禁用。
auto_prune_parallelism	并发清理任务的最大数量。
auto_create_topics	是否自动创建 Kafka topic，设为 false 时需手动预创建。
num_topics	用于存储 WAL 的 Kafka topic 数量。
replication_factor	每个 topic 的副本数量。
topic_name_prefix	Kafka topic 名称前缀，必须匹配正则 [a-zA-Z_:-][a-zA-Z0-9_:\-\.@#]*。
flush_trigger_size	触发 region flush 操作的预估大小阈值（如 "512MB"）。计算公式为 (latest_entry_id - flushed_entry_id) * avg_record_size。当此值超过 flush_trigger_size 时，MetaSrv 会触发 region flush 操作。设为 "0" 时由系统自动控制。该配置还可控制 region 重放期间从 topic 重放的最大数据量，较小的值有助于缩短 Datanode 启动时的重放时间。
checkpoint_trigger_size	触发 region checkpoint 操作的预估大小阈值（如 "128MB"）。计算公式为 (latest_entry_id - last_checkpoint_entry_id) * avg_record_size。当此值超过 checkpoint_trigger_size 时，MetaSrv 会启动检查点操作。设为 "0" 时由系统自动控制。较小的值有助于缩短 Datanode 启动时的重放时间。
create_topic_timeout	创建 Kafka topic 的超时时间，默认值为 "30s"。

Kafka Topic 与权限要求

请确保以下设置正确，以保证 Remote WAL 正常运行：

• 如果 auto_create_topics = false：
  • 必须在启动 Metasrv 之前手动创建好所有 WAL topics；
  • Topic 名称必须符合 {topic_name_prefix}_{index} 的格式，其中 index 的取值范围是 0 到 {num_topics - 1}。例如，默认前缀为 greptimedb_wal_topic，且 num_topics = 64 时，需要创建从 greptimedb_wal_topic_0 到 greptimedb_wal_topic_63 的 topic。
  • Topic 必须配置为支持LZ4 压缩。
• Kafka 用户需具备以下权限：
  • 对 topics 追加数据；
  • 读取 topics 中数据；
  • 删除 topics 中数据；
  • 若启用自动创建（auto_create_topics = true），还需具备 创建 topic 的权限。

Datanode 配置

Datanode 负责将数据写入 Kafka 并从中读取数据。

[wal]
provider = "kafka"
broker_endpoints = ["kafka.kafka-cluster.svc.cluster.local:9092"]
max_batch_bytes = "1MB"
overwrite_entry_start_id = true
connect_timeout = "3s"
timeout = "3s"

配置

配置项	说明
provider	设置为 "kafka" 以启用 Remote WAL。
broker_endpoints	Kafka broker 的地址列表。
max_batch_bytes	每个写入批次的最大大小，默认不能超过 Kafka 配置的单条消息上限（通常为 1MB）。
overwrite_entry_start_id	若设为 true，在 WAL 回放时跳过缺失的 entry，避免 out-of-range 错误（但可能掩盖数据丢失）。
connect_timeout	Kafka 客户端的连接超时时间，默认值为 "3s"。
timeout	Kafka 客户端操作的超时时间，默认值为 "3s"。

注意事项与限制

重要：Kafka 保留策略配置

请非常小心地配置 Kafka 保留策略以避免数据丢失。GreptimeDB 会自动回收不需要的 WAL 数据，因此在大多数情况下你不需要设置保留策略。但是如果你确实需要设置，请确保以下几点：

• 基于大小的保留策略：通常不需要设置，因为数据库会管理自己的数据生命周期
• 基于时间的保留策略：如果你选择设置此项，请确保保留时间远大于自动刷新间隔 (auto-flush-interval) 以防止过早删除数据。

不当的保留设置可能导致数据丢失，如果 WAL 数据在 GreptimeDB 处理之前被删除。

• 如果 overwrite_entry_start_id = true：

  • 确保 Metasrv 中的 auto_prune_interval 已启用，以允许自动清理 WAL；
  • Kafka topics 不应使用基于大小保留策略；
  • 如果启用基于时间的保留策略，请确保保留时间远大于自动刷新间隔（auto-flush-interval），至少是它的两倍。

• 确保 Datanode 使用的 Kafka 用户具有以下权限：

  • 对 topics 追加数据；
  • 读取 topics 中数据；

• 确保 max_batch_bytes 不超过 Kafka topic 的最大消息大小（通常为 1MB）。

Kafka 认证配置

Kafka 的认证参数在 Metasrv 和 Datanode 的 [wal] 段中配置。

SASL 认证

支持的 SASL 机制包括：PLAIN、SCRAM-SHA-256 和 SCRAM-SHA-512。

[wal]
broker_endpoints = ["kafka.kafka-cluster.svc.cluster.local:9092"]

[wal.sasl]
type = "SCRAM-SHA-512"
username = "user"
password = "secret"

TLS

要启用 TLS，可在 [wal.tls] 段进行配置，支持以下几种方式：

使用系统 CA 证书

无需提供证书路径，自动使用系统信任的 CA：

[wal]
broker_endpoints = ["kafka.kafka-cluster.svc.cluster.local:9092"]

[wal.tls]

使用自定义 CA 证书

用于 Kafka 集群使用私有 CA 的场景：

[wal]
broker_endpoints = ["kafka.kafka-cluster.svc.cluster.local:9092"]

[wal.tls]
server_ca_cert_path = "/path/to/server.crt"

使用双向 TLS（mTLS）

同时提供客户端证书与私钥：

[wal]
broker_endpoints = ["kafka.kafka-cluster.svc.cluster.local:9092"]
[wal.tls]
server_ca_cert_path = "/path/to/server_cert"
client_cert_path = "/path/to/client_cert"
client_key_path = "/path/to/key"