Kafka hibaelhárítás és üzemeltetés

Ezt az útmutatót előkészített backend/KafkaTester-környezethez használd. Olvasd el a beállításokat és előfeltételeket, mielőtt hitelesítő adatokat vagy topológiát módosítasz. A diagnózis során őrizd meg a topicadatokat, a partíció-hozzárendeléseket és a consumer offseteket.

1. Natív ABI-eltérés

Az ERR_DLOPEN_FAILED vagy a NODE_MODULE_VERSION ... üzenet általában azt jelenti, hogy egy natív modult más Node-főverzióra építettek. A backend Node 22 vagy újabb verziót igényel. Ugyanazzal a kiválasztott verzióval telepítsd és futtasd.

A backend mappájából telepítsd újra a megbízható lockfile-lal, vagy építsd újra a natív függőségeket:

pnpm install --trust-lockfile
pnpm kafka:rebuild-native

Az install script újraépíti a Kafka natív függőségeit, és megkísérli a better-sqlite3 újraépítését. Ne másold át egy másik Node-verzió node_modules mappáját.

2. Corepack-aláírási hiba

A Cannot find matching keyid hibánál vizsgáld meg a telepített Corepack/pnpm beállítást. A tároló a pnpm 10.27.0 verziót rögzíti. Ha a telepített Corepack támogatja ezt az utat:

corepack enable
corepack prepare pnpm@10.27.0 --activate
pnpm -v

Ezután ismételd meg a függőségek install lépését. A külön telepített, rögzített verziójú pnpm másik támogatott csomagkezelő-út. Ne másold át más fejlesztő abszolút binárisának útvonalát.

3. A service elindul, de nem dolgoz fel eseményt

Ellenőrizd a kiválasztott környezetet, az alkalmazási és admin szerepeket, a KafkaTopics topicneveket, a consumer groupot és a partíció-hozzárendelési naplókat. Minden hirdetett broker-endpointot el kell érni, nem csak a bootstrap portot. Az egyesített runtime a gyökér beállításokat olvassa. Az önálló workerek saját belépési pont konfigurációt használnak.

4. Az outbox nem publikál

Ellenőrizd az OutboxEvent.status értékét, a dispatcher naplóit és a producer hibáit. Felosztott gyakorlatnál győződj meg róla, hogy a pnpm kafka:kt:outbox:watch fut.

A PREQUEUED állapot explicit kiadást igényel. A PENDING állapot dispatchert igényel. A DISPATCHING állapotban a publikálás visszaigazolására vagy helyreállításra lehet várni. A stale recovery a broker állapotát ellenőrzi, mielőtt visszasorolna vagy megjelölne. Ne feltételezd, hogy az időtúllépés azt jelenti, hogy az eseményt soha nem publikálták.

Az állapotokat és a helyreállítási határokat lásd: outbox-viselkedés.

5. Érvénytelen státuszátmenetek

Hibák jelentésekor őrizd meg a pontos hibaüzenetet:

Érvénytelen outbox státuszváltás: SUCCESS -> PUBLISHED
Érvénytelen outbox státuszváltás: PUSHED_FAILURE -> PUBLISHED
Érvénytelen outbox státuszváltás: SUCCESS -> PUSHED_FAILURE

Ellenőrizd, hogy nem fedi-e át véletlenül az all-in-one és a felosztott runtime egymást. Futtass egy szándékolt topológiát. A jelenlegi publisher atomikus DISPATCHING lefoglalást és feltételes lezárást használ. A consumerek kihagyják a végállapotú munkát. Ezt az útvonalat vizsgáld, ne kényszerítsd vissza a végállapotú sorokat.

6. A consumer-elosztás eltér a várttól

Ugyanazon group tagjai osztoznak a partíciókon. A különböző groupok függetlenül olvasnak. Mielőtt hibásnak tekintenéd a tétlen tagot, ellenőrizd a groupneveket és a partíciószámot.

7. Üzemeltetési ellenőrzések

Tarts fenn explicit topicbeállítási szabályzatot a replikációra, a megtartásra és a hozzáférés-vezérlésre. Figyeld a consumer lagot, a dead-letter forgalmat, az outbox-torlódást és a rebalance-naplókat. Tartsd konzisztensen a Node-főverziót a natív moduloknál.

Egy sikeres kapcsolat nem bizonyítja a sorrendet, a feldolgozást vagy a provider-visszaigazolást. Ellenőrizd az érintett üzleti eredményt. A törlés és újralétrehozás, valamint az eraser-parancsok destruktív karbantartások, nem rutinszerű kapcsolati diagnózisok.