Szybki start z Apache Kafka – instalacja Kafka 4.2 za pomocą wiersza poleceń i lokalne przykłady

Apache Kafka 4.2.0 to obecnie wspierana linia wydania, a także najlepsze podstawy dla nowoczesnego przewodnika szybkiego startu, ponieważ Kafka 4.x jest w pełni niezależna od ZooKeepera i domyślnie zbudowana wokół KRaft.

Ten przewodnik to praktyczny, oparty na linii komend przewodnik szybkiego startu: instalacja Kafki, uruchomienie lokalnego brokera, nauka podstawowych narzędzi CLI Kafki oraz zakończenie na dwóch przykładach end-to-end, które możesz wkleić do swojego terminala.

Czym jest Apache Kafka i do czego się go używa

Apache Kafka to platforma do strumieniowania zdarzeń. W praktyce strumieniowanie zdarzeń oznacza przechwytywanie danych zdarzeniowych w czasie rzeczywistym ze źródeł (baz danych, czujników, aplikacji), trwałe przechowywanie powstałych strumieni oraz przetwarzanie lub routingowanie ich w czasie rzeczywistym (lub później).

Kafka łączy w jednej platformie trzy kluczowe możliwości: publikowanie i subskrybowanie strumieni zdarzeń, trwałe przechowywanie strumieni przez dowolnie długi czas oraz przetwarzanie strumieni w trakcie ich występowania lub retrospektywnie. To połączenie sprawia, że Kafka jest wykorzystywana do potoków danych w czasie rzeczywistym, integracji, komunikacji oraz analityki strumieniowej.

Aby zrozumieć, gdzie Kafka mieści się w szerszej infrastrukturze danych, zapoznaj się z filarem Infrastruktura danych dla systemów AI: Obiekty Storage, Bazy Danych, Wyszukiwanie & Architektura Danych AI, który obejmuje magazynowanie obiektów zgodne z S3, architekturę PostgreSQL, optymalizację Elasticsearch oraz warstwy danych natywnych dla AI.

Jeśli budujesz rozwiązania na AWS i potrzebujesz zarządzanej alternatywy, Budowa mikrousług zorientowanych na zdarzenia z AWS Kinesis omawia wdrażanie mikrousług zorientowanych na zdarzenia przy użyciu Kinesis Data Streams.

Dla stanu przetwarzania strumieniowego z Kafka, zobacz Apache Flink na K8s i Kafka: PyFlink, Go, ops, i ceny zarządzane.

Dla usług, które zapisują do bazy danych przed publikacją w Kafka, wzorzec transakcyjnego outbox zapewnia, że zdarzenia nigdy nie zostaną zagubione między zatwierdzeniem transakcji w bazie danych a wywołaniem produce w Kafka.

Operacyjnie Kafka to rozproszone system serwerów i klientów komunikujących się przez wysokowydajny protokół TCP: brokery przechowują i serwują dane; klienci (producenci i konsumenty) zapisują i odczytują zdarzenia, często w dużej skali i z tolerancją błędów.

Poniżej kilka pojęć, które będziesz spotykać powtarzalnie w CLI:

• Tematy (Topics) organizują zdarzenia. Temat jest wieloprojektowy i wielosubskrybencyjny, a zdarzenia mogą być odczytywane wielokrotnie, ponieważ retencja kontroluje, kiedy stare dane są usuwane.
• Partycje dzielą temat między brokery w celu skalowalności; kolejność jest gwarantowana w ramach partycji.
• Czynnik replikacji kontroluje tolerancję błędów. Dokumentacja przykładów zaleca czynniki replikacji 2 lub 3 w środowiskach produkcyjnych (jedno-node’owy lokalny przewodnik szybkiego startu zazwyczaj używa 1).

Instalacja Apache Kafka

Oficjalny przewodnik szybkiego startu Kafki używa wydania binarnego (tarball) lub oficjalnego obrazu Docker. Oba są poprawne dla rozwoju lokalnego.

Wymagania wstępne, których nie należy pomijać

Kafka 4.x wymaga nowoczesnego Java: dla serwera i narzędzi, Java 17+ jest podstawą do lokalnego uruchamiania, a Kafka 4.0 usunęła wsparcie dla Java 8.

Jeśli instalujesz Kafkę specjalnie w celu jej nauki, celuj w wspieraną JDK taką jak Java 17 lub 21. Strona wsparcia Java Kafki wymienia Java 17, 21 i 25 jako w pełni wspierane, podczas gdy Java 11 jest wspierana tylko dla podzbioru modułów (klienci i strumienie).

Instalacja z oficjalnego wydania binarnego

Oficjalny przewodnik szybkiego startu dla Kafki 4.2.0 zaczyna się od pobrania i rozpakowania dystrybucji binarnej:

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

Notatki dla zaawansowanych czytelników:

• “2.13” w nazwie pliku odzwierciedla linię budowy Scala. Dla binarnych wydań Kafki 4.x, Scala 2.13 jest podstawową linią dystrybucji, a Kafka 4.0 usunęła wsparcie dla Scala 2.12.
• Jeśli zależy Ci na integralności łańcucha dostaw, strona pobierania wyraźnie dokumentuje, że możesz zweryfikować pobrania przy użyciu opublikowanych procedur Apache i KEYS.

Instalacja z Docker

Kafka dostarcza również oficjalne obrazy Docker na Docker Hub. Przewodnik szybkiego startu pokazuje, że możesz pobrać i uruchomić Kafkę 4.2.0 w ten sposób:

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

Istnieje również linia obrazów “natywnych” (oparta na GraalVM native image). Dokumentacja Kafki i Kafka Improvement Proposal dla tej linii obrazów opisują ją jako eksperymentalną i przeznaczoną do rozwoju lokalnego i testów, nie do produkcji.

Uwaga dla użytkowników Windows

Dystrybucje Kafki zawierają skrypty Windows (pliki wsadowe). Dokumentacja Kafki historycznie zauważa, że na Windows używasz bin\windows\ i skryptów .bat zamiast skryptów Unix bin/ .sh.

Uruchomienie Kafki lokalnie z KRaft

Jeśli pytasz “Czy potrzebuję ZooKeepera, aby uruchomić Apache Kafka”, nowoczesna odpowiedź brzmi nie. Kafka 4.0 to pierwsze główne wydanie zaprojektowane do działania całkowicie bez ZooKeepera, działające domyślnie w trybie KRaft, co redukuje obciążenie operacyjne dla użycia lokalnego i produkcyjnego.

Uruchomienie pojedynczego lokalnego brokera z rozpakowanego tarballa

Przewodnik szybkiego startu Kafki 4.2 używa trzech poleceń:

1. Wygeneruj UUID klastra
2. Sformatuj katalogi logów
3. Uruchom serwer

# Generate a Cluster UUID
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"

# Format Log Directories (standalone local format)
bin/kafka-storage.sh format --standalone -t "$KAFKA_CLUSTER_ID" -c config/server.properties

# Start the Kafka broker
bin/kafka-server-start.sh config/server.properties

Dlaczego krok “format” ma znaczenie w KRaft: Dokumentacja operacyjna Kafki KRaft wyjaśnia, że kafka-storage.sh random-uuid generuje ID klastra i że każdy serwer musi być sformatowany przez kafka-storage.sh format. Jednym z uzasadnień jest to, że automatyczne formatowanie może ukrywać błędy, szczególnie wokół logu metadanych, więc jawne formatowanie jest preferowane.

Co uruchamiasz w tym przewodniku szybkiego startu

Dla rozwoju lokalnego Kafka może działać w uproszczonym ustawieniu “połączonym” (kontrolery i brokery razem). Dokumentacja Kafki KRaft wskazuje serwery połączone jako prostsze dla rozwoju, ale niezalecane w krytycznych środowiskach wdrożeniowych (gdzie chcesz mieć kontrolery odizolowane i skalowalne niezależnie).

Dla “prawdziwych” klastrów, kontrolery KRaft i brokery są osobnymi rolami (process.roles), a kontrolery są typowo wdrażane jako kworum 3 lub 5 węzłów (dostępność zależy od tego, czy większość jest żywa).

Podstawy CLI Kafki i główne parametry linii komend

Kafka dostarcza dużo narzędzi CLI w bin/. Oficjalne dokumenty operacyjne podkreślają dwie użyteczne właściwości:

• Wspólne narzędzia znajdują się w katalogu bin/ dystrybucji.
• Każde narzędzie drukuje swoje pełne użycie linii komend, gdy jest uruchomione bez argumentów.

Również ważne dla Kafki 4.x: Polecenia AdminClient już nie akceptują --zookeeper. Dokumentacja kompatybilności Kafki zauważa, że począwszy od Kafki 4.0, musisz używać --bootstrap-server do interakcji z klastrem.

Flagi połączenia Kafki, których będziesz używać stale

Większość narzędzi potrzebuje punktu wejścia do klastra:

• --bootstrap-server host:port
  Użyj tego dla operacji tematów, grup konsumentów i większości poleceń skierowanych do brokera. To kanoniczne zastąpienie dla przepływów pracy adminów opartych na ZooKeeper w Kafka 4.x.

KRaft wprowadza końcowe punkty brokera vs kontrolera dla niektórych narzędzi. Na przykład kafka-features.sh i części narzędzi metadanych mogą używać końcowych punktów kontrolera, podczas gdy wiele operacji adminów używa końcowych punktów brokera. Strona operacji KRaft pokazuje oba style w przykładach.

Zarządzanie tematami z kafka-topics.sh

Będziesz używać kafka-topics.sh do podstawowego cyklu życia:

• Tworzenie, opisywanie, listowanie tematów (Przewodnik szybkiego startu pokazuje --create, --describe, --topic).
• Określanie skali i trwałości poprzez partycje i czynnik replikacji. Przewodnik operacyjny pokazuje --partitions i --replication-factor i wyjaśnia, jak wpływają one na skalowalność i tolerancję błędów.
• Dodawanie nadpisań per temat w czasie tworzenia z --config key=value (dokumentacja konfiguracji tematów pokazuje konkretne przykłady).

Dobre “produkcyjne” polecenie tworzenia wygląda tak (ten dokładny kształt jest używany w oficjalnych dokumentach operacyjnych):

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

Produkowanie i konsumowanie z klientami konsolowymi

Przewodnik szybkiego startu używa konsolowego producenta i konsumenta, ponieważ są szybkie do walidacji i testów dymnych:

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

Kafka 4.2 zawiera również ulepszenia spójności CLI. W notatkach o aktualizacji:

• kafka-console-producer deprecjonuje --max-partition-memory-bytes i zaleca --batch-size zamiast tego.
• kafka-console-consumer deprecjonuje --property (właściwości formatownika) na rzecz --formatter-property.
• kafka-console-producer deprecjonuje --property (właściwości czytnika wiadomości) na rzecz --reader-property.

Jeśli utrzymujesz wewnętrzne podręczniki, te notatki są warte aktualizacji teraz, zanim Kafka 5.0 usunie deprecjonowane flagi.

Inspekcja opóźnienia konsumenta z kafka-consumer-groups.sh

Dla rzeczywistych systemów, “Czy mój konsument nadąża” to codzienna kwestia. Przewodnik operacyjny demonstruje:

• Listowanie grup: --list
• Opisanie grupy z offsetami i opóźnieniem: --describe --group ...
• Opisanie członków i przydziałów: --members i --verbose
• Usuwanie grup: --delete
• Bezpieczne resetowanie offsetów: --reset-offsets

Przykład:

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

Jedna uwaga konfiguracyjna dla lokalnego Docker i zdalnych klientów

Jeśli uruchamiasz Kafkę w kontenerach lub za load balancerami, ostatecznie natkniesz się na potrzebę poprawnego ustawienia nasłuchiwaczy. Dokumentacja konfiguracji brokera Kafki wyjaśnia advertised.listeners jako adresy, które brokery reklamują klientom i innym brokerom, szczególnie gdy adres powiązania nie jest adresem, którego klienci powinni używać.

Przykłady przewodnika szybkiego startu, które możesz uruchomić teraz

Poniższe przykłady są celowo oparte na CLI, abyś mógł zweryfikować lokalne ustawienie Kafki przed napisaniem jakiegokolwiek kodu aplikacji.

Przykład uruchomienia tematu i strumieniowania wiadomości end-to-end

To kanoniczny przepływ “utwórz, wyprodukuj, skonsumuj” z przewodnika szybkiego startu Kafki 4.2.

Otwórz terminal A i utwórz temat:

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

Teraz go opisz (opcjonalnie, ale użytecznie, gdy uczysz się partycji i czynnika replikacji):

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

Otwórz terminal B i uruchom producenta:

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

Wpisz kilka linii (każda linia staje się zdarzeniem), a następnie zostaw producenta uruchomionym:

This is my first event
This is my second event

Otwórz terminal C i uruchom konsumenta od początku:

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

Powinieneś zobaczyć te same linie wydrukowane.

Dlaczego to waliduje więcej niż “działa”: Przewodnik szybkiego startu Kafki wyjaśnia, że brokery trwale przechowują zdarzenia i że zdarzenia mogą być odczytywane wielokrotnie i przez wielu konsumentów. Ta trwałość jest powodem, dla którego ten wzorzec przewodnika szybkiego startu jest pierwszą rzeczą, którą powinieneś zrobić po każdej instalacji lub aktualizacji.

Przykład uruchomienia prostego potoku Kafka Connect z pliku do tematu do pliku

Kafka Connect odpowiada na nawracające pytanie “Jak przenieść dane do i z Kafki bez pisania niestandardowych producentów i konsumentów dla wszystkiego”. Przegląd Kafki Connect opisuje go jako narzędzie do skalowalnego, niezawodnego strumieniowania między Kafką a innymi systemami, poprzez konektory.

Przewodnik szybkiego startu Kafki 4.2 obejmuje minimalną, lokalną demonstrację Connect przy użyciu konektorów źródłowego i docelowego pliku.

Z katalogu Kafki, najpierw ustaw ścieżkę wtyczki roboczej, aby uwzględnić dostarczony jar konektora pliku:

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

Utwórz mały plik wejściowy:

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

Uruchom pracownika Connect w trybie standalone z konfiguracją zarówno źródłowego, jak i docelowego konektora:

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

Co powinno się wydarzyć (i dlaczego to jest użytecznie):

• Konektor źródłowy odczytuje linie z test.txt i produkuje je do tematu connect-test.
• Konektor docelowy odczytuje z connect-test i zapisuje do test.sink.txt.

Zweryfikuj plik docelowy:

more test.sink.txt

Powinieneś zobaczyć:

foo
bar

Możesz również zweryfikować temat bezpośrednio:

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

Ten drugi przykład to świetny budowniczy pamięci mięśniowej, ponieważ uczy Cię również, gdzie znajduje się konfiguracja Connect (konfiguracja pracownika plus konfiguracje konektorów) i pokazuje minimalny pętla “import, przechowywanie, eksport”.

Rozwiązywanie problemów i kolejne kroki

Większość problemów “Kafka Quickstart nie uruchamia się” sprowadza się do małego zestawu głównych przyczyn.

Broker nie uruchamia się

Zacznij od oficjalnych wymagań:

• Przewodnik szybkiego startu Kafki 4.2 wyraźnie wymaga Java 17+. Jeśli jesteś na starszej JDK, napraw to najpierw.
• W trybie KRaft, formatowanie magazynu jest wymaganym jawnym krokiem. Jeśli pominiesz kafka-storage.sh format, prawdopodobnie zobaczysz błędy uruchamiania lub błędy metadanych.

Jeśli eksperymentowałeś i teraz chcesz czystą płytę, przewodnik szybkiego startu Kafki pokazuje, jak usunąć lokalne katalogi danych używane w demonstracji:

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

Polecenia CLI zawodzą, nawet jeśli broker działa

W Kafka 4.x, zweryfikuj, że używasz --bootstrap-server (nie --zookeeper). Dokumentacja kompatybilności Kafki wyraźnie wskazuje usunięcie --zookeeper z poleceń AdminClient począwszy od Kafki 4.0.

Zaskoczenia sieciowe Docker

Jeśli Kafka jest w Dockerze, a Twoje narzędzie klienta jest na zewnątrz Dockera (lub na innej maszynie), możesz potrzebować poprawnej reklamy nasłuchiwaczy. Dokumentacja konfiguracji brokera wyjaśnia, że advertised.listeners jest używane, gdy adresy, do których klienci powinni się łączyć, różnią się od adresów powiązania (listeners).

Gdzie iść po przewodniku szybkiego startu

Jeśli ukończyłeś przykłady w tym poście, już odpowiedziałeś na najczęstsze pierwsze wyszukiwania:

• do czego używa się Kafki (strumieniowanie zdarzeń end-to-end)
• jak zainstalować Kafkę lokalnie (tarball lub Docker)
• dlaczego ZooKeeper zniknął i dlaczego KRaft jest domyślny w 4.x
• które narzędzia CLI są ważne na co dzień (tematy, producent, konsument, grupy)

Stąd najbardziej wartościowe kolejne kroki to zwykle:

• Przeczytaj “Wprowadzenie” Kafki dla głębszych modeli mentalnych tematów, partycji i replikacji.
• Odkryj Szybki Start Kafka Streams, jeśli chcesz pierwszą aplikację przetwarzania (Szybki Start Streams demonstruje uruchamianie demonstracji WordCount i inspekcję wyników z konsolowym konsumentem).