AutoMQ CLIautomq-shell实战指南集群拓扑声明、构建部署与诊断【免费下载链接】automqDiskless Kafka® on S3. 10x Cost-Effective. No Cross-AZ Traffic Cost. Autoscale in seconds. Single-digit ms latency. Multi-AZ Availability.项目地址: https://gitcode.com/GitHub_Trending/au/automqAutoMQ CLI 是 AutoMQ 仓库中用于创建、部署和诊断 AutoMQ 集群的命令行工具它以topo.yaml拓扑文件为核心把控制器节点 Broker 节点 S3 对象存储桶的声明式描述翻译成可直接执行的启动命令。本文基于 automq-shell/README.md 与automq-shell模块源码完整讲解 CLI 的构建方式、cluster create/deploy/describe三级命令、拓扑文件每一项配置的语义以及底层是如何做 S3 bucket 就绪检查、生成kafka-server-start.sh启动命令的。读完本文你将能独立完成一个 AutoMQ 集群从项目初始化到产出可运行启动命令的全流程。AutoMQ CLI 的定位与命令层级AutoMQ 是一个基于 S3 对象存储的 Diskless Kafka 实现Diskless Kafka on S3其数据平面与元数据可以完全落在对象存储上因此集群的部署本质上是为每个节点指定角色、nodeId 和 S3 桶配置。AutoMQ CLI模块名automq-shell正是为了把这个过程变成可声明、可重复、可审计的命令行流程而存在的。从项目构建脚本看automq-shell是一个独立的 Gradle 子模块在 settings.gradle 中注册其入口类为 AutoMQCLI.javaCommandLine.Command(name automq-cli, mixinStandardHelpOptions true, version automq-cli 1.0, description Command line tool for maintain AutoMQ cluster(s)., subcommands { Cluster.class }) public class AutoMQCLI { public static void main(String... args) { int exitCode new CommandLine(new AutoMQCLI()).execute(args); System.exit(exitCode); } }CLI 基于 picocli 4.7.6 构建见 build.gradle整体命令层级如下automq-cli └── cluster # 集群操作Cluster.java ├── create # 创建 AutoMQ 集群项目生成 topo.yaml 拓扑文件 ├── deploy # 基于拓扑文件生成各节点启动命令当前支持 --dry-run └── describe # 通过 Kafka AdminClient 描述集群节点与路由通道cluster子命令组定义在 Cluster.java 中声明了create、deploy、describe三个子命令并同样带mixinStandardHelpOptions即每个层级都支持-h/--help。此外automq-shell中还有 AutoMQApplication.java 这个轻量级的应用上下文容器基于ConcurrentHashMap的单例注册表 属性上下文用来保存CLUSTER_ID等进程级状态。构建 AutoMQ CLI从 Gradle 到 Native Image常规 JAR 构建与运行README 给出的构建命令位于仓库根目录执行./gradlew :cli:jar -x test java -jar cli/build/libs/cli-3.8.0-SNAPSHOT.jar -h需要说明的是README 中的:cli:jar与cli/build/libs/cli-3.8.0-SNAPSHOT.jar沿用了该工具早期版本的模块命名在当前仓库中这个模块的注册名是automq-shell见 settings.gradlebuild.gradle 中archivesBaseName automq-shell并且显式指定了可执行入口jar { manifest { attributes Main-Class: com.automq.shell.AutoMQCLI } }也就是说按当前仓库的实际模块名构建并运行等价于# 在仓库根目录执行编译 automq-shell 模块跳过测试以加快构建 ./gradlew :automq-shell:jar -x test # 运行 CLI 主入口-h 会输出完整的命令帮助信息 java -jar automq-shell/build/libs/automq-shell-version-SNAPSHOT.jar -hautomq-shell的依赖build.gradle包括picocli命令行框架、jackson-databind/jackson-yaml拓扑文件解析、s3streamS3 对象存储访问、BucketURI、ObjectStorage、clientsKafka Admin/Network 客户端、automq-metrics、automq-log-uploader以及guava、common-lang等。构建脚本对s3stream依赖做了大量排除opentelemetry、netty-tcnative、jnr、aspectj、argparse4j、bucket4j、aws-sdk 等目的是生成一个面向运维工具场景的精简运行时。Native Image 构建README 同时给出了 GraalVM Native Image 的构建方式将 CLI 编译为无需 JVM 即可直接执行的原生二进制适合容器镜像与轻量运维环境native-image -jar cli/build/libs/cli-3.8.0-SNAPSHOT.jar --initialize-at-build-timeorg.slf4j.LoggerFactory--initialize-at-build-timeorg.slf4j.LoggerFactory的作用是让 SLF4J 的LoggerFactory在构建期完成类初始化避免其在原生镜像运行时被重复初始化。若按当前模块名等价命令中的 JAR 路径相应替换为automq-shell/build/libs/automq-shell-version-SNAPSHOT.jar。automq-shell使用 picocli-codegen 作为注解处理器annotationProcessor info.picocli:picocli-codegen:4.7.6这也正是为 Native Image 场景预生成命令行元数据、减少反射配置的典型做法。cluster create声明式集群项目的起点cluster create的作用是在当前目录生成一个名为clusterName的集群项目项目内包含一份可编辑的拓扑文件clusters/clusterName/topo.yaml。其实现位于 Create.javaCommandLine.Command(name create, description Create a AutoMQ cluster project, mixinStandardHelpOptions true) public class Create implements CallableInteger { CommandLine.Parameters(index 0, description cluster name) private String clusterName; // ... }执行流程如下从 classpath 资源template/topo.yaml读取拓扑模板模板文件位于 template/topo.yaml用正则替换把模板中的clusterId: 替换为一个通过Uuid.randomUuid()生成的随机集群 ID在clusters/clusterName/topo.yaml写入该模板若目录已存在则报错退出打印下一步指引修改拓扑文件适配你的环境然后执行./bin/automq-cli.sh cluster deploy --dry-run clusters/clusterName。因此一个 AutoMQ 集群的运维起点就是一条命令 一份 YAML# 创建名为 demo 的集群项目 ./bin/automq-cli.sh cluster create demo # 生成后按提示修改 clusters/demo/topo.yaml 并部署 ./bin/automq-cli.sh cluster deploy --dry-run clusters/demo从 template/topo.yaml 可以看到create命令产出的拓扑骨架下一节详细解读它的每一部分。拓扑文件 topo.yaml 详解集群的全部声明topo.yaml是 AutoMQ CLI 的核心输入采用 YAML 格式顶层包含global、controllers、brokers三个部分。Deploy命令使用 Jackson 的YAMLFactory将其反序列化为 ClusterTopology.java包含Global global、ListNode controllers、ListNode brokers未知字段会被忽略。global集群全局配置global: clusterId: config: | s3.data.buckets0s3://xxx_bucket?regionus-east-1 s3.ops.buckets1s3://xxx_bucket?regionus-east-1 s3.wal.path0s3://xxx_bucket?regionus-east-1 log.dirs/root/kraft-logs envs: - name: AWS_ACCESS_KEY_ID value: xxxxx - name: AWS_SECRET_ACCESS_KEY value: xxxxx字段语义如下clusterIdAutoMQ 集群的唯一 ID。create命令会自动填入一个随机 UUID多个节点通过该 ID 标识属于同一集群。config一段properties 格式的全局配置文本对应 Global.java 中的config字段。Deploy在生成启动命令时会把这段文本解析成键值对逐个以--override参数追加到节点启动命令上。其中最关键的三项是s3.data.buckets数据桶存放业务数据流s3.ops.buckets运维桶存放集群运维相关的元数据s3.wal.pathWALWrite-Ahead Log路径同样是 S3 桶 URIlog.dirs本地落盘日志目录在 Diskless 架构下仅承担临时/缓存性质的落盘。envs一组环境变量键值对会被拼接到节点启动命令的最前面appendEnvs逻辑见 Deploy.java例如AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY等 S3 凭证。S3 桶 URI 格式与云厂商示例模板注释中明确了桶 URI 的格式与主流云厂商写法BucketURI.parseBuckets解析见 Deploy.javabucket URI pattern: 0s3://$bucket?region$regionendpoint$endpoint前缀数字0、1是桶的序号/编号s3://$bucket指定桶名查询参数region指定对象存储区域可选endpoint指定自定义 endpoint云厂商 S3 兼容网关或自建 S3 时使用。各厂商示例云厂商示例 URIAWS0s3://xxx_bucket?regionus-east-1AWS-CN0s3://xxx_bucket?regioncn-northwest-1endpointhttps://s3.amazonaws.com.cn阿里云 OSS0s3://xxx_bucket?regionoss-cn-shanghaiendpointhttps://oss-cn-shanghai.aliyuncs.com腾讯云 COS0s3://xxx_bucket?regionap-beijingendpointhttps://cos.ap-beijing.myqcloud.com注意阿里云 OSS 与腾讯云 COS 这类非 AWS 原生 endpoint需要显式传endpoint参数指向其兼容 S3 协议的网关地址。controllers 与 brokers节点声明controllers: # 默认情况下控制器节点是 combined 节点同时承担 controller 与 broker 角色 # 默认控制器端口为 9093默认 broker 端口为 9092 - host: 192.168.0.1 nodeId: 0 - host: 192.168.0.2 nodeId: 1 - host: 192.168.0.3 nodeId: 2 brokers: - host: 192.168.0.5 nodeId: 1000 - host: 192.168.0.6 nodeId: 1001每个节点只有host和nodeId两个必填字段模型见 Node.javanodeId默认值为Constants.NOOP_NODE_ID部署时若未设置会直接报错。模板注释强调了两个关键约定默认端口控制器controller 角色监听9093broker 监听9092combined 模式controllers列表中的节点默认是 combined 节点同时运行 controller 与 broker 两种角色而brokers列表中的节点则只承担 broker 角色。此外 Deploy.java 对控制器数量有硬性校验只支持 1 个或 3 个控制器用于生成controller.quorum.voters与controller.quorum.bootstrap.servers配置。cluster deploy拓扑到启动命令的翻译器cluster deploy接受一个位置参数集群项目路径并且当前只支持--dry-run模式--dry-run是必填选项./bin/automq-cli.sh cluster deploy --dry-run clusters/demo其实现逻辑在 Deploy.java整体流程为校验clusters/demo/topo.yaml是否存在不存在则报错退出若非--dry-run模式打印提示 Currently cluster deploy only support --dry-run即当前版本只输出命令、不实际拉起进程用 Jackson YAML 解析拓扑文件为ClusterTopology执行bucket 就绪检查见下节依次为每个 controller 节点生成基于config/kraft/server.properties的启动命令为每个 broker 节点生成基于config/kraft/broker.properties的启动命令并打印输出。Bucket 就绪检查部署前的第一道防线在生成任何启动命令之前Deploy会先对拓扑中声明的 S3 桶做连通性与凭证校验bucketReadinessCheck见 Deploy.java解析config中的s3.data.buckets与s3.ops.buckets两者缺一不可否则Exit.exit(-1)从envs中识别全局凭证KAFKA_S3_ACCESS_KEY/AWS_ACCESS_KEY_ID访问密钥与KAFKA_S3_SECRET_KEY/AWS_SECRET_ACCESS_KEY密钥逐个解析桶 URI 为BucketURI若桶 URI 自身未携带 access/secret 扩展参数则注入全局凭证通过ObjectStorageFactory构建ObjectStorage实例并调用readinessCheck()任一桶检查失败即整体退出。也就是说CLI 在真正产出启动命令前会先确认你声明的每个桶都可读可写避免命令生成了、启动后才发现 S3 访问失败的返工。生成的启动命令结构以控制器节点为例生成命令形如genServerStartupCmdDeploy.javaAWS_ACCESS_KEY_IDxxxxx AWS_SECRET_ACCESS_KEYxxxxx \ ./bin/kafka-server-start.sh -daemon config/kraft/server.properties \ --override cluster.iduuid \ --override node.idnodeId \ --override controller.quorum.votersnodeIdhost:9093,... \ --override controller.quorum.bootstrap.servershost:9093,... \ --override advertised.listenersPLAINTEXT://host:9092 \ --override globalConfigKeyglobalConfigValue ...broker 节点则基于config/kraft/broker.propertiesgenBrokerStartupCmdDeploy.java。被注入的--override项来自 ServerConfigKey.java 中定义的核心键node.id、controller.quorum.voters、listeners、advertised.listeners、s3.endpoint、s3.region、s3.bucket、s3.path.style再叠加topo.yaml中global.config里的全部键值对。值得注意的实现细节cluster.id与controller.quorum.voters是统一从拓扑的global与controllers列表推导出来的因此你只需在topo.yaml中声明一次集群 ID 和控制器清单所有节点的 quorum 配置都会自动保持一致从机制上杜绝了各节点 quorum 配置手写不一致导致集群起不来这类常见问题。命令输出末尾还会给出两条运维提醒Deploy.java运行命令前请确认主机已安装Java 17可用java -version验证先启动所有控制器再启动 broker。这与 KRaft 架构的启动顺序要求一致broker 需要先能访问 controller quorum 才能完成注册与元数据同步。cluster describe运行态集群诊断部署完成、集群启动后cluster describe用于查看集群当前的节点与路由通道状态它通过 KafkaAdminClient直接连接运行中的集群实现见 Describe.java# 连接指定 bootstrap server ./bin/automq-cli.sh cluster describe -b host:9092 # 或通过属性文件传入 AdminClient 配置含 SASL/SSL 等安全配置 ./bin/automq-cli.sh cluster describe -b host:9092 -c /path/to/client.properties参数说明-b, --bootstrap-server要连接的 Kafka server 地址-c, --command-config属性文件其中的配置会传给 AdminClient对应 Describe.java。输出内容包括两部分Nodes按 nodeId 排序的节点元数据列表来自admin.getNodes(...)和RouterChannelEpoch路由通道的 epoch 信息来自GetNodesResult.routerChannelEpoch()。其中RouterChannelEpoch是 AutoMQ 基于 S3 元数据服务的路由架构特有的概念反映当前路由通道的代际可用于判断元数据路由是否发生过切换。面向 S3 Stream 的底层能力从源码看 CLI 的扩展空间除了上述三个已接入的命令automq-shell源码中还存在一组面向 AutoMQ S3 Stream 协议的低层客户端基础设施从源码结构看可以推断它们是 CLI 未来做流/键值管理类命令的基础ClientStreamManager.java基于NetworkClient与 Kafka S3 协议请求DescribeStreamsRequest、GetOpeningStreamsRequest、CloseStreamsRequest实现流的按流 ID、按节点、按主题分区三种维度的描述与关闭能力ClientKVClient.java实现GetKVsRequest/PutKVsRequest/DeleteKVsRequest三类 KV 请求直接读写集群侧的键值存储CLIUtils.java封装了构造 KafkaNetworkClient含Selector、ApiVersions、ManualMetadataUpdater的完整参数链供上述两类客户端复用StreamTags.java定义了流标签编码规则——KEY0存 topic UUID、KEY1存十六进制分区号用于把 Stream 与 Kafka 主题分区建立映射。这些类当前尚未挂接到automq-cli的公开子命令树中公开子命令只有cluster但它们使用的请求类型DescribeStreamsRequest等与automq-shell的测试用例如 UtilsTest.java 对 GZIP 压缩/解压的往返验证都已有完整实现可作为后续扩展运维命令的现成地基。运维实践要点与限制综合 README、拓扑模板与源码实现使用 AutoMQ CLI 时建议遵循以下实践一条龙工作流cluster create name初始化项目 → 编辑clusters/name/topo.yaml填真实桶名、区域、endpoint、节点地址与 S3 凭证→cluster deploy --dry-run clusters/name产出启动命令。先检查再部署deploy --dry-run会自动执行 bucket 就绪检查要求s3.data.buckets与s3.ops.buckets同时存在任何桶不可达都会在生成命令前失败请确保凭证AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY正确、endpoint 可达。控制器数量约束控制器只能是 1 个或 3 个见 Deploy.java3 个控制器适用于生产高可用部署。运行环境要求目标主机需安装Java 17启动顺序为先控制器后 brokercombined 节点按控制器处理命令基于config/kraft/server.properties与config/kraft/broker.properties见 config/kraft可结合这两个文件理解 AutoMQ 在 KRaft 模式下的默认参数。当前版本限制deploy目前仅支持--dry-run输出命令而不实际拉起进程create不会覆盖已存在的同名集群项目模块在当前仓库中注册名为automq-shellREADME 中的:cli/cli-3.8.0-SNAPSHOT.jar为其早期命名构建与运行请以 settings.gradle 和 build.gradle 为准。诊断手段集群运行后用cluster describe -b host:9092检查节点清单与RouterChannelEpoch确认元数据路由健康。AutoMQ CLI 把多节点、多角色、多云对象存储的集群部署收敛为一份topo.yaml和三条子命令配合自动化的 quorum 推导与 bucket 就绪检查是理解 AutoMQ 集群组成结构、快速搭建验证环境时最直观的入口。【免费下载链接】automqDiskless Kafka® on S3. 10x Cost-Effective. No Cross-AZ Traffic Cost. Autoscale in seconds. Single-digit ms latency. Multi-AZ Availability.项目地址: https://gitcode.com/GitHub_Trending/au/automq创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
