Backups und Upgrades

Was gesichert werden muss, wie die Wiederherstellung auf einem neuen Host erfolgt, wie ein Upgrade durchgeführt wird und wie ein Mattermost-Server oder eine einzelne Community zu Antimatter migriert wird.

Was gesichert werden muss

Ohne den KI-Verschlüsselungsschlüssel kann ein wiederhergestellter Server die API-Schlüssel seiner Modellverbindungen nicht lesen, und jeder Schlüssel muss erneut eingegeben werden. Bewahren Sie eine Kopie des Schlüssels getrennt von den Datenbank-Backups auf, damit ein gestohlenes Backup nicht beide enthält. Siehe Der Verschlüsselungsschlüssel.

Die Datenbank und die Dateien gehören zusammen: Sichern Sie sie gleichzeitig und bewahren Sie Kopien getrennt vom Server auf. Die Volumennamen beginnen mit dem Namen des Compose-Projekts, antimatter (docker volume ls listet sie auf).

Sichern

Aus dem Verzeichnis von compose.yaml. Ein vorheriges Stoppen von Antimatter erzeugt eine vollständig konsistente Kopie; ein Backup, das während des Betriebs erstellt wird, ist in der Regel unbedenklich, aber während des Backups hochgeladene Dateien fehlen möglicherweise darin.

stamp=$(date +%Y%m%d-%H%M%S)
mkdir -p backups
docker compose stop antimatter
# Database
docker compose exec -T postgres pg_dump -U antimatter -d antimatter -Fc \
    > "backups/antimatter-db-$stamp.dump"
# File storage, GIF service and the data directory (the AI key file)
for v in files gifs data; do
    docker run --rm -v "antimatter_$v:/data:ro" -v "$PWD/backups:/backup" \
        alpine tar -czf "/backup/antimatter-$v-$stamp.tar.gz" -C /data .
done
docker compose start antimatter
# Secrets
cp .env "backups/env-$stamp"

Falls Sie AM_AI_ENCRYPTION_KEY nicht festgelegt haben, befindet sich die Schlüsseldatei des Servers im data-Volume, das im obigen Loop zusammen mit den Dateien gesichert wird. Besser ist es, den Inhalt gemäß Der Verschlüsselungsschlüssel in die .env aufzunehmen und eine Kopie davon getrennt von den Datenbank-Backups aufzubewahren.

Führen Sie das Skript über Cron für tägliche Backups aus und kopieren Sie das Verzeichnis backups/ auf einen anderen Rechner. Bewahren Sie die Kopien der .env genauso sicher wie den Server auf: Sie enthalten dessen Passwörter.

Um die hochgeladenen Dateien stattdessen objektweise zu kopieren (zum Beispiel in einen anderen S3-Speicher), verwenden Sie das AWS-Kommandozeilen-Tool des bucket-Dienstes:

docker compose run --rm -v "$PWD/backups/files:/backup" bucket \
    "aws --endpoint-url http://files:9000 s3 sync s3://antimatter /backup"

Sichern Sie bei einem Release-Archiv die Datenbank mit pg_dump -Fc sowie die Verzeichnisse data/ und config/ mit Ihren üblichen Tools (data/ enthält die KI-Schlüsseldatei). Sichern Sie bei Paketen die Datenbank auf dieselbe Weise sowie /etc/antimatter, /var/lib/antimatter, /etc/gifs-server und /var/lib/gifs-server.

Auf einem neuen Host wiederherstellen

Legen Sie compose.yaml, die gespeicherte .env und die Backups in ein neues Verzeichnis und führen Sie dann Folgendes aus:

stamp=20261016-030000          # the backup to restore
docker compose create           # creates the volumes, starts nothing
docker compose up -d postgres
docker compose exec -T postgres pg_restore -U antimatter -d antimatter --no-owner \
    < "backups/antimatter-db-$stamp.dump"
for v in files gifs data; do
    docker run --rm -v "antimatter_$v:/data" -v "$PWD/backups:/backup" \
        alpine tar -xzf "/backup/antimatter-$v-$stamp.tar.gz" -C /data
done
docker compose up -d

Verwenden Sie dieselbe .env: Der Speicher und die Datenbank müssen die Passwörter beibehalten, und die Modellverbindungen benötigen denselben KI-Verschlüsselungsschlüssel. Falls der neue Host eine andere Adresse hat, aktualisieren Sie SITE_URL (und DOMAIN).

Testen Sie Ihre Backups, indem Sie sie von Zeit zu Zeit auf einem anderen Rechner wiederherstellen.

Upgrade

1. Erstellen Sie ein Backup.
2. Ändern Sie den Image-Tag in der .env (ANTIMATTER_IMAGE), falls Sie einen festlegen, wie empfohlen.
3. Pull und Neustart:

   docker compose pull
   docker compose up -d
   docker compose logs -f antimatter

Beim Start aktualisiert der Server das Datenbankschema (verfolgen Sie dies im Protokoll; bei einem großen Server kann dies mehrere Minuten dauern) und installiert die neueren Versionen der mitgelieferten Apps aus dem Image. Bei einem Release-Archiv: Stoppen Sie den Server, ersetzen Sie alles außer config/, data/, logs/, plugins/ und client/plugins/ durch den Inhalt des neuen Archivs und starten Sie ihn erneut. Bei einem .deb- oder .rpm-Paket installieren Sie das neue Paket wie unter Ein Paket aktualisieren beschrieben.

Versionen

Der Antimatter-Server meldet die Version der Mattermost-Zeile, auf der er basiert (derzeit 12.0.0). Die Releases auf GitHub mit ihren Archiven und Paketen haben eigene Versionsnummern, während der Beta-Phase in der 0.9.0-Serie: antimatter version zeigt sie als Build-Nummer an. Die Images werden aus den main-Branches neu erstellt: antimatter-next jede Nacht (Tags nightly-<YYYYMMDD>) und beide Images bei jeder Änderung (Tags sha-<commit>). Fixieren Sie einen dieser Tags, aktualisieren Sie gezielt und notieren Sie den vorherigen Tag, damit Sie wissen, welches Backup dazu gehört.

PostgreSQL-Hauptversionen

Die Compose-Datei verwendet postgres:17-alpine. Antimatter benötigt PostgreSQL 15 oder neuer. Eine neue Hauptversion von PostgreSQL kann das Datenverzeichnis der vorherigen Version nicht lesen: Um auf eine neue Version zu wechseln, sichern Sie die Datenbank, starten Sie die neue Version auf einem neuen Volume und stellen Sie die Sicherung darin wieder her.

Upgrade auf 0.9.0

Beim ersten Start der Version 0.9.0 (oder eines Images, das ab dem 17. Oktober 2026 erstellt wurde) werden einige einmalige Änderungen an den Daten vorgenommen. Jeder dieser Schritte wird nur einmal ausgeführt und in der Datenbank protokolliert. Dabei werden Daten, die noch auf einem alten Standardwert standen, auf den neuen Wert gesetzt; Werte, die von einer Administratorin oder einem Administrator festgelegt wurden, bleiben unverändert. Die Änderungen werden im Log protokolliert.

Die Dienste der Agents-App

Beim Upgrade wird jeder KI-Dienst der Agents-App in eine serverweite Modellverbindung kopiert, die mit jeder Community geteilt wird und von allen außer Gästen genutzt werden kann (aktivieren Sie Auch Gäste, um ihnen dies zu ermöglichen). Die Schlüssel werden während des Vorgangs verschlüsselt, daher benötigt der Server seinen KI-Verschlüsselungsschlüssel: Legen Sie auf einem Cluster, dessen Dateien in S3 liegen, zuerst AM_AI_ENCRYPTION_KEY fest, andernfalls wartet der Kopiervorgang auf den nächsten Start. Prüfen Sie anschließend Systemkonsole › KI › Modellverbindungen:

• Jede Verbindung behält die ID ihres Dienstes, sodass die Agenten der App und eine automatische Übersetzung, die auf einen Agents-Dienst eingestellt ist, diesen weiterhin finden.
• OpenAI-, OpenAI-kompatible, Anthropic-, Mistral-, Cohere- und Gemini-Dienste werden zu Verbindungen zu ihren OpenAI-kompatiblen (oder Anthropic-) Endpunkten. Ein Azure-Dienst wird zu einer Verbindung zum OpenAI-kompatiblen Endpunkt der Ressource: Testen Sie diese.
• AWS Bedrock-, Google Vertex AI- und Cohere North-Dienste sowie unbekannte Typen werden als Benötigt Aufmerksamkeit markiert, zusammen mit dem Grund. Ihre Cloud-Zugangsdaten werden nicht kopiert: Weisen Sie sie dem OpenAI-kompatiblen Endpunkt des Anbieters oder einem Gateway wie LiteLLM zu und speichern Sie dann.
• Der Einbettungsdienst wird zum Embeddings-Modell der Verbindung mit derselben Adresse und demselben Schlüssel oder zu einer eigenen Verbindung. Der Transkriptionsdienst erhält das Modell whisper-1.
• Wenn für die Umformulierung und Zusammenfassungen noch keine Verbindung besteht, erhalten sie den Dienst und das Modell des Standard-Agenten der App.

Die Agenten der Agents-App

Nach den Diensten wandelt das Upgrade jeden Agenten der Agents-App (jetzt die KI-Chat-App) in einen serverweiten Agenten um, und zwar im selben Konto: seine Verbindung (die von seinem Dienst kopierte), das Modell, die Anweisungen, das Reasoning, die Tool-Turns und wer ihn verwenden darf. Der Server antwortet dann für diese Agenten. Wenn die App einen Agenten auf eine Weise eingeschränkt hat, die die Agenten des Servers nicht ausdrücken (die Kanäle, in denen er geantwortet hat, Blocklisten, attributbasierter Zugriff), wird der Agent auf die Mitglieder dieser Kanäle oder auf niemanden beschränkt und als „Handlungsbedarf“ markiert. Dasselbe gilt für einen Agenten, dessen Dienst nicht zu einer Verbindung wurde. Überprüfen Sie diese in Systemkonsole › KI › Modellverbindungen. Die anderen Einstellungen der App bleiben unverändert.

Weitere Änderungen der Standardwerte

• Calls: Testmodus ist standardmäßig deaktiviert und Video aktivieren ist standardmäßig aktiviert. Eine in der Konfiguration gespeicherte Auswahl bleibt erhalten. Calls richten sich auch nach der Art der Community (siehe Calls und Sprache).
• Das Anheften von Nachrichten oben ist für die Administratoren des Kanals, die Administratoren und Moderatoren der Community (mit Nachrichten verwalten) vorgesehen; Mitglieder einer Direktnachricht oder Gruppennachricht können dies weiterhin tun.
• Archivierte Kanäle können neue Mitglieder aufnehmen, die deren Verlauf lesen können. Niemand kann dort posten, reagieren oder etwas ändern.

Umstieg von Mattermost

Antimatter nutzt das Datenbankschema von Mattermost und fügt eigene Tabellen hinzu, sodass es die PostgreSQL-Datenbank und Dateien eines Mattermost-Servers übernehmen kann. Testen Sie dies zuerst auf einer Kopie:

1. Erstellen Sie ein Backup der Mattermost-Datenbank, des Dateispeichers (data/ oder S3-Bucket) und von config.json, und stoppen Sie dann Mattermost.
2. Stellen Sie die Datenbank in Antimatters PostgreSQL wieder her, oder verweisen Sie Antimatter auf eine Kopie davon (AM_SQLSETTINGS_DATASOURCE).
3. Kopieren Sie die Dateien in Antimatters Speicher und behalten Sie die Pfade bei: in den Bucket antimatter mit einem S3-Tool oder in data/ mit einem Release-Archiv.
4. Nutzen Sie Ihre Einstellungen weiter: Kopieren Sie config.json oder verschieben Sie es mit amctl --local config migrate in die Datenbank (siehe Konfiguration). Ihre MM_-Umgebungsvariablen funktionieren weiterhin; benennen Sie sie bei Gelegenheit in AM_ um.
5. Starten Sie Antimatter und verfolgen Sie das Protokoll, während es die Datenbank aktualisiert. Überprüfen Sie anschließend Systemkonsole › Plugins › Plugin-Verwaltung. Antimatter installiert seine eigenen Builds von Calls, KI-Chat und den Integrationen, wenn diese neuer sind als die installierte Version, sowie von Playbooks und Kanban (Boards), falls der Mattermost-Server eine dieser Apps bereits installiert hatte (keine von beiden wird auf einem neuen Server mehr gebündelt: siehe Gebündelte Apps). Wenn Mattermost eine neuere Version einer dieser Apps hatte, entfernen Sie diese App und starten Sie Antimatter neu, damit sein eigener Build installiert wird.
6. Richten Sie Push-Benachrichtigungen erneut ein, mit Ihrem eigenen Push-Proxy: Antimatter sendet niemals Benachrichtigungen an die Push-Dienste von Mattermost (Test- oder gehostete Dienste), die nur an die eigenen Apps von Mattermost liefern. Bis Sie den Push-Benachrichtigungs-Server ändern, sendet der Server keine Push-Benachrichtigungen (siehe Push-Benachrichtigungen).

Antimatter kontaktiert keinen Dienst, der von Mattermost, Inc. betrieben wird (siehe Verbindungen zu externen Diensten), auch wenn Ihre Konfiguration noch einen solchen nennt:

• Ein Push-Benachrichtigungs-Server bei Mattermost bleibt in den Einstellungen erhalten, wird aber niemals verwendet;
• Die Adressen von Mattermost für den App-Marktplatz (Marktplatz-URL) und für Produktankündigungen werden geleert;
• Die App-Download-Links, die die Standardwerte von Mattermost waren (Antimatter Apps Download Page Link, Android-App Downloadlink und iOS-App-Downloadlink), werden durch die Download-Seiten der Antimatter-Apps auf GitHub ersetzt; von Ihnen selbst festgelegte Links bleiben erhalten;
• Die Calls-App verwendet den öffentlichen STUN-Server von Cloudflare anstelle desjenigen von Mattermost, ohne die gespeicherte Einstellung zu ändern (siehe Calls);
• Die Prüfung auf Sicherheitsupdates und die Absturzberichterstattung entfallen, ebenso wie ihre Einstellungen in der Systemkonsole (Enable Security Alerts, Enable Diagnostics and Error Reporting) und die Seite Ankündigungen.

Der Socket für den lokalen Modus lautet nun /var/tmp/antimatter_local.socket; amctl versucht auch den alten Pfad /var/tmp/mattermost_local.socket. Mattermost unterstützt in seinen aktuellen Versionen nur noch PostgreSQL, und Antimatter tut dies ebenfalls: Migrieren Sie eine MySQL-Datenbank zuerst auf PostgreSQL. Wenn Sie nach der Datenbankaktualisierung durch Antimatter zu Mattermost zurückkehren möchten, müssen Sie Ihr Mattermost-Backup wiederherstellen.

Daten exportieren und importieren

Das Bulk-Exportformat verschiebt Daten zwischen Servern: den gesamten Server, bestimmte Communities oder bestimmte Kanäle, einschließlich Anhängen, Profilbildern und benutzerdefinierten Emojis, falls gewünscht.

# on the source server
amctl export create --team-name design --include-profile-pictures
amctl export list
amctl export download <export file> design.zip
# on the destination server
amctl import upload design.zip
amctl import list available
amctl import process <uploaded file> --imported-users active

Beobachten Sie die Aufträge mit amctl export job list und amctl import job list. Für den Export eines Kanals oder einer Community ist --imported-users erforderlich: active, wenn die Personen auf diesen Server wechseln, inactive, wenn sie in einen Server importiert werden, auf dem sie bereits Konten haben, damit Konten, die aufgrund unsicherer Übereinstimmungen erstellt wurden, deaktiviert bleiben, bis ein Administrator diese überprüft. --destination-team-name importiert in eine vorhandene Community. Exporte und Importe werden standardmäßig 30 Tage lang im Speicher des Servers aufbewahrt (ExportSettings.Directory, ImportSettings.Directory).

Auf dem Server selbst führen antimatter export bulk und antimatter import bulk --apply dieselben Aufgaben über Dateien aus, ohne die API.

Die Zeile eines Kanals im Export enthält dessen Typ und Einstellungen (am_type, am_mode, am_root_posts und bei Foren am_forum_view); eine Zeile ohne diese Angaben wird als einfacher Text-Chat-Kanal importiert. Die Zeile eines Root-Posts in einen Foren-Kanal benötigt props.am_thread_title, den Titel des Themas; ohne diesen schlägt der Import dieser Zeile fehl.