Backup und Wiederherstellung

Backup erstellen#

sudo aictl backup --backup-dir /mnt/backup/aictl-2026-10-08

Ohne --backup-dir landet das Backup in einem neuen Ordner ~/aictl-backup-<zeitstempel>. Weil der Befehl mit sudo läuft, ist das der Home-Ordner von root, also zum Beispiel /root/aictl-backup-20261008T020000Z, und die Dateien gehören root. Gib deshalb besser immer einen Zielordner an.

Was im Backup ist#

• alle Einstellungen der Plattform,
• alle Zugangsdaten, die Zugangsdaten der Erweiterungen und die Lizenzaktivierung,
• die Daten aller Bausteine: Chats, Benutzer und Gruppen, Wissensspeicher, Automationen und die automatisch ausgestellten Zertifikate,
• die Daten aller Erweiterungen, zum Beispiel Protokolle oder Dokumente, und welche Version jeder Erweiterung eingerichtet ist,
• eigene Anpassungsdateien der Erweiterungen,
• die Liste der Modell-Rechner,
• ein eigenes Firmenzertifikat samt Schlüssel und Stammzertifikat, falls du eines verwendest,
• zusätzlich ein vollständiger Export der Datenbank als Reserve.

Das Backup ist ein Ordner mit den Unterordnern configs, secrets, state und volumes, dem Datenbankexport und der Datei manifest.json. Diese Datei wird als letzte geschrieben. Fehlt sie, ist das Backup unvollständig.

Was nicht im Backup ist#

Ablauf und Unterbruch#

1. Der freie Platz am Ziel wird geprüft. Reicht er nicht, bricht backup ab, bevor es etwas anhält. Siehe unten unter «Freier Platz am Ziel».
2. Einstellungen und Zugangsdaten werden kopiert, während alles läuft.
3. Die Erweiterungen und alle Bausteine ausser der Datenbank und dem Gateway werden angehalten, damit nichts mehr geschrieben wird. Dann wird die Datenbank exportiert.
4. Die Datenbank wird angehalten, und die Daten der Plattform und der Erweiterungen werden kopiert. Ganz am Schluss hält auch das Gateway kurz an, damit seine Zertifikate gesichert werden können.
5. Die Plattform startet wieder, danach die Erweiterungen. aictl wartet bis zu 5 Minuten, bis sie gesund ist.

So zeigen Datenbankexport und kopierte Daten denselben Moment. Der Unterbruch dauert so lange wie der Export und das Kopieren aller Daten. Wer die Plattform währenddessen öffnet, sieht eine Wartungsseite mit deinem Firmenlogo, die sich von selbst neu lädt. Nur in den letzten Sekunden, während das Gateway anhält, ist gar nichts erreichbar. Plane Backups trotzdem nachts oder in ruhigen Zeiten.

Eine Erweiterung oder einen ihrer Dienste, die du vorher mit aictl stop angehalten hast, lässt backup angehalten. Die Bausteine der Plattform startet es dagegen alle.

Am Ende siehst du den Ordner und den Befehl zum Zurückspielen.

Gut zu wissen#

• Immer in einen neuen Ordner sichern. Schreibst du in einen Ordner, in dem schon ein Backup liegt, werden Dateien überschrieben. Bricht das neue Backup ab, gilt der Ordner als unvollständig und lässt sich nicht mehr zurückspielen, auch das alte Backup darin nicht.
• Die Plattform muss laufen. Hast du sie mit aictl stop angehalten, lehnt backup die Arbeit gleich ab. Starte sie vorher mit sudo aictl start.
• Schlägt ein Backup fehl, startet aictl die Plattform wieder.
• Freier Platz am Ziel. Bevor backup etwas anhält, prüft es, ob am Ziel Platz für alle Daten in unkomprimierter Grösse, den Datenbankexport und 1 GiB Reserve ist. Reicht der Platz nicht, bricht es ab und nennt Bedarf und freien Platz. Die Reserve schützt vor allem das Standardziel, das meist auf derselben Platte liegt wie die Daten der Plattform: Ist diese ganz voll, startet die Datenbank nicht mehr. Die Schätzung ist bewusst grosszügig, komprimiert ist ein Backup meist deutlich kleiner. Weisst du, dass es trotzdem passt, überspringst du die Prüfung mit --skip-space-check. Lässt sich die Grösse der Daten nicht ermitteln, entfällt die Prüfung.
• Backups enthalten alle Passwörter und die Lizenz. Bewahre sie geschützt auf, idealerweise auf einem anderen Gerät oder an einem anderen Standort.
• Alte Backups löscht aictl nur, wenn du --keep angibst. Siehe Alte Backups aufräumen.

Backups planen#

Ein Backup braucht keine Eingaben und lässt sich deshalb planen, zum Beispiel jede Nacht um 2 Uhr mit einem Eintrag in der Crontab von root (sudo crontab -e), der die letzten 14 Backups behält:

0 2 * * * /usr/local/bin/aictl backup --backup-dir /mnt/backup/aictl-$(date +\%F) --keep 14

Prüfe regelmässig, ob sich ein Backup auch zurückspielen lässt, am besten auf einem Testserver.

Letztes Backup im Blick#

sudo aictl status zeigt unter Deployment, wann und wohin das letzte Backup dieses Servers geschrieben wurde. Gab es noch nie eines oder ist das letzte älter als eine Woche, erscheint dort eine Warnung. Der Exit-Code von status bleibt dabei 0.

Gezählt werden alle Backups, die auf diesem Server fertig geschrieben wurden, also auch die Sicherung des aktuellen Stands vor einer Wiederherstellung. Ein Backup, das abbricht, zählt nicht. Nach einem Umzug auf einen neuen Server beginnt die Zählung neu.

Alte Backups aufräumen#

Mit --keep <anzahl> löscht backup nach einem erfolgreichen Backup ältere Backups, sodass nur die neuesten behalten werden, das eben geschriebene eingerechnet:

sudo aictl backup --backup-dir /mnt/backup/aictl-2026-10-12 --keep 14

• Gelöscht wird nur im selben übergeordneten Ordner, im Beispiel /mnt/backup. Lege deine Backups deshalb nebeneinander in einen gemeinsamen Ordner.
• Gelöscht werden nur vollständige Backups, die dieser Server geschrieben hat. Backups anderer Server im selben Ordner, abgebrochene Backups und andere Ordner bleiben unberührt.
• Backups aus Versionen vor dieser Option erkennt aictl nicht als seine eigenen. Räume sie einmal von Hand auf.
• Schlägt das Backup fehl, wird nichts gelöscht.
• Aufgeräumt wird erst nach dem neuen Backup. Das Ziel braucht deshalb Platz für die behaltenen Backups und ein weiteres, sonst lehnt die Platzprüfung das neue ab.

Backup wiederherstellen#

sudo aictl restore /mnt/backup/aictl-2026-10-08

Achtung: Die Wiederherstellung ersetzt alle aktuellen Daten der Plattform vollständig durch den Stand des Backups. Was seither dazugekommen ist, geht verloren. Die Modell-Engine und ihre Modelle bleiben unberührt.

Der Ablauf:

1. Backup prüfen. Fehlen Teile, sind die gesicherten Einstellungen nicht lesbar (etwa aus einer neueren Version) oder fehlt ein nötiges eigenes Firmenzertifikat, bricht restore ab und nennt den Grund. Verändert wird dabei nichts.
2. Plan anzeigen und nachfragen. Die Rückfrage hat «Nein» als Vorgabe. Mit -y entfällt sie. Ohne Terminal, etwa in einem Skript, ist -y Pflicht.
3. Den aktuellen Stand sichern. aictl bietet an, zuerst ein Backup des aktuellen Stands zu erstellen, in den Standardordner ~/aictl-backup-<zeitstempel>. Mit -y geschieht das ohne Rückfrage, mit --skip-current-backup entfällt es. Dabei gilt dieselbe Platzprüfung wie bei backup, --skip-space-check überspringt sie.
4. Anhalten. Plattform und Erweiterungen werden angehalten.
5. Zurückspielen. Zugangsdaten und Lizenz werden zurückgespielt, die Konfiguration wird aus den gesicherten Einstellungen für diesen Server neu erzeugt, und die Daten werden ersetzt.
6. Starten. Die Plattform startet. aictl wartet, bis sie gesund ist, standardmässig bis zu 10 Minuten (--health-wait).
7. Abschliessen. Firmen-Login, Erweiterungen und ihre Wiederherstellungs-Aufgaben werden eingerichtet, und fehlende DNS-Einträge werden angeboten. Pakete der Erweiterungen werden dabei bei Bedarf neu heruntergeladen.

Während der ganzen Wiederherstellung ist die Plattform nicht erreichbar. Ein vorheriges aictl stop wird aufgehoben.

Gut zu wissen#

• Die Sicherung des aktuellen Stands braucht eine laufende Plattform. Hast du sie mit stop angehalten, bricht restore gleich ab. Starte sie dann mit sudo aictl start oder verzichte mit --skip-current-backup auf die Sicherung. Schlägt die Sicherung fehl, bricht restore ab, ohne etwas zu verändern, und startet die Plattform wieder. Ist dein aktueller Stand ohnehin nicht mehr brauchbar, verwende --skip-current-backup.
• Zugangsdaten der Plattform verloren. Fehlt auf dem Server die Datei mit den Zugangsdaten der Plattform, lässt sich der aktuelle Stand nicht sichern. restore meldet das, überspringt die Sicherung und spielt das Backup trotzdem zurück.
• Abgebrochene Wiederherstellung. Bricht restore mittendrin ab, zum Beispiel durch einen Stromausfall, meldet status einen Fehler restore mit dem Hinweis, den Befehl zu wiederholen. Führe dann genau dieselbe Wiederherstellung erneut aus.
• Die Plattform wird nicht rechtzeitig gesund. Dann sind die Daten zwar zurück, die letzten Schritte (Firmen-Login, Erweiterungen, Wiederherstellungs-Aufgaben) aber nicht gelaufen. Führe sudo aictl apply aus, sobald status alles grün zeigt. Damit werden Firmen-Login und Erweiterungen eingerichtet. Die Wiederherstellungs-Aufgaben holt apply nicht nach. aictl zeigt dafür am Ende der Wiederherstellung die Befehle, mit denen du sie von Hand ausführst.
• Eine Erweiterung lässt sich nicht einrichten. Die übrigen werden trotzdem eingerichtet, restore endet aber mit einem Fehler, obwohl die Daten zurück sind. Behebe die Ursache und führe sudo aictl apply aus.
• Eine Wiederherstellungs-Aufgabe schlägt fehl. aictl zeigt dann für diese und jede danach ausgelassene Aufgabe den Befehl, mit dem du sie von Hand nachholst, sobald die Ursache behoben ist. apply führt diese Aufgaben nicht aus. Alternativ wiederholst du die Wiederherstellung oder meldest dich beim Support.
• Erweiterungen, die nach dem Backup installiert wurden, werden angehalten und nicht wieder eingerichtet, weil sie im gesicherten Stand nicht vorkommen. Ihre Daten bleiben auf dem Server liegen. Installiere sie neu oder entferne sie.
• Die Wiederherstellung braucht keine gültige Lizenz, das anschliessende apply aber schon.

Backups aus anderen Versionen#

• Ein älteres Backup auf einer neueren Version von aictl funktioniert. Die gesicherten Einstellungen werden mit den Standardwerten der neueren Version gelesen. Beim ersten Start können Bausteine ihre Daten auf den neuen Stand bringen. Plane dafür Zeit ein, notfalls mit --health-wait 20m. Stammt das Backup aus der Zeit vor einer neuen Hauptversion der Datenbank, zieht restore die Daten anschliessend selbst um, wie unter Updates beschrieben.
• Ein Backup aus einer neueren Version kann eine ältere Version von aictl nicht lesen. restore erkennt das und bricht ab, bevor es etwas verändert. Aktualisiere aictl dann mit sudo aictl update und starte die Wiederherstellung erneut.

Umzug auf einen neuen Server#

1. Auf dem alten Server ein Backup erstellen und den Ordner auf den neuen Server kopieren.

2. Lizenz freigeben. Die Lizenz ist an den alten Server gebunden. Ohne Freigabe lehnt der Lizenzserver die Aktivierung auf dem neuen Server ab. Dafür gibt es zwei Wege:

   • Entferne die Plattform auf dem alten Server mit sudo aictl uninstall --skip-backup (das Backup aus Schritt 1 genügt). Dabei gibt aictl die Lizenz frei. Bis der neue Server läuft, ist die Plattform nicht erreichbar.
   • Soll der alte Server bis zum Schluss weiterlaufen, bitte den Support unter [email protected], die Bindung aufzuheben.

3. Auf dem neuen Server das Werkzeug installieren und die Plattform installieren:

   curl -fsSL https://swaiz.ch/install | sh
   sudo aictl install --license LIC-XXXX-XXXX-XXXX-XXXX
   

4. Eigenes Firmenzertifikat zuerst einspielen, falls du eines verwendest und dein Backup es nicht enthält (ältere Backups). Sonst bricht die Wiederherstellung ab, bevor sie etwas verändert:

   sudo aictl proxy set-cert --cert zertifikat.pem --key schluessel.pem
   

5. Backup wiederherstellen:

   sudo aictl restore /pfad/zum/backup
   

6. Lizenz auf den neuen Server holen und alles abgleichen. Das Backup bringt die Lizenzaktivierung des alten Servers mit. Der Hintergrunddienst aktiviert die Lizenz bei seiner nächsten Bestätigung für den neuen Server, sofort geht es so:

   sudo aictl license renew
   sudo aictl apply
   

7. Modell-Rechner prüfen. Die Liste der Rechner kommt aus dem Backup mit. Zeigt sudo aictl status einen Rechner als nicht erreichbar, etwa weil seine Firewall nur den alten Server zulässt, lass ihn neu beitreten: Erzeuge auf dem neuen Hauptserver mit sudo aictl node join-command <name> den Befehl und führe ihn auf dem Rechner aus. Die Modelle auf den Rechnern bleiben erhalten.

8. DNS auf die Adresse des neuen Servers umstellen.

9. Automatische Updates bei Bedarf wieder einschalten.

10. Den alten Server mit sudo aictl uninstall entfernen, sobald alles läuft, falls du das nicht schon in Schritt 2 getan hast.

Die Plattform entfernen#

sudo aictl uninstall

Der Befehl zeigt, was er tun wird, und fragt nach. Die Vorgabe ist «Nein». Dann:

1. Der Hintergrunddienst wird entfernt.
2. Ein Backup wird erstellt (ohne --skip-backup), mit derselben Platzprüfung wie bei backup. Schlägt es fehl, wird nichts gelöscht. Ist die Plattform mit stop angehalten, bricht uninstall schon vor der Rückfrage ab. Starte sie vorher oder verzichte mit --skip-backup auf das Backup.
3. Alle Dienste der Plattform und der Erweiterungen werden angehalten und entfernt.
4. DNS-Einträge, die aictl selbst angelegt hat, werden gelöscht, sofern ihr Wert noch stimmt.
5. Die Lizenz wird auf dem Lizenzserver freigegeben, damit du sie auf einem anderen Server aktivieren kannst.
6. Alle Daten werden gelöscht, auch die Daten von Erweiterungen, die früher ohne --purge entfernt wurden, dazu die Einstellungen und die Lizenzaktivierung.

Nach --keep-data holst du die Plattform mit sudo aictl install zurück. Willst du sie später doch ganz entfernen, führe sudo aictl uninstall --skip-backup aus.

Was nach dem Entfernen bleibt#

• die Modell-Engine mit allen heruntergeladenen Modellen,
• das Werkzeug aictl selbst unter /usr/local/bin/aictl,
• die Laufzeitumgebung der Plattform und ihre heruntergeladenen Bestandteile,
• die Gruppenmitgliedschaft, die install der installierenden Person gegeben hat. Entferne sie mit sudo gpasswd -d <benutzer> <gruppe>,
• Firewall-Regeln, die aictl angelegt hat,
• DNS-Einträge, die aictl angelegt hat,
• alle Backups.

Wichtig: Kann uninstall den Lizenzserver nicht erreichen, etwa ohne Internetverbindung, meldet es das und entfernt die Plattform trotzdem. Die Lizenz bleibt dann an diesen Server gebunden. Bitte den Support, sie freizugeben, bevor du sie auf einem anderen Server aktivierst. Mit --keep-data bleibt die Lizenz immer gebunden.

uninstall braucht eine funktionierende Installation. Fehlen die Einstellungen oder die Zugangsdaten, verweigert der Befehl die Arbeit. Melde dich dann beim Support.