From 28265f30976b0c47552960ae09a66f7e0f0c4be2 Mon Sep 17 00:00:00 2001
From: Gordon <46924906+FGadvancer@users.noreply.github.com>
Date: Thu, 26 Jun 2025 14:19:48 +0800
Subject: [PATCH] build: docker compose file add some comments.

---
 docker-compose.yml | 29 +++++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/docker-compose.yml b/docker-compose.yml
index 60fc865f2..233348619 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -176,17 +176,38 @@ services:
     environment:
       #KAFKA_HEAP_OPTS: "-Xms128m -Xmx256m"
       TZ: Asia/Shanghai
+      # Unique identifier for the Kafka node (required in controller mode)
       KAFKA_CFG_NODE_ID: 0
+      # Defines the roles this Kafka node plays: broker, controller, or both
       KAFKA_CFG_PROCESS_ROLES: controller,broker
+      # Specifies which nodes are controller nodes for quorum voting.
+      # The syntax follows the KRaft mode (no ZooKeeper): node.id@host:port
+      # The controller listener endpoint here is kafka:9093
       KAFKA_CFG_CONTROLLER_QUORUM_VOTERS: 0@kafka:9093
+      # Specifies which listener is used for controller-to-controller communication
       KAFKA_CFG_CONTROLLER_LISTENER_NAMES: CONTROLLER
+      # Default number of partitions for new topics
       KAFKA_NUM_PARTITIONS: 8
+      # Whether to enable automatic topic creation
       KAFKA_CFG_AUTO_CREATE_TOPICS_ENABLE: "true"
+      # Kafka internal listeners; Kafka supports multiple ports with different protocols
+      # Each port is used for a specific purpose: INTERNAL for internal broker communication,
+      # CONTROLLER for controller communication, EXTERNAL for external client connections.
+      # These logical listener names are mapped to actual protocols via KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP
+      # In short, Kafka is listening on three logical ports: 9092 for internal communication,
+      # 9093 for controller traffic, and 9094 for external access.
+      KAFKA_CFG_LISTENERS: "INTERNAL://:9092,CONTROLLER://:9093,EXTERNAL://:9094"
+      # Addresses advertised to clients. INTERNAL://kafka:9092 uses the internal Docker service name 'kafka',
+      # so other containers can access Kafka via kafka:9092.
+      # EXTERNAL://localhost:19094 is the address external clients (e.g., in the LAN) should use to connect.
+      # If Kafka is deployed on a different machine than IM, 'localhost' should be replaced with the LAN IP.
+      KAFKA_CFG_ADVERTISED_LISTENERS: "INTERNAL://kafka:9092,EXTERNAL://localhost:19094"
+      # Maps logical listener names to actual protocols.
+      # Supported protocols include: PLAINTEXT, SSL, SASL_PLAINTEXT, SASL_SSL
+      KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,EXTERNAL:PLAINTEXT,INTERNAL:PLAINTEXT"
+      # Defines which listener is used for inter-broker communication within the Kafka cluster
+      KAFKA_CFG_INTER_BROKER_LISTENER_NAME: "INTERNAL"
 
-      KAFKA_CFG_LISTENERS: "PLAINTEXT://:9092,CONTROLLER://:9093,EXTERNAL://:9094"
-      KAFKA_CFG_ADVERTISED_LISTENERS: "PLAINTEXT://kafka:9092,EXTERNAL://localhost:19094"
-      KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,EXTERNAL:PLAINTEXT,PLAINTEXT:PLAINTEXT"
-      KAFKA_CFG_INTER_BROKER_LISTENER_NAME: "PLAINTEXT"
 
       # Authentication configuration variables - comment out to disable auth
       # KAFKA_USERNAME: "openIM"