AutoMQ 贡献者指南：从零参与 Diskless Kafka 开源社区（环境搭建、PR 流程与本地调试全解析）

AutoMQ（AutoMQ for Kafka）是一款构建在对象存储之上的"无盘"（Diskless）Kafka 发行版，将数据持久化到 S3，从而获得 10 倍成本节约、秒级弹性伸缩与跨 AZ 零流量成本。本文以仓库根目录的 CONTRIBUTING_GUIDE.md 为骨架，结合 devkit/README.md、devkit/justfile、config/kraft/server.properties 等仓库内一手资料，系统讲解：如何选择最适合自己的入门路径、如何提交 Issue 与 Pull Request、如何在本机用 IDEA 编译、配置 S3 存储并启动可断点调试的完整 AutoMQ 集群。读完本文，你将具备从"跑通一个 broker"到"提交第一个被合入的补丁"的完整实战能力。

开始之前：社区规范与沟通渠道

AutoMQ 社区欢迎一切形式的贡献，包括首次贡献者。正式参与前，请先阅读并遵守 CODE_OF_CONDUCT.md（行为准则）：项目要求所有在 Slack、微信群及代码仓库中互动的参与者，共同维护一个对年龄、性别、种族、性取向等所有维度都友好无骚扰的环境；发现违规行为可向项目维护者举报，团队会保密调查并采取纠正措施。

遇到问题可以通过社区微信群或 Community Slack 联系维护者与其它贡献者；也可以直接在 GitHub Issue 下提问，维护者会尽量解答疑问。任何人都可以成为贡献者，门槛只在于愿意动手。

建议的入门路径（三选一）

贡献指南为新手规划了三条由浅入深的路径，建议按顺序尝试，避免一上来就陷入本地编译的复杂性：

路径一：Docker 快速探索（适合完全新手）

• 按 README.md 中描述的 Docker 方式直接运行 AutoMQ；
• 亲自验证三件事：成功启动 broker、成功创建 Topic、成功生产与消费消息；
• 目标是在不搭建本地环境的前提下，快速建立对 AutoMQ 行为的直觉。

路径二：DevKit 本地开发（推荐给想写代码的贡献者）

• DevKit 是基于 Docker Compose 的一键本地开发环境，内置 MinIO（S3 存储模拟）与 JDWP 调试端口；
• 快速开始：cd devkit 后执行 just start-build（单节点）或 just start-build 3（3 节点集群）；
• 常用快捷命令：just topic-list、just produce <topic>、just logs；
• 完整说明见 devkit/README.md。

路径三：手动本地开发（需要完全控制环境时）

• 按下文"本地调试与构建"章节，用 IDEA/手动配置在本地编译并运行 AutoMQ；
• 当需要对本地组件与配置进行深度定制时，这条路径最合适。

建议：遇到环境问题，优先查阅 devkit/README.md 中的"Local Debug with IDEA"章节以及下文 S3 配置部分。对大多数贡献者，推荐从 DevKit 入手，仅在需要深度定制环境时才使用手动方案。

深入 DevKit：一键拉起可调试集群

DevKit 是当前仓库为贡献者准备的核心开发工具，所有命令统一通过 just 执行（devkit/justfile）。其架构为：MinIO 提供 S3 存储，由 mc 一次性初始化 bucket，其上是 AutoMQ 节点——0～2 号节点承担 controller + broker（KRaft 投票者），3 号及以后的节点仅为 broker。支持节点数 1、3、4、5（节点编号从 0 开始）。

生命周期与诊断命令一览：

just start                      # 跳过构建直接启动（单节点）
just start 3 tabletopic         # 3 节点 + Iceberg Table Topic 功能栈
just start-build                # 先构建镜像与代码再启动
just stop                       # 停止容器（保留数据）
just clean                      # 停止并删除全部卷
just restart                    # 重启容器（不重新构建）
just status                     # 查看容器状态
just logs 0 500                 # 查看 node-0 最近 500 行日志（stdout/stderr）
just logs 0 | grep ERROR        # 日志支持管道过滤
just exec 0 grep -R ERROR /tmp/kafka-logs   # 组件日志位于容器内 /tmp/kafka-logs
just shell 0                    # 进入 node-0 容器 shell

主题、消费组与集群操作：

just topic-create my-topic --partitions 16
echo "hello" | just produce my-topic            # 管道生产单条消息
printf 'k1:v1\nk2:v2\n' | just produce my-topic --property parse.key=true --property "key.separator=:"
just consume my-topic --from-beginning --max-messages 10
just group-describe my-group                     # 查看各分区 offset 与 lag
just group-reset my-group my-topic --to-earliest
just broker-list                                 # 列出 broker 与 API 版本
just bin kafka-topics.sh --bootstrap-server localhost:9092 --list   # 直接透传 bin/ 脚本

性能压测（-1 表示不限吞吐）与运行时诊断：

just perf-produce my-topic --num-records 100000 --record-size 1024 --throughput -1
just arthas-exec 0 'dashboard -n 1'              # Arthas 抓取 CPU/内存/线程快照
just jmx -e 'get -b kafka.server:name=BrokerState,type=KafkaServer Value'   # 3 表示 broker 已运行

DevKit 还内置了基于 tc netem 与 iptables 的混沌测试能力（容器已预置 NET_ADMIN 权限），可注入网络延迟/丢包、S3 故障、节点间分区等故障，非常适合验证故障恢复逻辑，例如：

just chaos-s3-delay 500 node-0   # 仅影响 node-0 到 MinIO 的流量（500ms 延迟）
just chaos-s3-down               # 暂停 MinIO，模拟 S3 完全不可用
just chaos-partition node-0 node-1   # 双向隔离两个节点
just chaos-reset                 # 测试结束后务必清理全部故障规则

JDWP 调试端口从 node-0 的 5005 开始依次递增（node-1 → 5006，node-2 → 5007……），在 IDEA 中新建 Remote JVM Debug 指向 localhost:5005 即可断点调试；JMX 在 node-0 暴露于 9999 端口。

代码贡献工作流

查找或报告 Issue

查找已有 Issue：浏览项目 Issue 列表，标有 good first issue 标签的条目专门面向新手开放。认领方式很简单：在 Issue 下回复 /assign，GitHub 机器人会自动把 Issue 分配给你。

报告新 Issue：发现 Bug 或有功能诉求时，创建新 Issue 并选择对应模板（Bug Report 或 Feature Request），按表单填写即可。

提交 Pull Request 的完整流程

代码贡献的标准工作流如下（共 11 步）：

1. Fork AutoMQ 仓库；
2. 本地 Clone 仓库；
3. 为你的功能/Bug 修复创建分支，分支名格式为 {YOUR_USERNAME}/{FEATURE/BUG}，例如 jdoe/source-stock-api-stream-fix；
4. 提交修改（commit）；
5. 将本地分支推送到你的 Fork；
6. 提交 Pull Request，等待审查；
7. 链接一个已有的 Issue（通过上述步骤创建的、或你认领的、且不带 needs triage 标签的 Issue）。没有链接 Issue 的 PR 将被关闭；
8. 按 PULL_REQUEST_TEMPLATE.md 编写 PR 标题与描述。该模板要求说明变更的详细背景、测试策略（行为变更必须有单元/集成测试，较大变更应考虑系统测试），并核对 committer 清单：设计实现是否验证、测试覆盖与 CI 构建状态、文档（含升级说明）是否更新；
9. AutoMQ 维护者会为你的 PR 触发 CI 测试并进行代码审查；
10. 及时响应维护者的反馈与问题；
11. 合并贡献。

Pull Request 的审查会定期进行。请注意两点：务必回应反馈并签署 CLA；长期无更新的 PR 会因不活跃而被关闭。Fork 后 Clone 仓库的命令为：

git clone https://gitcode.com/GitHub_Trending/au/automq.git

环境要求

要求项	版本
编译要求	JDK 17
编译要求	Scala 2.13
运行要求	JDK 17

注意：本地开发与调试建议至少预留 8GB 内存。若尚未安装 Scala 2.13，可参考 Scala 官方下载页安装（仓库内 core 模块的 Scala 源码编译依赖 2.13 工具链）。

本地调试与构建（IDEA 手动方案）

Gradle 构建体系

AutoMQ 的构建方式与 Apache Kafka 完全一致：使用 Gradle 作为项目管理工具，Gradle 工程基于 Groovy 语法的脚本管理。与 Maven 的"根 POM + 子模块 POM"不同，Kafka/AutoMQ 的所有模块统一由根目录的 build.gradle 管理，各子模块不再单独维护构建脚本（子模块定义见 settings.gradle）。

不建议手动安装 Gradle：根目录的 gradlew 脚本会自动下载并锁定指定版本的 Gradle（当前仓库由 gradle/wrapper/gradle-wrapper.properties 固定为 Gradle 8.8，并带 SHA-256 校验），保证所有贡献者使用一致的构建环境。

编译项目

./gradlew jar -x test

-x test 跳过测试以加速首次编译；提交 PR 前应确保相关模块的测试通过。

准备 S3 服务

AutoMQ 的"无盘"设计要求一个 S3 兼容存储来持久化数据，本地开发有两种选择：

• LocalStack：安装并启动 localstack 以在本机模拟 S3 服务；
• AWS S3 服务：直接使用真实 AWS S3。

使用 localstack 时，先创建 bucket（ko3 为示例名）：

aws s3api create-bucket --bucket ko3 --endpoint=http://127.0.0.1:4566

修改配置

修改 config/kraft/server.properties，需要变更以下设置（以"键 = 值"简化写法为例）：

s3.endpoint=https://s3.amazonaws.com

# S3 服务所在的 region
# 若使用阿里云 OSS，需将 region 设为 aws-global（阿里云 OSS 支持通过 Amazon S3 SDK 访问）
s3.region=us-east-1

# 用于存储数据的 S3 bucket
s3.bucket=ko3

提示：若使用 localstack，s3.endpoint 必须写 http://127.0.0.1:4566 而不是 localhost，region 设为 us-east-1，bucket 与上一步创建的一致。

仓库实际配置格式：需要说明的是，config/kraft/server.properties 中 AutoMQ 的 S3 配置实际以完整 URL 形式给出，格式为：

s3.data.buckets=0@s3://ko3?region=us-east-1
s3.ops.buckets=0@s3://ko3?region=us-east-1
s3.wal.path=0@s3://ko3?region=us-east-1

URL 完整格式为 0@s3://$bucket?region=$region[&endpoint=$endpoint][&pathStyle=$enablePathStyle][&authType=$authType][&accessKey=$accessKey][&secretKey=$secretKey][&checksumAlgorithm=$checksumAlgorithm]，参数说明如下：

参数	取值	说明
pathStyle	true / false	对象存储访问路径风格；使用 MinIO 时必须为 true
authType	instance / static	instance 使用实例配置文件鉴权；static 从 URL 或系统环境变量 KAFKA_S3_ACCESS_KEY / KAFKA_S3_SECRET_KEY 读取密钥
endpoint	URL	S3 服务地址（MinIO/localstack 场景必填）
accessKey / secretKey	字符串	static 鉴权时使用

格式化元数据（KRaft 模式）

AutoMQ 使用 KRaft 模式（无需 ZooKeeper），首次启动前需要生成集群 UUID 并格式化元数据目录：

# 生成集群 UUID
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"

# 格式化元数据目录
bin/kafka-storage.sh format -t $KAFKA_CLUSTER_ID -c config/kraft/server.properties

脚本位于 bin/kafka-storage.sh。

IDE 启动配置

在 IDEA 中按以下配置创建运行项：

配置项	值
Main	core/src/main/scala/kafka/Kafka.scala（文件位于 core/src/main/scala/kafka/Kafka.scala）
ClassPath	-cp kafka.core.main
VM Options	-Xmx1G -Xms1G -server -XX:+UseZGC -XX:MaxDirectMemorySize=2G -Dkafka.logs.dir=logs/ -Dlog4j.configuration=file:config/log4j.properties -Dio.netty.leakDetection.level=paranoid
CLI Arguments	config/kraft/server.properties
Environment	KAFKA_S3_ACCESS_KEY=test;KAFKA_S3_SECRET_KEY=test

提示：使用 localstack 时，access key / secret key 可填任意值；使用真实 S3 服务时，KAFKA_S3_ACCESS_KEY 与 KAFKA_S3_SECRET_KEY 必须设置为对目标 bucket 具有读写权限的真实密钥。

从 VM Options 可以看到 AutoMQ 本地调试的典型 JVM 形态：-XX:+UseZGC（低延迟 GC）、-XX:MaxDirectMemorySize=2G（为 S3 流式读写预留直接内存）。这与 config/kraft/server.properties 中 S3 流分配器（s3.stream.allocator.policy，支持 POOLED_HEAP / POOLED_DIRECT，默认 POOLED_HEAP）及块缓存（s3.block.cache.size，默认 1GB）、WAL 缓存（s3.wal.cache.size，默认 2GB）等参数相呼应——若使用 DIRECT 内存分配器，必须同步调大 -Xmx 与 -XX:MaxDirectMemorySize。

关于运行时配置的更多细节

config/kraft/server.properties 中还包含一批与 AutoMQ 特性直接相关的关键项，调试时可按需调整：

• elasticstream.enable=true：开启"数据存储在弹性流层（S3）"的核心开关；
• s3.wal.upload.threshold：WAL 累积到该阈值后批量上传至 S3（默认 500MB）；
• s3.network.baseline.bandwidth：broker 网络基线带宽（默认 100MB/s），用于 compaction 与追赶读期间的网络限速；
• metric.reporters=kafka.autobalancer.metricsreporter.AutoBalancerMetricsReporter：Auto Balancer 的指标上报器；
• s3.telemetry.metrics.exporter.uri：指标导出 URI（OTLP/Prometheus 格式，完整格式见 kafka.automq.AutoMQConfig 的文档注释）。

另外，仓库还提供了集群模式配置示例，见 config/kraft/broker.properties 与 config/kraft/controller.properties（分别对应纯 broker 与纯 controller 角色）。

文档贡献

我们欢迎一切提升文档质量的 Pull Request，包括但不限于：改进语法、优化文章结构、修正拼写错误。文档类 PR 与代码 PR 遵循相同的提交与审查流程。

参与社区的其他方式

除代码与文档外，另一种重要的贡献方式是报告 Bug 与帮助其他用户：你可以在 GitHub 上提交 Issue 反馈问题，也可以进入 Community Slack 为其它使用者答疑解惑——这些行为同样是社区不可或缺的贡献。

结语

从"用 Docker 跑通一个 broker"到"用 DevKit 拉起 3 节点可调试集群"，再到"提交一个带完整测试、链接了 Issue 的 Pull Request"，本文完整还原了 AutoMQ 贡献者指南的推荐路径，并结合仓库源码补齐了 S3 URL 配置格式、Gradle 构建体系、KRaft 格式化、IDE 调试参数等一手细节。AutoMQ 的核心思想——把 Kafka 的存储层搬到 S3 上以获得成本与弹性的双重收益——决定了它的贡献者需要同时理解 Kafka 生态与对象存储的交互方式，而 DevKit 与本文介绍的本地调试链路，正是快速建立这种理解的最短路径。现在，从 good first issue 开始你的第一次贡献吧。