Migration von Easypanel zu Tugport: fünf Fehler und daraus gezogene Lehren

Am 24. Oktober migrierte ein Entwickler seinen primären Produktionsserver von der Deployment-Plattform Easypanel zu Tugport, einem neuen Tool, das er gerade entwickelt. Die Migration umfasste die Übertragung von 14 Projekten und 57 Diensten, darunter Datenbanken, Blogs und Bots, mittels einer einzelnen Befehlszeilenanweisung. Obwohl die Umstellung weitgehend erfolgreich verlief, traten während des Prozesses fünf spezifische Probleme auf, die häufige Fallstricke bei automatisierten Infrastruktur-Migrationen verdeutlichen.

Was passiert ist

Der Migrationsprozess begann mit einem Probelauf (Dry Run), um die Dienste ohne Änderungen abzubilden, gefolgt von der eigentlichen Ausführung des Befehls tugport migrate easypanel. Tugport, eine in Rust geschriebene Binärdatei, die neben Docker läuft, importierte den Status von Easypanel, einschließlich Projekte, Umgebungsvariablen, Domains und Zertifikate. Anschließend wurden die Datenbanken nacheinander verschoben, wobei sichergestellt wurde, dass die alte Instanz stoppte, bevor die neue im selben Datenverzeichnis startete, um Datenkorruption zu verhindern. Die Anwendungen wurden als Nächstes neben ihren alten Gegenstücken gestartet, unter Verwendung exakt derselben Images, um Rebuilds während des Wechsels zu vermeiden.

Der Traffic-Wechsel erfolgte, als der Proxy von Tugport innerhalb einer halben Sekunde die Ports 80 und 443 vom Traefik-Proxy von Easypanel übernahm. Ein Sicherheitsmechanismus stellte sicher, dass der alte Proxy die Kontrolle wieder übernimmt, falls der neue Proxy nicht innerhalb von 30 Sekunden antwortet. Das System protokollierte jeden Schritt, sodass bei Bedarf fortgesetzt oder zurückgerollt werden konnte. Volumes und Bind Mounts blieben an ihrem Platz, und Zertifikate wurden importiert, statt neu ausgestellt. Letztendlich liefen 54 Dienste auf Tugport, während drei zuvor skalierte Dienste angehalten blieben.

Trotz des sorgfältigen Designs traten bei dieser ersten Produktionsmigration fünf Bugs auf. Erstens wurden Vorlagen für Umgebungsvariablen von Easypanel, wie z. B. $(PROJECT_NAME), wörtlich kopiert, anstatt aufgelöst zu werden, was manuelle Korrekturen erforderte. Zweitens verwirrten von Easypanel zugewiesene Platzhalter-Domains die Health Checks von Tugport, wodurch Nicht-Web-Dienste hingen, während sie auf HTTP-Antworten warteten. Drittens kam es zu einem Subnetz-Konflikt im Netzwerk, da der alte CI-Runner-Stack sein festgelegtes Netzwerk noch hielt, was eine manuelle Bereinigung erforderte. Viertens wurde bei erneuten Ausführungen ein harmloser Fehlercode angezeigt, der unnötige Alarmierung auslöste. Schließlich traten bei Telegram-Polling-Bots temporäre Konflikte auf, da sowohl alte als auch neue Instanzen gleichzeitig versuchten, Updates abzurufen.

Wichtige Details

• Die Migration verschob 57 Dienste über 14 Projekte hinweg, einschließlich Postgres-, MySQL- und Mongo-Datenbanken.
• Fünf spezifische Bugs wurden identifiziert: wörtliche Kopie von Env-Vorlagen, Ausfall der Health Checks durch Platzhalter-Domains, Überschneidungen im Netzwerk-Pool, kosmetische Fehlerprotokollierung und Konflikte beim Bot-Polling.
• Health Checks für Datenbanken liefen zunächst unter hoher Last in einen Timeout, da sie alle 5 Sekunden mit einem Timeout von 5 Sekunden ausgeführt wurden; diese wurden auf Intervalle von 30 Sekunden mit Timeouts von 15 Sekunden angepasst.
• Ein schwebendes Docker-Tag (mysql:9) führte zu einer unbeabsichtigten Minor-Version-Upgrades von 9.7.0 auf 9.7.4, was zu drei Minuten Downtime führte.
• Der Migrant pinnt Datenbank-Images nun auf ihre exakten Versionen und löst Vorlagen für Umgebungsvariablen automatisch auf.

Hintergrund

Tugport ist ein selbst gehostetes Deployment-Panel, geschrieben in Rust. Es arbeitet neben Docker auf einem benutzereigenen Server und处理 Builds aus Git-Pushes, HTTPS-Terminierung und Service-Management. Im Gegensatz zu einigen Plattformen, die die zugrunde liegende Infrastruktur abstrahieren, ist Tugport auf Transparenz und Kontrolle ausgelegt und bietet API-Schlüssel mit begrenztem Zugriff für KI-Agenten sowie integrierte Migrations-Tools für Wettbewerber wie Easypanel und Coolify. Das Tool ist Open Source unter der MIT-Lizenz.

Easypanel ist ein beliebtes Server-Management-Panel, das das Deployment von Anwendungen über Docker vereinfacht. Es nutzt Traefik als Reverse Proxy und verwaltet Dienste über eine grafische Oberfläche. Bei der Migration zwischen solchen Panels liegt die Herausforderung nicht nur darin, Daten zu verschieben, sondern auch darin, Konfigurationsnuancen, Netzwerkeinstellungen und Health-Check-Logiken zu übersetzen, die oft implizit in der ursprünglichen Plattform enthalten sind.

Warum das wichtig ist

Für Teams, die selbst gehostete Software betreiben, veranschaulicht diese Fallstudie, dass automatisierte Migrationen selten nahtlos verlaufen. Selbst mit einem gut gestalteten Tool können Unterschiede darin, wie Plattformen Umgebungsvariablen, internes Networking und Health Checks handhaben, zu Dienstunterbrechungen führen. Das Verständnis dieser Fehlermodi hilft Ingenieuren, Risiken bei einem Wechsel des Infrastruktur-Anbieters oder Tools vorherzusehen. Es betont die Notwendigkeit gründlicher Tests und die Wichtigkeit, Dry-Run-Ausgaben sorgfältig zu lesen, bevor Live-Änderungen ausgeführt werden.

Der Vorfall mit dem schwebenden Docker-Tag dient als kritische Erinnerung für Produktionsumgebungen. Das Verlassen auf mutierbare Tags wie latest oder nur Major-Version-Tags kann zu unerwarteten Upgrades und Downtimes führen. Das Pinnen von Images auf spezifische Versionen gewährleistet Reproduzierbarkeit und Stabilität, eine Best Practice, die oft übersehen wird, bis eine Migration eine Neubewertung der Deployment-Konfigurationen erzwingt.

Was Sie tun können

• Führen Sie immer zuerst einen Dry-Run der Migration durch, um Mapping-Probleme, fehlende Konfigurationen und Dienste zu identifizieren, die nicht automatisch übertragen werden.
• Pinnen Sie alle Container-Images auf spezifische Versionen, anstatt schwebende Tags zu verwenden, um unbeabsichtigte Upgrades während Redeployments zu verhindern.
• Überprüfen und passen Sie Health-Check-Intervalle und -Timeouts nach der Migration an, insbesondere wenn die neue Plattform unterschiedliche Standard-Ressourcennutzungsmuster aufweist.
• Verifizieren Sie Umgebungsvariablen, die Template-Syntax verwenden, manuell, da automatisierte Tools plattformspezifische Platzhalter möglicherweise nicht korrekt auflösen.
• Planen Sie temporäre Konflikte bei Polling-basierten Diensten, wie Chatbots, indem Sie sicherstellen, dass alte Instanzen vollständig gestoppt sind, bevor neue beginnen, Anfragen zu verarbeiten.
• Bereinigen Sie alte Netzwerke und ungenutzte Ressourcen nach einer erfolgreichen Migration, um Speicherplatz freizugeben und Subnetz-Konflikte zu verhindern.