lore-hex/quill-router안전한 LLM 프록시를 위한 TrustedRouter.com 저장소
# TrustedRouter
[](https://github.com/Lore-Hex/quill-router/actions/workflows/ci.yml)
[](https://github.com/Lore-Hex/quill-router/actions/workflows/deploy.yml)
[](https://github.com/Lore-Hex/quill-router/actions/workflows/prod-smoke.yml)
[](https://github.com/Lore-Hex/quill-router/actions/workflows/trust-drift.yml)
[](https://status.trustedrouter.com)
[](https://trust.trustedrouter.com)
[](https://www.npmjs.com/package/@lore-hex/trusted-router)
[](https://pypi.org/project/trusted-router-py/)
[](LICENSE)
# 종단 간 암호화된 LLM. 하나의 API. 증명이 있는 프라이버시.
누가 당신의 프롬프트를 볼 수 있는지 걱정하지 마세요. 코딩 에이전트에게 프로젝트를
이전하라고 지시하고, 원하는 프라이버시 수준을 선택하고, 모델을 고르고, 키를 넣으면
끝입니다. 동일한 API, 30개 이상의 모델, 하나의 키. 게이트웨이는 하드웨어
엔클레이브에서 실행되며, 절대 로그를 남기지 않는다는 것을 암호학적으로 검증할 수 있습니다.
### 하나의 프롬프트로 프로젝트 이전하기
Codex, Claude Code, 또는 Cursor에 이것을 붙여넣으세요 — 마이그레이션을 대신 해줍니다:
```text
Migrate this project to TrustedRouter, a privacy-first LLM router
(https://trustedrouter.com). Repoint my LLM client to base_url
"https://api.trustedrouter.com/v1" (or "https://api.trustedrouter.com" for the
Anthropic SDK), read the key from the TRUSTEDROUTER_API_KEY env var, and keep
all my existing calls working.
For a hard provider-side confidential-compute and end-to-end-encryption
requirement, add {"provider": {"min_privacy": "confidential"}}. TrustedRouter
fails closed when the selected model or provider cannot satisfy both controls.
Then tell me to sign up at trustedrouter.com, add a card, and paste my sk-tr
key into TRUSTEDROUTER_API_KEY.
```
그런 다음:
1. **개인정보 보호 수준 또는 지역을 선택하세요** — 하드 제로 보존 하한선에는
`{"provider": {"min_privacy": "zdr"}}`를 사용하거나, 더 강력한 하드
기밀 컴퓨팅 + E2EE 하한선에는
`{"provider": {"min_privacy": "confidential"}}`를 사용하세요. 편리한 `trustedrouter/zdr` 및
`trustedrouter/e2e` (`trustedrouter/confidential`) 별칭이 해당
풀을 선택합니다. EU 중심 라우팅에는
`https://api-europe-west4.quillrouter.com/v1`과 함께 `trustedrouter/eu`를 사용하세요.
2. **모델을 선택하세요** — 수백 가지 중 하나를 선택하거나, 가장 엄격한 개인정보 보호
필터보다 공급자 폭이 더 중요할 때 자동
폴백을 위해 `trustedrouter/auto`를 사용하세요.
3. **가입하고, 카드를 추가하고, 키를 받으세요** — https://trustedrouter.com 에서.
4. **배포하세요** — 이제 프롬프트가 검증 가능한 경로를 통해 실행됩니다.
<details>
<summary>직접 연결하는 것을 선호하시나요?</summary>
```bash
# Codex
export OPENAI_BASE_URL="https://api.trustedrouter.com/v1"
export OPENAI_API_KEY="sk-tr-v1-..."
# Claude Code
export ANTHROPIC_BASE_URL="https://api.trustedrouter.com"
export ANTHROPIC_API_KEY="sk-tr-v1-..."
```
```python
# Any OpenAI SDK
client = OpenAI(base_url="https://api.trustedrouter.com/v1", api_key="sk-tr-v1-...")
```
</details>
- **키 발급 / 후원하기:** https://trustedrouter.com
- **먼저 사용해 보기 (가입 불필요):** https://trustedrouter.com/chat
- **기술적 세부 사항 (전문가용):** https://trustedrouter.com/security
- **이미지 생성:** [docs/image-generation.md](https://github.com/lore-hex/quill-router/blob/main/docs/image-generation.md)
- **비디오 생성:** [docs/video-generation.md](https://github.com/lore-hex/quill-router/blob/main/docs/video-generation.md)
- **개발 동기:** https://jperla.com/blog/attestation-is-all-you-need
---
<details>
<summary><strong>전문가용: 프라이버시가 어떻게 증명 가능한가</strong></summary>
TrustedRouter의 게이트웨이는 GCP Confidential Space 내에서 실행됩니다. 플랫폼은
실행 중인 컨테이너의 측정값에 서명합니다. 서명된 증거를 검증하고
그 이미지 다이제스트를 공개된 릴리스 측정값과 비교하십시오. 소스 검토와
릴리스 빌드 출처(provenance)는 해당 측정된 이미지가 무엇을 하는지 입증합니다.
다이제스트가 일치한다는 것만으로는 버그나 로깅의 부재를 증명하지 못합니다.
계정 없이 GCP 증거를 확인하십시오:
```bash
NONCE=$(openssl rand -hex 16)
curl --fail --silent --show-error \
"https://api-us-central1.quillrouter.com/attestation?nonce=$NONCE" \
--output attestation.jwt
# GCP returns a raw Google-signed JWT, not a JSON response.
# Decoded claims include eat_nonce and submods.container.image_digest.
# GCP evidence has no pcrs field; PCRs belong to AWS Nitro evidence.
```
JWT를 저장하거나 디코딩하는 것은 **검증이 아닙니다**. 발급자/서명, 신선한 nonce, TLS 인증서/exporter 바인딩, 그리고 예상되는 릴리스 측정값을 검증하려면 검토된 `quill-cloud-proxy` 체크아웃에서
[attestation verifier](https://github.com/Lore-Hex/quill-cloud-proxy/blob/main/tools/verify-attestation.py)를 사용하십시오.
GCP 엔드포인트의 경우 해당 체크아웃에서 다음을 실행하십시오:
```bash
DIGESTS=$(curl --fail --silent --show-error \
https://trust.trustedrouter.com/trust/accepted-image-digests-gcp.txt)
test -n "$DIGESTS" && uv run --script tools/verify-attestation.py \
--api-host api-us-central1.quillrouter.com --expect-digest "$DIGESTS"
```
검증기는 자신이 검증하는 TLS 연결에서 최신 증거를 가져옵니다. 해당 검사는 이후의 별도 `curl` 또는 SDK 연결을 증명하지 않습니다. 이 예제들은 GCP 증거 형식을 선택하기 위해 공개된 US Central GCP 호스트명을 사용합니다. 글로벌 엔드포인트는 다른 클라우드를 선택할 수 있습니다. 해당 클라우드별 검증 정책과 측정값을 [신뢰 사이트](https://trust.trustedrouter.com/)에서 사용하십시오.
| | 신뢰 모델 |
|---|---|
| OpenRouter, 호스팅 제공업체 | "우리는 로그를 남기지 않습니다." 확인할 수 없는 정책. |
| Portkey, Cloudflare AI Gateway | 관측성을 위해 모든 것을 로그로 남깁니다. |
| LiteLLM | 자체 호스팅이지만, 실행 중인 프록시는 검증되지 않습니다. |
| **TrustedRouter** | **오픈 소스 + 하드웨어 증명. 코드 경로를 검증하십시오. 아무것도 로그로 남기지 않습니다.** |
솔직한 범위: 증명은 실행 중인 바이너리가 게시된 바이너리이며, 논스로 챌린지할 수 있는 하드웨어에서 실행되고 있음을 입증합니다. 이는 물리적 호스트 접근 권한을 가진 국가 행위자를 막지 못하며, 오픈 소스 바이너리에 버그가 없음을 증명하지도 않습니다. 신뢰 앵커는 Google Confidential Computing의 하드웨어 기반 증명 체인입니다. 업스트림 제공업체는 자체 정책에 따라 프롬프트를 처리합니다. 각 제공업체의 입장은 모델 페이지에 게시되어 있습니다.
</details>
---
## 저장소 레이아웃
이 저장소는 컨트롤 플레인 계약을 구현합니다: 라우트 커버리지, 인증/키 관리, 청구 원장 의미론, 사용 메타데이터, 프롬프트/출력 로깅 금지, Sentry 스크러버, 그리고 제공업체 추상화. 증명된 게이트웨이 구현은 `quill-cloud-proxy`에 있습니다.
신뢰 경계: `api.trustedrouter.com`은 증명된 프롬프트 경로이며 Confidential Space 내부에서 TLS를 종료해야 합니다. `trustedrouter.com`은 컨트롤 플레인이며 프로덕션 추론 폴백을 절대 제공해서는 안 됩니다.
`api.quillrouter.com`은 영구적인 작동 별칭(동일한 증명된 게이트웨이 및 인증서)으로 남아 있으므로, 기존 통합은 마이그레이션 없이 계속 작동합니다.
## 로컬
```bash
uv sync
uv run pytest
uv run uvicorn trusted_router.main:app --reload
```
실행 중인 인스턴스에 대한 엔드투엔드 스모크 테스트:
```bash
TR_SMOKE_BASE_URL=http://127.0.0.1:18080/v1 uv run python scripts/smoke_e2e.py
```
프로덕션 환경에서는 `TR_SMOKE_BASE_URL=https://api.trustedrouter.com/v1`을 설정하고, 내부 게이트웨이 라우트가 토큰으로 보호되는 경우 `TR_SMOKE_INTERNAL_TOKEN`을 설정하세요.
로컬 운영자/프로바이더 키는 다음 위치에 설정하세요:
```text
/Users/jperla/claude/.quill_cloud_keys.private
```
해당 파일은 절대 커밋되지 않습니다. dotenv 형식일 것으로 예상됩니다:
```text
ANTHROPIC_API_KEY=...
OPENAI_API_KEY=...
GEMINI_API_KEY=...
CEREBRAS_API_KEY=...
DEEPSEEK_API_KEY=...
MISTRAL_API_KEY=...
STRIPE_SECRET_KEY=...
STRIPE_WEBHOOK_SECRET=...
SENTRY_DSN=...
```
배포 스크립트는 일부 운영자 파일에서 이미 사용 중인 로컬 별칭도 허용합니다: Anthropic의 경우 `CLAUDE_API_KEY`, OpenAI의 경우 `CHATGPT_API_KEY`, 그리고 `STRIPE_SECRET_KEY`의 경우 `STRIPE_KEY`입니다.
Vertex는 다른 제공자 플랫폼과 다릅니다: 프로덕션 GCP 배포는 Cloud Run 또는 Confidential Space 서비스 계정과 메타데이터/ADC에서 발급된 단기 Google 액세스 토큰을 사용합니다. 자사 선불 Vertex 경로의 경우 이 파일에 장기 수명의 Vertex 키를 넣지 마십시오. 대신 런타임 서비스 계정에 Vertex 권한을 부여하십시오.
## 라이선스
Business Source License 1.1. 소스는 공개되어 있으므로 누구나 TrustedRouter의 프라이버시 및 증명(attestation) 주장(https://trust.trustedrouter.com) 뒤에 있는 정확한 코드를 읽고, 빌드하고, 검증할 수 있습니다 — 그것이 이 코드가 여기 있는 이유입니다. 비프로덕션 사용(보안 검토, 감사, 로컬 평가)은 무료입니다. 프로덕션 사용에는 Lore Hex Corp의 상용 라이선스가 필요합니다: [email protected]. 각 버전은 공개 후 4년이 지나면 Apache License 2.0으로 전환됩니다. 2026년 7월 3일 이전에 공개된 코드는 Apache-2.0으로 유지됩니다.
## 보안 기본값
- 프롬프트 및 출력 콘텐츠는 절대 기록되지 않습니다. 일반적인 동기 및 스트리밍 추론은 이를 보존하지 않습니다. 옵트인 Batch API는 엔클레이브로 암호화된 아티팩트를 최대 30일 동안 일시적으로 보존합니다.
- 사용 로그에는 메타데이터만 포함됩니다.
- API 키는 불투명한 키 ID와 함께 솔트 처리된 SHA-256 해시로 저장됩니다.
- 사용자가 제출한 BYOK 제공자 키는 키마다 Secret Manager 객체 하나가 아니라 봉투 암호화된(envelope-encrypted) 암호문 행으로 저장됩니다. 프로덕션에서는 Cloud KMS가 키별 DEK를 래핑하며, 외부 `env://...` 참조는 운영자 관리 키에 대해 계속 지원됩니다.
- 게이트웨이 인증에는 암호화된 BYOK 봉투를 위한 비밀이 아닌 `byok_cache_key`가 포함됩니다. 증명된 게이트웨이는 이를 짧은 TTL의 메모리 전용 복호화 키 캐싱에 사용합니다. BYOK 교체는 키를 변경하며, 삭제 시 봉투 반환이 중단됩니다.
- BYOK 원시 키는 일회성 입력 전용입니다. 공개/컨트롤 플레인 응답은 짧은 첫/마지막 키 힌트와 암호화된 참조 메타데이터만 노출하며, 평문은 절대 노출하지 않습니다.
- 프로덕션 구성은 내부 게이트웨이 토큰, 서명된 Stripe 웹훅 시크릿, 그리고 비메모리 스토리지 백엔드가 없으면 폐쇄적으로 실패(fail closed)합니다.
- 프로덕션 컨트롤 플레인 앱은 `/chat/completions`, `/messages`, `/responses`, `/embeddings`를 등록하지 않습니다. 이들은 증명된 API 플레인에 속합니다.
- Sentry는 컨트롤 플레인 전용이며 요청 본문, 인증 헤더, API 키, BYOK 키, 프롬프트 메시지, 출력 텍스트를 스크러빙합니다. 클라이언트 측 Sentry 플러드 게이트는 지문(fingerprint)당 반복되는 이슈와 프로세스/윈도우당 총 이벤트 수를 제한하여, 하나의 시끄러운 통합이 전체 오류 예산을 다시 소진하지 못하도록 합니다.
- 증명된 엔클레이브에는 어떤 Sentry 구성도 속하지 않습니다.
## Broadcast 관측성
워크스페이스 소유자는 `/v1/broadcast/destinations`에서 또는 콘솔의 Broadcast 아래에서 Broadcast 대상을 구성할 수 있습니다. 지원되는 대상은 PostHog와 OTLP JSON 웹훅입니다. Broadcast는 기본적으로 메타데이터 전용입니다: 모델, 제공자, 토큰 수, 지연 시간, 비용, 경로 유형, 리전, 사용자 정의 트레이스 메타데이터. 프롬프트/출력 콘텐츠는 대상이 `include_content`를 명시적으로 활성화한 경우에만 내보내집니다. 콘텐츠가 활성화된 이러한 암호화된 대상은 일반 관리 응답이 아니라 증명된 게이트웨이에만 반환됩니다. 메타데이터 전용 전달은 먼저 영구 Broadcast 아웃박스에 기록되고 `/internal/broadcast/drain`에 의해 비동기적으로 처리되므로, PostHog/웹훅 장애가 추론을 차단하거나 프로세스 재시작 시 이미 정산된 메타데이터를 잃지 않습니다.
## 고정 라우팅 티어
이 별칭들은 명시적으로 순서가 지정된 모델 풀을 사용합니다: 첫 번째 멤버가 선호되며 나머지는 폴백입니다. 이들은 시도당 하나의 모델을 실행하며, 합성, 오케스트레이션, 암묵적 프라이버시 하한이 없습니다. 필요할 때 `provider.min_privacy`를 명시적으로 설정하십시오. 라이브 `/v1/models` 카탈로그는 각 풀을 `auto_candidates`에 게시합니다.
- `trustedrouter/frontier`: 고정 프런티어 모델 풀.
- `trustedrouter/advanced`: 고정 고급 모델 풀.
- `trustedrouter/professional`: 고정 전문가 모델 풀.
- `trustedrouter/efficient`: 고정 효율 모델 풀.
## 합성 모니터링
TrustedRouter는 공개 가동 시간을 위한 별도의 합성 모니터링 플레인을 갖추고 있습니다.
합성 워커는 엔클레이브 외부에서 실행되며, 공개 증명된 API로 작은 실제 요청을 보내고
메타데이터만 저장합니다. 모니터 모델 별칭은 다음과 같습니다:
- `trustedrouter/free`: OpenRouter 스타일 무료 풀. 사용자에게 유용하지만
SLA 신호는 아닙니다.
- `trustedrouter/cheap`: 공급자 다양성을 갖춘 최저가 유료 풀.
- `trustedrouter/eu`: EU 중심 공급자 풀. 유럽, EU 지역화 가능, 프라이버시 우선
공급자를 선호하며, 특히 `https://api-europe-west4.quillrouter.com/v1`과 함께
사용할 때 그렇습니다. 이는 라우팅 정책이며, 포괄적인 데이터 상주 보장은
아닙니다.
- `trustedrouter/monitor`: PONG 및 폴백 검사를 위한 내부 가동 시간 풀.
투명성을 위해 카탈로그에 표시되지만, 권한 부여에는 구성된
`TR_SYNTHETIC_MONITOR_API_KEY`가 필요하며, 일반 API 키는 403을 받습니다.
워커는 `us-central1` 및 `europe-west4`에서 실행되어야 하며, 하드 지출 한도와
자동 충전이 설정된 전용 `trustedrouter-synthetic-monitoring` 워크스페이스/키를
사용해야 합니다. 원시 샘플은 추가 전용 Bigtable 행이며, 공개 상태 페이지는
`/status`, `/status.json`, `/status/history?window=5m|24h|daily`에서 노출되는
압축 롤업을 읽습니다. 합성 생성은 `TrustedRouter Synthetic` 앱 레이블을 사용하며
고객/앱 분석에서 제외됩니다.
모든 모니터 호출은 또한 `stream: true` 채팅 완성을 수행하며, SSE 데이터 이벤트,
터미널 청크, `[DONE]`을 수신하지 못하면 실패합니다. 반복되는 Stage D 작업은
`--expect-stage-d`를 추가한 다음, 해당 요청의 타입 지정된 권한 부여를 조회하고
바인딩된 `stage_d_boot_kid`와 `heartbeat_seq > 0`을 요구합니다. 해당 워크스페이스는
의도적으로 분리되어 있습니다: `scripts/provision_stage_d_probe_workspace.py`로
프로비저닝하고 그 id를 `TR_STAGE_D_PILOT_WORKSPACE_IDS`에 추가하십시오. 키는
하트비트를 지원하는 로컬 타입 지정 키여야 하며, 배포는 이를
`trustedrouter-stage-d-probe-api-key`에서 읽고 `trustedrouter/cheap`을 사용하므로
일반 모니터 전용 키와 독립적입니다. 일반 롤아웃은 Stage D 자격을 비활성화된
상태로 두므로, 키를 생성하는 것만으로는 Stage D가 활성화되지 않습니다.
공급자 측정은 두 가지 독립적인 프로브 클래스를 사용합니다:
- 짧은 PONG 프로브는 전체 활성 카탈로그를 무작위로 커버하며 가동 시간,
TTFB, TTFT, 업스트림 API 드리프트를 측정합니다.
- 지속적인 512토큰 스트림은 `us-central1`에서 결정적 순환으로 가장 중요한
200개의 공급자/모델 경로를 커버합니다. 첫 토큰 이후의 초당 출력 토큰 수를
측정합니다. 별도의 Cloud Run Job에서 실행되므로 느린 스트림이 가동 시간
프로브를 지연시킬 수 없습니다. 장기 프로브 실패는 공급자 가동 시간이나
API 드리프트 경고에 절대 반영되지 않습니다.
현재의 2분 주기는 각 지속 경로에 주당 약 25개의 샘플과 30일당 108개의 샘플을
제공합니다. CI는 라이브 카탈로그로부터 최대 용량 지출 추정치를 계산하고,
검토된 월간 상한을 초과하면 실패합니다.
상태는 두 가지 서비스 SLO 클래스를 업스트림 공급자 동작과 혼합하지 않고
분리합니다:
- `router_core`: 증명된 API에 도달 가능하고, 키 권한 부여가 작동하며, 경로
후보/폴백이 사용 가능하고, 정산/환불이 내구성을 갖춥니다.
- `control_plane`: 대시보드, 청구 UI, 키, 크레딧, 문서, 신뢰, 상태 표면.
배포 워치독과 내부 소진율 경고는 기본적으로 `router_core`를 사용합니다.
공급자 전용 실패는 `/status`와 `/leaderboard`에서 공급자별로 측정되며, 폴백이
사용 가능한 경우 라우터 코어 오류 예산을 소비하지 않습니다.
## 공개 포지셔닝
- 가격 책정: 선불 및 BYOK 사용량은 부동 소수점 달러가 아닌 정수 마이크로달러로 추적되므로, 아주 작은 토큰 비용도 원장에서 감사 가능한 상태로 유지됩니다.
- 가동 시간 목표: `trustedrouter/auto`는 로컬/테스트 컨트롤 플레인 추론에서 실제 채팅 모델 별칭이며, 업스트림 제공자 장애 시 다음으로 구성된 제공자로 롤오버됩니다. `trustedrouter/eu`는 EU 중심 제공자 풀을 선호하고, `trustedrouter/zdr`는 Anthropic을 최우선으로 하는 제로 보존 제공자 하한을 강제하며, `trustedrouter/e2e`는 Tinfoil을 최우선으로 하는 기밀 + E2EE 경로를 강제합니다. 채팅 요청은 또한 OpenRouter 스타일의 `models` 및 `provider` 라우팅 필터(`order`, `only`, `ignore`, `allow_fallbacks`, `min_privacy`, `data_collection`, `sort`, `max_price`, `require_parameters`, `zdr`)를 준수하므로, 클라이언트는 명시적인 폴백 체인이나 제공자 선호를 요청할 수 있습니다. `provider.order`는 폴백이 활성화된 상태에서는 선호 사항이며, 목록에 없는 제공자도 선호 목록 이후에 자격을 유지합니다. `allow_fallbacks=false`인 경우 라우팅은 정렬된 제공자 집합으로 제한되며 그중 첫 번째 사용 가능한 경로만 승인됩니다. `provider.only`는 항상 하드 제공자 허용 목록입니다. 요청 최상위 수준에서 또는 `provider.allow_fallbacks`로 `allow_fallbacks=false`를 설정하면 다른 모델로의 대체도 방지됩니다. `min_privacy="confidential"`은 제공자 측의 하드 기밀 컴퓨팅 + E2EE 요구 사항이며 실패 시 닫힙니다(fail closed). 요청 값 별칭인 `e2e`와 `e2ee`는 더 약한 경로로 폴백하지 않고 동일한 등급을 선택합니다. 알 수 없는 요청 또는 제공자 옵션은 정확한 필드 이름과 함께 `400`을 반환합니다. 인식되지만 구현되지 않은 OpenRouter 제어는 안정적인 `501 not_supported_in_alpha`를 반환하며, 라우터의 무시(no-op)로 절대 수용되지 않습니다.
- 청구: 선불 크레딧 및 BYOK 우선; 구독은 필요하지 않습니다.
- 신뢰: 호스팅된 오픈 소스이며, 실행 중인 API의 소스 커밋, 이미지 참조, 이미지 다이제스트, 증명 정책이 `trust.trustedrouter.com`에 게시됩니다.
- 가입: 이메일 가입은 워크스페이스용 일회성 관리 키를 생성합니다.
- 지갑/암호화폐: 스테이블코인 결제는 요청 시 Stripe Checkout의 Crypto 결제 수단을 통해 연결됩니다. 카드/기본 Checkout이 기본 경로로 유지됩니다.
## 규모 목표
목표는 OpenRouter급 규모를 지원하는 것입니다:
- 하루 1조 토큰, 즉 하루 평균 약 초당 1,160만 토큰.
- 100만~400만 개발자 계정.
- 300개 이상의 활성 라우팅 가능 모델.
- 60개 이상의 제공자.
- 엣지 배포 라우터와 경쟁력 있는 글로벌 라우팅 오버헤드.
현재 프로덕션 배포는 아직 그 목표를 충족하지 **못합니다**. 컨트롤 플레인을 글로벌 LB 뒤의 4개 GCP 리전에서 리전별 Serverless NEG와 함께 실행하며, 4개의 라이브 증명 API 리전을 운영합니다. 더 많은 증명 풀이 온라인화됨에 따라 용량은 수평적으로 확장되며, 정확성, 신뢰, 청구, SDK 호환성은 정상 상태(steady-state)입니다.
요청량은 평균 생성 크기에 크게 의존합니다. 하루 1조 토큰 기준:
| 평균 토큰/요청 | 요청/일 | 평균 요청 속도 |
| ---: | ---: | ---: |
| 1,000 | 10억 | 11.6k rps |
| 2,500 | 4억 | 4.6k rps |
| 10,000 | 1억 | 1.2k rps |
아키텍처는 이 규모로 진화할 수 있지만, 핫 경로가 요청별 글로벌 병목을 피해야만 가능합니다. 즉 리전별 무상태 게이트웨이 플릿, 리전별 제공자 풀, 샤딩된 할당량 임대, 추가 전용(append-only) 메타데이터 쓰기, 비동기 집계가 필요합니다.
## 현재 지연 시간
2026년 5월 2일 이 개발 머신에서 중앙 집중식 GCP `us-central1` 증명 API까지 측정:
| 프로브 | p50 | p95 | 비고 |
| --- | ---: | ---: | --- |
| 인증되지 않은 `/v1/chat/completions` 거부 | 174 ms | 184 ms | DNS, TCP, 공개 TLS, 엔클레이브 요청 처리를 포함. |
| TCP 연결 | 55 ms | 59 ms | 이 머신에서 `us-central1`까지의 네트워크 경로. |
| TLS 핸드셰이크 완료 | 112 ms | 124 ms | 공개 ACME 인증서가 엔클레이브 내부에서 종료됨. |
| `/attestation` | 1.06 s | 1.12 s | GCP 증명 토큰 생성을 포함하므로 일반 라우팅 오버헤드를 대표하지 않음. |
중앙 집중식 네트워크 오버헤드는 OpenRouter가 보고한 엣지 오버헤드보다 훨씬 높지만, 모델 지연 시간이 보통 대화형 요청을 지배합니다. 첫 번째 프로덕션 확장 단계는 즉시 맞춤형 글로벌 엣지를 구축하는 것이 아니라 멀티 리전으로 가는 것이어야 합니다.
## 수평 확장 형태
프로덕션 경로는 프롬프트 게이트웨이를 무상태로 유지하여 확장하도록 설계되었습니다:
- `api.trustedrouter.com` 인스턴스는 TCP 패스스루 뒤에서 복제될 수 있습니다. 이들은 제어 플레인을 통해 인가, 예약, 정산하지만, 프롬프트 바이트는 증명된 경로를 벗어나지 않습니다.
- Spanner는 강력한 일관성을 가진 제어 플레인 및 청구 상태를 저장합니다: 사용자, 워크스페이스, 키, BYOK 메타데이터, 결제 이벤트 멱등성, 잔액, 집계, 활성 예약, 그리고 30일 종료 요청 감사 기간.
- Bigtable은 워크스페이스와 날짜를 키로 하는 제한된 고용량 활동 메타데이터를 저장합니다. 활동 및 제공자 벤치마크는 30일, 원시 합성 샘플은 14일, 압축 상태 롤업은 24개월 동안 보존됩니다. 프롬프트, 출력, 도구 호출 인자는 저장되지 않습니다.
- API 키 검증은 포인트 읽기를 위해 고엔트로피 조회 해시를 사용하며, 키를 스캔하지 않습니다.
- 속도 제한은 라우트 핸들러 이전에 적용되며 구성된 저장소를 사용하므로, 프로덕션 카운터는 Cloud Run 인스턴스 간에 공유됩니다.
OpenRouter 규모의 트래픽에서 다음 병목은 엔클레이브 바이너리가 아니라 동기식 청구/인가 경로입니다. 아키텍처는 공개 트래픽이 증가하도록 허용되기 전에 샤딩된 예약, 리전별 Bigtable 클러스터, Cloud Armor 엣지 제한, 그리고 여러 게이트웨이 복제본이 필요합니다.
## 멀티 리전 계획
멀티 리전은 신뢰 경계를 유지하면서 실현 가능하지만, 신중하게 수행해야 합니다:
상파울루(`southamerica-east1`)는 활성 Cloud Run 제어 플레인으로 남아 있습니다: `trusted-router`는 글로벌 로드 밸런서를 통해 계속 배포하고 서비스합니다. 엔클레이브 게이트웨이 MIG만 폐기되었으며(quill-cloud-proxy #309), 오래된 리전 게이트웨이 DNS 레코드는 삭제되었습니다. 제어 플레인 배포 리전은 `us-central1`, `us-east4`, `europe-west4`, `southamerica-east1`로 유지됩니다.
오리건(`us-west1`)은 반대의 경우로, 게이트웨이 전용 리전입니다. `api-us-west1.quillrouter.com`에서 증명된 게이트웨이 풀을 실행하며 Cloud Run 제어 플레인이 없습니다. 게이트웨이는 글로벌 로드 밸런서를 통해 제어 플레인에 도달하며, 로드 밸런서는 가장 가까운 제어 플레인 리전(`us-central1`)으로 전송합니다. `scripts/deploy`에서 Cloud Run 서비스, 스케줄러 작업, NEG를 생성하는 것은 없으며, 웜 리전 또는 최소 인스턴스 기본값에 항목이 없습니다.
- `us-central1`, `us-east4`, `europe-west4`, `us-west1`에서 독립적인 웜 증명 게이트웨이 풀을 실행합니다. 엔클레이브 인벤토리는 `src/trusted_router/enclave_regions.py`이며, 합성 프로브, 프로바이더 스모크 검사, 워치독 기본값, `TR_REGIONS` 배포 기본값에서 공유됩니다. 동일한 모듈이 로컬 컨트롤 플레인이 없는 게이트웨이 리전(`ENCLAVE_REGIONS_WITHOUT_LOCAL_CONTROL_PLANE`)의 이름을 지정합니다.
- TLS 개인 키를 각 리전별 Confidential Space 워크로드 내부에 유지합니다.
- 인증서 발급을 증명된 워크로드 내부에 유지합니다. 인증서는 암호화된 캐시를 통해 레플리카 간에 공유됩니다. 최초 리전 호스트명은 모든 노드가 정규 증명과 정착된 PONG을 통과한 후에만 하나의 노드에 노출되며, 리전 인증서와 동일한 게이트가 모든 노드에서 통과된 후에만 확장됩니다.
- 결정론적 증명, 스모크 테스트, SDK 페일오버를 위해 `api-us-central1.quillrouter.com`, `api-us-east4.quillrouter.com`, `api-europe-west4.quillrouter.com`, `api-us-west1.quillrouter.com`과 같은 리전 호스트명을 유지합니다.
- `api.trustedrouter.com`은 TLS를 종료하지 않는 지연/지역 기반 DNS 또는 TCP 패스스루 뒤에 배치합니다. Cloudflare 오렌지 클라우드 프록시는 프롬프트 경로 신뢰 주장과 호환되지 않습니다.
- 모든 요청에 대해 단일 전역 Spanner 카운터 변경이 아닌 샤딩된 청구 행을 통해 권한을 부여합니다. 새 워크스페이스와 키는 16개의 정확한 청구 샤드로 시작합니다. 리전 할당량 임대는 향후 작업으로 남아 있습니다: 2026-09 리전 할당량 및 지출 임대 파일럿은 제거되었습니다.
- 생성 메타데이터를 리전 Bigtable 클러스터에 기록한 다음, 비동기적으로 전역 활동 뷰로 집계합니다.
- 프로바이더 라우팅을 리전 단위로 유지하며, 프로바이더별 서킷 브레이커, 폴백 정책, 프로바이더별 속도 제한을 둡니다.
핵심 설계 규칙: 리전 장애는 페일 클로즈되거나 다른 증명된 리전으로 라우팅될 수 있지만, 절대 비증명 프롬프트 핸들러로 조용히 저하되어서는 안 됩니다.
## 라우터 코어 포 나인스 목표
목표는 내부 SLO이며 계약상 SLA가 아닙니다. 99.99%는 연간 약 52분 36초의 다운타임을 허용합니다. 공개 상태 페이지는 최소 30-60일간 측정된 99.99% 라우터 코어 가동 시간이 존재할 때까지 이 수치를 목표로 표시합니다.
라우터 코어 가용성의 의미:
- 증명된 TLS에 도달 가능함;
- API 키 검증 및 게이트웨이 권한 부여가 작동함;
- 라우트 후보가 반환되고 폴백이 정상 프로바이더를 선택할 수 있음;
- 정산/환불이 내구성을 가지거나 안전하게 복구 가능함;
- 어떤 프롬프트 요청도 비증명 경로로 폴백되지 않음.
현재 이 로드맵을 지원하는 코드 경로:
- `/status.json`은 `slo_classes.router_core`, `slo_classes.control_plane`, 그리고 5m, 1h, 6h, 24h 윈도우에 대한 번 레이트 알림을 내보냅니다.
- 배포 워치독은 기본적으로 `router_core`를 읽으므로, 프로바이더 전용 장애가 컨트롤 플레인 배포를 자동으로 롤백하지 않습니다.
- SDK는 실패를 표면화하기 전에 리전 증명 엔드포인트 전반에 걸쳐 연결 실패와 502/503/504를 재시도해야 합니다.
- Bigtable 활동 쓰기는 내구성 있는 정산 아웃박스에서 복구 가능합니다. 정산은 결정론적 생성 ID를 사용하므로, 재시도가 동일한 인덱스 행을 덮어쓰며 이중 청구나 활동 중복이 발생할 수 없습니다.
포 나인스를 목표가 아닌 측정된 가용성으로 설명하기 전에, 3개의 웜 GCP 증명 리전, 테스트된 페이징, 라우터 코어 카오스 테스트, 롤백 게이트가 있는 단계적 리전 배포, 그리고 99.99% 이상의 최소 30일간 측정된 라우터 코어 가동 시간이 필요합니다.
## 내부 게이트웨이 계약
증명된 API 플레인은 프롬프트나 출력 콘텐츠를 컨트롤 플레인에 전송하지 않고 사용량을 예약하고 정산할 수 있습니다:
- `POST /v1/internal/gateway/authorize`: API 키 해시를 검증하고, 크레딧/키 한도를 예약하며, provider/BYOK 라우팅 메타데이터, `model`, `models`, `provider` 요청 필터에서 파생된 라우트 후보, 그리고 구성된 리전 엔드포인트를 반환합니다.
- `POST /v1/internal/gateway/settle`: 성공한 사용량을 정산하고 메타데이터 전용 활동 행을 추가합니다.
- `POST /v1/internal/gateway/refund`: provider 실패 또는 클라이언트 연결 끊김 후 예약을 해제합니다.
로컬 개발 환경 외부에서는 `TR_INTERNAL_GATEWAY_TOKEN`을 설정하세요.
## 프로덕션 스토리지
프로덕션에서는 다음을 사용합니다:
```text
TR_STORAGE_BACKEND=spanner-clickhouse
TR_SPANNER_INSTANCE_ID=trusted-router-nam6
TR_SPANNER_DATABASE_ID=trusted-router
TR_OPERATIONAL_ANALYTICS_CLICKHOUSE_URL=http://<clickhouse-ilb>:8123
TR_OPERATIONAL_ANALYTICS_CLICKHOUSE_PASSWORD=<control-read secret>
```
---
[Read more](https://github.com/lore-hex/quill-router)