xtokenhub

# XTokenHub XTokenHub는 LLM 제공자 API를 위한 셀프 호스팅 집계 게이트웨이입니다. 여러 제공자에 걸쳐 보유한 API 키를 단일 채널 기반 패널로 수집하고, 클라이언트에 표준화된 프로토콜 엔드포인트를 노출하며, 토큰 사용량과 캐시 적중률을 실시간으로 보고합니다. 설계 원칙은 가능한 한 제공자의 네이티브 프로토콜을 통해 트래픽을 전달하고, 프로토콜 변환은 폴백(fallback)으로 처리하는 것입니다. ## 핵심 기능 - **채널 기반 키 관리** — 제공자 엔드포인트당 하나의 항목을 생성하며, 가용성 프로빙, 활성화/비활성화 전환, 제공자가 지원하는 경우 잔액 조회를 수행합니다. - **모델 그룹화 및 라우팅** — 각 채널은 자체 모델 리스트(업스트림에서 온디맨드로 가져옴)를 가지며, 모든 업스트림은 단일 모델 리스트 엔드포인트로 병합됩니다. 라우팅은 우선순위와 가중치 랜덤 선택 방식을 사용하며, 동일한 모델을 제공하는 채널 간 자동 페일오버를 지원합니다. - **사용량 인사이트** — 대시보드를 통해 요청 수, 토큰 사용량, 캐시 적중률, 평균 지연 시간을 모델, 채널 또는 호출자 키별로 집계하여 보고합니다. GitHub 스타일의 활동 히트맵과 일일 트렌드 차트가 WebSocket을 통해 제공됩니다. - **프로토콜 변환** — 게이트웨이는 OpenAI 스타일의 chat 및 responses 엔드포인트와 Anthropic 스타일의 messages 엔드포인트를 동시에 노출합니다. 요청은 인바운드와 업스트림 프로토콜이 다를 때만 변환되며, 일치하는 프로토콜은 재작성 없이 전달되어 툴 호출(tool calls) 및 멀티모달 페이로드가 보존됩니다. - **게이트웨이 키 및 호출자별 통계** — 서로 다른 호출자를 위해 클라이언트용 키가 발행되며, 요청 및 토큰 총계가 키별로 집계됩니다. - **단일 바이너리 셀프 호스팅** — 프론트엔드가 Go 바이너리에 내장되어 있어, 빌드 시 Linux 또는 macOS 머신으로 복사 가능한 단일 정적 아티팩트(CGO 없음)가 생성됩니다. ## 라우팅 및 계측 작동 방식 README에서는 다음과 같은 4단계 흐름을 설명합니다: 1. 제공자 기본 URL, API 키, 모델 리스트를 포함한 채널을 생성합니다. API 스타일(OpenAI 호환은 Bearer, Anthropic 호환은 x-api-key)은 기본 URL에서 자동 감지되며 수동으로 변경할 수 있습니다. 베어 도메인, /v1 접미사, /anthropic과 같은 하위 경로 마운트 및 버전 지정 마운트 등 다양한 기본 URL 마운트 형식을 지원합니다. 2. 네이티브 프로토콜 프로브가 각 프로토콜 엔드포인트로 최소 요청을 보냅니다. 2xx 응답이 오면 해당 프로토콜을 채널의 네이티브 프로토콜로 표시하며, 이는 수동으로 수정 가능합니다. 3. 들어오는 요청은 해당 모델을 제공하는 활성 채널로 필터링됩니다. 네이티브 채널이 우선적으로 선택되며, 변환 채널은 폴백으로만 사용됩니다. 선택은 우선순위 오름차순 및 가중치 랜덤 방식으로 이루어지며, 네트워크 오류, 401/403/408/429 또는 5xx 오류 발생 시 페일오버가 트리거됩니다. 4. 사용량은 업스트림 응답에서 보고된 경우 이를 파싱하며(스트리밍 사용량 옵션 자동 추가), 업스트림에서 보고하지 않는 경우 로컬 휴리스틱 추정치를 사용합니다. 캐시 적중률은 제공자의 cached-token 필드에서 가져오며, 모든 요청은 로그 테이블에 기록되고 UI로 전송됩니다. ## 대시보드 및 API 표면 관리자 API는 채널, 게이트웨이 키, 보존 기간 정리가 포함된 요청 로그, 다양한 통계 엔드포인트(요약, 일일 트렌드, 모델별, 채널별, 키별, 누적 합계, 모델별 트렌드)와 헬스 체크 엔드포인트, 실시간 이벤트를 위한 WebSocket 엔드포인트를 제공합니다. 게이트웨이 엔드포인트에는 병합된 모델 리스트와 chat, responses, messages 경로가 포함됩니다. 호출자 인증은 Bearer 토큰 또는 x-api-key 헤더를 허용하며, 설정을 통해 끌 수 있습니다. ## 설정 및 운영 설정 우선순위는 환경 변수, YAML 파일, 내장 기본값 순입니다. 데이터는 WAL 모드의 SQLite에 단일 라이터 연결로 저장됩니다. 요청 로그는 기본적으로 무제한으로 증가하므로, 설정 가능한 일수보다 오래된 행을 삭제하는 보존 작업이 수행됩니다. 주기 간격, 배치 크기 및 선택적 VACUUM 설정이 가능합니다. 프로젝트 측은 삭제 후에도 SQLite 파일 크기가 자동으로 줄어들지 않는다고 명시하고 있습니다. ## 테스트 유닛 테스트는 미러링된 외부 테스트 패키지 레이아웃에 위치하며 설정 로딩, 인메모리 SQLite 리포지토리, 이벤트 버스, WebSocket 동작, 가짜 업스트림을 통한 제공자 프로빙 및 변환, 게이트웨이 선택 및 통계 영속성, 엔드-투-엔드 핸들러/라우터 경로를 다룹니다. README에 따르면 race-enabled 테스트를 모두 통과했으며 87.6%의 구문 커버리지를 달성했고, WebSocket 재연결 및 데이터 변환에 대한 프론트엔드 테스트도 수행되었습니다. ## 프로젝트가 명시한 알려진 제한 사항 - 변환 경로는 텍스트 채팅만 처리합니다. 툴 호출, 멀티모달 및 캐시 제어 페이로드는 네이티브 패스스루 채널이 필요합니다. - 잔액 조회는 현재 DeepSeek만 지원합니다. 다른 제공자의 잔액 API는 문서화되지 않았거나, 만료되는 쿠키 인증이 필요하거나, 공개되지 않았기 때문입니다. - 로컬 토큰 추정은 휴리스틱 방식이며 폴백으로만 사용됩니다. - 관리자 API에는 로그인 인증이 없으며, 외부 네트워크가 격리된 셀프 호스팅 인트라넷 사용을 상정하고 설계되었습니다. 키는 평문으로 저장됩니다. - 캐시 적중률 및 키별 집계는 요청 로그 스냅샷에 의존하므로, 삭제된 키의 과거 사용량은 해당 이름 아래에 그대로 남습니다. ## 컴패니언 앱 및 라이선스 별도의 SwiftUI 메뉴 바 앱이 백엔드 변경 없이 동일한 관리자 API와 WebSocket을 사용합니다. XTokenHub는 MIT 라이선스로 배포됩니다.