Zum Inhalt springen

Deployments ohne Ausfall für Node-Apps mit Docker Compose · Teil 2 von 11 der Serie

Teil 2: Health Checks und sauberes Beenden

Bring dem Gästebuch die zwei Dinge bei, die jedes Deployment von ihm verlangt: ehrlich zu sagen, ob es bereit für Besucher ist, und seine offenen Anfragen zu beenden, bevor es geht.

Quest-Ziele

  • Die zwei Fragen kennen, die ein Deployment einer App stellt
  • Einen Health Check einbauen, der die Datenbank einbezieht
  • Die App am Leben halten, wenn die Datenbank kurz verschwindet
  • Die Signale SIGTERM und SIGINT verstehen
  • Die App so beenden, dass keine offene Anfrage abgeschnitten wird

Eine Version einer App ohne Lücke gegen eine andere zu tauschen, ist Teamarbeit. Den Tausch erledigt der Server, aber er muss die App zwei Dinge fragen, und die App muss antworten können:

  • „Bist du bereit für Besucher?“ Das wird die neue Version gefragt, bevor jemand zu ihr geschickt wird. Die Antwort ist ein Health Check. Ohne ihn würden Besucher bei einer Version landen, die noch nicht fertig gestartet ist oder gar nicht funktionieren kann.

  • „Bitte bring zu Ende, was du gerade tust, und geh.“ Das wird der alten Version gesagt, sobald die neue übernommen hat. Ordentlich zu gehen, heißt Graceful Shutdown, sauberes Beenden. Ohne es würde die alte Version die Anfragen fallen lassen, die sie gerade beantwortet.

Für beides braucht es weder Docker noch einen Server. Beides sind ein paar Zeilen in der App, und du kannst sie auf deinem eigenen Rechner ausprobieren.

Ein Health Check

Ein Health Check ist eine Adresse, die ein Programm abfragen kann. Gib der App zuerst eine Möglichkeit herauszufinden, ob die Datenbank da ist. Füg das am Ende von src/db.js an:

src/db.js
/** The cheapest possible question: is the database there and answering? */
export async function ping() {
  await pool.query('select 1');
}

Importier die neue Funktion in src/app.js, indem du die zweite Zeile änderst:

src/app.js
import { addEntry, listEntries, ping } from './db.js';

Und füg die Adresse selbst am Ende derselben Datei an:

src/app.js
app.get('/health', async (c) => {
  try {
    await ping();
    return c.json({ status: 'ok', version });
  } catch {
    return c.json({ status: 'error', version }, 503);
  }
});

Warum fragt er die Datenbank? Weil „das Programm läuft“ und „die App funktioniert“ nicht dasselbe sind. Ein Gästebuch, das seine Einträge nicht erreicht, antwortet jedem Besucher mit einem Fehler. So eine Version darf die Besucher nicht bekommen, also fragt der Health Check nach dem einen, ohne das die App nicht auskommt.

Die Antwort kommt in zwei Formen. Menschen lesen den Text, ok oder error. Programme lesen den Statuscode, die Zahl, mit der jede Antwort im Web beginnt: 200 heißt, alles ist in Ordnung, und 503 heißt „gerade nicht verfügbar“. Starte die App mit npm run dev, falls sie nicht läuft, und frag sie:

~/projects/guestbook
$ curl --include http://localhost:3000/healthHTTP/1.1 200 OKContent-Type: application/jsonDate: Tue, 17 Nov 2026 09:08:01 GMTConnection: keep-aliveKeep-Alive: timeout=5Content-Length: 31{"status":"ok","version":"dev"}

In der ersten Zeile steht der Statuscode und in der letzten der Text, mit der Version, die du aus der Fußzeile der Seite kennst.

Wenn die Datenbank verschwindet

Jetzt finde heraus, was der Health Check sagt, wenn die Datenbank weg ist. Lass die App laufen. Frag in einem zweiten Terminal noch einmal den Health Check und stopp gleich danach die Datenbank, beides in einer Zeile:

~/projects/guestbook
$ curl http://localhost:3000/health && docker compose stop db{"status":"ok","version":"dev"}

Die Anfrage davor ist wichtig: Sie lässt eine Verbindung zur Datenbank im Pool warten, und der Pool schließt Verbindungen, die zehn Sekunden lang nichts zu tun hatten. Schau ins Terminal mit der App:

~/projects/guestbook
node:events:505    throw er; // Unhandled 'error' event    ^error: terminating connection due to administrator command    at parseErrorMessage (/home/robin/projects/guestbook/node_modules/pg-protocol/dist/parser.js:306:11)    at Parser.handlePacket (/home/robin/projects/guestbook/node_modules/pg-protocol/dist/parser.js:143:27)

Das ist kein ehrliches „nicht gesund“. Die ganze App ist abgestürzt, obwohl nur die Datenbank gestoppt wurde. Der Grund ist der Pool aus Teil 1. Er hält ein paar Verbindungen zur Datenbank offen, die auf die nächste Abfrage warten. Fährt die Datenbank herunter, bricht eine wartende Verbindung ab und meldet das als Fehler. Niemand hört auf diesen Fehler, und in Node.js beendet ein Fehler, auf den niemand hört, das Programm.

Dass eine Datenbank neu startet, ist nichts Ungewöhnliches, also muss die App das überleben. Hör auf den Fehler: Füg diese zwei Zeilen in src/db.js ein, direkt unter der Zeile, die den Pool anlegt:

src/db.js
// A connection that breaks while it waits in the pool must not take the whole app down.
pool.on('error', (error) => console.error(`Lost a database connection: ${error.message}`));

Der Pool wirft eine kaputte Verbindung von selbst weg und öffnet für die nächste Abfrage eine neue. Es fehlte nur jemand, der das zur Kenntnis nimmt. Jetzt noch einmal. Starte die Datenbank:

~/projects/guestbook
$ docker compose start db

Starte die App wieder mit npm run dev (drück vorher Strg+C, falls ihr Terminal noch belegt ist), führ die Zeile von vorhin noch einmal aus, die erst fragt und dann die Datenbank stoppt, und frag den Health Check erneut:

~/projects/guestbook
$ curl http://localhost:3000/health{"status":"error","version":"dev"}$ docker compose start db$ curl http://localhost:3000/health{"status":"ok","version":"dev"}

Diesmal ist die App oben geblieben. Ohne ihre Datenbank sagt sie error, mit dem Statuscode 503, und ein paar Sekunden nachdem die Datenbank zurück ist, sagt sie wieder ok, ohne dass jemand sie neu gestartet hat. Ihr Terminal zeigt, was passiert ist:

~/projects/guestbook
Guestbook listening on port 3000Lost a database connection: terminating connection due to administrator command

Sauberes Beenden

Bei der zweiten Frage geht es ums Gehen. Ein Programm wird mit einem Signal gebeten aufzuhören, einer kurzen Nachricht vom Betriebssystem. Zwei davon sind hier wichtig:

  • SIGTERM heißt „bitte beende dich“. Das schickt Docker einem Container, wenn es ihn stoppt.

  • SIGINT heißt „unterbrechen“. Das schickt dein Terminal, wenn du Strg+C drückst.

Ein Node.js-Programm, das diese Signale nicht behandelt, endet auf der Stelle. Ein Besucher, dessen Eintrag in diesem Moment gespeichert wird, bekommt keine Antwort, nur eine abgebrochene Verbindung. Bei einem Deployment wird die alte Version gestoppt, während Besucher auf der Seite sind, das würde also bei jedem Update passieren.

Ersetz src/server.js durch das hier:

src/server.js
import { serve } from '@hono/node-server';
import { app } from './app.js';
import { pool } from './db.js';

const port = Number(process.env.PORT ?? 3000);

const server = serve({ fetch: app.fetch, port }, () => {
  console.log(`Guestbook listening on port ${port}`);
});

/**
 * Docker stops a container with SIGTERM, and Ctrl+C in a terminal sends SIGINT. Either way:
 * take no new requests, let the open ones finish, close the database, then leave.
 */
function shutdown(signal) {
  console.log(`${signal} received, finishing open requests`);
  server.close(async () => {
    await pool.end();
    console.log('All done, bye');
    process.exit(0);
  });
  // A request that hangs must not keep the old version alive forever.
  setTimeout(() => process.exit(1), 10_000).unref();
}

process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));

Die erste Hälfte ist, was du hattest, nur dass der Pool importiert wird und der Server jetzt in einer Variable steht. Die Funktion shutdown ist neu, und die letzten beiden Zeilen rufen sie auf, wenn eines der Signale ankommt. Sie tut drei Dinge:

  • server.close sorgt dafür, dass der Server keine neuen Anfragen mehr annimmt. Die offenen werden wie gewohnt beantwortet. Erst wenn die letzte fertig ist, läuft die Funktion darin.

  • pool.end() schließt die Verbindungen zur Datenbank, und dann endet das Programm mit process.exit(0). Die Null heißt „alles gut gegangen“.

  • Das setTimeout ist ein Sicherheitsnetz. Hängt eine Anfrage und wird nie fertig, endet das Programm nach zehn Sekunden trotzdem, mit einer Eins für „etwas ging schief“. unref() sagt Node.js, dass es auf diesen Timer nicht warten soll, damit er das Programm nicht selbst am Leben hält.

Zehn Sekunden sind keine zufällige Zahl. Nachdem Docker SIGTERM geschickt hat, wartet es zehn Sekunden darauf, dass der Container geht. Dann verliert es die Geduld und beendet ihn mit Gewalt. Eine App, die in dieser Zeit fertig wird, entscheidet selbst, wie sie endet.

Probier es aus. Beende die App und starte sie ohne den Modus, der beim Speichern neu startet, denn der geht auf seine eigene Art mit Strg+C um. Drück dann Strg+C:

~/projects/guestbook
$ node --env-file=.env src/server.jsGuestbook listening on port 3000^CSIGINT received, finishing open requestsAll done, bye

Die App hat das Signal bemerkt, ist fertig geworden und hat sich verabschiedet. Auf deinem Rechner gab es keine offene Anfrage, auf die sie warten musste, also ging es schnell. Auf einem Server mit Betrieb sind diese zwei Zeilen der Unterschied zwischen einem Besucher, der seine Antwort bekommt, und einem, der einen Fehler bekommt.

Commit

Sichere den Stand:

~/projects/guestbook
$ git add .$ git commit --message "Health check and graceful shutdown"$ git push

Was du jetzt hast

Eine App, die beide Fragen eines Deployments beantworten kann. Sie sagt, ob sie bereit ist, und sie sagt die Wahrheit über ihre Datenbank. Und wenn sie gehen soll, bringt sie zuerst ihre Arbeit zu Ende. Im nächsten Teil packst du sie in ein Image, und Docker fängt an, diese Fragen zu stellen.

Kommentare

Die Kommentare sind GitHub Discussions: Zum Schreiben mit GitHub anmelden.

Die Kommentare kommen über giscus von GitHub. Beim Laden gehen deine IP-Adresse an giscus.app und GitHub.