Documentation Index
Fetch the complete documentation index at: https://docs.automq.com/llms.txt
Use this file to discover all available pages before exploring further.
本文旨在解释 AutoMQ 部署过程中涉及的配置参数，包括配置定义、描述、设置范围和规范等，以帮助开发者在生产环境中进行必要的自定义调整。
AutoMQ 基于对象存储实现了存储计算分离，完全兼容 Apache Kafka，因此关于 Kafka 的功能配置（例如 ACL、网络等）均可以参考官方配置文档。本文档仅列举 AutoMQ 新增的存储模块相关的配置参数。
公共配置
elasticstream.enable
列表项
| 说明
|
|---|
配置描述
| 是否启动 AutoMQ，该参数必须设置为 true。
|
值类型
| boolean
|
默认值
| false
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
automq.zonerouter.channels
通过开启跨可用区请求路由功能，减少跨可用区数据传输，减少流量成本。该功能详情请参考 概述▸ 。
列表项
| 说明
|
|---|
配置描述
| 跨可用区的 channel 配置，通过配置跨可用区路由组件可极大减少跨 zone 流量带来的成本。目前只支持对象存储，格式是：0@s3://$bucket?region=$region[&batchInterval=250][&maxBytesInBatch=8388608]
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
S3Stream 相关配置
s3.data.buckets
列表项
| 说明
|
|---|
配置描述
| 数据面对象存储的URI。格式是：0@s3://$bucket?region=$region[&endpoint=$endpoint][&pathStyle=$enablePathStyle][&authType=$authType][&accessKey=$accessKey][&secretKey=$secretKey][&checksumAlgorithm=$checksumAlgorithm]。
不同厂商配置参见：对象存储配置▸。
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
s3.ops.buckets
列表项
| 说明
|
|---|
配置描述
| 控制面对象存储的URI。格式是：1@s3://$bucket?region=$region[&endpoint=$endpoint][&pathStyle=$enablePathStyle][&authType=$authType][&accessKey=$accessKey][&secretKey=$secretKey][&checksumAlgorithm=$checksumAlgorithm]。
不同厂商配置参见：对象存储配置▸ 。
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
s3.wal.path
列表项
| 说明
|
|---|
配置描述
| 用于存储本地 WAL 的块存储设备挂载路径，格式是：
0@s3://$bucket?region=$region[&batchInterval=250][&maxBytesInBatch=8388608]
不同厂商参见：对象存储配置▸
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
s3.wal.cache.size
列表项
| 说明
|
|---|
配置描述
| WAL（预写日志）缓存是一个FIFO（先进先出）队列，其中包含尚未上传到对象存储的数据，以及已经上传但尚未从缓存中逐出的数据。当尚未上传的缓存数据填满整个容量时，存储将会对后续请求产生回压，直到完成数据上传。默认情况下，它会根据内存设置一个合理的值。
|
值类型
| long，单位为 byte
|
默认值
| -1，由程序自动设置合适的参数值
|
合法输入范围
| [1, …]
|
重要级别
| 低，设置相对宽泛
|
s3.wal.upload.threshold
列表项
| 说明
|
|---|
配置描述
| 触发 WAL 向对象存储上传的阈值。配置值需要小于 s3.wal.cache.size 。配置值越大，数据聚合度越高，元数据存储的成本越低。默认情况下，它会根据内存设置一个合理的值。
|
值类型
| long，单位为 byte
|
默认值
| -1，由程序自动设置合适的参数值
|
合法输入范围
| [1, …]
|
重要级别
| 低，设置相对宽泛
|
s3.block.cache.size
列表项
| 说明
|
|---|
配置描述
| s3.block.cache.size 是 block cache 的大小。block cache 用于缓存从对象存储读取的冷数据。建议将此配置项设置为大于 4MB * 每个分区的并发冷读数，以实现更好的冷读性能。默认情况下，它会根据内存设置一个合理的值。
|
值类型
| long，单位为 byte
|
默认值
| -1，由程序自动设置合适的参数值
|
合法输入范围
| [1, …]
|
重要级别
| 低，设置相对宽泛
|
s3.stream.object.compaction.interval.minutes
列表项
| 说明
|
|---|
配置描述
| Stream object 进行 compaction 的间隔周期。间隔越大，API调用的成本越低，但它增加了元数据存储的规模。
|
值类型
| int，单位是分钟
|
默认值
| 30
|
合法输入范围
| [1, …]
|
重要级别
| 低，设置相对宽泛
|
s3.stream.object.compaction.max.size.bytes
列表项
| 说明
|
|---|
配置描述
| Stream object compaction 允许合成的对象的最大大小。这个值越大，API调用的成本越高，但元数据存储的规模越小。
|
值类型
| long，单位为 byte
|
默认值
| 1073741824
|
合法输入范围
| [1, …]
|
重要级别
| 低，设置相对宽泛
|
s3.stream.set.object.compaction.interval.minutes
列表项
| 说明
|
|---|
配置描述
| 设置 stream object compaction 的间隔。这个值越小，元数据存储的规模就越小，数据变得紧凑的时间也会更早。然而，最终生成的流对象经历的压缩次数会增加。
|
值类型
| int，单位是分钟
|
默认值
| 20
|
合法输入范围
| [1, …]
|
重要级别
| 低，设置相对宽泛
|
s3.stream.set.object.compaction.cache.size
列表项
| 说明
|
|---|
配置描述
| 在 stream object compaction 过程中可用的内存大小。这个值越大，API调用的成本越低。
|
值类型
| long，单位是 byte
|
默认值
| 209715200
|
合法输入范围
| [1048576, …]
|
重要级别
| 低，设置相对宽泛
|
s3.stream.set.object.compaction.stream.split.size
列表项
| 说明
|
|---|
配置描述
| 在 Stream object compaction 过程中，如果单个 Stream 中的数据量超过此阈值，这个 Stream 的数据将直接被分割并写入单个 Stream 对象。这个值越小，数据从 Stream set object 中分割的时间就越早，Stream object compaction 的后续 API 调用成本就越低，但是分割的 API 调用成本就越高。
|
值类型
| long，单位为 byte
|
默认值
| 8388608
|
合法输入范围
| [1, …]
|
重要级别
| 低，设置相对宽泛
|
s3.network.baseline.bandwidth
列表项
| 说明
|
|---|
配置描述
| 对象存储请求的总可用带宽。这是用来防止 stream set object compaction 和追赶读取占据正常读写流量。生产和消费也会分别消耗进出流量。
例如，假设这个值设置为100MB/s，而正常的读写流量是80MB/s，那么用于 stream set object compaction 的可用流量就是 20MB/s。
|
值类型
| long，单位为 byte/s
|
默认值
| 104857600
|
合法输入范围
| [1, …]
|
重要级别
| 低，设置相对宽泛
|
s3.stream.allocator.policy
列表项
| 说明
|
|---|
配置描述
| S3Stream 内存分配器策略。请注意，当配置为使用DIRECT内存时，需要修改虚拟机选项中的堆大小（例如，-Xmx）和直接内存大小（例如，-XX:MaxDirectMemorySize）。您可以通过环境变量KAFKA_HEAP_OPTS来设置它们。
|
值类型
| string
|
默认值
| POOLED_HEAP
|
合法输入范围
| POOLED_HEAP, POOLED_DIRECT
|
重要级别
| 低，设置相对宽泛
|
s3.telemetry.metrics.level
列表项
| 说明
|
|---|
配置描述
| 设置记录 Metrics 的级别。
“INFO”级别包括大多数用户应该关心的指标，例如常见流操作的吞吐量和延迟。“DEBUG”级别包括有助于诊断的详细指标，例如写入底层块设备时不同阶段的延迟。
|
值类型
| string
|
默认值
| INFO
|
合法输入范围
| INFO, DEBUG
|
重要级别
| 低，设置相对宽泛
|
s3.telemetry.exporter.report.interval.ms
列表项
| 说明
|
|---|
配置描述
| 设置 Metrics 导出的时间间隔。
|
值类型
| int，单位是毫秒
|
默认值
| 30000
|
合法输入范围
| N/A
|
重要级别
| 低，设置相对宽泛
|
s3.telemetry.metrics.base.labels
列表项
| 说明
|
|---|
配置描述
| Metrics 的多维标签，用于为所有监控指标附加静态的多维度标签，实现指标的分类、聚合与精细化分析。格式是：key1=value1,key2=value2。
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 中，需要谨慎配置
|
s3.telemetry.metrics.exporter.uri
列表项
| 说明
|
|---|
配置描述
| Metrics 的导出uri。格式是：$type://?$param1=$value1&$param2=$value2。目前type支持的类型有prometheus, otlp。
prometheus的格式：prometheus://?host=$hostname&port=$port
otlp的格式：otlp://?endpoint=$endpoint&protocol=$protocol&compression=$compression
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
持续数据重平衡配置
metric.reporters
列表项
| 说明
|
|---|
配置描述
| metrics reporters 的类列表。实现 org.apache.kafka.common.metrics.MetricsReporter 接口可以实现动态加载新的 Metrics。 JmxReporter 总是被包含在内，以注册JMX统计信息。要启用自动平衡（AutoBalancing）， metric.reporters 必须包含 kafka.autobalancer.metricsreporter.AutoBalancerMetricsReporter 。
|
值类型
| list
|
默认值
| ""
|
合法输入范围
| N/A
|
重要级别
| 低，设置相对宽泛
|
autobalancer.reporter.metrics.reporting.interval.ms
列表项
| 说明
|
|---|
配置描述
| Metrics Reporter 上报数据的间隔。
|
值类型
| long，单位是毫秒
|
默认值
| 10000
|
合法输入范围
| [1000, …]
|
重要级别
| 高，需要谨慎配置
|
autobalancer.controller.enable
列表项
| 说明
|
|---|
配置描述
| 是否启用自动重平衡。
|
值类型
| boolean
|
默认值
| false
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
autobalancer.controller.anomaly.detect.interval.ms
列表项
| 说明
|
|---|
配置描述
| Controller 检查是否需要进行数据重平衡的最小间隔。下一次重平衡的实际时间也取决于已经被重新分配的分区的数量。降低最小检查间隔可以提高数据重新平衡的灵敏度。该值应大于 broker metrics的上报间隔，以防止控制器错过最近重新分配的结果。
|
值类型
| long，单位是毫秒
|
默认值
| 60000
|
合法输入范围
| [1, …]
|
重要级别
| 高，需要谨慎配置
|
autobalancer.controller.exclude.topics
列表项
| 说明
|
|---|
配置描述
| 需要排除，不进行数据重平衡的 Topic 列表。
|
值类型
| list
|
默认值
| ""
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
autobalancer.controller.exclude.broker.ids
列表项
| 说明
|
|---|
配置描述
| 需要排除，不进行数据重平衡的 Broker Id 列表。
|
值类型
| list
|
默认值
| ""
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
Table Topic
Table Topic 是 AutoMQ 面向现代数据湖架构设计的核心功能，其核心作用在于实现流式数据与静态数据湖的集成，通过架构创新解决传统流批分离、ETL 复杂、成本高昂等问题。详情参见 概述▸ 。 automq.table.topic.enable
列表项
| 说明
|
|---|
配置描述
| 是否启用 AutoMQ Table Topic。启用后将创建 Iceberg Table，用于存储 AutoMQ Table 数据。
|
值类型
| boolean
|
默认值
| false
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
automq.table.topic.commit.interval.ms
列表项
| 说明
|
|---|
配置描述
| Table Topic 的数据提交间隔时间。提交间隔越短，数据实时性越高，相应的处理成本也会增加，反之亦然。
|
值类型
| long
|
默认值
| 300000，单位ms
|
合法输入范围
| 整整数
|
重要级别
| 高，需要谨慎配置
|
automq.table.topic.upsert.enable
列表项
| 说明
|
|---|
配置描述
| 是否启用 Table Topic 的 Upsert 功能。开启后，系统会根据主键自动判断是插入新记录还是更新已有记录。
|
值类型
| boolean
|
默认值
| false
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
automq.table.topic.partition.by
列表项
| 说明
|
|---|
配置描述
| 定义 Table Topic 的分区规则，通过字段或函数对数据进行分区。
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
automq.table.topic.id.columns
列表项
| 说明
|
|---|
配置描述
| 指定表的唯一主键列。
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
automq.table.topic.cdc.field
列表项
| 说明
|
|---|
配置描述
| 指定记录 CDC（Change Data Capture）操作类型的字段名称。用于标识数据库变更操作类型，值为单个字符 I 、 U 或 D ，分别对应数据的插入、更新和删除动作。
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
automq.table.topic.schema.type
列表项
| 说明
|
|---|
配置描述
| schema类型。支持两种模式： schemaless （不解析消息内容）和 schema （需在 schema registry 预定义消息 value 的 Schema，并根据该 Schema 写入到 Iceberg 中）。
|
值类型
| string
|
默认值
| schemaless
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
automq.table.topic.namespace
列表项
| 说明
|
|---|
配置描述
| Table topic 的命名空间
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
automq.table.topic.schema.registry.url
列表项
| 说明
|
|---|
配置描述
| Schema Registry 的服务地址
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
automq.table.topic.catalog.type
列表项
| 说明
|
|---|
配置描述
| 指定 Catalog 的类型，目前支持rest、glue、nessie、tablebucket、hive五种类型
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
AutoMQ Table Topic 支持多种 Iceberg Catalog 类型，不同类型需要配置不同的参数。详情参见：Table Topic 配置▸ rest
automq.table.topic.catalog.uri
列表项
| 说明
|
|---|
配置描述
| 指定 Iceberg REST Catalog 服务地址
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
automq.table.topic.catalog.warehouse
列表项
| 说明
|
|---|
配置描述
| 指定 Catalog 仓库的 S3 路径
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
automq.table.topic.catalog.oauth2-server-uri
列表项
| 说明
|
|---|
配置描述
| 指定 oauth 认证服务地址
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 可选
|
automq.table.topic.catalog.credential
列表项
| 说明
|
|---|
配置描述
| 指定 Catalog 的证书
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 可选
|
automq.table.topic.catalog.token
列表项
| 说明
|
|---|
配置描述
| 指定 Catalog 的 token
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 可选
|
automq.table.topic.catalog.scope
列表项
| 说明
|
|---|
配置描述
| 指定 Catalog 认证范围
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 可选
|
glue
automq.table.topic.catalog.warehouse
列表项
| 说明
|
|---|
配置描述
| 指定 Iceberg 仓库的 S3 路径
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
nessie
automq.table.topic.catalog.uri
列表项
| 说明
|
|---|
配置描述
| 指定 Iceberg Catalog 服务地址
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
automq.table.topic.catalog.warehouse
列表项
| 说明
|
|---|
配置描述
| 指定 Iceberg 仓库的 S3 路径
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
tablebucket
automq.table.topic.catalog.warehouse
列表项
| 说明
|
|---|
配置描述
| 指定 Iceberg 仓库的 S3 路径
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
hive
automq.table.topic.catalog.uri
列表项
| 说明
|
|---|
配置描述
| 指定 Iceberg Catalog 服务地址
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
automq.table.topic.catalog.warehouse
列表项
| 说明
|
|---|
配置描述
| 指定 Iceberg 仓库的 S3 路径
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 高，需要谨慎配置
|
automq.table.topic.catalog.auth
列表项
| 说明
|
|---|
配置描述
| 指定 Catalog 认证服务地址
|
值类型
| string
|
默认值
| null
|
合法输入范围
| N/A
|
重要级别
| 可选
|
