Zum Hauptinhalt springen
Sie haben am Montag eine strengere pii-shield-Policy ausgeliefert, ein Teammitglied hat am Mittwoch ein Regex erweitert, und nun wirft echter Traffic False Positives. Sie müssen sehen, was sich geändert hat, wer es geändert hat, und zurückrollen — ohne das vorherige JSON zu raten oder irgendetwas neu zu deployen. Genau das gibt Ihnen die Guardrail-Versionierung: eine History-Zeile pro Änderung, einen Diff zwischen zwei beliebigen und Ein-Klick-Revert. Diese Seite ist die fokussierte Landingpage für die Versionierungs-Oberfläche. Die Guardrail-Engine selbst — Regeltypen, Stages, Actions — finden Sie in der Guardrails-Übersicht oder der vollständigen Guardrails-Referenz.

​
1. Was die Guardrail-Versionierung aufzeichnet

Jede Mutation an einem Guardrail — create, update, delete und revert — schreibt eine Append-only-History-Zeile in derselben Transaktion wie die Änderung. Die Zeile erfasst einen Snapshot der benutzersichtbaren Konfiguration in jenem Moment:
  • den Guardrail-Namen,
  • ob es aktiviert war,
  • ob es der Workspace-Default war,
  • den vollständigen rules-Body.
Jede Zeile trägt eine monotone version-Nummer (beginnend bei 1), die operation, die sie erzeugte, den Autor und einen Zeitstempel. Weil die Zeile transaktional mit der Bearbeitung geschrieben wird, kann die History nie aus dem Takt mit der Live-Policy geraten — wenn die Bearbeitung committet, dann auch ihre History-Zeile.
Die History ist append-only. Ein Revert spult vergangene Zeilen weder zurück noch schreibt er sie um; er hängt eine neue Version an (siehe §4). Sie sehen stets die vollständige Sequenz, wer was tat, in Reihenfolge.

​
2. Ein konkretes Beispiel — die fehlerhafte Bearbeitung finden und zurückrollen

Angenommen, Guardrail 42 ist abgedriftet. Sie verfassen all dies aus der Konsole in Ihrer eigenen Session — der sk-orca-...-Relay-Key ist nur für /v1/*-Aufrufe, nie zum Lesen oder Ändern von Policy.
1

Die History auflisten

Öffnen Sie History in der Guardrail-Zeile in /console/guardrails. Der Feed ist neueste zuerst. Sie sehen v5 update (Mittwoch, von einem Teammitglied), v4 update (Montag, von Ihnen), v3 update und so weiter zurück bis v1 create. Das Lesen der History ist für jedes Workspace-Member offen.
2

Die verdächtige Änderung diffen

Wählen Sie die beiden Versionen, die die Regression einrahmen — v4 und v5 — und betrachten Sie den Diff. Der rules-Body wird nebeneinander gezeigt, sodass das erweiterte Regex als die geänderte Zeile ins Auge springt.
3

Revert

Stellen Sie v4 wieder her. Name, Enabled-Flag, Default-Flag und Regeln des Live-Guardrails werden auf jenen Snapshot zurückgesetzt, und eine frische v6 revert-Zeile wird angehängt. Die Änderung ist beim nächsten Request live — kein Redeploy, keine SDK-Änderung. Der Revert erfordert die Rolle Developer+.
Derselbe Ablauf über die REST-API, alles auf Ihrem Session-/Access-Token (nie dem Relay-Key), workspace-bezogen über X-Workspace-Id: 
# 1. List versions (Member)
curl https://api.orcarouter.ai/api/guardrail/42/history \
  -H "Authorization: Bearer <session-token>" \
  -H "X-Workspace-Id: <ws-id>"

# 2. Diff v4 against v5 (Member) — returns both snapshots to render side by side
curl "https://api.orcarouter.ai/api/guardrail/42/history/diff?from=4&to=5" \
  -H "Authorization: Bearer <session-token>" \
  -H "X-Workspace-Id: <ws-id>"

# 3. Revert to v4 — appends a new "revert" version (Developer+)
curl -X POST https://api.orcarouter.ai/api/guardrail/42/revert \
  -H "Authorization: Bearer <session-token>" \
  -H "X-Workspace-Id: <ws-id>" \
  -H "Content-Type: application/json" \
  -d '{"to_version": 4}'
Die Revert-Antwort gibt das Live-Guardrail nach dem Revert zurück, sodass Ihre UI ohne zusätzlichen Round-Trip aktualisieren kann. Der nächste von diesem Guardrail geprüfte /v1/*-Aufruf sieht die wiederhergestellte Policy.

​
3. History, Diff und der Versions-Feed

GET /api/guardrail/:id/history gibt die Versionsspur zurück, neueste zuerst. Jeder Eintrag ist ein Snapshot mit seiner Versionsnummer, Operation (create / update / delete / revert), Autor und Zeitstempel. Der Feed ist workspace-bezogen — ein Aufrufer in einem anderen Workspace erhält denselben Not-Found-Umschlag wie bei einem fehlenden Guardrail, sodass die Existenz nie leakt.
GET /api/guardrail/:id/history/:version ruft einen Snapshot über seine Versionsnummer ab — praktisch, um den exakten rules-Body zu inspizieren, der zu einem Zeitpunkt live war, bevor Sie entscheiden, ob Sie dorthin zurückkehren.
GET /api/guardrail/:id/history/diff?from=N&to=M gibt beide Snapshots zurück — from und to — sodass die Konsole einen Nebeneinander-Vergleich von Name, Flags und Regeln rendern kann. Beide Versionen müssen zu Ihrem Workspace gehören, sonst gibt der Aufruf den einheitlichen Not-Found-Umschlag zurück.
Lesezugriffe — History-Liste, einzelne Version und Diff — sind für jedes Workspace-Member offen. Sie sind reine Inspektion: Nichts am Traffic ändert sich, und kein Modell- oder Anbieter-Aufruf wird getätigt.

​
4. Revert stellt als neue Version wieder her

Ein Revert ist kein Zurückspulen. POST /api/guardrail/:id/revert mit einem to_version-Body:
  1. Lädt den Snapshot der Zielversion.
  2. Stellt Name, Enabled-Flag, Default-Flag und Regeln des Live-Guardrails auf jenen Snapshot wieder her — atomar, in einer Transaktion.
  3. Hängt eine frische revert-History-Zeile an, die den nun-live Zustand erfasst.
v5 zurück auf v4 zu reverten erzeugt also eine neue v6, deren Inhalt gleich v4 ist. Ihre History liest v1 → v2 → … → v5 → v6(revert) — jeder Schritt erhalten, nichts mutiert. Reverten Sie jenen älteren Snapshot später erneut, und Sie erhalten eine v7, und so weiter.
Ein wiederhergestellter deaktivierter oder nicht-Default-Zustand geht intakt mit. Wenn die Version, zu der Sie zurückkehren, enabled: false hatte oder nicht der Workspace-Default war, setzt der Revert das Live-Guardrail genau darauf zurück — er hält die Policy nicht stillschweigend an. Diffen Sie zuerst, damit Sie wissen, ob ein Revert auch jene Flags umlegt.
Weil die Bindung im Gateway lebt, verschiebt ein Revert jeden an dieses Guardrail angehängten API-Key auf einmal — und den Workspace-Default, falls dies einer ist — beim nächsten Aufruf. Siehe An einen Key anhängen und Der Workspace-Default dazu, wie die Anhängung aufgelöst wird.

​
5. Rollen und Aufbewahrung

ActionRouteRolle
Versionen auflisten / lesen, diffenGET …/history, …/history/diff, …/history/:versionMember
Zu einer Version revertenPOST …/revertDeveloper+
Alle History-Routen sind /api/guardrail/* und authentifizieren sich mit Ihrem Session-/Access-Token unter X-Workspace-Id — nie mit einem sk-orca-...-Relay-Key. Das Reverten trägt dasselbe Developer+-Gate wie das Erstellen oder Aktualisieren eines Guardrails, da es Live-Traffic ändert.
Die History wird bei den 50 jüngsten Versionen pro Guardrail behalten. Ältere Zeilen werden automatisch beschnitten, während Sie weiter bearbeiten, sodass ein geschwätziger Edit-Loop-Workflow die Spur nie unbegrenzt wachsen lässt. Der Listen-Endpunkt gibt bis zu den neuesten 50 zurück, neueste zuerst.
Kombinieren Sie Versionierung mit Flag-first-Tuning: Liefern Sie eine neue Regel als flag aus, beobachten Sie den Matches-Feed, und wenn sie sich schlecht verhält, diffen und reverten Sie in Sekunden, statt die alte Policy von Hand zu rekonstruieren.

​
6. Wie es weitergeht

Test & Eval vor dem Ausliefern

Beweisen Sie eine Policy in der Sandbox und gegen ein Korpus, bevor sie eine Version wird, die Sie reverten müssten.

False Positives justieren

Die Flag-dann-Promote-Schleife, die Versionierung sicher macht.

Actions: block, mask, flag

Was jede Regel tut, sobald eine Version live ist.

Guardrails-Referenz

Die vollständige Engine — Regeltypen, Stages, Presets und die komplette API.
Versionierung hier deckt die Guardrail-Content-Policy ab. Die Firewall hat ihre eigene Änderungsoberfläche für Tool-Policy; wie sich die beiden Durchsetzungsebenen unterscheiden, finden Sie unter Guardrails vs. Firewall.