Szybki start z Apache Kafka – instalacja Kafka 4.2 z użyciem CLI i przykładami lokalnymi

Apache Kafka 4.2.0 to obecnie wspierana wersja i stanowi najlepszą podstawę do nowoczesnego szybkiego startu, ponieważ Kafka 4.x jest całkowicie pozbawiona ZooKeepera i domyślnie oparta na KRaft.

Ten przewodnik to praktyczny przewodnik szybkiego startu skupiony na wierszu poleceń: instalacja Kafki, uruchomienie lokalnego brokera, nauka podstawowych narzędzi CLI Kafki oraz zakończenie dwoma przykładami end-to-end, które możesz wkleić do terminala.

Czym jest Apache Kafka i do czego służy

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

Kafka połączyła trzy podstawowe możliwości w jednej platformie: publikowanie i subskrybowanie strumieni zdarzeń, trwałe przechowywanie strumieni przez dowolnie długi czas oraz przetwarzanie strumieni w miarę ich występowania lub retrospektywnie. To połączenie sprawia, że Kafka jest używana do rurociągów danych w czasie rzeczywistym, integracji, wymiany wiadomości i strumieniowej analizy.

Aby zrozumieć, gdzie Kafka mieści się w szerszej infrastrukturze danych, zobacz filar Infrastruktura danych dla systemów AI: Magazynowanie obiektowe, bazy danych, wyszukiwanie i architektura danych AI, który obejmuje kompatybilne ze S3 magazynowanie obiektowe, architekturę PostgreSQL, optymalizację Elasticsearcha oraz natywne dla AI warstwy danych.

Jeśli budujesz na AWS i potrzebujesz zarządzanej alternatywy, Budowanie mikroserwisów sterowanych zdarzeniami z AWS Kinesis opisuje implementację mikroserwisów sterowanych zdarzeniami przy użyciu Kinesis Data Streams.

W ujęciu operacyjnym Kafka to rozproszony system serwerów i klientów komunikujących się za pomocą wydajnego protokołu TCP: brokerzy przechowują i obsługują dane; klienci (producenci i konsumenci) zapisują i odczytują zdarzenia, często w dużej skali i z tolerancją błędów.

Oto kilka pojęć, które powtarzają się wielokrotnie w CLI:

• Tematy (Topics) organizują zdarzenia. Temat obsługuje wielu producentów i wielu subskrybentów, a zdarzenia mogą być odczytywane wielokrotnie, ponieważ zasady retencji kontrolują, kiedy stare dane są usuwane.
• Partycje (Partitions) dzielą temat między brokerów w celu skalowalności; kolejność jest gwarantowana w ramach partycji.
• Współczynnik replikacji kontroluje tolerancję błędów. Przykłady w dokumentacji zalecają współczynniki replikacji 2 lub 3 w środowiskach produkcyjnych (pojedynowy węzeł w środowisku deweloperskim zazwyczaj używa 1).

Instalacja Apache Kafka

Oficjalny przewodnik szybkiego startu Kafki używa wersji binarnej (tarballa) lub oficjalnego obrazu Docker. Oba rozwiązania są odpowiednie do lokalnego dewelopmentu.

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 w Kafce 4.0 usunięto obsługę Java 8.

Jeśli instalujesz Kafkę specjalnie, aby się jej nauczyć, dąż do obsługiwanego JDK, takiego jak Java 17 lub 21. Strona obsługi Java Kafki wymienia Java 17, 21 i 25 jako w pełni obsługiwane, podczas gdy Java 11 jest obsługiwana tylko dla podzbioru modułów (klienci i strumienie).

Instalacja z oficjalnej wersji binarnej

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

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

Uwagi dla zaawansowanych czytelników:

• “2.13” w nazwie pliku odzwierciedla linię budowania Scala. Dla binarnych plików Kafki 4.x, Scala 2.13 jest główną linią dystrybucji, a w Kafce 4.0 usunięto obsługę Scala 2.12.
• Jeśli zależy Ci na integralności łańcucha dostaw, strona pobierania wyraźnie dokumentuje, że możesz weryfikować pobrane pliki za pomocą opublikowanych przez Apache procedur i kluczy KEYS.

Instalacja z Docker

Kafka udostępnia również oficjalne obrazy Docker na Docker Hub. Przewodnik szybkiego startu pokazuje, że możesz pobrać i uruchomić Kafkę 4.2.0 w następujący 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” (opartych na obrazie natywnym GraalVM). Dokumentacja Kafki i propozycja poprawy Kafki (KIP) dla tej linii obrazów opisują ją jako eksperymentalną i przeznaczoną do lokalnego dewelopmentu i testów, nie do środowisk produkcyjnych.

Uwaga dotycząca platformy dla użytkowników Windows

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

Uruchomienie Kafki lokalnie z KRaft

Jeśli pytasz “Czy potrzebuję ZooKeepera do uruchomienia Apache Kafka”, nowoczesna odpowiedź brzmi nie. Kafka 4.0 jest pierwszym głównym wydaniem zaprojektowanym tak, aby działać całkowicie bez ZooKeepera, uruchamiając się domyślnie w trybie KRaft, co zmniejsza nakłady operacyjne dla użytku lokalnego i produkcyjnego.

Uruchomienie lokalnego brokera pojedynczego węzła z rozpakowanego tarballa

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

1. Wygenerowanie UUID klastra
2. Sformatowanie katalogów dzienników
3. Uruchomienie serwera

# Wygeneruj UUID klastra
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"

# Sformatuj katalogi dzienników (tryb standalone lokalny)
bin/kafka-storage.sh format --standalone -t "$KAFKA_CLUSTER_ID" -c config/server.properties

# Uruchom brokera Kafki
bin/kafka-server-start.sh config/server.properties

Dlaczego krok “formatowania” ma znaczenie w KRaft: Dokumentacja operacji KRaft Kafki wyjaśnia, że kafka-storage.sh random-uuid generuje ID klastra i że każdy serwer musi być sformatowany za pomocą kafka-storage.sh format. Jednym z podanych powodów jest to, że automatyczne formatowanie może ukrywać błędy, szczególnie wokół dziennika metadanych, więc preferowane jest jawnego formatowanie.

Co uruchamiasz w tym przewodniku szybkiego startu

Dla lokalnego dewelopmentu Kafka może działać w uproszczonej konfiguracji “połączonej” (kontrolery i brokerzy razem). Dokumentacja KRaft Kafki wskazuje, że połączone serwery są prostsze do dewelopmentu, ale nie są zalecane w środowiskach krytycznych (gdzie chcesz mieć kontrolery izolowane i skalowane niezależnie).

W “prawdziwych” klastrach kontrolery KRaft i brokerzy to oddzielne role (process.roles), a kontrolery są zazwyczaj wdrażane jako kworum 3 lub 5 węzłów (dostępność zależy od większości będącej w stanie aktywnym).

Podstawy CLI Kafki i główne parametry wiersza poleceń

Kafka jest dostarczana z dużą ilością narzędzi CLI w katalogu bin/. Oficjalna dokumentacja operacyjna podkreśla dwie użyteczne właściwości:

• Najczęstsze narzędzia znajdują się w katalogu bin/ dystrybucji.
• Każde narzędzie wyświetla pełne użycie wiersza poleceń, gdy jest uruchamiane bez argumentów.

Ważne również dla Kafki 4.x: polecenia AdminClient nie akceptują już --zookeeper. Dokumentacja kompatybilności Kafki wskazuje, że począwszy od Kafki 4.0, musisz użyć --bootstrap-server do interakcji z klastrem.

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

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

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

KRaft wprowadza punkty końcowe brokera i kontrolera dla niektórych narzędzi. Na przykład kafka-features.sh i część narzędzi do metadanych mogą używać punktów końcowych kontrolera, podczas gdy wiele operacji administracyjnych używa punktów końcowych 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 i listowanie tematów (przewodnik szybkiego startu pokazuje --create, --describe, --topic).
• Określanie skali i trwałości poprzez partycje i współ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ń dla pojedynczych tematów w momencie tworzenia za pomocą --config key=value (dokumentacja konfiguracji tematów pokazuje konkretne przykłady).

Dobre polecenie “produkcyjne” tworzenia wygląda następująco (ten dokładnie kształt jest używany w oficjalnej dokumentacji operacyjnej):

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

Produkowanie i konsumowanie za pomocą klientów konsolowych

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.
• 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 instrukcje uruchamiania, warto teraz zaktualizować te notatki, 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 codzienne pytanie. Przewodnik operacyjny demonstruje:

• Listowanie grup: --list
• Opisanie grupy z przesunięciami i opóźnieniem: --describe --group ...
• Opisanie członków i przypisania: --members i --verbose
• Usuwanie grup: --delete
• Bezpieczne resetowanie przesunięć: --reset-offsets

Przykład:

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

Jedna pułapka konfiguracji dla lokalnego Docker i zdalnych klientów

Jeśli uruchamiasz Kafkę w kontenerach lub za balanserami obciążenia, ostatecznie napotkasz potrzebę prawidłowego ustawienia nasłuchujących punktów końcowych. Dokumentacja konfiguracji brokera Kafki wyjaśnia advertised.listeners jako adresy, które brokerzy reklamują klientom i innym brokerom, szczególnie gdy adres wiązania nie jest adresem, którego powinni używać klienci.

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

Poniższe przykłady są celowo oparte na CLI, abyś mógł zweryfikować lokalną konfigurację Kafki zanim napiszesz jakikolwiek kod aplikacji.

Przykład: uruchomienie tematu i strumieniowanie wiadomości end-to-end

To jest kanoniczny przepływ “stwórz, wyprodukuj, zkonsumuj” z przewodnika szybkiego startu Kafki 4.2.

Otwórz terminal A i stwórz temat:

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

Teraz opisz go (opcjonalnie, ale przydatne, gdy uczysz się o partycjach i współczynniku 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 uruchomionego:

To jest moje pierwsze zdarzenie
To jest moje drugie zdarzenie

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ć wydrukowane te same linie.

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

Przykład: uruchomienie prostego rurociągu Kafka Connect od pliku do tematu i z powrotem do pliku

Kafka Connect odpowiada na powtarzające się pytanie “Jak przemieszczać 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 za pomocą łączników (connectors).

Przewodnik szybkiego startu Kafki 4.2 zawiera minimalną, lokalną demo Connect używającą łączników źródła i zlewu (source i sink).

Z katalogu Kafki najpierw ustaw ścieżkę wtyczki pracownika, aby zawierała dostarczony jar łącznika pliku:

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

Stwórz mały plik wejściowy:

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

Uruchom pracownika Connect w trybie standalone z konfiguracją łącznika źródłowego i końcowego:

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

Co się powinno stać (i dlaczego to jest przydatne):

• Łącznik źródłowy czyta linie z test.txt i produkuje je do tematu connect-test.
• Łącznik końcowy czyta z connect-test i zapisuje do test.sink.txt.

Zweryfikuj plik końcowy:

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 również, gdzie znajduje się konfiguracja Connect (konfiguracja pracownika plus konfiguracje łączników) i pokazuje minimalną pętlę “pobierz, przechowaj, wyeksportuj”.

Rozwiązywanie problemów i kolejne kroki

Większość problemów z “nieuruchamianiem się przewodnika szybkiego startu Kafki” sprowadza się do małego zestawu przyczyn źródłowych.

Broker nie może się uruchomić

Zacznij od oficjalnych wymagań:

• Przewodnik szybkiego startu Kafki 4.2 wyraźnie wymaga Java 17+. Jeśli masz starszy JDK, napraw to jako pierwsze.
• 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 czystego startu, przewodnik szybkiego startu Kafki pokazuje, jak usunąć lokalne katalogi danych używane w demo:

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

Polecenia CLI nie działają, mimo że broker działa

W Kafce 4.x upewnij się, ż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 związane z siecią Docker

Jeśli Kafka jest w Dockerze, a narzędzie klienta jest poza Dockerem (lub na innym komputerze), możesz potrzebować prawidłowej reklamy nasłuchujących punktów końcowych. 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 wiązania (listeners).

Gdzie podać się 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 służy Kafka (strumieniowanie zdarzeń end-to-end)
• jak zainstalować Kafkę lokalnie (tarball lub Docker)
• dlaczego ZooKeeper zniknął i dlaczego KRaft jest domyślnym w 4.x
• które narzędzia CLI mają znaczenie na co dzień (tematy, producent, konsument, grupy)

Stąd najbardziej wartościowymi kolejnymi krokami są zazwyczaj:

• Przeczytaj “Wstęp” do Kafki dla głębszych modeli mentalnych tematów, partycji i replikacji.
• Odkryj Szybki start Kafka Streams, jeśli chcesz pierwszą aplikację do przetwarzania (Szybki start Streams demonstruje uruchamianie demo WordCount i inspekcję wyników za pomocą konsolowego konsumenta).