Kafka локально и первый топик

Теперь проверим журнал и группы на настоящем Kafka. Запускаем один локальный broker/controller в KRaft, публикуем три события и читаем их двумя группами. После этого смотрим сохранённую позицию, повторяем историю и наблюдаем распределение трёх партиций между двумя участниками.

Подготовить настоящий Docker

Все команды этой страницы выполняются в терминале твоего компьютера. Встроенный учебный терминал сайта их не исполняет. На Windows используй Docker Desktop с Linux containers и PowerShell; на macOS — Docker Desktop; на Linux — Docker Engine. Если Docker ещё не готов, начни с официальной установки.

docker version
docker ps -a --filter name=roadmap-kafka

Должны быть доступны клиент и сервер Engine. Если имя уже занято твоим прошлым стендом, продолжи его осознанно либо выбери новое имя и замени его во всех командах. Чужой контейнер удалять ради свободного имени не нужно. Порт 9092 на компьютере также должен быть свободен.

docker pull apache/kafka:4.3.1
docker run -d --name roadmap-kafka -p 127.0.0.1:9092:9092 apache/kafka:4.3.1
docker logs roadmap-kafka

Не меняем переменные брокера: образ содержит стандартную конфигурацию одного совмещённого узла KRaft. CLI будем запускать внутри этого же контейнера, поэтому его localhost:9092 обозначает брокер. Java на хосте не требуется. Порт опубликован только на loopback, а стенд использует plaintext без настройки аутентификации.

Сначала дождись завершения запуска, затем проверь доступность:

docker exec roadmap-kafka /opt/kafka/bin/kafka-topics.sh --bootstrap-server localhost:9092 --list

У пустого стенда список пользовательских топиков может быть пуст. Если есть ошибка подключения, изучи logs и повтори после готовности. Статус контейнера сам по себе не равен успешному ответу Kafka API. Команды сверены для версии 4.3.1; ниже приведены ожидаемые наблюдения, которые ты проверишь своим запуском.

Создать один журнал с известным порядком

docker exec roadmap-kafka /opt/kafka/bin/kafka-topics.sh --bootstrap-server localhost:9092 --create --topic message-demo --partitions 1 --replication-factor 1
docker exec roadmap-kafka /opt/kafka/bin/kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic message-demo

В описании найди PartitionCount: 1, ReplicationFactor: 1, партицию 0, её Leader и ISR. Конкретный идентификатор брокера берётся из вывода. RF=1 здесь нужен для одной машины; другой реплики при отказе этого узла нет.

Инструкция ниже предполагает новый пустой message-demo. Повторный запуск --create не очищает существующий топик. Для новой попытки выбери новое имя и последовательно замени его в командах. Это сохранит понятные offsets, не затрагивая старую историю.

Записать key и JSON value

Открой интерактивный producer:

docker exec -it roadmap-kafka /opt/kafka/bin/kafka-console-producer.sh --bootstrap-server localhost:9092 --topic message-demo --sync --reader-property parse.key=true --reader-property "key.separator=|" --command-property acks=all --command-property enable.idempotence=true

Введи ровно три строки по одной, затем заверши producer через Ctrl+C:

17|{"event_id":"e-101","payload":"one"}
17|{"event_id":"e-102","payload":"two"}
17|{"event_id":"e-103","payload":"three"}

Слева от | находится настоящий key записи, справа — value. --sync ждёт результат каждой отправки и удобен для этой проверки. Все события окажутся в единственной партиции; успешно принятые записи нового топика получат offsets 0, 1, 2. Этот опыт не демонстрирует хеширование между несколькими партициями.

В Kafka 4.3 используем --reader-property для разбора ввода и --command-property для настроек клиента. Старые --property и --producer-property встречаются в инструкциях прежних версий; для нового листинга они не нужны.

Прочитать и проверить позицию группы

Во втором терминале запусти consumer. Он продолжает работать после трёх строк, ожидая новые записи:

docker exec -it roadmap-kafka /opt/kafka/bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic message-demo --group roadmap-a --from-beginning --command-property enable.auto.commit=true --command-property auto.commit.interval.ms=1000 --formatter-property print.key=true --formatter-property print.partition=true --formatter-property print.offset=true

Ожидаются три строки с Partition:0, offsets 0…2, ключом 17 и соответствующим JSON. После вывода подожди несколько секунд, оставляя consumer запущенным, и в третьем терминале посмотри группу:

docker exec roadmap-kafka /opt/kafka/bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group roadmap-a
docker exec roadmap-kafka /opt/kafka/bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group roadmap-a --members --verbose

Когда auto commit завершился, для партиции 0 ожидаются CURRENT-OFFSET = 3, LOG-END-OFFSET = 3, LAG = 0. Вторая команда показывает активного участника и назначение. Если commit ещё не виден, дождись следующего интервала и проверь снова.

Auto commit в этом опыте допустим: единственный эффект consumer — печать полученных строк. Для записи в базу нужен протокол из главы о доставке. Затем останови consumer через Ctrl+C.

Запусти такую же команду с --group roadmap-b. Новая группа прочитает три сохранённых события независимо. Останови её после наблюдения. Повторный запуск roadmap-a с --from-beginning продолжит с существующего commit 3; флаг не сбрасывает пригодную сохранённую позицию.

Replay и назначение нескольких партиций

Для replay группа roadmap-a должна быть без активных участников. Сначала посмотри план, затем выполни reset только этого топика этой группы:

docker exec roadmap-kafka /opt/kafka/bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --reset-offsets --group roadmap-a --topic message-demo --to-earliest
docker exec roadmap-kafka /opt/kafka/bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --reset-offsets --group roadmap-a --topic message-demo --to-earliest --execute

Для созданного в этом опыте топика ожидаемый NEW-OFFSET равен 0. Запусти roadmap-a снова и проверь повтор трёх событий. Сам reset не создаёт новых записей в топике. После проверки останови consumer.

Для отдельного наблюдения групп создай топик с тремя партициями:

docker exec roadmap-kafka /opt/kafka/bin/kafka-topics.sh --bootstrap-server localhost:9092 --create --topic group-demo --partitions 3 --replication-factor 1
docker exec -it roadmap-kafka /opt/kafka/bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic group-demo --group roadmap-parallel

Запусти второй consumer с той же командой в ещё одном терминале. В свободном терминале посмотри --describe --group roadmap-parallel --members --verbose. В стабильном состоянии назначены три партиции на двух участников, обычно как 2 и 1. Событий может ещё не быть: участие и назначение видно даже в пустом топике. После остановки одного участника дождись нового назначения и проверь оставшегося.

Три практические проверки и завершение

1. На новом message-demo запиши три заданных события. Сопоставь key, partition и offsets в выводе consumer. Проверка: одна партиция, три разных offsets, значения payload one, two, three в порядке отправки.
2. Получи commit 3 для roadmap-a. Прочитай историю новой группой, затем выполни запланированный reset неактивной roadmap-a. Проверка: история читается повторно, количество исходных записей не увеличивается.
3. Для group-demo запусти два участника одной группы, посмотри назначения и останови одного. Проверка: после перераспределения оставшийся участник владеет всеми тремя партициями. Это наблюдение rebalance, а не проверка EOS.

Заверши все интерактивные клиенты. Для сохранения стенда можно выполнить docker stop roadmap-kafka, а позже docker start roadmap-kafka: данные остаются в слое того же контейнера. Если этот учебный стенд больше не нужен, после остановки удали именно его:

docker stop roadmap-kafka
docker rm roadmap-kafka

Том не подключён, поэтому удаление контейнера удалит его данные. Это сознательно небольшой стенд для опытов. Он не проверяет репликацию между машинами, Kafka transactions, Registry или Connect. Ошибка из-за недоступного брокера внутри контейнера сначала требует проверки logs; при переходе к клиентам на другой машине также понадобится корректная настройка advertised listeners.