Chuyển đến nội dung chính
Bạn đã phát hành một chính sách pii-shield chặt hơn vào thứ Hai, một đồng đội mở rộng một regex vào thứ Tư, và giờ traffic thực đang ném ra dương tính giả. Bạn cần thấy cái gì đã thay đổi, ai đã thay đổi nó, và quay lui — mà không đoán JSON trước đó hoặc triển khai lại bất cứ thứ gì. Đó là cái versioning guardrail cho bạn: một hàng lịch sử cho mỗi thay đổi, một diff giữa bất kỳ hai cái nào, và revert một-cú-nhấp. Trang này là trang đích tập trung cho bề mặt versioning. Về bản thân engine guardrail — loại quy tắc, giai đoạn, hành động — bắt đầu tại Tổng quan Guardrails hoặc tài liệu tham khảo Guardrails đầy đủ.

​
1. Versioning guardrail ghi lại cái gì

Mỗi đột biến trên một guardrail — create, update, delete, và revert — viết một hàng lịch sử chỉ-thêm trong cùng transaction với thay đổi. Hàng bắt một snapshot của cấu hình người-dùng-thấy-được tại thời điểm đó:
  • name của guardrail,
  • liệu nó có được bật,
  • liệu nó có là mặc định workspace,
  • toàn bộ body rules.
Mỗi hàng mang một số version đơn điệu (bắt đầu ở 1), operation đã tạo ra nó, tác giả, và một dấu thời gian. Vì hàng được viết theo transaction với chỉnh sửa, lịch sử không bao giờ có thể trôi lệch khỏi chính sách trực tiếp — nếu chỉnh sửa commit, thì hàng lịch sử của nó cũng vậy.
Lịch sử là chỉ-thêm. Một revert không tua lại hoặc viết lại các hàng quá khứ; nó thêm một phiên bản mới (xem §4). Bạn luôn thấy chuỗi hoàn chỉnh ai đã làm gì, theo thứ tự.

​
2. Một ví dụ cụ thể — tìm chỉnh sửa tồi và quay lui nó

Giả sử guardrail 42 đã trôi lệch. Bạn soạn tất cả điều này từ console trên phiên của riêng bạn — relay key sk-orca-... chỉ dùng cho các cuộc gọi /v1/*, không bao giờ để đọc hoặc thay đổi chính sách.
1

Liệt kê lịch sử

Mở History trên hàng guardrail trong /console/guardrails. Feed là mới-nhất-trước. Bạn thấy v5 update (thứ Tư, bởi một đồng đội), v4 update (thứ Hai, bởi bạn), v3 update, v.v. trở về v1 create. Đọc lịch sử mở cho bất kỳ Member workspace nào.
2

Diff thay đổi đáng ngờ

Chọn hai phiên bản kẹp regression — v4 và v5 — và xem diff. Body rules được hiển thị cạnh nhau, nên regex được mở rộng nhảy ra như dòng đã thay đổi.
3

Revert

Khôi phục v4. Name, cờ enabled, cờ default, và rules của guardrail trực tiếp được đặt lại về snapshot đó, và một hàng v6 revert mới được thêm. Thay đổi trực tiếp ở request kế tiếp — không triển khai lại, không đổi SDK. Revert yêu cầu vai trò Developer+.
Cùng luồng qua REST API, tất cả trên session / access token của bạn (không bao giờ relay key), theo phạm vi workspace qua 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}'
Phản hồi revert trả về guardrail trực tiếp sau-revert để UI của bạn có thể làm mới mà không có một round-trip thêm. Cuộc gọi /v1/* kế tiếp được sàng lọc bởi guardrail này thấy chính sách đã khôi phục.

​
3. Lịch sử, diff, và feed phiên bản

GET /api/guardrail/:id/history trả về dấu vết phiên bản, mới nhất trước. Mỗi mục là một snapshot với số phiên bản, operation (create / update / delete / revert), tác giả, và dấu thời gian. Feed theo phạm vi workspace — một người gọi trong một workspace khác nhận cùng envelope not-found như một guardrail thiếu, nên sự tồn tại không bao giờ rò rỉ.
GET /api/guardrail/:id/history/:version lấy một snapshot theo số phiên bản của nó — tiện để kiểm tra body rules chính xác đã trực tiếp tại một thời điểm trước khi bạn quyết định có revert về nó hay không.
GET /api/guardrail/:id/history/diff?from=N&to=M trả về cả hai snapshot — from và to — để console có thể render một so sánh cạnh nhau của name, cờ, và rules. Cả hai phiên bản phải thuộc workspace của bạn, hoặc cuộc gọi trả về envelope not-found đồng nhất.
Các thao tác đọc — liệt kê lịch sử, phiên bản đơn, và diff — mở cho bất kỳ Member workspace nào. Chúng là kiểm tra thuần: không gì về traffic thay đổi, và không có cuộc gọi mô hình hay vendor nào được thực hiện.

​
4. Revert khôi phục như một phiên bản mới

Một revert không phải một tua lại. POST /api/guardrail/:id/revert với một body to_version:
  1. Nạp snapshot của phiên bản đích.
  2. Khôi phục name, cờ enabled, cờ default, và rules của guardrail trực tiếp về snapshot đó — nguyên tử, trong một transaction.
  3. Thêm một hàng lịch sử revert mới bắt trạng thái nay-trực-tiếp.
Nên revert v5 về v4 tạo ra một v6 mới mà nội dung bằng v4. Lịch sử của bạn đọc v1 → v2 → … → v5 → v6(revert) — mỗi bước được giữ, không gì bị thay đổi. Revert snapshot cũ đó lần nữa sau và bạn nhận một v7, v.v.
Một trạng thái disabled hoặc non-default được khôi phục round-trip nguyên vẹn. Nếu phiên bản bạn revert về có enabled: false hoặc không phải mặc định workspace, revert đặt guardrail trực tiếp lại về chính xác điều đó — nó không âm thầm giữ chính sách bật. Diff trước để bạn biết liệu một revert có cũng lật các cờ đó.
Vì liên kết nằm ở gateway, một revert dịch chuyển mọi API key được gắn vào guardrail này cùng lúc — và mặc định workspace, nếu đây là nó — ở lần gọi kế tiếp. Xem gắn vào một key và mặc định workspace cho cách liên kết phân giải.

​
5. Vai trò và lưu giữ

Hành độngRouteVai trò
Liệt kê / đọc phiên bản, diffGET …/history, …/history/diff, …/history/:versionMember
Revert về một phiên bảnPOST …/revertDeveloper+
Tất cả route lịch sử là /api/guardrail/* và xác thực với session / access token của bạn dưới X-Workspace-Id — không bao giờ một relay key sk-orca-.... Revert mang cùng gate Developer+ như tạo hoặc cập nhật một guardrail, vì nó thay đổi traffic trực tiếp.
Lịch sử được lưu giữ ở 50 phiên bản gần nhất cho mỗi guardrail. Các hàng cũ hơn được tỉa tự động khi bạn tiếp tục chỉnh sửa, nên một workflow vòng-lặp-chỉnh-sửa lắm lời không bao giờ làm dấu vết tăng không giới hạn. Endpoint danh sách trả về tới 50 cái mới nhất, mới nhất trước.
Ghép versioning với tinh chỉnh flag-trước: phát hành một quy tắc mới dưới dạng flag, theo dõi matches feed, và nếu nó hành xử tồi, diff và revert trong vài giây thay vì tái dựng chính sách cũ bằng tay.

​
6. Đi đâu tiếp theo

Test & eval trước khi bạn phát hành

Chứng minh một chính sách trong sandbox và đối với một corpus trước khi nó trở thành một phiên bản bạn sẽ phải revert.

Tinh chỉnh dương tính giả

Vòng lặp flag-rồi-thăng-cấp mà versioning làm an toàn.

Hành động: block, mask, flag

Mỗi quy tắc làm gì khi một phiên bản trực tiếp.

Tài liệu tham khảo Guardrails

Engine đầy đủ — loại quy tắc, giai đoạn, preset, và API hoàn chỉnh.
Versioning ở đây bao quát chính sách nội dung guardrail. Firewall có bề mặt thay đổi riêng của nó cho chính sách tool; về cách hai lớp thực thi khác nhau, xem guardrails so với firewall.