OpenShip v0.4.7 Servermigration: Abnahme-Checkliste

Am 28.07.2026 wurde OpenShip v0.4.7 laut dem offiziellen Changelog veröffentlicht; dort wird eine Verbesserung der Zuverlässigkeit bei der Remote-Docker-Migration genannt. Das bedeutet jedoch nicht, dass eine abgeschlossene Migration automatisch produktionsbereit ist. Wenn die Ziel-Container laufen, aber Datenbank, Datenvolumen oder Hintergrundjobs noch nicht nachgewiesen sind, dürfen Sie den Datenverkehr nicht umschalten. Die schnellste Lösung ist eine getrennte Abnahme mit überprüfbaren Belegen für Container, Images, Daten, Berechtigungen, Domain, TLS, Jobs und Rückfall.

Diese Anleitung richtet sich an Entwickler, die bestehende Docker-Anwendungen mit OpenShip übernehmen, an Betriebsteams beim Wechsel eines Produktionsservers und an technische Verantwortliche, die vor der Umschaltung ein klares Freigabekriterium benötigen. Wenn Sie nur eine neue Testumgebung aufbauen, können Sie die Rückfall- und DNS-Prüfungen verkürzen; bei einer produktiven AI-SaaS-Anwendung sollten Sie keinen dieser Bereiche überspringen.

Letzte Aktualisierung: 03.08.2026. Die Versionsangabe und die Änderung an der Remote-Docker-Migrationskette wurden anhand des offiziellen Changelogs, der aktuellen Dokumentation und des offiziellen Repository-Standes geprüft. Eine erneute Prüfung ist erforderlich, sobald OpenShip die Migrationslogik, den Umgang mit Datenvolumen oder die Zertifikatsverwaltung ändert.

Was „Migration abgeschlossen“ bei OpenShip noch nicht bedeutet

OpenShip beschreibt einen Ablauf, bei dem ein Image gebaut, über SSH an einen Zielserver übertragen und dort als neuer Container gestartet wird. Die Plattform nennt außerdem Routing, automatische TLS-Verwaltung und Rollback als Bestandteile des Workflows. Diese Aussagen beschreiben die vorgesehene Produktfunktion; sie ersetzen nicht den Nachweis in Ihrer konkreten Umgebung. Die offizielle Workflow-Beschreibung ist deshalb als Prüfliste für erwartete Funktionen nützlich, aber nicht als Beleg dafür, dass Ihre Datenbank oder Ihre Jobs korrekt übernommen wurden. (openship.io)

Bei einer echten OpenShip v0.4.7 Servermigration treten meist vier voneinander unabhängige Risiken auf:

• Laufzeitrisiko: Ein Container kann den Status „running“ anzeigen, obwohl der Prozess intern keine Datenbankverbindung aufbauen kann oder nur eine Fehlerseite ausliefert.
• Datenrisiko: Ein korrekt gestarteter Container kann an einem leeren oder veralteten Datenvolumen hängen. Die Anwendung wirkt erreichbar, zeigt aber einen alten Datenbestand.
• Betriebsrisiko: Cronjobs, Queue-Consumer oder Webhook-Verarbeiter können auf dem alten und neuen Server gleichzeitig laufen und Aufgaben doppelt ausführen.
• Zugriffsrisiko: Die Migration kann technisch erfolgreich sein, während Umgebungsvariablen, Registry-Zugang, API-Schlüssel oder Datenbankrechte auf die falsche Umgebung zeigen.
• Rückfallrisiko: Ein Rollback ist nur dann belastbar, wenn der alte Server erreichbar bleibt und Sie wissen, welche Daten nach der Umschaltung bereits auf dem neuen Knoten geschrieben wurden.

Für die Abnahme sollten Sie daher nicht nur das Dashboard öffnen. Sie benötigen eine Beweiskette: Befehl oder Protokoll, Ergebnis, verantwortliche Person und eine konkrete Aktion bei Fehlern.

Erste Prüfung: Version, Umfang und Ausgangszustand dokumentieren

Bevor Sie den Zielserver testen, halten Sie fest, was überhaupt migriert werden soll. Der häufigste Fehler bei einer Docker Migration ist nicht ein defekter Container, sondern ein Dienst, der in der aktuellen Compose-Datei nicht sichtbar ist, aber für den Betrieb benötigt wird.

1. OpenShip-Version am Steuerungsrechner und am Zielsystem prüfen.

Verwenden Sie die von Ihrer Installation unterstützten Status- oder Versionsbefehle und speichern Sie die Ausgabe als Textdatei. Verlassen Sie sich nicht auf eine Browseransicht, die möglicherweise aus einem zwischengespeicherten Zustand stammt.

1. Quelle und Ziel eindeutig benennen.

Notieren Sie Hostname, öffentliche Adresse, SSH-Benutzer, Docker-Kontext und die verantwortliche Person. Der alte Server bleibt bis zum Abschluss der Abnahme aktiv und wird nicht vorschnell gelöscht.

1. Vollständige Dienstliste bilden.

Vergleichen Sie die deklarierte Compose- oder Projektdefinition mit der tatsächlichen Ausgabe von docker ps -a, docker image ls und den vorhandenen Netzwerken. Berücksichtigen Sie auch gestoppte Container, einmalige Migrationsdienste, Worker, Datenbankdienste und Reverse-Proxy-Komponenten.

1. Rückfall-Einstieg sichern.

Dokumentieren Sie, wie Sie den alten Container, den alten DNS-Eintrag, die alte Konfiguration und die alte Datenbank wieder aktivieren. Ein Screenshot des alten Zustands reicht nicht aus, wenn kein ausführbarer Befehl oder kein getesteter Zugang dahintersteht.

Als Beleg gehören in das Migrationsprotokoll mindestens die Version, die Dienstliste, die Image-Tags oder Digests, die Namen der Datenvolumen, der letzte erfolgreiche Backup-Zeitpunkt und der geplante Umschaltzeitraum. Diese Angaben sind keine Bürokratie: Ohne sie können Sie später nicht unterscheiden, ob ein Fehler durch ein anderes Image, eine falsche Konfiguration oder fehlende Daten verursacht wurde.

Zweiter Schritt: Container und Images gegen den realen Zustand prüfen

OpenShip kann den Bereitstellungsweg vereinfachen, aber die Abnahme muss den Zustand auf dem Server prüfen. Die offizielle Installationsdokumentation beschreibt die Selbstinstallation, Docker-Compose-Variante und den Statuscheck; für Ihre Anwendung brauchen Sie zusätzlich eine Dienst-für-Dienst-Prüfung. (openship.io)

Für jeden Dienst prüfen Sie:

• Läuft genau ein erwarteter Container?
• Verwendet der Container das erwartete Image und den erwarteten Tag beziehungsweise Digest?
• Sind Netzwerk, Ports und Abhängigkeiten korrekt verbunden?
• Gibt es wiederholte Neustarts, OOM-Fehler oder fehlgeschlagene Healthchecks?
• Sind die im Projekt definierten Umgebungsvariablen im Zielsystem vorhanden?
• Wird ein Build-Dienst tatsächlich neu gebaut oder nur ein altes Image gestartet?
• Kann ein Image-Dienst aus der vorgesehenen Registry abgerufen werden?

Führen Sie anschließend eine kontrollierte Neubereitstellung durch. Dabei geht es nicht darum, möglichst schnell erneut zu deployen, sondern um einen Beweis: Der Zielserver muss den Dienst aus der vorgesehenen Quelle reproduzierbar erstellen können. Prüfen Sie danach erneut Container-ID, Image-Digest, Logs, Netzwerkzuordnung und Anwendungsantwort.

Was tun Sie, wenn der alte Container „stopped“ anzeigt, die Anwendung aber erreichbar bleibt? Prüfen Sie zuerst, ob Sie den richtigen Docker-Kontext und den richtigen Server abgefragt haben. Danach kontrollieren Sie Reverse-Proxy, DNS-Auflösung, Cache und eventuell einen zweiten Container mit ähnlichem Namen. Wenn die Antwort weiterhin aus dem alten Knoten kommt, ist die Migration noch nicht abgenommen. Speichern Sie docker ps -a, die Proxy-Zuordnung und die DNS-Auflösung gemeinsam, statt nur den Containerstatus zu bewerten.

Ein typischer Fehlversuch sieht so aus: Das Dashboard zeigt den neuen Dienst als aktiv, aber die Domain zeigt weiterhin auf die alte Adresse. Der Betreiber interpretiert die erfolgreiche Browserantwort als neuen Betrieb. Erst ein Header oder eine eindeutige Build-Kennung in der Anwendung zeigt, welcher Knoten tatsächlich antwortet.

Datenbank und Datenvolumen: Welche Beweise reichen wirklich?

Die Frage, ob eine OpenShip-Migration des Docker-Servers Daten verlieren kann, lässt sich nicht mit einem allgemeinen „Ja“ oder „Nein“ beantworten. Das Risiko hängt davon ab, welche Daten außerhalb des Containers gespeichert werden, wie die Kopie erstellt wurde und ob die Wiederherstellung erfolgreich getestet wurde. Docker weist selbst darauf hin, dass ein Datenvolumen nach dem Löschen eines Containers bestehen bleiben kann; daraus folgt aber nicht, dass es auf dem Zielserver automatisch vorhanden oder aktuell ist. Die Docker-Dokumentation zu Volumes beschreibt auch Verfahren für Sicherung, Migration und Wiederherstellung. (docs.docker.com)

Prüfen Sie die Daten in vier Ebenen:

1. Volumenbestand: Stimmen Namen, Mountpoints und erwartete Anzahl der Datenvolumen zwischen Quelle und Ziel überein? Ein Volumen mit einem ähnlichen Namen ist kein ausreichender Beleg.
2. Datenbankstruktur: Stimmen Tabellen, Migrationen, Indizes und Rollen mit dem Ausgangssystem überein? Prüfen Sie nicht nur, ob der Datenbankprozess läuft.
3. Geschäftsdaten: Lesen Sie mehrere bekannte Datensätze aus unterschiedlichen Bereichen. Bei einer AI-SaaS-Anwendung können dies Benutzer, Projekte, Abrechnungsstatus, Prompt-Konfigurationen und Aufgabenstände sein.
4. Schreibfähigkeit und Persistenz: Schreiben Sie einen eindeutig markierten Testdatensatz, lesen Sie ihn zurück, starten Sie den betroffenen Container neu und lesen Sie ihn erneut.

Der wichtigste zusätzliche Nachweis ist eine isolierte Wiederherstellung. Ein Backup-Job mit dem Status „successful“ beweist nur, dass ein Prozess ohne gemeldeten Fehler beendet wurde. Kopieren Sie das Backup in eine getrennte Testumgebung, stellen Sie die Datenbank oder das Datenvolumen wieder her und führen Sie anschließend dieselben Lese- und Schreibtests aus. Erst dann kennen Sie die tatsächliche Wiederherstellbarkeit.

Diese Tabelle ist das eigentliche Freigabewerkzeug: Ein Bereich mit „nicht geprüft“ ist kein grüner Bereich, auch wenn die Website bereits eine Startseite ausliefert.

Geheimnisse, Berechtigungen und externe Abhängigkeiten

Eine Migration kann die Anwendung starten und trotzdem sicherheits- oder funktionskritisch falsch konfiguriert sein. Prüfen Sie deshalb jede sensible Abhängigkeit getrennt:

• Datenbank-Benutzer und Datenbankname
• Registry- oder Git-Zugang
• API-Schlüssel für AI-, Zahlungs-, E-Mail- und Monitoring-Dienste
• Webhook-Signaturen
• SSH-Schlüssel und bekannte Hosts
• Verschlüsselungsschlüssel für Sessions oder gespeicherte Dateien
• interne Service-Adressen und erlaubte Quellnetze

Ordnen Sie jeden Schlüssel einer Umgebung zu: Quelle, Ziel, Test oder Produktion. Ein häufiger Fehler besteht darin, die gesamte .env-Datei unverändert zu kopieren, obwohl darin Hostnamen, Callback-Adressen oder Produktionsrechte enthalten sind, die auf dem neuen Server nicht gelten sollen.

Nutzen Sie für Deployment und Wiederherstellung ein Konto mit den geringsten erforderlichen Rechten. Prüfen Sie gleichzeitig, ob nur die notwendigen Ports erreichbar sind. Das Dashboard, die Docker-API oder interne Datenbankports dürfen nicht versehentlich öffentlich exponiert werden. Die OpenShip-Dokumentation weist bei der Compose-Installation auf die verwendeten Ports und das persistente Datenverzeichnis hin; vergleichen Sie diese Angaben mit Ihrer tatsächlichen Firewall- und Reverse-Proxy-Konfiguration. (openship.io)

Speichern Sie als Nachweis nicht die geheimen Werte selbst. Dokumentieren Sie nur Variablenname, Zielumgebung, Änderungszeitpunkt und das Ergebnis des Funktionstests. Wenn ein Geheimnis während der Migration offen in Logs, Shell-Historie oder Supportdateien gelandet ist, behandeln Sie es als kompromittiert und ersetzen Sie es.

Domain, Zertifikat und WebSocket vor der Umschaltung testen

Wie wechseln Sie bei einem Serverwechsel Domain und Zertifikat, ohne die alte Route zu früh abzuschalten? Testen Sie zunächst mit einer temporären Subdomain oder einer lokalen Hosts-Datei gegen die neue Adresse. So können Sie HTTP, HTTPS, Redirects, Proxy-Header und WebSocket-Verbindungen prüfen, bevor der öffentliche DNS-Eintrag geändert wird.

Führen Sie diese Reihenfolge aus:

1. Zielserver über eine Testadresse erreichen.
2. HTTP- und HTTPS-Verhalten prüfen.
3. Zertifikatskette, Hostname und Ablaufdaten kontrollieren.
4. Weiterleitungen und X-Forwarded-*- beziehungsweise vergleichbare Proxy-Header prüfen.
5. Einen WebSocket-Aufbau testen, falls Ihre Anwendung Live-Ausgaben, Agentenstatus, Benachrichtigungen oder Streaming verwendet.
6. Healthcheck und kritische Anwendungspfade über die neue Domain ausführen.
7. Erst danach TTL, DNS-Ziel und Umschaltzeit notieren.

OpenShip beschreibt automatische Let’s-Encrypt-Zertifikate und den Wechsel auf die neue Container-Version als Teil seines vorgesehenen Routing-Ablaufs. Für die Abnahme müssen Sie jedoch zusätzlich kontrollieren, ob die DNS-Auflösung bereits auf den Zielserver zeigt, ob die Zertifikatsausstellung die neue Adresse erreicht und ob der Proxy Upgrade-Header für langlebige Verbindungen weitergibt. (openship.io)

Planen Sie eine klare Zeitgrenze: Der alte Server bleibt bis zum Ende der Beobachtungsphase erreichbar, aber nur ein Knoten darf produktive Schreibvorgänge ausführen. Ohne diese Grenze entsteht ein Split-Brain-Zustand, bei dem Benutzer auf unterschiedlichen Datenständen landen.

Hintergrundjobs, Queues und Umschaltung kontrollieren

Webzugriffe sind nur ein Teil der Produktion. AI-SaaS-Anwendungen besitzen häufig Worker, geplante Aufgaben, E-Mail-Versand, Abrechnung, Webhook-Verarbeitung oder Queue-Consumer. Starten Sie diese Komponenten nicht auf beiden Servern parallel, wenn sie nicht ausdrücklich idempotent und für parallelen Betrieb ausgelegt sind.

Vor der Umschaltung:

• pausieren oder koordinieren Sie Cronjobs;
• stoppen Sie alte Queue-Consumer kontrolliert;
• prüfen Sie die Zahl unbearbeiteter und laufender Aufgaben;
• kennzeichnen Sie den Zeitpunkt des letzten erfolgreichen Verbrauchs;
• sichern Sie Dead-Letter- oder Fehlerwarteschlangen;
• aktivieren Sie die Verbraucher auf dem Zielserver erst nach der Datenprüfung.

Nach der Umschaltung testen Sie mindestens einen neuen Auftrag, eine erfolgreiche Verarbeitung und einen absichtlich erzeugten Fehlerpfad. Prüfen Sie dabei, ob Statusänderungen in der Datenbank persistiert werden und ob Monitoring oder Benachrichtigung auslöst.

Wenn ein Job auf dem alten und neuen Server gestartet wurde, halten Sie nicht einfach nur einen Prozess an. Prüfen Sie, ob er bereits externe Nebenwirkungen ausgelöst hat: E-Mail, Zahlung, Modellaufruf, Dateiablage oder Webhook. Die technische Ursache und die fachliche Auswirkung müssen getrennt dokumentiert werden.

Rollback: Wann dürfen Sie den alten Server abschalten?

Kann ein fehlgeschlagener OpenShip-Serverumzug auf den alten Knoten zurückgesetzt werden? Ja, aber nur dann belastbar, wenn der alte Knoten noch erreichbar ist, die alte Route bekannt ist und Sie die Datenbewegung seit der Umschaltung kontrollieren können. Ein in der Oberfläche vorhandener Rollback-Knopf ist kein vollständiger Rückfallplan für eine Servermigration.

Führen Sie vor der endgültigen Freigabe einen kontrollierten Rückfalltest durch:

1. Definieren Sie ein beobachtbares Fehlerkriterium, etwa fehlgeschlagene Datenbankverbindungen oder nicht verarbeitete Jobs.
2. Schalten Sie die neue Route zurück auf den alten Server.
3. Prüfen Sie Login, Lesen, Schreiben und eine zentrale Benutzeraktion.
4. Kontrollieren Sie, ob der alte Server noch die aktuelle Datenbasis besitzt.
5. Stoppen Sie neue Verbraucher auf dem Zielserver, damit keine parallelen Schreibvorgänge entstehen.
6. Dokumentieren Sie Dauer, Datenverlustfenster und manuelle Nacharbeiten.

Der Rückfall ist nicht bestanden, wenn nur die Startseite des alten Servers erscheint. Sie müssen auch die Geschäftslogik, Datenbankzugriffe, Hintergrundjobs und externe Integrationen prüfen.

Eine praktische Freigabeformel lautet:

• Alle Prüfbereiche bestanden: Umschaltung freigeben.
• Nur Anzeige funktioniert, Daten- oder Jobprüfung offen: Umschaltung verschieben.
• Zielserver funktioniert, Rückfall ungeprüft: alte Umgebung aktiv lassen.
• Datenstand zwischen Quelle und Ziel unklar: keine weiteren Schreibvorgänge zulassen und Wiederherstellung klären.

Die von OpenShip beschriebene Möglichkeit, frühere Versionen bereitzuhalten und zurückzurollen, ist eine Plattformfunktion. Ob sie bei einem Wechsel des Servers, des Datenvolumens oder der externen Abhängigkeiten genügt, müssen Sie in Ihrer Umgebung nachweisen. (openship.io)

Die endgültige Abnahme in einem Protokoll festhalten

Am Ende sollten Sie nicht „Migration erfolgreich“ als einzigen Status eintragen. Verwenden Sie pro Prüffeld vier Spalten:

• Testobjekt: etwa PostgreSQL-Volume, Worker, TLS-Domain oder Image-Digest;
• Beleg: Logdatei, Terminalausgabe, Backup-ID, Testdatensatz oder Screenshot mit Zeitstempel;
• Durchkriterium: das konkrete erwartete Ergebnis;
• Fehleraktion: Verschieben, pausieren, wiederherstellen, rotieren oder zurückschalten.

Verlinken Sie die Protokolle nicht öffentlich, wenn sie Hostnamen, interne IP-Adressen oder Betriebsdaten enthalten. Bei der gemeinsamen Prüfung können Sie zusätzlich den kvmboot Hilfe-Center als organisatorischen Bezugspunkt verwenden, insbesondere wenn Sie für die Migration einen getrennten Zielknoten und eine parallele Testphase benötigen.

Ein Serverwechsel ist erst abgeschlossen, wenn die neue Umgebung nicht nur läuft, sondern reproduzierbar neu bereitgestellt, aus einem Backup wiederhergestellt, über die echte Domain erreicht und bei einem Fehler kontrolliert verlassen werden kann. Genau diese Nachweise unterscheiden eine fertige Bereitstellung von einer produktionsfähigen Migration.

Wenn Ihre aktuelle Maschine keine parallele Alt- und Neuumgebung zulässt, ist ein zusätzlicher temporärer Knoten oft risikoärmer als eine direkte Umschaltung mit nur einem Versuch. Selbstbetrieb auf einer einzelnen Maschine hat dann drei konkrete Nachteile: kein sauberer Vergleich zwischen Quelle und Ziel, ein engeres Rollback-Fenster und ein höheres Risiko, dass Datenprüfung und Produktionsbetrieb gleichzeitig stattfinden. Für eine zeitlich begrenzte Doppelspur können Sie deshalb einen unabhängigen Server von kvmboot evaluieren, die Migration dort anhand dieser Tabelle abnehmen und erst danach entscheiden, ob der dauerhafte Betrieb auf Ihrer eigenen Infrastruktur sinnvoll bleibt.