Bereitstellung aktualisieren und wiederherstellen

Bei einer Workspace-Bereitstellung ändert tale update CLI und Workspace-Dateien; tale deploy ändert die laufenden Dienste. Wähle Zielversion und Wiederherstellungspunkt vor beiden Schritten. Ein Blue-Green-Rollout lässt Anwendungsreplikate überlappen, doch Snapshots, Entleerungsphasen und der Austausch zustandsbehafteter Dienste können Arbeit unterbrechen.

Verwaltete Bereitstellungen verwenden feste Quellrevisionen und vorbereitete Bundles statt dieses Workspace-Ablaufs. Folge dafür Verwaltete Bereitstellungen. Wenn sich nur Client-Inhalte ändern, nutze Konfigurations-Releases.

Upgrade vorbereiten

1. Führe tale status im vorgesehenen Workspace aus. Halte laufende Version, Workspace-Version und aktuellen Bereitstellungszustand fest.
2. Lies die Release Notes der Zielversion zu Kompatibilität, erforderlicher Konfiguration und bekannten Einschränkungen. Für Instanzen vor 0.5 gilt der getrennte Umstieg weiter unten.
3. Prüfe eine wiederherstellbare Sicherung außerhalb des Hosts, passende Schlüssel und den Sicherungsumfang externer Datenbanken und Buckets. Backups und Wiederherstellung beschreibt die benötigten Bestandteile.
4. Plane Kapazität für alte und neue Anwendungsreplikate gleichzeitig. Vereinbare ein Wartungsfenster, wenn Snapshots, Sandbox-Austausch oder zustandsbehaftete Dienste benötigte Arbeit unterbrechen können.
5. Prüfe die Vorschau von Update und Bereitstellung. Ein erfolgreicher Probelauf beweist nicht, dass eine echte Migration gelingt; lies alle Warnungen.

Version auswählen

Workspace-Befehle versuchen, die CLI an die Version aus tale.json anzupassen. Schlägt der Download fehl, warnt die CLI und verwendet das vorhandene Programm weiter. Kläre eine unerwartete Abweichung, bevor du die Bereitstellung änderst.

Ohne Versionsargument wählt tale update das neueste Release innerhalb der aktuellen major.minor-Linie. Eine andere Linie wählst du ausdrücklich:

tale update --dry-run
tale update --version <target-version> --dry-run
tale update --version <target-version>

Das Update ersetzt die CLI und gleicht Workspace-Vorlagen ab; laufende Container bleiben bestehen. Scheitert der Dateiabgleich, versucht die CLI, zur vorherigen Workspace-Version zurückzukehren. Prüfe danach Dateien und Ausgabe vor der Bereitstellung.

Vorschau prüfen und bereitstellen

tale deploy --dry-run
tale deploy
tale status

Ein Versionswechsel oder eine Überschreibung der Host-Konfiguration erstellt vor Änderungen einen lokalen Snapshot, sofern du nicht --skip-backup angibst. Dieser Snapshot ist ein zusätzlicher Schutz und ersetzt keine externe Sicherung.

tale deploy --stop

TALE_PLATFORM_REPLICAS, TALE_BACKEND_API_REPLICAS und TALE_BACKEND_WORKER_REPLICAS erlauben 1–16 Replikate. Erhöhe die Rolle, deren Engpass du gemessen hast. Mehr Worker beheben weder einen Datenbankausfall noch ein ausgeschöpftes Anbieterlimit.

Die Übergabe verstehen

Die CLI startet die freie Farbe und wartet auf erfolgreiche Zustandsprüfungen ihrer Replikate, bevor sie die Übergabe abschließt. Während der Überlappung können beide Versionen Anfragen bedienen. Releases müssen daher während der Migration mit der vorherigen Anwendungsversion zusammenarbeiten können.

Vor dem Entfernen wird die alte API geleert: Neue Chat-Turns können eine Drain-Verweigerung erhalten, während laufende Turns Zeit zum Abschluss bekommen. Die Chat-Phase wartet bis zu drei Minuten; die Web-Phase nutzt DRAIN_TIMEOUT, standardmäßig 30 Sekunden. Die Web-Zustandsroute bleibt gesund, solange ihr Alias gemeinsam verwendet wird. Das Trennen der alten Container von den bedienenden Netzwerken entfernt sie aus DNS und kann übrige Verbindungen kappen. Deshalb erfolgt es nach den Entleerungsphasen.

Browser-Tabs, die vor der Übergabe geöffnet wurden, laufen weiter mit der vorherigen Version. Braucht ein solcher Tab zum ersten Mal einen Teil der Anwendung, den die neue Version ersetzt hat, etwa eine Dokumentvorschau, lädt er sich einmal neu und arbeitet mit der neuen Version weiter. Lässt sich dieser Teil auch nach dem Neuladen nicht laden, zum Beispiel weil der Tab erneut die alte Farbe erreicht hat, lädt er kein zweites Mal neu. Stattdessen zeigt er Eine neue Version ist verfügbar mit der Aktion Neu laden. Ein Tab, der Tale gar nicht erreicht, lädt nicht neu; er zeigt seinen Verbindungshinweis, bis Tale wieder antwortet.

Wird die neue Gruppe nicht innerhalb von HEALTH_CHECK_TIMEOUT gesund, schließt die CLI den Wechsel nicht ab. Prüfe gespeicherten Bereitstellungszustand und Protokolle vor einem erneuten Versuch. Ein unterbrochener Rollout kann beide Gruppen oder eine ausstehende Übergabe hinterlassen. Folge den Wiederherstellungshinweisen der CLI, statt Container oder Zustandsdateien von Hand zu löschen.

Migrationen und Nutzerergebnis prüfen

Beim Start wendet das Backend seine nummerierten Migrationen in der Reihenfolge ihrer Dateinamen unter einem sitzungsgebundenen Advisory Lock an. SQL-Migrationen ändern das Schema, TypeScript-Datenmigrationen aktualisieren bestehende Zeilen nach den Regeln der Anwendung. Die Tabelle app_migrations verzeichnet beide Arten mit ihrem Dateinamen, sodass jede Migration pro Datenbank nur einmal läuft. Andere Replikate warten darauf. Ein Migrationsfehler verhindert den regulären Start des neuen Backends. Prüfe Fehler und Datenbank vor einem neuen Versuch. Vorwärtsgerichtete Migrationen werden durch einen anderen Image-Tag nicht rückgängig gemacht.

tale migrate aktualisiert mitgelieferte Organisationsstandards und rollt keine Datenbankmigration zurück. Prüfe vor einer Überschreibung der Host-Konfiguration, ob lokale Anpassungen tatsächlich ersetzt werden sollen.

Prüfe nach der Bereitstellung öffentliches Zertifikat und Anmeldung, öffne ein vorhandenes Projekt oder einen Chat und lade eine bekannte Datei herunter. Teste kontrolliert die genutzten Wissens- und Automatisierungsfunktionen. Kontrolliere Worker-Fortschritt, Speicherzustand und die tatsächlich laufende Version. Bewahre die Sicherung von vor dem Upgrade bis zur Abnahme auf.

Rollback-Weg wählen

tale rollback

--yes überspringt die Bestätigung für einen bereits genehmigten unbeaufsichtigten Lauf. Die Prüfung derselben Versionslinie ist eine Schranke, kein eigenständiger Nachweis der Kompatibilität aller externen Integrationen und lokalen Anpassungen. Eine ältere Migrationsliste als Präfix der neuen macht ein Downgrade allein nicht sicher.

tale rollback tauscht nur die Anwendungs-Images von platform, backend-api und backend-worker aus. Es stellt kein Volume wieder her und lässt Datenbank, Speicher, Proxy, Sandbox-Dienste und Modell-Gateway, wie sie sind. Auch sonst stellt kein Bereitstellungsschritt von selbst Daten wieder her: Scheitert ein gewöhnlicher Deploy (ohne --services) an seinen Zustandsprüfungen, bleibt die bisherige Anwendungsfarbe in Betrieb, doch was er bereits an Ort und Stelle ersetzt hat, bleibt ersetzt. Nur tale restore spielt die Volumes eines Snapshots zurück.

Bifrost 1.6 → 2.2: Der Speicher des Modell-Gateways wird migriert

Ein Release nach 0.5.64 stellt das Modell-Gateway (sandbox-llm-gateway) von Bifrost 1.6 auf Bifrost 2.2 um; seine Release Notes nennen den Wechsel. Beim ersten Start migriert das neue Gateway seinen Speicher in llm-gateway-data an Ort und Stelle und behält Anbieter, Schlüssel, Budgets und Admin-Konto; von Hand ist nichts zu tun. Die Migration indiziert auch das Anfrageprotokoll des Gateways, daher kann dieser Start bei einer Instanz mit langer Anfragehistorie länger dauern.

tale deploy ersetzt das Gateway, bevor es die neue Anwendungsfarbe startet. Scheitert die Bereitstellung danach, kann der Speicher also schon migriert sein. Der Snapshot, den ein tale deploy mit Versionswechsel vorher erstellt, enthält llm-gateway-data zusammen mit den anderen Volumes und ist damit auch der Wiederherstellungspunkt des Gateways. Snapshots, die entstanden sind, bevor die CLI den Speicher des Gateways erfasste, enthalten kein solches Archiv; tale restore führt sie als without gateway. Stellst du mit --skip-backup bereit, kopiere das Volume vorher selbst: Stoppe das Gateway, was laufende Agent-Turns und Modellaufrufe beendet, kopiere das Volume und stelle dann bereit. <id> ist die id in tale.json:

docker stop <id>-sandbox-llm-gateway
docker run --rm -v <id>_llm-gateway-data:/from:ro -v "$PWD/llm-gateway-data-backup:/to" alpine:3.22 cp -a /from/. /to/

Das Gateway eines Releases vor dem Wechsel startet auf dem migrierten Speicher und bedient Tale, protokolliert aber Fehler no such column: oauth_configs.token_id, und Bifrost unterstützt dieses Downgrade nicht. tale rollback startet dieses Gateway nicht: Das Gateway bleibt bei dem neueren Image und seinem Speicher. Gestartet wird es, sobald wieder ein Release vor dem Wechsel bereitgestellt wird, etwa mit tale update --version und tale deploy nach einer Snapshot-Wiederherstellung. Bring deshalb zuerst den Speicher zurück. Stellst du den Snapshot von vor dem Upgrade wieder her, kommt llm-gateway-data mit den anderen Volumes zurück. Führt tale restore diesen Snapshot als without gateway, stoppe das Gateway und spiele deine Kopie zurück, bevor du das ältere Release bereitstellst:

docker stop <id>-sandbox-llm-gateway
docker run --rm -v "$PWD/llm-gateway-data-backup:/from:ro" -v <id>_llm-gateway-data:/to alpine:3.22 sh -c 'find /to -mindepth 1 -delete && cp -a /from/. /to/'

Ein Gateway ohne Admin-Konto, bei einer neuen Installation oder nachdem sein Volume ersetzt wurde, legt das Konto jetzt nur für einen Aufrufer an, der sein Setup-Token vorweist; das Image übernimmt es aus SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD. tale deploy, die Compose-Datei im Repository und die Kubernetes-Manifeste dieser Dokumentation geben dem Gateway diese Variable bereits. Eine selbst geschriebene Compose-Datei oder ein Manifest, das sie nur dem Backend gibt, muss sie auch dem Gateway geben.

Zwei Verhaltensweisen ändern sich. Legt ein Aufrufer auf, beendet das Gateway jetzt den Modellaufruf, ob er eine ganze Antwort oder einen Stream angefordert hat. Eine abgebrochene Anfrage hält ein selbst betriebenes Modell also nicht mehr beschäftigt; die Modell-Endpunkte verbuchen einen solchen Aufruf mit seinem Prompt und der Ausgabe, die den Aufrufer erreicht hatte. Und ein Upstream, der die Antwort-Header einer gestreamten Antwort zurückhält, etwa ein Router, der Anfragen bis zu einem freien Modell in eine Warteschlange stellt, muss seine Antwort innerhalb des Anfrage-Timeouts des Gateways beginnen: 600 Sekunden, oder länger, wenn SANDBOX_LLM_GATEWAY_STREAM_IDLE_TIMEOUT_SECONDS es anhebt.

0.4 → 0.5: eine separate Installation

Mit 0.5 ersetzte Postgres den früheren Convex-Anwendungsspeicher. Es gibt keinen Importer für einen direkten Wechsel dieser Datenbanken. Halte alte Instanz und Backups intakt, während du eine neue Bereitstellung mit separatem Workspace und Datenbestand vorbereitest.

Erstelle Organisationen und Nutzer neu, prüfe und übertrage kompatible Konfiguration und importiere benötigte Dokumente erneut. Dateien in einem externen Bucket erhalten nicht automatisch Referenzen in der neuen Anwendungsdatenbank. Nimm die Ersatzumgebung ab, bevor du die alte stilllegst.

Die CLI verweigert den nicht unterstützten Umstieg standardmäßig. Die Expertenoption --accept-data-loss ist kein Migrationswerkzeug und erhält keine alten Anwendungsdaten. Historische Volumes oder Datenbanken können nach früheren Upgrades verbleiben. Ihr Vorhandensein allein ist kein Grund, sie bei diesem Ablauf zu löschen.

0.3 → 0.4: die OpenAI-kompatible API entfällt

Von 0.2.10 bis 0.3 bot Tale unter /api/v1 eine OpenAI-kompatible Schicht: POST /api/v1/chat/completions und POST /api/v1/images/generations mit Anfragen und Antworten im OpenAI-Format sowie ein GET /api/v1/models im OpenAI-Format. Ihr Feld model konnte einen Agenten nennen. Mit dem Neuaufbau in 0.4 ist diese Schicht entfallen. Aufrufer dieser Routen, auch OpenAI-SDKs, die auf die Instanz zeigen, funktionieren danach nicht mehr, denn 0.4 bedient keine der drei Routen, und spätere Versionen bringen sie nicht zurück. Eine aktuelle Version beantwortet Chat Completions und Bildgenerierung mit 404 NOT_FOUND, oder mit 400 ORG_SLUG_REQUIRED, wenn der Schlüsselinhaber mehreren Organisationen angehört und die Anfrage keinen X-Organization-Slug mitschickt, den ein OpenAI-SDK standardmäßig nicht sendet. Ihr GET /api/v1/models liefert die eigene Liste von Tale mit Modellen und Agent-Laufzeiten, die ein OpenAI-Client nicht lesen kann.

Finde diese Aufrufer vor dem Upgrade und plane ihren Ersatz. Ein Aufrufer, der die Antwort eines Modells braucht, kann auf die Modell-Endpunkte umsteigen, die Versionen ab API-Vertrag 3.7.0 anbieten. Sie unterscheiden sich von der Schicht aus 0.3: Die Basis-URL ist /api/v1/openai, für Anthropic-Clients /api/v1/anthropic, statt /api/v1; model nennt ein Modell als <providerSlug>/<modelId>, nie einen Agenten; Bildgenerierung wird nicht bedient; und die Endpunkte sind ausgeschaltet, bis ein Admin unter Einstellungen > Richtlinien > Modelle den Schalter Modell-Endpunkte für API-Schlüssel einschaltet. Danach durchläuft jeder Aufruf Modellzugriff, Eingabe-Guardrails und Budgets. Die Modell-Endpunkte erreichen die Modelle über dasselbe Modell-Gateway wie verwaltete Agenten. Fragen aus Skripten an den eingebauten Assistenten wandern zur asynchronen REST-Chat-API, die als Assistent antwortet und nicht als reines Modell. Editor-Integrationen, die das Wissen von Tale brauchen, nutzen den MCP-Endpoint, und Arbeit, die in Tale laufen soll, in einer Sandbox und mit Prüfung durch eine Person, geht an einen Projektagenten an einer Aufgabe. Tale aus deinem Editor oder einem Skript nutzen beschreibt jeden dieser Wege.