跳轉到主要內容
你週一出貨了一個更嚴格的 pii-shield 政策，一個隊友週三放寬了一個正規表示式，而現在實際流量正拋出誤報。你需要看見什麼變了、是誰變的，並回滾——而不必猜測先前的 JSON 或重新部署任何東西。那就是防護欄版本控制給你的：每次變更一筆歷史列、任意兩者之間的一個比對，以及一鍵還原。 本頁是版本控制介面的聚焦落地頁。防護欄引擎本身——規則類型、階段、動作——請從 防護欄總覽 或完整的 防護欄參考 開始。

​
1. 防護欄版本控制記錄什麼

對一個防護欄的每次變動——建立、更新、刪除與還原——都會在與變更相同的交易中寫入一筆僅追加的歷史列。該列擷取那一刻使用者可見設定的一個快照：
  • 防護欄的名稱，
  • 它是否已啟用，
  • 它是否是工作區預設值，
  • 完整的規則主體。
每一列都攜帶一個單調遞增的版本號（從 1 開始）、產生它的操作、作者，以及一個時間戳。由於該列是與編輯交易性地寫入的，歷史永遠不會與實際政策漂移失同步——如果編輯提交，它的歷史列也會提交。
歷史是僅追加的。一次還原不會倒帶或重寫過去的列；它會追加一個新版本（參見 §4）。你總是能依序看到誰做了什麼的完整序列。

​
2. 一個具體範例——找到壞編輯並回滾它

假設防護欄 42 已經漂移。你在自己工作階段上從主控台撰寫這一切——sk-orca-... 中繼金鑰只用於 /v1/* 呼叫，絕不用於讀取或變更政策。
1

列出歷史

在 /console/guardrails 中該防護欄列上開啟 History。動態是最新優先。你會看到 v5 update（週三，由一個隊友）、v4 update（週一，由你）、v3 update，依此類推回到 v1 create。讀取歷史對任何工作區 Member 開放。
2

比對可疑的變更

挑選夾住這次退步的兩個版本——v4 和 v5——並檢視比對。規則主體會並排顯示，所以被放寬的正規表示式會作為改變的那一行跳出來。
3

還原

還原 v4。實際防護欄的名稱、啟用旗標、預設旗標與規則會被設回那個快照，而一筆新鮮的 v6 revert 列會被追加。變更在下次請求時生效——無需重新部署，無需修改 SDK。還原需要 Developer+ 角色。
透過 REST API 的相同流程，全都在你的工作階段／存取權杖上（絕非中繼金鑰），透過 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}'
還原回應會傳回還原後的實際防護欄，這樣你的 UI 就能在不額外往返的情況下重新整理。下一個被此防護欄審查的 /v1/* 呼叫會看到已還原的政策。

​
3. 歷史、比對與版本動態

GET /api/guardrail/:id/history 傳回版本軌跡，最新優先。每個項目是一個快照，附上它的版本號、操作（create / update / delete / revert）、作者與時間戳。動態是工作區限定的——另一個工作區中的呼叫方會得到與遺失防護欄相同的 not-found 封包，所以存在性永不洩漏。
GET /api/guardrail/:id/history/:version 以版本號擷取一個快照——在你決定是否還原到某個時間點之前，用以檢查當時實際生效的確切規則主體很方便。
GET /api/guardrail/:id/history/diff?from=N&to=M 傳回兩個快照——from 和 to——這樣主控台就能渲染名稱、旗標與規則的並排比較。兩個版本都必須屬於你的工作區，否則呼叫會傳回統一的 not-found 封包。
讀取——歷史清單、單個版本與比對——對任何工作區 Member 開放。它們是純檢查：流量沒有任何改變，也不發出任何模型或廠商呼叫。

​
4. 還原會還原為一個新版本

一次還原不是倒帶。POST /api/guardrail/:id/revert 帶有一個 to_version 主體：
  1. 載入目標版本的快照。
  2. 把實際防護欄的名稱、啟用旗標、預設旗標與規則還原到那個快照——原子地，在一個交易中。
  3. 追加一筆新鮮的 revert 歷史列，擷取現在生效的狀態。
所以把 v5 還原回 v4 會產生一個內容等於 v4 的新 v6。你的歷史讀作 v1 → v2 → … → v5 → v6(revert)——每一步都被保留，沒有東西被變動。之後再次還原那個較舊的快照，你就得到一個 v7，依此類推。
一個被還原的已停用或非預設狀態會完整往返。如果你還原到的版本帶有 enabled: false 或不是工作區預設值，還原會把實際防護欄設回正好那樣——它不會靜默地讓政策保持開啟。先比對，這樣你就知道一次還原是否也會翻動那些旗標。
由於綁定關係存在於閘道上，一次還原會一次性切換綁定到此防護欄的每一把 API 金鑰——以及工作區預設值，如果這就是它的話——於下次呼叫。綁定如何解析請見 綁定到金鑰 和 工作區預設值。

​
5. 角色與保留

動作路由角色
列出／讀取版本、比對GET …/history、…/history/diff、…/history/:versionMember
還原到一個版本POST …/revertDeveloper+
所有歷史路由都是 /api/guardrail/*，並在 X-Workspace-Id 下以你的工作階段／存取權杖驗證——絕非一把 sk-orca-... 中繼金鑰。還原攜帶與建立或更新防護欄相同的 Developer+ 把關，因為它改變實際流量。
歷史保留每個防護欄最近 50 個版本。隨著你持續編輯，較舊的列會被自動修剪，所以一個健談的編輯迴圈工作流程永不會讓軌跡無界成長。清單端點傳回最新的最多 50 個，最新優先。
把版本控制與 先標記的調校 配對：把一條新規則以 flag 出貨，觀察 匹配動態，而如果它行為不當，在幾秒內比對與還原，而不必手動重建舊政策。

​
6. 下一步去哪裡

出貨前先測試與評測

在一個政策成為你必須還原的版本之前，在沙盒中與針對一個語料庫證明它。

調校誤報

版本控制讓其安全的先標記再晉升迴圈。

動作：block、mask、flag

一個版本生效後每條規則做什麼。

防護欄參考

完整引擎——規則類型、階段、預設與完整 API。
這裡的版本控制涵蓋防護欄內容政策。防火牆對工具政策有它自己的變更介面；關於這兩個強制執行層如何不同，參見 防護欄與防火牆。