OpenShip-Bereitstellung fehlgeschlagen: Leitfaden

Der OpenShip-Status zeigt „bereitgestellt“, doch Ihre Domain liefert einen Timeout oder eine leere Fehlerseite.

Die schnellste Lösung: Nicht neu installieren, sondern die Fehlerkette in fünf Schichten prüfen — lokaler Build, SSH-Übertragung, Containerstart, Domainrouting und abhängige Dienste.

Diese Anleitung richtet sich an Sie, wenn Sie OpenShip erstmals für ein AI-SaaS, einen Backend-Dienst oder eine Anwendung mit Datenbank einsetzen. Sie ist außerdem für Administratoren gedacht, die eigene Server warten und den Unterschied zwischen einem Codefehler, einem Netzwerkproblem und einem ungeeigneten Build-Rechner schnell erkennen müssen.

Wenn Ihr Mac den Build nicht zuverlässig schafft, während des Deployments in den Ruhezustand wechselt oder nicht dauerhaft online bleiben kann, ist ein stabiler Remote-Build-Knoten die sinnvollere Entscheidung. Einen Plattformwechsel sollten Sie erst erwägen, wenn die Fehlerursache nicht in einer einzelnen Schicht liegt.

Starten Sie mit einer belastbaren Fehlerkarte

OpenShip beschreibt den Weg von der Quelle bis zur laufenden Anwendung als getrennte Phasen: Der Code wird gebaut, ein versioniertes Artefakt wird erzeugt, über SSH an das Ziel übertragen, dort als Container gestartet und anschließend über Routing und TLS erreichbar gemacht. Die offiziellen OpenShip-Installationshinweise und der offizielle Projektstand im Quellcode sind deshalb die erste Referenz für unterstützte Installations- und Bereitstellungspfade.

Bevor Sie Änderungen vornehmen, halten Sie diese fünf Informationen fest:

1. Vollständiger Build-Log, nicht nur die letzte Fehlermeldung.
2. Exit-Code der fehlgeschlagenen Aktion.
3. Zieladresse, Port und Benutzer für SSH.
4. Containerstatus, Startlog und Healthcheck-Ergebnis.
5. Öffentliche DNS-Antwort und tatsächliche HTTP-Antwort.

Ein häufiger verdeckter Kostenfaktor ist die gleichzeitige Änderung mehrerer Variablen. Wenn Sie DNS, Container-Port und Umgebungsvariablen auf einmal ändern, verlieren Sie die Vergleichsbasis. Ändern Sie pro Prüfzyklus nur eine Ursache und dokumentieren Sie die resultierende Evidenz.

Hinweis: „Deployment abgeschlossen“ ist kein Verfügbarkeitsnachweis. Erst eine echte Anfrage über den vorgesehenen öffentlichen Endpunkt bestätigt, dass Anwendung, Routing, TLS und Abhängigkeiten zusammen funktionieren.

Prüfen Sie den Build vor jeder Serverdiagnose

Bei einer OpenShip-Bereitstellung fehlgeschlagen ist der Build die erste Station, auch wenn die Oberfläche den Fehler erst während des Deployments anzeigt. OpenShip kann Projekte aus einem Repository oder aus einem lokalen Ordner übernehmen und die Anwendung anhand ihrer Projektstruktur erkennen. Die offizielle Einführung in die Projektquellen beschreibt diese beiden Wege.

1. Abhängigkeitsinstallation

Suchen Sie im vollständigen Log nach dem Abschnitt, in dem Paketmanager oder Systempakete installiert werden. Relevant sind nicht nur Meldungen wie „package not found“, sondern auch:

• Lockfile und Manifest passen nicht zusammen.
• Eine private Abhängigkeit ist ohne Zugriffsschlüssel nicht erreichbar.
• Die konfigurierte Laufzeit ist zu alt oder zu neu.
• Ein Installationsskript erwartet ein Betriebssystemwerkzeug, das im Build-Kontext fehlt.

Prüfen Sie danach die Dateien, die den Build bestimmen, beispielsweise package.json, Lockfile, Dockerfile, Build-Konfiguration und .dockerignore. Verwenden Sie für die Fehlersuche Platzhalter und geben Sie keine echten Geheimnisse in Logauszüge ein:

grep -nE "error|failed|permission|not found|exit code" <vollstaendiger-build-log>
cat <projektverzeichnis>/package.json
cat <projektverzeichnis>/<lockfile>

Behandlung: Stimmen Manifest, Lockfile und Laufzeit nicht überein, beheben Sie zuerst die Projektkonfiguration. Ein lokaler Ressourcenmangel sieht anders aus: Der Prozess wird beendet, der Rechner wird extrem langsam, der Arbeitsspeicher ist erschöpft oder der Speicherplatz reicht nicht aus, während die Konfiguration selbst plausibel bleibt.

2. Build-Kommando und Laufzeit

Prüfen Sie, welches Kommando tatsächlich ausgeführt wird. Ein Projekt kann lokal mit npm run build funktionieren, während OpenShip ein anderes Skript oder ein falsches Arbeitsverzeichnis verwendet. Kontrollieren Sie daher:

npm run <build-script>
echo $?
node --version
npm --version

Bei einer anderen Laufzeit ersetzen Sie die Kommandos durch die entsprechenden Prüfungen. Der entscheidende Beweis ist der Exit-Code zusammen mit der ersten kausalen Fehlermeldung. Ein späteres „artifact missing“ ist oft nur die Folge eines früheren Kompilierungsfehlers.

Verifizierung nach der Reparatur: Führen Sie den Build mit exakt derselben Laufzeit, denselben Umgebungsvariablen und demselben Arbeitsverzeichnis erneut aus. Ein grüner lokaler Build genügt nicht, wenn OpenShip aus einem anderen Ordner oder mit einem anderen Secret-Satz baut.

3. Ressourcen gegen Konfigurationsfehler abgrenzen

Wenn der Build nur auf Ihrem Mac scheitert, vergleichen Sie drei Fälle:

• Scheitert das Projekt reproduzierbar an derselben Quellcodezeile, liegt der Verdacht bei Code oder Konfiguration.
• Bricht es an wechselnden Stellen ab und verschwindet der Prozess, prüfen Sie Arbeitsspeicher, Speicherplatz und thermische Drosselung.
• Funktioniert der Build auf einem leistungsfähigeren, dauerhaft verfügbaren Rechner unverändert, ist Ihr lokaler Rechner wahrscheinlich die Engstelle — nicht automatisch der Quellcode.

OpenShip dokumentiert für die selbst gehostete Plattform eigene Systemanforderungen. Beziehen Sie sich bei der Kontrolle auf die aktuelle Installationsdokumentation, statt Mindestwerte aus einem alten Blogbeitrag zu übernehmen.

Trennen Sie SSH-Verbindung und Übertragung

OpenShip kann ein Zielsystem über SSH ansprechen; laut offizieller Plattformbeschreibung wird das erzeugte Artefakt an das Ziel übertragen und dort als frischer Container gestartet. Dadurch sind drei Fehlerbilder auseinanderzuhalten: keine Verbindung, abgebrochene Übertragung und Verbindung ohne ausreichende Ausführungsrechte.

1. Erster Verbindungsversuch schlägt fehl

Testen Sie zuerst nur die Verbindung:

ssh -vvv \
  -i <pfad-zum-privaten-schluessel> \
  -p <ssh-port> \
  <benutzer>@<ziel-host> \
  "printf 'ssh-ok\n'; id; hostname"

Dieser Test soll drei Beweise erzeugen:

• Wird der Zielhost erreicht?
• Wird der erwartete Hostschlüssel akzeptiert?
• Meldet der Server den korrekten Benutzer und Hostnamen?

Ein Timeout deutet eher auf falsche Adresse, falschen Port, fehlende Route oder Firewall hin. „Permission denied“ weist eher auf Benutzername, Schlüsseltyp, Dateirechte oder eine nicht hinterlegte öffentliche Schlüsseldatei hin. Eine Warnung zum Hostschlüssel ist kein Grund, die Prüfung blind zu überspringen. Entfernen Sie einen alten Eintrag nur, wenn Sie die Identität des Servers außerhalb der betroffenen Verbindung bestätigt haben.

2. Übertragung bricht ab

Wenn die SSH-Sitzung funktioniert, die Image-Übertragung aber abbricht, prüfen Sie freie Ressourcen und Verbindungsstabilität auf dem Ziel:

df -h
free -h
uptime
ss -tulpn

Erzeugen Sie zusätzlich einen kleinen Testtransfer:

scp -v -i <pfad-zum-privaten-schluessel> \
  <kleine-testdatei> \
  <benutzer>@<ziel-host>:/tmp/<testdatei>

Ein kleiner erfolgreicher Transfer bei einem großen fehlgeschlagenen Artefakt lenkt den Verdacht auf Speicherplatz, Verbindungsabbrüche, Limits oder einen Prozessabbruch während des Imports. Ändern Sie nicht gleichzeitig MTU, Firewall und OpenShip-Konfiguration. Prüfen Sie jeweils, welcher Schritt den Abbruch auslöst.

3. Verbindung besteht, aber kein Ausführungsrecht

Ein erfolgreicher Login bedeutet nicht, dass der verwendete Benutzer Container verwalten oder in das vorgesehene Arbeitsverzeichnis schreiben darf. Prüfen Sie:

id
groups
ls -ld <zielverzeichnis>
docker ps

Wenn nur ein privilegierter Benutzer bestimmte Befehle ausführen kann, dokumentieren Sie die benötigte Berechtigung und beschränken Sie sie auf das Deployment. Für öffentlich erreichbare Systeme gilt das Prinzip der minimalen Angriffsfläche: SSH nur über den tatsächlich benötigten Port, keine unnötigen Verwaltungsports und keine direkte Freigabe interner Datenbankdienste.

Beachten Sie außerdem Datenschutz und Schlüsselhygiene. Private Schlüssel gehören nicht in Build-Logs, Repositorys oder unverschlüsselte Chatverläufe. Für die organisatorische Prüfung können Sie die Datenschutzhinweise von Kvmkit als Ergänzung heranziehen; sie ersetzen jedoch keine serverseitige Schlüssel- und Zugriffsrichtlinie.

Stabilisieren Sie Containerstart und Healthcheck

Ein Container kann erfolgreich erzeugt worden sein und trotzdem sofort beendet werden. Prüfen Sie deshalb nicht nur die Anzeige „live“, sondern den Prozess innerhalb des Containers.

docker ps -a
docker logs --tail 200 <container-name>
docker inspect <container-name>
docker inspect --format='{{json .State.Health}}' <container-name>

Achten Sie auf diese Signale:

• Exit-Code 1 oder 2: häufig Startkommando, Konfiguration oder Anwendungscode.
• Fehlende Umgebungsvariable: Secret oder Konfiguration wurde nicht in die Zielumgebung übernommen.
• Port bereits belegt: ein anderer Dienst nutzt den erwarteten Port.
• Healthcheck schlägt fehl: Prozess läuft, antwortet aber nicht am vorgesehenen Pfad.
• Out-of-memory-Signal: der Prozess wird vom Betriebssystem beendet.
• Verbindung verweigert: Anwendung erwartet einen Dienst, der nicht erreichbar ist.

Das interne Listening ist besonders wichtig. Eine Anwendung, die ausschließlich auf 127.0.0.1 lauscht, ist aus einem anderen Container oder über einen Reverse Proxy möglicherweise nicht erreichbar. Prüfen Sie den tatsächlichen Bind-Host und den Port:

docker exec -it <container-name> sh -lc \
  "ss -lntp || netstat -lntp"

Prüfen Sie anschließend die Anwendung mit einer realen Anfrage:

curl -i http://127.0.0.1:<port>/<health-pfad>
curl -i https://<ihre-domain>/<health-pfad>

Die erste Anfrage prüft den Prozess, die zweite die gesamte öffentliche Kette. OpenShip beschreibt automatische Zertifikate, Routing, Logs und Rollbacks als Bestandteile des Betriebsmodells; die konkrete Verfügbarkeit muss trotzdem anhand Ihrer laufenden Version und des eigenen Servers bestätigt werden.

Bewahren Sie die vorherige stabile Version auf. Wenn der neue Container wiederholt neu startet, ist ein Rollback mit unverändertem Datenbestand meist sicherer als eine Folge undokumentierter Änderungen. Löschen Sie keinen Container und kein Datenvolumen, bevor Logs, Konfiguration und Sicherung gesichert sind.

Prüfen Sie Domain, HTTPS und externe Erreichbarkeit

Wenn der lokale Test funktioniert, die Domain aber nicht, arbeiten Sie von außen nach innen. Die Reihenfolge verhindert, dass Sie einen DNS-Fehler mit einer Containeränderung „reparieren“.

1. DNS-Auflösung

Nutzen Sie mehrere öffentliche Resolver:

dig +short <ihre-domain> A
dig +short <ihre-domain> AAAA
dig @1.1.1.1 <ihre-domain> A
dig @8.8.8.8 <ihre-domain> A

Ein falscher A- oder AAAA-Eintrag führt dazu, dass Ihre Anfrage einen anderen Server erreicht. Wenn nur IPv6 fehlschlägt, IPv4 aber funktioniert, prüfen Sie den AAAA-Eintrag und die IPv6-Erreichbarkeit getrennt.

2. Zertifikat

Prüfen Sie Zertifikat, Aussteller und Gültigkeit:

openssl s_client \
  -connect <ihre-domain>:443 \
  -servername <ihre-domain> </dev/null 2>/dev/null \
  | openssl x509 -noout -issuer -subject -dates

Ein Zertifikatsfehler kann durch falsche DNS-Ziele, blockierte Validierung, eine nicht erreichbare Domain oder einen abweichenden Hostnamen entstehen. Die OpenShip-Dokumentation nennt automatische SSL-Konfiguration im Schnellstart, doch ein Zertifikat ist kein Beweis, dass Ihre Anwendung korrekt antwortet.

3. Route und HTTP-Antwort

curl -Ivs https://<ihre-domain>/
curl -Ivs https://<ihre-domain>/<health-pfad>

Dokumentieren Sie Statuscode, Location, Serverantwort und Zeitüberschreitungen. Ein 404 zeigt meist, dass Sie den Server erreichen, aber Pfad oder Route nicht stimmen. Ein 502 oder 504 deutet häufig auf einen nicht erreichbaren Upstream hin. Wenn nur der Server selbst zugreifen kann, prüfen Sie Bind-Adresse, Firewall, DNS-Split-Horizon, Reverse-Proxy-Regel und den tatsächlich geöffneten Eingangsport.

OpenShip weist in seiner Routing-Dokumentation darauf hin, dass ein privater Netzwerklink nicht automatisch jeden Zielport öffnet. Ein Dienst muss am vorgesehenen Port erreichbar sein; ein Link ohne passende Portfreigabe kann daher stillschweigend scheitern. Vergleichen Sie diese Prüfung mit der aktuellen Routing-Dokumentation, da sich technische Details zwischen Versionen ändern können.

Isolieren Sie Datenbank- und Hintergrunddienste

Eine Anwendung kann starten und trotzdem bei jedem Login, API-Aufruf oder Schreibvorgang scheitern. Dann ist die Datenbank nicht zwingend „kaputt“. Prüfen Sie vier getrennte Fragen:

1. Läuft der Datenbankdienst?
2. Liegen Anwendung und Datenbank im vorgesehenen privaten Netzwerk?
3. Zeigt die Verbindungszeichenfolge auf die richtige Umgebung?
4. Existiert das Datenvolumen mit den erwarteten Daten?

Auf Anwendungsebene testen Sie zunächst nur die Namensauflösung und den Port:

getent hosts <datenbank-host>
nc -vz <datenbank-host> <datenbank-port>

Danach verwenden Sie ein temporäres Diagnosekommando mit nicht protokollierten Zugangsdaten. Geben Sie Passwörter niemals direkt in Shell-Historie oder Screenshots ein. Ein Fehler wie „connection refused“ ist ein Verfügbarkeits- oder Netzwerkhinweis. „Authentication failed“ weist eher auf Benutzer, Passwort oder Datenbanknamen hin. Ein erfolgreicher Login mit anschließendem Fehler bei Migrationen weist dagegen auf Schema, Berechtigungen oder inkompatible Versionen hin.

Vor jeder Wiederherstellung sichern Sie Datenbank, Volumes und relevante Umgebungsvariablen. Testen Sie einen Restore in einer getrennten Umgebung. Die konkrete Datenhaltung hängt vom gewählten Ziel und der verwendeten OpenShip-Version ab. Deshalb müssen Sie die Angaben in Ihrer eigenen Konfiguration und Dokumentation gegenprüfen.

Entscheiden Sie zwischen Reparatur und neuem Build-Knoten

Nicht jede fehlgeschlagene OpenShip-Bereitstellung rechtfertigt einen Wechsel der Umgebung. Nutzen Sie diese Entscheidungshilfe:

Ein Remote-Mac ist besonders dann sinnvoll, wenn Ihr lokaler Rechner den Build beendet, nicht dauerhaft online bleibt oder mehrere Teammitglieder denselben reproduzierbaren Build-Ort benötigen. Wenn hingegen der Container auf dem Zielserver wegen eines falschen Ports oder fehlender Datenbankrechte nicht startet, löst zusätzliche Hardware das Problem nicht.

Führen Sie die Prüfung für die Wiederinbetriebnahme als Meilensteinkette durch

Nach der Reparatur sollten Sie nicht direkt auf „Deploy“ klicken und den Vorgang als erledigt markieren. Dokumentieren Sie sieben Meilensteine:

1. Build: Vollständiger Log gespeichert, Exit-Code erfolgreich, Artefakt vorhanden.
2. Übertragung: SSH-Test erfolgreich, Testtransfer abgeschlossen, Zielressourcen ausreichend.
3. Start: Neuer Container läuft mit erwarteter Prozess-ID und ohne wiederholte Neustarts.
4. Healthcheck: Interner Healthcheck liefert die erwartete Antwort.
5. Domain: Öffentliche DNS-Auflösung, gültiges HTTPS und externe HTTP-Anfrage bestätigt.
6. Daten: Ein kontrollierter Lese- und Schreibtest funktioniert; Backup ist auffindbar.
7. Rollback: Vorherige Version wurde identifiziert und der Rückweg mindestens als Test dokumentiert.

Für die Teamübergabe genügt ein standardisiertes Fehlerprotokoll:

Zeitpunkt:
Commit oder Release:
Zielhost:
Fehlerschicht:
Erwartetes Verhalten:
Tatsächliches Verhalten:
Vollständiger Log gespeichert unter:
Exit-Code:
Ausgeführte Prüfungen:
Veränderte Variable:
Reparatur:
Nachweis der Verifizierung:
Rollback-Version:
Freigabe durch:

Wenn der Fehler nach diesen Prüfungen eindeutig im lokalen Build-Rechner liegt, prüfen Sie als nächsten Schritt eine dauerhaft erreichbare Umgebung. Kvmkit bietet dafür Mac-mini-Mietoptionen für die USA-Ostküste an. Für einen allgemeinen Überblick über verfügbare Mac-Umgebungen können Sie auch die Mac-Lösungen von Kvmkit ansehen.

Häufige Fragen zur OpenShip-Fehlerbehebung

OpenShip-Build fehlgeschlagen: Welcher Logabschnitt ist entscheidend?

Sichern Sie zuerst den kompletten Build-Log und den Exit-Code. Entscheidend ist die erste kausale Fehlermeldung: Abhängigkeit, Laufzeitversion, Build-Kommando, Umgebungsvariable oder Image-Erzeugung. Eine spätere Meldung wie „Artefakt fehlt“ ist oft nur eine Folge. Vergleichen Sie die gefundene Stelle mit Manifest, Lockfile, Dockerfile und dem tatsächlich verwendeten Arbeitsverzeichnis.

OpenShip erreicht den Server nicht über SSH — was ist zu prüfen?

Trennen Sie Netzwerk und Authentifizierung. Ein Timeout prüft Adresse, Port, Route und Firewall; „Permission denied“ prüft Benutzer, Schlüssel und Dateirechte. Verwenden Sie eine ausführliche SSH-Verbindung mit Platzhaltern und führen Sie danach einen kleinen Testtransfer aus. Wenn beides funktioniert, aber der Einsatzbefehl scheitert, untersuchen Sie die Berechtigungen des Remote-Benutzers und den verfügbaren Speicher.

OpenShip ist erfolgreich, aber die Domain bleibt nicht erreichbar — warum?

Die Statusanzeige bestätigt nicht automatisch DNS, TLS und Anwendungspfad. Prüfen Sie zuerst A- und AAAA-Auflösung über öffentliche Resolver, danach Zertifikat und schließlich die HTTP-Antwort mit curl -Ivs. Wenn der Dienst nur lokal antwortet, kontrollieren Sie Bind-Adresse, internen Port, Routingregel und Firewall. Nehmen Sie DNS und Containerkonfiguration nicht gleichzeitig als Änderungsziel.

Wie beheben Sie wiederholte Neustarts eines OpenShip-Containers?

Lesen Sie Status, Startlog und Healthcheck gemeinsam. Ein falsches Startkommando, fehlendes Secret, falscher Port, ein nicht erreichbarer Dienst oder Speichermangel erzeugt unterschiedliche Signale. Testen Sie den Prozess mit derselben Konfiguration außerhalb des automatischen Neustartzyklus. Bewahren Sie die letzte stabile Version auf und führen Sie bei erfolgloser Korrektur einen Rollback statt einer Neuinstallation durch.

Wie stellen Sie eine OpenShip-Datenbankverbindung ohne Datenverlust wieder her?

Erstellen Sie zuerst ein Backup und prüfen Sie, ob es tatsächlich wiederherstellbar ist. Danach testen Sie Dienststatus, interne Namensauflösung, Port, Datenbankname und Zugangsdaten getrennt. „Verbindung verweigert“ und „Authentifizierung fehlgeschlagen“ haben unterschiedliche Ursachen. Löschen Sie kein Datenvolumen als Standardmaßnahme. Erst nach einem Restore-Test in einer isolierten Umgebung sollten Sie Migration oder Neuinitialisierung planen.

Wenn die Ursache bei Ihrem aktuellen Ansatz liegt, sind ein lokaler Mac mit begrenztem Arbeitsspeicher, ein nicht dauerhaft laufendes Gerät und fehlende zentrale Logs die drei praktischen Schwachstellen. Ein stabiler Remote-Mac von Kvmkit kann diese Einschränkungen für temporäre Builds, Tests und kontrollierte Bereitstellungen ausgleichen. Für dauerhafte Hochlast, spezielle physische Schnittstellen oder vollständig lokale Datenverarbeitung bleibt ein eigener Rechner jedoch die passendere Wahl.

FAQ