메인 콘텐츠로 건너뛰기
월요일에 더 엄격한 pii-shield 정책을 출시했고, 수요일에 팀원이 정규식을 넓혔는데, 이제 실제 트래픽이 거짓 양성을 던집니다. 무엇이 바뀌었고, 누가 바꿨고, 롤백하는 것을 — 이전 JSON을 추측하거나 무언가를 재배포하지 않고 — 봐야 합니다. 그것이 guardrail 버전 관리가 주는 것입니다: 변경당 히스토리 행, 임의의 두 버전 사이의 diff, 그리고 원클릭 되돌리기. 이 페이지는 버전 관리 표면에 초점을 둔 랜딩입니다. guardrail 엔진 자체 — 규칙 타입, 스테이지, 액션 — 는 Guardrails 개요나 전체 Guardrails 레퍼런스에서 시작하세요.

​
1. guardrail 버전 관리가 기록하는 것

guardrail에 대한 모든 변경 — create, update, delete, revert — 은 변경과 동일한 트랜잭션에서 추가 전용 히스토리 행을 씁니다. 행은 그 순간 사용자에게 보이는 구성의 스냅샷을 캡처합니다:
  • guardrail 이름,
  • 활성화 여부,
  • 워크스페이스 기본값 여부,
  • 전체 rules 본문.
각 행은 단조 증가하는 버전 번호(​1에서 시작), 그것을 생성한 operation, 작성자, 그리고 타임스탬프를 운반합니다. 행이 편집과 트랜잭션으로 작성되므로, 히스토리는 라이브 정책과 결코 동기화가 어긋날 수 없습니다 — 편집이 커밋되면, 그 히스토리 행도 커밋됩니다.
히스토리는 추가 전용입니다. 되돌리기는 과거 행을 되감거나 재작성하지 않습니다; 새 버전을 추가합니다 (§4 참조). 항상 누가 무엇을 했는지의 완전한 시퀀스를 순서대로 봅니다.

​
2. 하나의 구체적인 예 — 나쁜 편집을 찾아 롤백하기

guardrail 42가 드리프트했다고 합시다. 이 모든 것을 당신의 세션에서 콘솔에서 작성합니다 — sk-orca-... 릴레이 키는 /v1/* 호출 전용이며, 정책을 읽거나 변경하는 데 결코 쓰이지 않습니다.
1

히스토리 나열

/console/guardrails의 guardrail 행에서 History를 엽니다. 피드는 최신순입니다. v5 update(수요일, 팀원에 의해), v4 update(월요일, 당신에 의해), v3 update 등 v1 create까지 보입니다. 히스토리 읽기는 모든 워크스페이스 Member에게 개방됩니다.
2

의심스러운 변경 diff

회귀를 괄호로 묶는 두 버전 — v4와 v5 — 를 선택하고 diff를 봅니다. rules 본문이 나란히 표시되므로, 넓혀진 정규식이 바뀐 줄로 두드러집니다.
3

되돌리기

v4를 복원합니다. 라이브 guardrail의 이름, 활성화 플래그, 기본값 플래그, 규칙이 그 스냅샷으로 되돌려지고, 새로운 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}'
되돌리기 응답은 되돌리기 후 라이브 guardrail을 반환하므로 당신의 UI가 추가 왕복 없이 새로 고칠 수 있습니다. 이 guardrail로 검사되는 다음 /v1/* 호출은 복원된 정책을 봅니다.

​
3. 히스토리, diff, 그리고 버전 피드

GET /api/guardrail/:id/history는 버전 추적을 최신순으로 반환합니다. 각 항목은 그 버전 번호, operation(create / update / delete / revert), 작성자, 그리고 타임스탬프가 있는 하나의 스냅샷입니다. 피드는 워크스페이스 범위입니다 — 다른 워크스페이스의 호출자는 누락된 guardrail과 동일한 not-found 봉투를 받으므로, 존재가 결코 유출되지 않습니다.
GET /api/guardrail/:id/history/:version은 버전 번호로 하나의 스냅샷을 가져옵니다 — 그것으로 되돌릴지 결정하기 전에 특정 시점에 라이브였던 정확한 rules 본문을 검사하는 데 편리합니다.
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. 라이브 guardrail의 이름, 활성화 플래그, 기본값 플래그, 규칙을 그 스냅샷으로 복원합니다 — 원자적으로, 하나의 트랜잭션에서.
  3. 이제 라이브인 상태를 캡처하는 새로운 revert 히스토리 행을 추가합니다.
따라서 v5를 v4로 되돌리면 그 내용이 v4와 같은 새 v6이 생성됩니다. 당신의 히스토리는 v1 → v2 → … → v5 → v6(revert)로 읽힙니다 — 모든 단계가 보존되고, 아무것도 변경되지 않습니다. 나중에 그 더 오래된 스냅샷을 다시 되돌리면 v7을 얻고, 이런 식입니다.
복원된 비활성화 또는 비기본값 상태는 그대로 왕복합니다. 되돌리는 버전이 enabled: false였거나 워크스페이스 기본값이 아니었다면, 되돌리기는 라이브 guardrail을 정확히 그것으로 되돌립니다 — 정책을 조용히 켜둔 채로 두지 않습니다. 되돌리기가 그 플래그도 전환할지 알도록 먼저 diff하세요.
바인딩이 게이트웨이에 존재하므로, 되돌리기는 이 guardrail에 연결된 모든 API 키를 — 그리고 이것이 그것이라면 워크스페이스 기본값을 — 다음 호출에서 한 번에 이동시킵니다. 연결이 어떻게 해석되는지는 키에 연결하기와 워크스페이스 기본값을 참조하세요.

​
5. 역할과 보존

액션라우트역할
버전 나열 / 읽기, diffGET …/history, …/history/diff, …/history/:versionMember
버전으로 되돌리기POST …/revertDeveloper+
모든 히스토리 라우트는 /api/guardrail/*이며 X-Workspace-Id 아래 당신의 세션 / 액세스 토큰으로 인증합니다 — 결코 sk-orca-... 릴레이 키가 아닙니다. 되돌리기는 라이브 트래픽을 변경하므로 guardrail을 생성하거나 업데이트하는 것과 동일한 Developer+ 게이트를 운반합니다.
히스토리는 guardrail당 가장 최근 50개 버전으로 보존됩니다. 더 오래된 행은 계속 편집하면서 자동으로 정리되므로, 수다스러운 편집 루프 워크플로가 추적을 무한히 키우지 않습니다. 목록 엔드포인트는 가장 최근 50개까지를 최신순으로 반환합니다.
버전 관리를 flag 우선 튜닝과 짝지으세요: 새 규칙을 flag로 출시하고, matches 피드를 지켜보고, 잘못 동작하면 이전 정책을 손으로 재구성하는 대신 몇 초 만에 diff하고 되돌리세요.

​
6. 다음으로 갈 곳

출시 전에 테스트 및 평가

되돌려야 할 버전이 되기 전에 샌드박스와 코퍼스에 대해 정책을 증명합니다.

거짓 양성 튜닝

버전 관리가 안전하게 만드는 flag 후 프로모트 루프.

액션: block, mask, flag

버전이 라이브가 되면 각 규칙이 무엇을 하는지.

Guardrails 레퍼런스

전체 엔진 — 규칙 타입, 스테이지, 프리셋, 그리고 완전한 API.
여기 버전 관리는 guardrail 콘텐츠 정책을 다룹니다. firewall은 툴 정책을 위한 자체 변경 표면을 가집니다; 두 강제 레이어가 어떻게 다른지는 guardrails vs. firewall을 참조하세요.