Interne Dokumentation

INTERNAL — Architektur, Betrieb, Admin-API

Interne Dokumentation für Betreiber. Nicht an Kunden geben. Kundenseitige Dokumente: API.md und QUEUE.md. Betriebsabläufe (Deploy, Rollback, Notfall) stehen in ../RUNBOOK.md und werden hier nicht wiederholt, nur verlinkt.

Diese Datei ist die Quelle für public/admin-api-docs.html. Das HTML wird generiert, nie von Hand bearbeitet — siehe Dokumentation und Generator.

Inhalt

1. Architektur in einem Bild
2. Prozessmodell
3. Netz, Bind-Adressen, Shared Secret
4. Queue — Aufbau und Datenmodell
5. Memory-Guard
6. Browser-Liveness und Quarantäne
7. Proxy-Relay und SSRF-Schutz
8. Medienablage
9. Webhooks intern
10. Admin-API (JWT)
11. Interne Instanz-API (X-Internal-Auth)
12. Konfiguration und Umgebungsvariablen
13. Deploy und Rollback

· 13.1 Inbetriebnahme der Queue — gestufte Schrittfolge

1. Dokumentation und Generator
2. Bekannte Grenzen und offene Punkte
3. Abweichungen zwischen Kontrakt und Code

1. Architektur in einem Bild

                       Internet
                          │  TLS, nginx
                          ▼
        ┌──────────────────────────────────────────┐
        │  admin-server.js        :3001            │
        │  ─ Admin-Panel (JWT)                     │
        │  ─ Externe API (Bearer <apiKey>)         │
        │  ─ 6 Bestandsrouten  +  ~45 v2-Routen    │
        │  ─ reine Durchreichung, KEINE Umformung  │
        └───────┬───────────────┬──────────────────┘
                │  HTTP 127.0.0.1, X-Internal-Auth
      ┌─────────▼───┐     ┌─────▼───────┐    …
      │ instance-   │     │ instance-   │
      │ server.js   │     │ server.js   │      ein Kindprozess je Instanz
      │ :3013       │     │ :3014       │      Bind ausschliesslich 127.0.0.1
      │             │     │             │
      │ ┌─────────┐ │     │ ┌─────────┐ │
      │ │ lib/    │ │     │ │ lib/    │ │      Outbox-Queue je Prozess,
      │ │ queue   │ │     │ │ queue   │ │      genau EIN Schreiber je Instanz
      │ └────┬────┘ │     │ └────┬────┘ │
      │      │      │     │      │      │
      │ ┌────▼────┐ │     │ ┌────▼────┐ │
      │ │ wwebjs  │ │     │ │ wwebjs  │ │      whatsapp-web.js 1.34.7
      │ │ + Chrome│ │     │ │ + Chrome│ │      LocalAuth, sessions/<id>/
      │ └─────────┘ │     │ └─────────┘ │
      └──────┬──────┘     └──────┬──────┘
             │                   │
             └────────┬──────────┘
                      ▼
        PostgreSQL 17.7, DB chatbot_management, Schema wa_gateway

Redis läuft auf dem Host, wird von uns aber nicht benutzt. Begründung siehe §4.

2. Prozessmodell

• Eine Instanz = ein Node-Prozess = ein Chrome-Baum = eine WhatsApp-Nummer.
• Der Kindprozess erbt process.env vom Admin-Prozess. Alle QUEUE_*-Variablen und das

Shared Secret brauchen deshalb keinen eigenen Übergabeweg.

• Die Instanzkonfiguration (id, name, apiKey, port, proxy, webhook, queue) kommt als

INSTANCE_CONFIG-JSON in der Umgebung des Kindprozesses.

• Registry: data/instances.json. Die einzige Quelle der Wahrheit für Limits.

loadInstances() ergänzt fehlende queue-Blöcke beim Lesen aus DEFAULTS_EXISTING — die Migration der Registry ist damit ein reiner Lesevorgang, es gibt keine Migrationsdatei.

• Autostart nach einem Neustart des Gateways: gestaffelt, AUTOSTART_STAGGER_MS.

Wichtig: genau ein Schreiber je Instanz

Die Queue-Zähler werden nicht separat geführt, sondern per Indexabfrage aus genau den Zeilen abgeleitet, die den Versand protokollieren. Sie können deshalb nicht driften. Das funktioniert, weil es je Instanz genau einen schreibenden Prozess gibt. Diese Annahme darf nicht gebrochen werden — zwei Prozesse auf derselben instance_id würden sich gegenseitig über das Limit schieben, obwohl FOR UPDATE SKIP LOCKED Doppelversand verhindert.

3. Netz, Bind-Adressen, Shared Secret

INSTANCE_SHARED_SECRET ist Pflicht. Ohne den Schlüssel bricht deploy.sh ab. Die .env muss 0600 gehören — sie enthält Shared Secret, JWT_SECRET, Admin-Passwort und die DB-URL.

INSTANCE_AUTH_MODE=audit ist ein Notausgang, kein Betriebsmodus. In diesem Modus wird ein Aufruf ohne gültiges X-Internal-Auth durchgelassen und nur als WARN geloggt (unauthenticated internal request …). Gedacht ist er ausschliesslich für die Umstellungsphase, in der man sehen will, wer den Header noch nicht setzt. Default und Zielzustand ist enforce. Wer ihn dauerhaft auf audit stehen lässt, hat die Loopback-Grenze effektiv aufgehoben: jeder Prozess auf der Maschine — inklusive des fremden Chatbot-Dienstes unter derselben UID — darf dann senden. Nach dem Deploy prüfen: grep INSTANCE_AUTH_MODE .env muss leer sein oder enforce liefern.

Ein Trailing Slash wird vor der Prüfung normalisiert, damit /health/ nicht fälschlich 401 liefert.

Externe Autorisierung

4. Queue — Aufbau und Datenmodell

Warum PostgreSQL und nicht Redis

Der Host-Redis läuft mit appendonly no und save 3600 1 300 100 60 10000. Bei einem Host-Crash sind damit bis zu 60 Sekunden Schreibvorgänge verloren. Zusammen mit maxmemory 0 und noeviction nimmt eine volllaufende Queue ausserdem den 7,7-GB-Host mit — inklusive aller Kundeninstanzen. Beides disqualifiziert Redis als Quelle der Wahrheit, nicht als Meinung, sondern per Konfiguration. Der einzige echte Redis-Vorteil (atomares INCR über Prozessgrenzen) wird nicht gebraucht, weil es je Instanz genau einen Schreiber gibt.

Ablage

Schema wa_gateway in der bestehenden DB chatbot_management. Die Rolle chatbot darf kein neues DB anlegen (rolcreatedb=f), aber ein neues Schema. Alle Statements sind explizit schema-qualifiziert, kein Verlass auf search_path.

Migration:

npm run queue:migrate      # legt Schema/Tabellen/Indizes idempotent an
npm run queue:verify       # prueft Existenz, exit 0/1
npm run queue:test         # Selbsttests ohne DB
npm run queue:test:pg      # Selbsttests gegen die echte DB

DDL liegt in lib/queue/schema.sql, der Runner in lib/queue/migrate.js.

Module

Zwei Schichten, nicht eine

scheduled_at ist eine Planung, keine Durchsetzung. Der Planner verteilt, das Gate setzt durch. Ohne die zweite Schicht wird jeder Stillstand (Disconnect, geordneter Restart, Limitänderung, Uhrumstellung, Wiederanlauf) zu einem Burst, weil schlagartig viele Slots gleichzeitig fällig sind — exakt das Muster, auf das WhatsApps Spam-Erkennung reagiert. Verletzt ein Job das Gate, geht er mit neuem scheduled_at zurück in die Warteschlange und wird nicht gesendet.

Queue.limitsEnforced() sagt, ob gerade durchgesetzt wird: true in pg und in memory-degraded, false nur in disabled. Der Wert steht in stats() und summary().

Zustände und die eine Regel

queued → scheduled → sending → {sent | failed | unknown}, dazu cancelled und expired.

scheduled verlässt den Prozess nicht. Die Unterscheidung queued (kein Slot vergeben) / scheduled (Slot steht) ist eine interne Planungsstufe, keine fachliche Aussage — in beiden Fällen ist die Nachricht angenommen und noch nicht raus. v2SubmitResponse() (instance-server.js:3245) bildet deshalb scheduled → queued ab, bevor geantwortet wird; die Rohstufe bleibt daneben als queueState sichtbar. Terminale Zustände werden nicht eingeebnet, sonst meldete ein Idempotenz-Replay einer längst zugestellten Nachricht queued. /api/send-bulk antwortet aus demselben Grund je Eintrag mit status:'queued'. Ebenso gibt es kein message.scheduled-Ereignis: die Annahme feuert immer message.queued (lib/queue/accept.js:138).

INVARIANTE D: Sobald der wwebjs-Aufruf angestossen wurde, gibt es keinen Uebergang
mehr in einen sendefaehigen Zustand. Weder durch Code, noch durch Recovery,
noch durch einen Operator.

Der Zustandswechsel nach sending wird vor dem wwebjs-Aufruf committed. Findet ein Neustart sending-Zeilen vor, werden sie zu unknown mit process_crash_while_sending — nie zu einem Retry. Genau diese Regel hält den historischen Duplikat-Vorfall geschlossen.

Es gibt keinen automatischen Retry. Die einzige Rückkehr aus sending ist der Fall "beweisbar noch nicht gesendet" (WhatsApp getrennt, Seite während der Nummernvalidierung gestorben) mit Backoff 5 s → 60 s, maximal 10 Mal, danach failed / REQUEUE_EXHAUSTED.

Modi

Laufzeit-Umschaltung. Queue._onStoreFailure() prüft über Queue.isConnectivityError(), ob ein Speicherfehler „die Datenbank ist gerade nicht da" bedeutet (PG-SQLSTATE 08*, 57P0*, 53300/53400 und die üblichen Socket-Codes). Nur dann wird umgeschaltet — ein Constraint-Verstoss oder ein SQL-Tippfehler ist ein Programmfehler und darf die Instanz nicht still in den Fallback rutschen lassen. Alle übrigen Speicherfehler kommen als QueueError('QUEUE_STORE_UNAVAILABLE', 503) heraus statt als nackter pg-Fehler mit 500.

Rückweg: Reconnect-Probe alle QUEUE_DEGRADED_PROBE_MS (30 s). Bei Erfolg wird der In-Memory-Rückstand zuerst leergefahren (_adoptFromMemory), dann übernimmt der Dispatcher. Das im Moment des Umschaltens laufende Item bleibt beim Fallback — eine Übernahme wäre ein Duplikat.

Angenommene Items im Degraded-Modus werden zusätzlich forensisch nach data/queue/<instanceId>.degraded.jsonl geschrieben. Kein automatisches Replay — das würde exakt den Duplikat-Vorfall reproduzieren.

Im Degraded-Modus fallen die message.*-Webhooks aus. lib/queue/memory-fallback.js hat keinen einzigen emit-Aufruf; message.queued/sent/failed/unknown kommen ausschliesslich aus accept.js und dispatcher.js, also nur aus dem PG-Pfad. Gesendet wird weiter, benachrichtigt nicht. Die Lücke ist von aussen exakt eingerahmt: queue.degraded markiert ihren Anfang, queue.recovered ihr Ende. Wer Geschäftslogik an message.sent hängt, muss diese Spanne nachziehen (GET /api/v2/queue/items, sobald mode wieder pg ist). Das gehört in die Ankündigung an jeden Kunden, der Queue-Events abonniert — bisher tut das niemand, weil keines dieser Ereignisse in WEBHOOK_DEFAULT_EVENTS steht.

QUEUE_PAUSED gilt bewusst nur für /api/v2/*. Die sechs Bestandsrouten kennen dieses Fehlerbild heute nicht; sie werden während eines geordneten Restarts angenommen und warten im normalen Ablauf. Der LEGACY_SYNC_TIMEOUT_MS-Timeout (Default 20 s, gedeckelt auf 25 s) ist dort die vorhandene Absicherung.

5. Memory-Guard

Ein Chrome-Baum je Instanz auf einem 7,7-GB-Host. Der Guard misst den Prozessbaum, nicht nur den Node-Heap.

Werte stehen live in /health.memory (heapUsedMB, rssMB, browserTreeMB, totalMB, softLimitMB, hardLimitMB, hostAvailMB).

Der geordnete Restart (orderedRestart()) setzt sendPaused = true, pausiert den Dispatcher, wartet bis zu 35 s auf das laufende Item (drainInFlight), speichert den Message-Store und startet erst dann neu. Ein sauberer Restart hinterlässt deshalb keine sending-Zeile und erzeugt kein unknown.

Herleitung der Schwellen und die ehrliche Grenze ("Ausreisser-Detektor, kein Kapazitätsplan"): RUNBOOK.md §8.

6. Browser-Liveness und Quarantäne

Der klassische Zombie: Node lebt, WhatsApp Web meldet weiterhin connected und empfängt Nachrichten, aber client.info ist weg und senden ist unmöglich. Das erholt sich nie von selbst.

• GET /health liefert 503, sobald der Browser als tot gilt — das ist die einzige

Verhaltensänderung gegenüber früher. /api/status bleibt bewusst unverändert und leitet status/connected weiterhin nur aus clientStatus ab, weil externe Kundenintegrationen darauf matchen. Die Browser-Wahrheit steht rein additiv in data.browser.

• GET /health/deep erzwingt eine sofortige Probe (statusneutral, ändert browserState nicht).
• Zusätzlich: clientStatus === 'authenticated' länger als AUTH_STUCK_MS gilt als hängend.

Quarantäne (admin-server.js): häufen sich Restarts im Fenster RESTART_WINDOW_MS, wird die Instanz auf status = 'quarantined' gesetzt, quarantinedAt/quarantineReason gefüllt und ein Alarm an ALERT_WEBHOOK_URL geschickt. Eine quarantänierte Instanz wird nicht automatisch wieder gestartet — nur über POST /api/instances/:id/start. Vorgehen: RUNBOOK.md §4.

7. Proxy-Relay und SSRF-Schutz

Ist für eine Instanz ein SOCKS5-Upstream konfiguriert, öffnet der Prozess ein lokales Relay auf 127.0.0.1:<relayPort> und schickt allen Node-Egress (Medien-Download, Webhooks an externe Ziele) als socks5h:// dorthin — Remote-DNS, eine Credential-Quelle, ein Pfad. Chrome bekommt zusätzlich --host-resolver-rules=MAP * ~NOTFOUND , EXCLUDE 127.0.0.1.

Webhooks an Loopback-Ziele (z. B. der Chatbot auf 127.0.0.1:3000) gehen bewusst nicht über den Proxy. Ist das Relay nicht bereit, wird der Webhook verworfen und laut geloggt statt ungeproxyt rauszugehen (fail-closed).

SSRF-Prüfung für mediaUrl (isPublicHttpUrl + resolveMediaUrl):

1. Schema http/https, keine privaten/Loopback-/Link-Local-Ziele, DNS-Auflösung wird geprüft.
2. Redirects werden selbst verfolgt (redirect: 'manual'), jede Location erneut geprüft,

maximal 3 Hops.

1. Vorprüfung per HEAD, nicht per Range-GET — ein Vorab-GET entwertet signierte Einmal-URLs.

Antwortet der Server nicht sinnvoll auf HEAD, wird die bereits validierte Original-URL unverändert benutzt; der finale Abruf läuft mit redirect:'manual' und kann nicht umgelenkt werden.

1. Grössenabbruch bei MEDIA_MAX_BYTES (16 MiB) durch node-fetch.
2. Die Prüfung läuft beim Dispatch ein zweites Mal. Zwischen Annahme und Versand können

Stunden liegen und DNS kann sich ändern.

8. Medienablage

Bytes gehören nicht in wa_outbox.payload. In der Zeile steht nur eine media_ref: {type:'url'|'file'|'store', …}.

9. Webhooks intern

• Opt-in je Instanz. Es gibt keinen globalen WEBHOOK_URL-Fallback mehr — der hätte alle

Bestandsinstanzen auf einen Schlag scharfgeschaltet.

• Default-Events ohne eigene Auswahl: message, ready, disconnected, instance_restarting, test.

Bewusst ohne message_ack/message_sent/message_reaction (bis zu 4 Events je Nachricht).

• * abonniert alles.
• Umschlag v2: {v, eventId, event, instanceId, timestamp, data}. event/instanceId/

timestamp/data behalten Name, Typ und Reihenfolge — der Chatbot bricht nicht.

• Signatur: der Body wird einmal serialisiert; genau diese Bytes werden signiert und

gesendet. Zwei Formen parallel: X-Webhook-Signature: sha256=<hex> (Legacy, das ist was der Chatbot erwartet) und X-Webhook-Signature-V2: t=<ts>,v1=<hex> über "<ts>.<body>".

• Hochfrequente Events: 1 Versuch statt 3 (message_ack, message_sent,

message_reaction, unread_count, media_uploaded, message_ciphertext, message_ciphertext_failed, change_battery). Ohne das flutet ein toter Empfänger das Log — das war der 414-MB-Vorfall.

• remote_session_saved wird nicht abonniert: es feuert nur unter RemoteAuth, wir nutzen

LocalAuth.

• Das Event code transportiert den Pairing-Code. Er darf in keiner Logzeile stehen.
• Jeder der 19 zusätzlichen Listener läuft in try/catch und mit .catch(). Eine geworfene

Exception in einem Listener würde sonst zur unhandledRejection und träfe verifyBrowserOrRestart — ein Mapper-Bug würde die ganze Instanz neu starten.

10. Admin-API (JWT)

Basis: https://wa.outrnk.io. Alle Routen ausser /api/auth/login und /health brauchen Authorization: Bearer <JWT>.

Anmelden

TOKEN=$(curl -s -X POST "$WA_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"'"$ADMIN_USERNAME"'","password":"'"$ADMIN_PASSWORD"'"}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["token"])')

Token läuft nach 24 h ab.

Instanzverwaltung

curl -s -X POST "$WA_URL/api/instances" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"kunde-xy","queue":{"enabled":true,"maxPerHour":40,"maxPer24h":500}}'

Webhooks

Reihenfolge: erst persistieren, dann live pushen. Vorher überlebte die Konfiguration keinen Instanz-Neustart (sie lag nur im Heap).

Limits und Queue

curl -s -X PUT "$WA_URL/api/instances/$ID/limits" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"maxPerHour":40,"maxPer24h":500,"minDelayMs":4000,"maxDelayMs":12000,
       "quietHours":{"start":"22:00","end":"07:00","tz":"Europe/Berlin"}}'

Antwort: {id, queue, persisted:true, livePushed:boolean, liveError:string|null}. Ist die Instanz nicht erreichbar, ist persisted trotzdem true — beim nächsten Start greift die Konfiguration.

Ist die Instanz gestoppt, antworten die Queue-Routen mit 503 INSTANCE_UNREACHABLE; im data-Block steht der persistierte Stand als Kontext. Das ist im Panel ein normaler Betriebszustand, keine Ausnahme.

Nachrichten und Chats (Panel-Ansicht)

Gateway-Health

GET /health (öffentlich, keine Auth):

{ "success": true, "service": "WhatsApp Multi-Session API", "version": "1.0.0",
  "timestamp": "…",
  "instances": { "total":5, "online":4, "offline":0, "starting":1, "degraded":0, "quarantined":0 },
  "queue": { "degraded": 0 } }

total/online/offline heissen aus Kompatibilität weiter so. starting/degraded/quarantined sind neu, damit online + offline < total nicht länger stillschweigend Instanzen aus der Überwachung fallen lässt. Bewusst nur Zähler: die Route ist unauthentifiziert. Details (quarantinedAt, quarantineReason) stehen in der JWT-geschützten Instanzliste und gehen zusätzlich per ALERT_WEBHOOK_URL raus.

queue.degraded > 0 bedeutet: mindestens eine laufende Instanz meldet den Modus memory-degraded — PostgreSQL ist für sie gerade nicht erreichbar. Die Limits gelten dort weiter: lib/queue/memory-fallback.js ruft dasselbe evaluateGate() auf wie der PG-Pfad, und queue.degraded als Webhook trägt limitsEnforced: true. (Die frühere Fassung dieses Absatzes behauptete das Gegenteil; das war der Stand vor Entscheidung F4 und ist seither falsch — ein DB-Ausfall wäre sonst die einfachste Methode gewesen, die Drosselung abzuschalten.)

Der verbleibende Unterschied ist einer, und er ist real: der Zähler des Fallbacks ist prozesslokal. Er lebt im Heap des Instanzprozesses (_dispatchTimes), startet beim Umschalten bei null und verschwindet beim Neustart. Das 24-h-Fenster aus der Datenbank geht im Moment des Umschaltens verloren. Folgen, in dieser Reihenfolge:

• Die Drosselung wird im Ausfallfenster zu grosszügig, nie zu streng — schon versandte

Nachrichten der letzten Stunde zählen nicht mehr mit. In der Spitze kann eine Instanz direkt nach dem Umschalten maxPerHour ein zweites Mal ausschöpfen.

• Ein Prozessneustart im Degraded-Modus setzt den Zähler erneut auf null.
• remainingHour / remaining24h in den API-Antworten sind in diesem Modus null

(limitsBlockLive() zählt nur im Modus pg) — Kontingente sind also nicht ablesbar, obwohl sie durchgesetzt werden.

Zum Unterscheiden der Modi ohne Ratespiel: GET /api/v2/queue liefert mode, limitsEnforced und degradedSince. queue.degraded in /api/status ist dagegen ein grober Monitoring-Boolean (queueMode() !== 'pg') und ist deshalb auch im Default-Modus disabled true — nur der Zähler in /health filtert auf memory-degraded.

Externe v2-Durchreichung — Grundsätze

Der Admin-Server reicht alle /api/v2/** 1:1 durch und formt nichts um:

1. Statuscode und Body der Instanz gehen unverändert nach aussen (validateStatus: () => true).

Bei v2 ist der Statuscode Teil des Kontrakts: 202 (neu eingereiht) gegen 200 (Idempotenz-Replay). Die alten sechs Routen kollabieren jeden Fehler auf 500 — genau das darf hier nicht passieren.

1. Der Header X-Idempotency-Key reist mit. Wer ihn verliert, macht die zentrale Zusage der

Welle C wirkungslos.

1. maxRedirects: 0 — das Shared Secret darf den Loopback nie verlassen.
2. Binäre Routen (…/media) werden gestreamt, nicht gepuffert.
3. Log auf debug, nicht info — eine Zeile je Aufruf war der Hauptverursacher der 414-MB-Datei.
4. Transportfehler: 504 INSTANCE_TIMEOUT (Nachricht kann angenommen worden sein) gegen

502 INSTANCE_UNREACHABLE (Instanz hat den Request nie gesehen). Der Unterschied ist für den Aufrufer entscheidungsrelevant.

Timeouts: Senden 60 s, Interaktion/Lesen 30 s, Queue-Status 10 s, Upload 120 s.

11. Interne Instanz-API (X-Internal-Auth)

Nur über Loopback erreichbar. Alles ausser /health und /health/deep braucht den Header.

POST /api/limits akzeptiert {queue:{…}} oder den flachen Block, validiert über lib/queue/limits.js und ruft queueCore.applyConfig(). Schlägt der Live-Push fehl, antwortet die Route 500 QUEUE_APPLY_FAILED — die Persistenz liegt beim Admin-Server und ist davon unberührt.

12. Konfiguration und Umgebungsvariablen

Vollständige Liste mit Kommentaren: .env.example. Hier die Schlüssel, die man kennen muss.

Pflicht

Queue

pg-native ist verboten — es braucht libpq + node-gyp und würde npm ci brechen.

Medien

MEDIA_MAX_BYTES 16 MiB · MEDIA_BASE64_MAX_BYTES 7 MiB · MEDIA_UPLOAD_MAX_BYTES 64 MiB · MEDIA_RETENTION_HOURS 72 · MEDIA_STORE_MAX_BYTES 16 MiB · MEDIA_STORE_MAX_MB 2048 · MEDIA_LOW_DISK_MIN_MB 5120 · MEDIA_ALLOW_HTTP · MEDIA_URL_ALLOWLIST

v2-Grenzen

INTERACTION_RATE_POINTS 60 / INTERACTION_RATE_DURATION_S 60 · FETCH_MESSAGES_MAX 200 / FETCH_MESSAGES_DEADLINE_MS 30000 · V2_MAX_BULK_ITEMS 500

Betrieb

ALERT_WEBHOOK_URL · AUTOSTART_STAGGER_MS (15000) · INSTANCE_BIND_HOST (127.0.0.1) · ADMIN_BIND_HOST · INSTANCE_AUTH_MODE (enforce, siehe §3) · INSTANCE_MEM_* · BROWSER_PROBE_* · BROWSER_GRACE_MS · READY_TIMEOUT_MS · RESTART_WINDOW_MS / RESTART_MAX_IN_WINDOW (Quarantäne-Schwelle) · RESTART_INIT_TIMEOUT_MS / RESTART_DESTROY_TIMEOUT_MS · ORDERED_RESTART_HARD_MS · OUTBOX_MEDIA_TTL_MS · PROXY_RELAY_PORT_OFFSET / PROXY_SELFTEST_* · WEBHOOK_DEFAULT_EVENTS · INSTANCES_DB_PATH · SESSIONS_PATH · LOG_LEVEL

Achtung PM2. Die vier INSTANCE_MEM_*-Schlüssel stehen im env-Block von ecosystem.config.js. PM2 setzt sie, bevor dotenv die .env liest, und dotenv überschreibt nichts bereits Gesetztes. Ein abweichender Wert in der .env wirkt deshalb nicht. Details: RUNBOOK.md §0.1.

Infrastruktur-Voraussetzung, die kein Code lösen kann

In ganz /etc/nginx gibt es kein client_max_body_size. Es gilt der Default 1m. Damit beantwortet nginx jeden Upload und jedes grössere Base64 selbst mit 413, bevor unser Code den Request sieht. Nötig im server-Block von wa.outrnk.io:

client_max_body_size 32m;
client_body_timeout  120s;

proxy_read_timeout 300s ist bereits gesetzt und reicht.

13. Deploy und Rollback

Nicht hier dokumentiert — RUNBOOK.md ist die Quelle. Insbesondere:

13.1 Inbetriebnahme der Queue — gestufte Schrittfolge

Der Ausgangszustand nach dem Deploy ist absichtlich ein Nullzustand:

• QUEUE_PG_URL ist nicht gesetzt. Der Queue-Kern wirft deswegen nicht — init() wirft

laut Kontrakt nie —, sondern geht in den Fallback (lib/queue/index.js: kein connectionString ⇒ _enterDegraded('QUEUE_PG_URL not configured')).

• Alle Instanzen stehen auf queue.enabled = false (QUEUE_DEFAULTS_EXISTING). Für sie

greift der Fallback gar nicht erst: init() bricht vorher mit Modus disabled ab. Ihr Verhalten ist bit-für-bit das von vorher.

Daraus folgt die Reihenfolge. Sie ist nicht beliebig: wird eine Instanz auf enabled = true gestellt, bevor QUEUE_PG_URL in ihrer Prozessumgebung steht, landet sie in memory-degraded statt in pg — sie sendet dann zwar weiter und drosselt korrekt, aber ohne Persistenz und mit 503 auf allen /api/v2/send-*. Das ist kein Ausfall, aber auch nicht das Ziel des Rollouts.

In jedem Schritt ist Rollback ohne Datenverlust möglich.

Schritt 1 — Code deployen, Queue bleibt überall aus.

Normaler Deploy nach RUNBOOK §1.1. QUEUE_PG_URL noch nicht setzen, queue.enabled bei keiner Instanz anfassen.

• Prüfpunkt: npm run queue:test ist grün (118/118, kein Datenbankzugriff nötig).

GET /api/instances/:id/limits zeigt für jede Instanz queue.enabled = false. Die sechs Bestandsrouten antworten unverändert.

• Abbruchkriterium: eine Instanz meldet nach dem Start einen anderen Modus als disabled,

oder eine Bestandsroute ändert Statuscode oder Antwortform ⇒ Deploy-Rollback nach RUNBOOK §1.3, bevor Schritt 2 beginnt.

Schritt 2 — Schema anlegen.

cd /home/ubuntu/apps/whatsapp-multi-api
# migrate.js lädt KEIN dotenv. Die Variablen müssen in der Shell stehen:
set -a; . ./.env; set +a
QUEUE_PG_URL='postgresql://…@127.0.0.1:5432/chatbot_management' npm run queue:migrate

Das Skript ist idempotent und mehrfach ausführbar. Es legt nur wa_gateway an, nimmt keinen Lock auf einer Chatbot-Tabelle, und der laufende Alt-Code sieht davon nichts.

• Prüfpunkt: npm run queue:verify beendet mit Exit 0 und meldet nichts Fehlendes

(3 Tabellen, 10 Indizes, Spalte wa_outbox.dispatch_attempted).

• Abbruchkriterium: Exit ≠ 0, permission denied for database (die Rolle darf kein Schema

anlegen) oder invalid QUEUE_SCHEMA ⇒ stopp. Rückfallpunkt: DROP SCHEMA wa_gateway CASCADE. Kein Schritt 3, solange --verify nicht sauber ist.

Schritt 3 — QUEUE_PG_URL setzen und in die Prozesse bringen.

Eintragen in die .env (nicht in ecosystem.config.js — dort ist es beim nächsten pm2 restart <NAME> weg, siehe RUNBOOK §0.1). Die Vorlage .env.example führt seit dem Review alle acht QUEUE_*-Schlüssel mit Default und Wirkung; von dort abschreiben statt raten. Alle acht sind optional — nur QUEUE_PG_URL entscheidet über pg vs. memory-degraded. Danach muss der Wert zweimal ankommen: dotenv läuft nur im admin-server.js; die Instanzen sind Kindprozesse und erben ihre Umgebung im Moment von spawn(). Ein laufender Kindprozess sieht eine neue .env-Zeile also nie.

pm2 restart ecosystem.config.js --only whatsapp-api --update-env
# danach die Instanzen einzeln durchstarten (RUNBOOK §2), nicht alle gleichzeitig

• Prüfpunkt: im Log jeder neu gestarteten Instanz steht nicht mehr

QUEUE_PG_URL not configured. GET /health liefert weiterhin queue.degraded = 0 (die Instanzen stehen ja noch auf disabled und zählen dort nicht mit).

• Abbruchkriterium: max_connections-Fehler oder 53300 in irgendeinem Instanzlog ⇒ Zeile

wieder aus der .env entfernen und neu starten. Verbindungsbudget nachrechnen: Instanzen × QUEUE_PG_POOL_MAX (Default 3) + 2 für den Admin.

Schritt 4 — Instanzen einzeln umstellen (Canary).

Pro Instanz, eine nach der anderen, kleinste zuerst:

curl -X PUT "$ADMIN/api/instances/$ID/limits" -H "Authorization: Bearer $JWT" \
  -H 'Content-Type: application/json' \
  -d '{"enabled":true,"maxPerHour":40,"maxPer24h":500,"minDelayMs":4000,"maxDelayMs":12000}'

Ein Neustart ist nicht nötig: applyConfig() startet den PG-Pfad zur Laufzeit (_startPg()), sofern Schritt 3 erledigt ist. Die Antwort ist 200 — bei 207 hat nur das Persistieren geklappt und der Live-Push nicht (warning, liveError lesen).

• Prüfpunkt: GET /api/instances/:id/queue (bzw. GET /api/v2/queue an der Instanz) meldet

mode: "pg" und limitsEnforced: true. Eine Testnachricht bekommt einen jobId mit Präfix wq_ und erreicht den Zustand sent. unknown24h bleibt 0.

• Abbruchkriterium: mode bleibt memory-degraded (⇒ Schritt 3 hat diese Instanz nicht

erreicht), oder unknown24h > 0, oder eine Bestandsroute antwortet 504 QUEUE_WAIT_TIMEOUT häufiger als erklärbar ⇒ sofort {"enabled":false} zurücksetzen. Die bereits geschriebenen Zeilen bleiben stehen und gehen bei erneutem Einschalten weiter; verloren geht nichts.

Schritt 5 — beobachten, dann verbreitern.

Erste Instanz 24 h beobachten, danach die nächste. Nach 7 Tagen ohne Befund den Rest.

• Prüfpunkt (täglich): GET /health → queue.degraded = 0; je Instanz unknown24h = 0 und

counts.queued + counts.scheduled läuft nicht monoton nach oben (das wäre ein Rückstau). npm run queue:verify weiterhin Exit 0.

• Abbruchkriterium: queue.degraded > 0 über mehr als zwei Probe-Intervalle

(QUEUE_DEGRADED_PROBE_MS, Default 30 s) hinweg, oder ein Rückstau, der QUEUE_MAX_PENDING (5000, ⇒ 422 QUEUE_FULL) ansteuert ⇒ betroffene Instanz auf enabled = false, Rollout anhalten, Ursache klären.

Vorbedingung für Schritt 4 ist zusätzlich die Prüfliste aus §15 B2: alle dort genannten Nachweise müssen im deployten Stand vorhanden sein. Insbesondere lib/queue/gate.js und lib/queue/job.js müssen existieren und npm run queue:test muss grün sein — ohne sie sind Medienversand, chatId-Ziele und die Limitdurchsetzung defekt.

Dokumentation und Generator

Es gibt genau drei gepflegte Quellen:

Die HTML-Seiten werden daraus generiert:

node scripts/build-docs.js          # schreibt public/api-docs.html + public/admin-api-docs.html
node scripts/build-docs.js --check  # exit 1, wenn das HTML nicht mehr zur Quelle passt

Beide HTML-Dateien tragen oben den Hinweis „generiert, nicht von Hand bearbeiten" und im <head> einen data-doc-hash mit dem SHA-256 der Quelle. --check vergleicht diesen Hash und eignet sich als Deploy-Vorprüfung.

Der Generator ist ~300 Zeilen ohne Abhängigkeiten (eigener Markdown-Renderer für die hier benutzte Teilmenge: Überschriften, Tabellen, Listen, Codeblöcke, Blockzitate, Inline-Code, Fett/Kursiv, Links). Kein Build-Schritt, kein npm-Paket, kein CI nötig.

Regel: Wer eine Route ändert, ändert docs/API.md und führt node scripts/build-docs.js aus. Wer das HTML von Hand anfasst, verliert seine Änderung beim nächsten Lauf.

15. Bekannte Grenzen und offene Punkte

A. Bewusst akzeptierte Lücken

B. Offener Defekt

Verifiziert gegen den Code in diesem Verzeichnis, Stand dieser Datei.

B2. Was in dieser Runde behoben wurde — zur Kontrolle

Der vorangegangene Review hatte sieben weitere Blocker gemeldet. Sie sind im aktuellen Stand nachweislich geschlossen; hier steht, woran man das erkennt, damit ein Rollback nicht unbemerkt dahinter zurückfällt.

C. Betriebliche Grenzen

• Der Memory-Guard ist ein Ausreisser-Detektor, kein Kapazitätsplan (RUNBOOK §8.3).
• Die Browser-Probe erkennt einen toten Browser, nicht einen langsamen.
• fetchMessages mit hohem limit bleibt der teuerste Aufruf im System (Cap 200, 30-s-Deadline).
• Es gibt keine Mandantentrennung innerhalb einer Instanz — eine Instanz = eine Nummer = ein Kunde.

16. Abweichungen zwischen Kontrakt und Code

Der Bauplan der Wellen C+D und der tatsächliche Code weichen an folgenden Stellen ab. Der Code gewinnt, die Dokumente oben beschreiben den Code.

Was der Chatbot heute wirklich benutzt

chatbot-src/services/whatsappIntegrationService.ts:221-238 ruft POST /api/instances/:id/send-message gegen http://localhost:3001. Diese Route existiert im admin-server.js nicht — der Pfad ist tot. Der Chatbot ruft über diesen Service also keine der sechs Bestandsrouten produktiv auf. Trotzdem bleiben alle sechs unverändert; die Annahme „der Chatbot hängt daran" darf nicht die einzige Begründung sein, aber die Kompatibilitätszusage gilt gegenüber jedem Kunden.

Relevant für B1: der Chatbot übergibt ausschliesslich chatId, nie phone. Sobald für seine Instanz queue.enabled = true gesetzt wird, träfe ihn B1 sofort und vollständig.