tchiotludo/akhq

AKHQ Docker镜像文档

1. 镜像概述与主要用途

AKHQ（曾用名：KafkaHQ）是一款针对Apache Kafka的图形化管理工具（GUI），旨在提供直观的界面用于管理Kafka集群中的主题（topics）、主题数据、消费者组（consumers group）、Schema Registry、Connect等核心组件。通过AKHQ，用户可简化Kafka集群的日常运维、监控与调试工作。

2. 核心功能与特性

• 主题管理：支持创建、查看、编辑、删除Kafka主题，配置分区数量、副本因子、保留策略等参数。
• 主题数据管理：查看主题消息内容，支持按分区、偏移量（offset）筛选，支持发送测试消息。
• 消费者组管理：监控消费者组状态、消费进度（包括当前偏移量、滞后量），支持重置偏移量。
• Schema Registry集成：管理Avro、JSON等 schema，查看版本历史、兼容性配置。
• Connect集成：管理Connect集群及连接器（connector），查看连接器状态、配置与任务详情。

3. 使用场景与适用范围

适用场景

• Kafka集群日常管理：管理员通过图形界面高效操作主题、消费者组等资源，替代命令行工具（如kafka-topics.sh）。
• 开发调试：开发人员快速验证消息生产/消费逻辑，查看消息格式与内容。
• 监控与问题排查：实时监控消费者组滞后情况，定位数据流转异常（如消息积压、消费失败）。

适用用户

• Kafka集群管理员
• 后端开发人员（使用Kafka进行消息传递的应用开发）
• 运维人员（负责Kafka集群监控与维护）

4. 使用方法与配置说明

4.1 前提条件

• 已部署Apache Kafka集群（支持Kafka 2.0+版本）。
• （可选）已部署Schema Registry、Kafka Connect服务（如需使用对应功能）。

4.2 Docker快速启动（docker run）

通过环境变量配置Kafka集群连接信息，启动AKHQ容器：

bash
docker run -d \
  --name akhq \
  -p 8080:8080 \  # AKHQ默认Web端口
  -e AKHQ_KAFKA_CLUSTERS_DEFAULT_BOOTSTRAPSERVERS=kafka:9092 \  # Kafka集群bootstrap servers（必填）
  -e AKHQ_KAFKA_CLUSTERS_DEFAULT_NAME=my-kafka-cluster \  # 集群显示名称（可选，默认"default"）
  -e AKHQ_KAFKA_CLUSTERS_DEFAULT_SCHEMAREGISTRY=http://schema-registry:8081 \  # Schema Registry URL（可选）
  -e AKHQ_KAFKA_CLUSTERS_DEFAULT_CONNECT=http://connect:8083 \  # Connect集群URL（可选）
  tchiotludo/akhq:latest

启动后，访问 http://<容器IP>:8080 即可打开AKHQ界面。

4.3 Docker Compose配置

搭配Kafka集群、Schema Registry、Connect的典型部署示例（docker-compose.yml）：

yaml
version: '3.8'
services:
  # Kafka集群（示例，实际环境可替换为已有集群）
  zookeeper:
    image: confluentinc/cp-zookeeper:latest
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
    ports:
      - "2181:2181"

  kafka:
    image: confluentinc/cp-kafka:latest
    depends_on:
      - zookeeper
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092
    ports:
      - "9092:9092"

  # Schema Registry（可选）
  schema-registry:
    image: confluentinc/cp-schema-registry:latest
    depends_on:
      - kafka
    environment:
      SCHEMA_REGISTRY_KAFKASTORE_BOOTSTRAP_SERVERS: PLAINTEXT://kafka:9092
      SCHEMA_REGISTRY_HOST_NAME: schema-registry
    ports:
      - "8081:8081"

  # AKHQ服务
  akhq:
    image: tchiotludo/akhq:latest
    depends_on:
      - kafka
      - schema-registry  # 如无需Schema Registry可移除
    ports:
      - "8080:8080"
    environment:
      # 配置Kafka集群连接（必填）
      AKHQ_KAFKA_CLUSTERS_DEFAULT_BOOTSTRAPSERVERS: kafka:9092
      AKHQ_KAFKA_CLUSTERS_DEFAULT_NAME: local-kafka-cluster
      # 启用Schema Registry集成（可选）
      AKHQ_KAFKA_CLUSTERS_DEFAULT_SCHEMAREGISTRY: http://schema-registry:8081

启动命令：

bash
docker-compose up -d

4.4 配置参数说明

AKHQ主要通过环境变量配置，核心参数如下（前缀AKHQ_KAFKA_CLUSTERS_<集群名称>中的<集群名称>可自定义，默认集群建议用default）：

5. 许可证

本镜像基于 https://github.com/tchiotludo/akhq/blob/master/LICENSE 开源，版权归 https://github.com/tchiotludo 所有。