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

Установите Kafka 4.2 и начните потоковую обработку событий за несколько минут.

Содержимое страницы

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

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

инфографика распределенной обработки сообщений apache kafka

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

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

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

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

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

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

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

  • Темы (Topics) организуют события. Тема поддерживает множественных производителей и подписчиков, а события могут быть прочитаны несколько раз, так как правила удержания определяют, когда старые данные удаляются.
  • Партиции (Partitions) шуннируют тему между брокерами для масштабируемости; порядок гарантируется внутри каждой партиции.
  • Коэффициент репликации контролирует отказоустойчивость. Примеры в документации обычно рекомендуют коэффициенты репликации 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 является основной, а поддержка Scala 2.12 была удалена в Kafka 4.0.
  • Если вам важна целостность цепочки поставок, на странице загрузок явно указано, что вы можете проверять загрузки, используя опубликованные процедуры 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-скрипты (bat-файлы). В документации Kafka исторически отмечается, что на Windows следует использовать bin\windows\ и .bat скрипты, а не Unix-скрипты bin/ .sh.

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

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

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

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

  1. Генерация UUID кластера
  2. Форматирование директорий логов
  3. Запуск сервера
# Генерация Cluster UUID
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"

# Форматирование директорий логов (режим standalone local)
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 может работать в упрощенной “комбинированной” конфигурации (контроллеры и брокеры объединены). Документация KRaft указывает, что комбинированные серверы проще для разработки, но не рекомендуются для критически важных сред развертывания (где требуется изоляция контроллеров и возможность их независимого масштабирования).

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

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

Kafka поставляется с множеством инструментов CLI в каталоге 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

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

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

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

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

  • 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 как адреса, которые брокеры объявляют клиентам и другим брокерам, особенно когда адрес привязки отличается от адреса, который должны использовать клиенты.

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

Приведенные ниже примеры намеренно основаны на CLI, чтобы вы могли проверить локальную настройку 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 в режиме standalone с конфигурацией коннектора источника и приемника:

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 Quickstart не запускается” сводятся к небольшому набору коренных причин.

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

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

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

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

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

Команды CLI не работают, хотя брокер запущен

В 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
  • какие инструменты CLI важны в повседневной работе (темы, продюсер, консьюмер, группы)

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

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