Быстрый старт с Apache Kafka — установка Kafka 4.2 с использованием CLI и локальных примеров

Apache Kafka 4.2.0 является текущей поддерживаемой веткой выпуска, и это наилучшая базовая линия для современного быстрого старта, поскольку Kafka 4.x полностью работает без ZooKeeper и по умолчанию построена вокруг KRaft.

Это руководство представляет собой практический быстрый старт с упором на командную строку: установка Kafka, запуск локального брокера, изучение основных инструментов командной строки Kafka и завершение двумя примерами от начала до конца, которые можно вставить прямо в терминал.

Что такое Apache Kafka и для чего она используется

Apache Kafka — это платформа потоковой передачи событий. В практическом смысле потоковая передача событий означает захват данных о событиях в реальном времени из источников (базы данных, датчики, приложения), надежное хранение полученных потоков и их обработка или маршрутизация в реальном времени (или позже).

Kafka объединяет три основные возможности в одной платформе: публикация и подписка на потоки событий, надежное хранение потоков столько, сколько необходимо, и обработка потоков по мере их возникновения или ретроспективно. Именно эта комбинация делает Kafka подходящей для потоков данных в реальном времени, интеграции, обмена сообщениями и потоковой аналитики.

Чтобы понять место Kafka в более широкой инфраструктуре данных, см. раздел Инфраструктура данных для систем ИИ: объектное хранилище, базы данных, поиск и архитектура данных для ИИ, который охватывает объектное хранилище, совместимое с S3, архитектуру PostgreSQL, оптимизацию Elasticsearch и уровни данных, ориентированные на ИИ.

Если вы работаете в AWS и вам нужен управляемый альтернативный вариант, Построение микросервисов, управляемых событиями, с помощью AWS Kinesis, описывает реализацию микросервисов, управляемых событиями, с использованием Kinesis Data Streams.

Для потоковой обработки с сохранением состояния с Kafka см. Apache Flink на K8s и Kafka: PyFlink, Go, эксплуатация и управляемые цены.

С эксплуатационной точки зрения Kafka — это распределенная система серверов и клиентов, общающихся по высокопроизводительному протоколу TCP: брокеры хранят и обслуживают данные; клиенты (производители и потребители) записывают и читают события, часто в больших масштабах и с отказоустойчивостью.

Несколько концепций, которые вы будете встречать постоянно в командной строке:

• Топики организуют события. Топик поддерживает множественных производителей и множественных подписчиков, а события можно читать многократно, поскольку управление временем удержания определяет, когда старые данные удаляются.
• Партиции разделяют топик между брокерами для масштабируемости; порядок гарантируется внутри каждой партиции.
• Коэффициент репликации контролирует отказоустойчивость. В документационных примерах обычно рекомендуются коэффициенты репликации 2 или 3 в производственной среде (для одноузловой разработки в быстром старте обычно используется 1).

Установка Apache Kafka

Официальный быстрый старт Kafka использует бинарный релиз (tarball) или официальный образ Docker. Оба варианта подходят для локальной разработки.

Предварительные требования, которые нельзя пропустить

Kafka 4.x требует современной версии Java: для сервера и инструментов базовой линией для локального запуска является Java 17+, а в Kafka 4.0 поддержка Java 8 была удалена.

Если вы устанавливаете Kafka специально для обучения, стремитесь к поддерживаемой версии JDK, такой как Java 17 или 21. Страница поддержки Java в Kafka указывает, что Java 17, 21 и 25 полностью поддерживаются, в то время как Java 11 поддерживается только для подмножества модулей (клиенты и потоки).

Установка из официального бинарного релиза

Официальный быстрый старт для Kafka 4.2.0 начинается с загрузки и распаковки бинарной дистрибуции:

tar -xzf kafka_2.13-4.2.0.tgz
cd kafka_2.13-4.2.0

Примечания для продвинутых читателей:

• “2.13” в имени файла отражает ветку сборки Scala. Для бинарных файлов Kafka 4.x основной линией дистрибуции является Scala 2.13, а в Kafka 4.0 поддержка Scala 2.12 была удалена.
• Если вас беспокоит целостность цепочки поставок, страница загрузок явно указывает, что вы можете проверять загрузки, используя опубликованные процедуры Apache и KEYS.

Установка с помощью Docker

Kafka также предоставляет официальные образы Docker на Docker Hub. В быстром старте показано, как получить и запустить Kafka 4.2.0 следующим образом:

docker pull apache/kafka:4.2.0
docker run -p 9092:9092 apache/kafka:4.2.0

Существует также линия образов “native” (на основе нативного образа GraalVM). Документация Kafka и Предложение по улучшению Kafka (KIP) для этой линии образов описывают её как экспериментальную и предназначенную для локальной разработки и тестирования, а не для продакшена.

Примечание по платформе для пользователей Windows

Дистрибутивы Kafka включают скрипты для Windows (файлы пакетов). В документации Kafka исторически отмечается, что на Windows используются bin\windows\ и скрипты .bat, а не Unix-скрипты bin/ .sh.

Запуск Kafka локально с KRaft

Если вы спрашиваете: “Нужен ли мне ZooKeeper для запуска Apache Kafka”, современный ответ — нет. Kafka 4.0 — это первый крупный релиз, разработанный для работы полностью без ZooKeeper, работающий по умолчанию в режиме KRaft, что снижает эксплуатационную нагрузку для локального и производственного использования.

Запуск локального брокера с одним узлом из распакованного tarball

Быстрый старт Kafka 4.2 использует три команды:

1. Генерация UUID кластера
2. Форматирование директорий журналов
3. Запуск сервера

# Генерация UUID кластера
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"

# Форматирование директорий журналов (независимый локальный формат)
bin/kafka-storage.sh format --standalone -t "$KAFKA_CLUSTER_ID" -c config/server.properties

# Запуск брокера Kafka
bin/kafka-server-start.sh config/server.properties

Почему шаг “форматирования” важен в KRaft: документация операций KRaft в Kafka объясняет, что kafka-storage.sh random-uuid генерирует ID кластера и что каждый сервер должен быть отформатирован с помощью kafka-storage.sh format. Одна из причин заключается в том, что автоматическое форматирование может скрыть ошибки, особенно связанные с журналом метаданных, поэтому предпочтительно явное форматирование.

Что вы запускаете в этом быстром старте

Для локальной разработки Kafka может работать в упрощенной конфигурации “combined” (контроллеры и брокеры объединены). В документации KRaft Kafka отмечается, что объединенные серверы проще для разработки, но не рекомендуются для критически важных сред развертывания (где вы хотите, чтобы контроллеры были изолированы и масштабируемы независимо).

Для “настоящих” кластеров контроллеры KRaft и брокеры представляют собой отдельные роли (process.roles), и контроллеры обычно развертываются как кворум из 3 или 5 узлов (доступность зависит от того, что большинство узлов живы).

Основные инструменты командной строки Kafka и основные параметры

Kafka поставляется с множеством инструментов командной строки в директории bin/. Официальная документация по операциям подчеркивает два полезных свойства:

• Общие инструменты находятся в директории bin/ дистрибуции.
• Каждый инструмент выводит полное описание использования командной строки при запуске без аргументов.

Также важно для Kafka 4.x: Команды AdminClient больше не принимают --zookeeper. Документация совместимости Kafka отмечает, что начиная с Kafka 4.0, для взаимодействия с кластером необходимо использовать --bootstrap-server.

Флаги подключения Kafka, которые вы будете использовать постоянно

Большинству инструментов нужна точка входа в кластер:

• --bootstrap-server host:port
  Используйте это для операций с топиками, группами потребителей и большинства команд, ориентированных на брокер. Это каноничная замена для рабочих процессов администрирования, основанных на ZooKeeper, в Kafka 4.x.

KRaft вводит endpoints брокера и контроллера для некоторых инструментов. Например, kafka-features.sh и части инструментария метаданных могут использовать endpoints контроллера, в то время как многие операции администрирования используют endpoints брокера. Страница операций KRaft показывает оба стиля в примерах.

Управление топиками с помощью kafka-topics.sh

Вы будете использовать kafka-topics.sh для основного жизненного цикла:

• Создание, описание и перечисление топиков (быстрый старт показывает --create, --describe, --topic).
• Указание масштаба и надежности через партиции и коэффициент репликации. Руководство по операциям показывает --partitions и --replication-factor и объясняет, как они влияют на масштабируемость и отказоустойчивость.
• Добавление переопределений для конкретного топика при создании с помощью --config key=value (документация по конфигурации топов показывает конкретные примеры).

Хорошая команда создания с учетом требований продакшена выглядит следующим образом (эта точная форма используется в официальных документах по операциям):

bin/kafka-topics.sh --bootstrap-server localhost:9092 \
  --create --topic my_topic_name \
  --partitions 20 --replication-factor 3 \
  --config x=y

Производство и потребление с помощью консольных клиентов

В быстром старте используются консольный производитель и потребитель, потому что они быстры для валидации и smoke-тестов:

• kafka-console-producer.sh --topic ... --bootstrap-server ...
• kafka-console-consumer.sh --topic ... --from-beginning --bootstrap-server ...

Kafka 4.2 также включает улучшения согласованности командной строки. В заметках об обновлении:

• kafka-console-producer устаревает --max-partition-memory-bytes и рекомендует использовать --batch-size.
• kafka-console-consumer устаревает --property (свойства форматтера) в пользу --formatter-property.
• kafka-console-producer устаревает --property (свойства считывателя сообщений) в пользу --reader-property.

Если вы поддерживаете внутренние руководства, эти заметки стоит обновить сейчас, до того, как Kafka 5.0 удалит устаревшие флаги.

Проверка задержки потребителей с помощью kafka-consumer-groups.sh

Для реальных систем вопрос “Успевает ли мой потребитель” является ежедневным. Руководство по операциям демонстрирует:

• Перечисление групп: --list
• Описание группы со смещениями и задержкой: --describe --group ...
• Описание участников и назначений: --members и --verbose
• Удаление групп: --delete
• Безопасная сброс смещений: --reset-offsets

Пример:

bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group my-group

Одна тонкость конфигурации для локального Docker и удаленных клиентов

Если вы запускаете Kafka в контейнерах или за балансировщиками нагрузки, вам в конечном итоге придется правильно настроить listeners. Документация конфигурации брокера Kafka объясняет advertised.listeners как адреса, которые брокеры рекладируют клиентам и другим брокерам, особенно когда адрес привязки отличается от адреса, который должны использовать клиенты.

Примеры быстрого старта, которые можно запустить прямо сейчас

Приведенные ниже примеры намеренно основаны на командной строке, чтобы вы могли проверить локальную настройку Kafka, прежде чем писать какой-либо код приложения.

Пример: запуск топика и потоковая передача сообщений от начала до конца

Это канонический поток “создать, произвести, потребовать” из быстрого старта Kafka 4.2.

Откройте терминал A и создайте топик:

bin/kafka-topics.sh --create --topic quickstart-events --bootstrap-server localhost:9092

Теперь опишите его (опционально, но полезно при изучении партиций и коэффициента репликации):

bin/kafka-topics.sh --describe --topic quickstart-events --bootstrap-server localhost:9092

Откройте терминал B и запустите производителя:

bin/kafka-console-producer.sh --topic quickstart-events --bootstrap-server localhost:9092

Введите пару строк (каждая строка становится событием), затем оставьте производителя запущенным:

Это мое первое событие
Это мое второе событие

Откройте терминал C и запустите потребителя с самого начала:

bin/kafka-console-consumer.sh --topic quickstart-events --from-beginning --bootstrap-server localhost:9092

Вы должны увидеть напечатанными те же строки.

Почему это подтверждает больше, чем просто “это работает”: быстрый старт Kafka объясняет, что брокеры надежно хранят события и что события можно читать многократно и многими потребителями. Именно эта надежность делает этот паттерн быстрого старта первым, что вы должны сделать после любой установки или обновления.

Пример: запуск простого конвейера Kafka Connect из файла в топик и обратно в файл

Kafka Connect отвечает на повторяющийся вопрос: “Как мне перемещать данные в Kafka и из неё, не создавая кастомных производителей и потребителей для всего”. Обзор Kafka Connect описывает его как инструмент для масштабируемой и надежной потоковой передачи между Kafka и другими системами через коннекторы.

Быстрый старт Kafka 4.2 включает минимальную локальную демонстрацию Connect с использованием коннекторов источника и приемника файлов.

Из вашей директории Kafka сначала установите путь плагина рабочего процесса, чтобы включить предоставленный jar-файл коннектора файлов:

echo "plugin.path=libs/connect-file-4.2.0.jar" >> config/connect-standalone.properties

Создайте небольшой входной файл:

echo -e "foo\nbar" > test.txt

Запустите рабочий процесс Connect в автономном режиме с конфигурацией коннектора источника и приемника:

bin/connect-standalone.sh \
  config/connect-standalone.properties \
  config/connect-file-source.properties \
  config/connect-file-sink.properties

Что должно произойти (и почему это полезно):

• Коннектор источника читает строки из test.txt и производит их в топик connect-test.
• Коннектор приемника читает из connect-test и записывает в test.sink.txt.

Проверьте файл приемника:

more test.sink.txt

Вы должны увидеть:

foo
bar

Вы также можете проверить топик напрямую:

bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic connect-test --from-beginning

Этот второй пример — отличный тренажер мышечной памяти, потому что он также учит, где находится конфигурация Connect (конфигурация рабочего процесса плюс конфигурации коннекторов), и показывает минимальный цикл “ввод, хранение, экспорт”.

Устранение неполадок и следующие шаги

Большинство проблем “быстрый старт Kafka не запускается” сводятся к небольшому набору коренных причин.

Брокер не запускается

Начните с официальных требований:

• Быстрый старт Kafka 4.2 явно требует Java 17+. Если вы используете более старую версию JDK, исправьте это в первую очередь.
• В режиме KRaft форматирование хранилища является обязательным явным шагом. Если вы пропустите kafka-storage.sh format, вы, скорее всего, увидите ошибки запуска или ошибки метаданных.

Если вы экспериментировали и теперь хотите начать с чистого листа, быстрый старт Kafka показывает, как удалить локальные директории данных, используемые в демонстрации:

rm -rf /tmp/kafka-logs /tmp/kraft-combined-logs

Команды командной строки не выполняются, хотя брокер запущен

В Kafka 4.x убедитесь, что вы используете --bootstrap-server (а не --zookeeper). Документация совместимости Kafka явно указывает на удаление --zookeeper из команд AdminClient, начиная с Kafka 4.0.

Сюрпризы сетевого взаимодействия Docker

Если Kafka работает в Docker, а ваш клиентский инструмент находится вне Docker (или на другой машине), вам может потребоваться правильная реклама listeners. Документация конфигурации брокера объясняет, что advertised.listeners используется, когда адреса, к которым должны подключаться клиенты, отличаются от адресов привязки (listeners).

Куда двигаться после быстрого старта

Если вы выполнили примеры в этом посте, вы уже ответили на самые распространенные первые поисковые запросы:

• для чего используется Kafka (потоковая передача событий от начала до конца)
• как установить Kafka локально (tarball или Docker)
• почему ZooKeeper исчез и почему KRaft является стандартом в 4.x
• какие инструменты командной строки важны в повседневной работе (топики, производитель, потребитель, группы)

Отсюда следующие наиболее ценные шаги обычно заключаются в следующем:

• Прочитайте “Введение” в Kafka для более глубоких ментальных моделей топиков, партиций и репликации.
• Изучите Быстрый старт Kafka Streams, если вы хотите создать первое приложение обработки (быстрый старт Streams демонстрирует запуск демо WordCount и проверку результатов с помощью консольного потребителя).