Skip to Content
플랫폼 아키텍처개요

플랫폼 아키텍처

AXE Labs 의 아키텍처는 소규모 운영자(1인) 가 다수의 customer 를 일관된 패턴으로 호스팅 할 수 있도록 설계되었습니다. 모든 결정은 DECISIONS 에 누적 기록되며, 본 페이지는 그 결과의 정적 요약입니다.

약어가 익숙하지 않으면 용어 사전 먼저 참조. 핵심: MCP (Model Context Protocol, AI 가 외부 도구·데이터에 접근하는 표준), OIDC (OpenID Connect, 신원 확인), PKCE (Proof Key for Code Exchange, OAuth 코드 가로채기 방지).

6 가지 설계 원칙

  1. 격리는 OS-level — customer 1개 = macmini 1대. 다중 customer 가 한 머신을 공유하지 않습니다. SPOF (macmini 자체 장애) 는 cold storage 백업으로 흡수.
  2. 테넌트 ID = 이메일 도메인 → customers.yaml 매핑. 사용자가 [email protected] 으로 로그인하면 axellc.com → axe customer, realchoice.co.kr → realchoice customer 로 자동 라우팅.
  3. Path-based 1-level subdomain. {customer}.axelabs.ai/{service} 형식. 2-level wildcard SSL 무료 미지원 → path-based 로 회피.
  4. Tailscale 메시 + SSH key. 운영자 ↔ customer macmini 간 push 기반 deploy. 자체 mTLS X.
  5. Microsoft Entra ID + customer 별 own tenant. 각 customer 의 직원은 자기 회사 tenant 로 인증.
  6. GitHub source-of-truth + push deploy. customer macmini 가 pull-polling 하지 않음.

High-Level Topology

┌────────────────────────────────────────────────────────────────────────┐
│                                                                        │
│   직원 노트북 (Windows / macOS)                                          │
│   ├─ Claude Code 네이티브 앱 + Microsoft Entra ID 로그인                  │
│   └─ claude.ai 측에 Custom Connector 1회 등록                            │
│            │                                                            │
│            ↓  (Anthropic backend OAuth flow)                            │
│                                                                        │
│   Microsoft Entra ID (customer tenant)                                 │
│   - axe:        122fb574-...  (axellc.com)                              │
│   - realchoice: <TBD>          (realchoice.co.kr)                       │
│                                                                        │
│            ↓  (Bearer access_token, aud = MCP URL)                      │
│                                                                        │
│   Cloudflare DNS / Cloudflare Tunnel (axelabs-tunnel)                  │
│            │                                                            │
│            ↓  (host.docker.internal:3712)                               │
│                                                                        │
│   ┌──── customer macmini (axe-macmini / realchoice-macmini) ────┐       │
│   │                                                              │       │
│   │  axe-frame-proxy (Caddy, port 3712)  ← blue/green selector   │       │
│   │         │                                                    │       │
│   │         ├──→ frame-mcp-blue  :3710   (active)                │       │
│   │         └──→ frame-mcp-green :3711   (passive)               │       │
│   │                  │                                           │       │
│   │                  ↓                                           │       │
│   │           frame-postgres :3700                                │       │
│   │                                                              │       │
│   │  blueprint :3100   axe-vaultwarden :443/vault                │       │
│   │  stream :8780      magnet :8770                              │       │
│   │                                                              │       │
│   └──────────────────────────────────────────────────────────────┘       │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘

인증 흐름 (간략)

1. 직원 → claude.ai Custom Connector → URL https://{customer}.axelabs.ai/frame/mcp
2. claude.ai 백엔드 → frame /mcp (no auth) → 401 + WWW-Authenticate
3. claude.ai → /.well-known/oauth-protected-resource → AS = Microsoft Entra
4. claude.ai → Microsoft authorize 엔드포인트 (PKCE S256 + client_secret)
5. 브라우저 → Microsoft 로그인 → consent → code 발급
6. claude.ai → Microsoft /token → access_token (aud = Application ID URI)
7. claude.ai → frame /mcp with Authorization: Bearer <access_token>
8. frame middleware → Microsoft JWKS RS256 검증 + audience match + entity 매핑
9. frame → MCP session 생성 → tools 호출

상세는 인증 · 권한 참조.

다음 단계

Last updated on
소개Topology · 네트워크