跳转到主要内容
你在周一上线了一个更严格的 pii-shield 策略，一个队友在周三 放宽了一个正则，现在真实流量正抛出误报。你需要看到什么变了、 谁改的，并回滚——而不必猜测之前的 JSON 或重新部署任何东西。 那就是防护栏版本管理给你的：每次变更一条历史记录、任意 两个之间的 diff，以及一键回退。 本页是版本管理面的专注落地页。防护栏引擎本身——规则类型、 阶段、动作——从防护栏概览或 完整的防护栏参考开始。

​
1. 防护栏版本管理记录什么

对一个防护栏的每次变更——create、update、delete 和 revert——都会在与变更相同的事务中写入一条只追加的 历史记录。该记录捕获那一刻用户可见配置的一个快照：
  • 防护栏的 name，
  • 它是否已启用，
  • 它是否是工作区默认值，
  • 完整的 rules 主体。
每条记录都带有一个单调递增的 version 号（从 1 开始）、产生它 的 operation、author 和一个时间戳。由于该记录与编辑事务性 地一起写入，历史永远不会与实时策略失去同步——如果编辑提交， 它的历史记录也提交。
历史是只追加的。一次回退不会倒带或重写过去的记录；它追加 一个新版本（参见 §4）。你总是能 按顺序看到完整的谁做了什么的序列。

​
2. 一个具体示例——找出糟糕的编辑并回滚它

假设防护栏 42 已经漂移。你从你自己会话上的控制台编写这 一切——sk-orca-... 中继密钥只用于 /v1/* 调用，绝不用于读取或 更改策略。
1

列出历史

在 /console/guardrails 中防护栏行上打开 History。信息流 最新优先。你看到 v5 update（周三，由一个队友）、v4 update （周一，由你）、v3 update，依此类推回到 v1 create。读取历史 对任何工作区 Member 开放。
2

Diff 可疑的变更

选择夹住此次回归的两个版本——v4 和 v5——并查看 diff。规则 主体并排显示，因此被放宽的正则作为发生改变的那一行跳出来。
3

回退

恢复 v4。实时防护栏的名字、enabled 标志、default 标志和 规则被设回那个快照，并追加一条新的 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. 历史、diff 和版本信息流

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 信封。
读取——历史列表、单个版本和 diff——对任何工作区 Member 开放。 它们是纯检查：流量没有任何改变，也不发出模型或供应商调用。

​
4. 回退以新版本形式恢复

回退不是倒带。带 to_version 主体的 POST /api/guardrail/:id/revert：
  1. 加载目标版本的快照。
  2. 恢复实时防护栏的名字、enabled 标志、default 标志和规则到 那个快照——原子地，在一个事务中。
  3. 追加一条新的 revert 历史记录，捕获现在实时的状态。
所以把 v5 回退到 v4 会产生一个新的 v6，其内容等于 v4。 你的历史读作 v1 → v2 → … → v5 → v6(revert)——每一步都保留， 什么都不被修改。稍后再次回退那个更旧的快照，你会得到一个 v7， 依此类推。
一个被恢复的已禁用或非默认状态会完整往返。如果你回退到 的版本曾是 enabled: false 或不是工作区默认值，回退会把实时 防护栏设回正是那样——它不会静默地让策略保持开启。先 diff， 这样你就知道一次回退是否也会翻转那些标志。
由于绑定关系存在于网关上，一次回退会在下一次调用时一次性切换 绑定到这个防护栏的每个 API 密钥——以及工作区默认值，如果这 就是它。绑定如何解析见 绑定到密钥和 工作区默认值。

​
5. 角色与保留

操作路由角色
列出 / 读取版本，diffGET …/history、…/history/diff、…/history/:versionMember
回退到一个版本POST …/revertDeveloper+
所有历史路由都是 /api/guardrail/*，并在 X-Workspace-Id 下用 你的会话 / 访问令牌鉴权——绝不是 sk-orca-... 中继密钥。回退 带有与创建或更新一个防护栏相同的 Developer+ 门控，因为它改变 实时流量。
历史保留每个防护栏最近的 50 个版本。随着你继续编辑，更旧的 记录会被自动修剪，因此一个频繁的编辑循环工作流永远不会让轨迹 无界增长。列表端点返回至多最新的 50 个，最新优先。
把版本管理与先 flag 的调优 配对：把一个新规则作为 flag 上线，观察 matches 信息流，如果它行为 不当，几秒内就 diff 和回退，而不是手工重建旧策略。

​
6. 接下来去哪里

上线前测试与 eval

在它成为一个你不得不回退的版本之前，在沙箱中并针对一个 语料库证明一个策略。

调优误报

版本管理使其安全的先 flag、再晋级的循环。

动作：block、mask、flag

一旦一个版本实时，每条规则做什么。

防护栏参考

完整引擎——规则类型、阶段、预设，以及完整的 API。
这里的版本管理涵盖防护栏内容策略。防火墙对工具策略有它 自己的变更面；关于这两个执行层有何不同，参见 防护栏 vs. 防火墙。