Einleitung

Nach einem Update von Zammad kann es vorkommen, dass beim Aufruf der Weboberfläche nur noch ein 502 Bad Gateway erscheint.

Die Ursache liegt häufig nicht im Webserver oder Reverse Proxy, sondern in der Datenbankversion.
Aktuelle Zammad-Versionen benötigen PostgreSQL 13 oder neuer. Wenn noch PostgreSQL 11 verwendet wird, startet der Zammad-Webserver nicht mehr, so wie in meinem Fall.

In diesem Beitrag zeigen wir Schritt für Schritt, wie:

• der Fehler identifiziert wird
• PostgreSQL korrekt auf Version 15 aktualisiert wird
• die Zammad-Datenbank migriert wird
• Zammad wieder vollständig funktionsfähig startet

Die Anleitung basiert auf einer Installation unter Debian 12 (Bookworm).

Typischer Fehler

In den Systemlogs erscheint häufig folgende Meldung:

Error: incompatible database backend version (PostgreSQL 13+ required; 11.22 found)

Das bedeutet:

• Zammad erwartet PostgreSQL ≥ 13
• installiert ist PostgreSQL 11

Dadurch beendet sich der Webserver sofort und der Reverse Proxy liefert 502 Bad Gateway.

Die Fehlermeldung lässt sich mit dem folgenden Befehl einsehen:

grep -n "PostgreSQL 13+ required" /var/log/syslog | tail -n 10 || true

Schritt 1 – PostgreSQL Version prüfen

Zuerst prüfen, welche PostgreSQL-Version aktuell aktiv ist.

pg_lsclusters

oder

su - postgres -c "psql -c 'show server_version;'"

Beispiel:

Ver Cluster Port Status Owner
11 main 5432 online postgres

In diesem Fall läuft noch PostgreSQL 11.

Schritt 2 – Zammad Dienste stoppen

Vor Änderungen an der Datenbank sollten die Zammad-Prozesse gestoppt werden.

systemctl stop zammad-web-1
systemctl stop zammad-worker-1
systemctl stop zammad-websocket-1

Schritt 3 – Datenbank Backup erstellen

Vor dem Upgrade sollte immer ein vollständiges Backup erstellt werden.

su - postgres -c "pg_dumpall > /home/<username>/postgres_backup.sql"

Backup überprüfen:

ls -lh /home/<username>/postgres_backup.sql

Schritt 4 – PostgreSQL 15 installieren

Unter Debian 12 ist PostgreSQL 15 normalerweise bereits verfügbar.

apt install postgresql-15

Falls über die vorherigen Befehle schon sichtbar ist, dass Version 15 bereits installiert ist (wie in meinem Fall), muss die Installation nicht mehr gemacht werden.

Schritt 5 – PostgreSQL Cluster prüfen

Debian nutzt ein Cluster-System für PostgreSQL.

pg_lsclusters

Beispiel:

Ver Cluster Port Status Owner
11 main 5432 online postgres
15 main 5434 online postgres

Wenn der neue Cluster leer ist, kann er gelöscht werden. Dies muss sicher sein, da ihr euch ansonsten Daten löscht! Wie immer gilt: Kein Backup – Kein Mitleid!

Schritt 6 – Leeren Zielcluster entfernen

pg_ctlcluster 15 main stop
pg_dropcluster 15 main

Schritt 7 – PostgreSQL Upgrade durchführen

Das Upgrade erfolgt mit dem Debian-Tool pg_upgradecluster.

pg_ctlcluster 11 main stop
pg_upgradecluster 11 main

Nach erfolgreichem Upgrade erscheint:

Success. Please check that the upgraded cluster works.

Schritt 8 – PostgreSQL 15 starten

pg_ctlcluster 15 main start

Version prüfen:

su - postgres -c "psql -c 'show server_version;'"

Beispiel:

15.x

Schritt 9 – Alten PostgreSQL Cluster entfernen

Wenn alles funktioniert, kann der alte Cluster gelöscht werden.

pg_dropcluster 11 main --stop

Kontrolle:

pg_lsclusters

Beispiel:

Ver Cluster Port Status Owner
15 main 5432 online postgres

Schritt 10 – Zammad Datenbank Migrationen durchführen

Nach einem größeren Upgrade müssen Datenbank-Migrationen ausgeführt werden.

Status prüfen:

zammad run rake db:migrate:status

Falls Migrationen fehlen:

zammad run rake db:migrate

Danach erneut prüfen.

Schritt 11 – Zammad Dienste starten

systemctl start zammad-web-1
systemctl start zammad-worker-1
systemctl start zammad-websocket-1

Schritt 12 – Funktion testen

Prüfen, ob der Zammad Webserver wieder erreichbar ist.

ss -ltnp | grep :3000

Test mit curl:

curl -I http://127.0.0.1:3000/

Wenn ein Reverse Proxy verwendet wird (z. B. Nginx):

systemctl restart nginx

Optional – Elasticsearch prüfen

Zammad nutzt Elasticsearch für die Suche.

Status prüfen:

systemctl status elasticsearch

API testen:

curl http://127.0.0.1:9200

Falls die Suche Probleme macht:

zammad run rake searchindex:rebuild

Fazit

Der Fehler 502 Bad Gateway bei Zammad nach einem Update wird meist durch eine veraltete PostgreSQL-Version verursacht, bei der keine Migration der Daten auf eine neuere Datenbank-Version durchgeführt wurde.

Die Lösung besteht aus drei Schritten:

1. PostgreSQL auf Version 15 upgraden
2. Datenbank-Migrationen ausführen
3. Zammad Dienste neu starten

Danach läuft Zammad wieder stabil.

Systemumgebung

Diese Anleitung wurde getestet mit:

• Debian GNU/Linux 12 (Bookworm)
• Zammad aktuelle Version
• PostgreSQL 15

Empfehlung

Vor größeren Updates immer:

• ein Datenbank-Backup erstellen
• optional einen VM Snapshot anlegen

So lassen sich Fehler schnell rückgängig machen.

Disclaimer

Dieser Artikel wurde mit Unterstützung von dieser KI gemacht, von der gerade alle reden und die den RAM so teuer macht…