오픈 소스 프로젝트 (No.73): Sub2API - Claude/OpenAI/Gemini 구독을 API로 중계하는 올인원 솔루션

서론

"AI 구독 할당량을 유연하게 활용하고 모든 비용의 가치를 극대화하세요." 이것은 "하루에 하나의 오픈 소스 프로젝트" 시리즈의 73번째 글입니다. 오늘은 Sub2API (CRS2로도 알려짐)를 살펴보겠습니다. Claude Code나 GitHub Copilot과 같은 네이티브 AI 파워 도구의 부상으로, 많은 개발자들이 여러 개의 AI 구독(Claude Pro 또는 OpenAI Plus 등)을 보유하게 되었습니다. 하지만 이러한 구독에는 종종 사용량 제한이나 유휴 할당량이 발생합니다. 어떻게 하면 이렇게 흩어진 구독 리소스를 통합하고 다양한 도구와 사용자에게 비용을 효율적으로 분배할 수 있을까요? Sub2API는 완벽한 오픈 소스 솔루션을 제공합니다. 이는 단순한 포워더(Forwarder) 그 이상입니다. 계정 관리 및 할당량 분배부터 자동 결제 및 내장된 결제 시스템에 이르기까지 전체 파이프라인을 처리하는 풀 기능 API 프록시(Proxy) 플랫폼입니다. 특히 팀 공유, "카풀(Carpooling)"(비용 분담 사용), 또는 개인의 다중 계정 통합에 매우 적합합니다.

학습 내용

• Sub2API의 핵심 포지셔닝과 해결하는 페인 포인트(Pain points).
• 지원되는 주요 모델 및 구독 유형.
• 핵심 기능: 다중 계정 관리, 지능형 스케줄링, 그리고 토큰(Token) 단위 과금.
• 빠른 배포 방법: 스크립트 설치 및 Docker Compose.
• Sub2API를 사용하여 자신만의 AI API 중계 서비스를 구축하는 방법.

사전 요구 사항

• AI 모델 API(OpenAI, Claude, Gemini 등)에 대한 기본적인 이해.
• 기본적인 Linux 커맨드 라인(Command-line) 경험.
• Docker 또는 컨테이너화된 배포 개념에 대한 익숙함.

프로젝트 배경

프로젝트 개요
Sub2API는 Go 언어로 개발된 AI API 게이트웨이(Gateway) 플랫폼입니다. 핵심 로직은 다양한 채널(OAuth 인증 계정, 세션 키(Session Keys), 또는 표준 API 키 포함)로부터 AI 구독을 "풀링(Pooling)"하는 것입니다. Sub2API를 통해 다음과 같은 작업이 가능합니다:

• 리소스 통합: 여러 개의 Claude Pro 또는 OpenAI 계정을 연결하여 단일화된 표준 API를 출력합니다.
• 비용 공유: 내장된 과금 시스템을 통해 사용량에 따라 요금을 부과하는 "카풀(Carpooling)" 메커니즘을 지원합니다.

매끄러운 통합 (Seamless Integration): 생성된 API는 복잡한 클라이언트 측 설정 없이도 Claude Code, OpenClaw 등과 같은 네이티브 도구와 완벽하게 작동합니다.

저자/팀 유지보수: Wei-Shaw

생태계 (Ecosystem): 이 프로젝트는 모바일 관리 콘솔 (sub2api-mobile) 및 기타 주변 도구들을 포함하여 활발한 커뮤니티 지원을 받고 있습니다.

프로젝트 데이터
📄 핵심 저장소 (Core Repository): Wei-Shaw/sub2api
🛠️ 기술 스택 (Tech Stack): Go (Gin, Ent), Vue 3, PostgreSQL, Redis
📄 라이선스 (License): LGPL-3.0
📈 통계 (Stats): GitHub에서 22k 이상의 스타 (Note: 과거 저장소 데이터 또는 높은 커뮤니티 관심을 포함할 수 있음).

주요 기능
핵심 유틸리티
Sub2API는 AI 사용 시 발생하는 "리소스 섬 (resource island)" 문제를 해결합니다:
상위 계정 풀 (Upstream Account Pool: Claude, OpenAI, Gemini)
↓ 통합
Sub2API 플랫폼 레이어 (인증 (Auth), 과금 (Billing), 부하 분산 (Load Balancing), 세션 지속성 (Session Persistence))
↓ 통합 배포
하위 애플리케이션 (Downstream Applications: IDE, 채팅 클라이언트, 스크립트)

주요 특징
다중 계정 관리 (Multi-Account Management): 다양한 상위 계정 유형을 지원하며 세션 지속성을 자동으로 처리합니다.
정밀한 과금 (Precise Billing): 토큰 (Token) 단위의 사용량 추적 및 사용자 정의 요율을 통한 비용 계산을 지원합니다.
스마트 스케줄링 (Smart Scheduling): 긴 대화의 연속성을 보장하기 위해 스티키 세션 (Sticky Sessions) 및 부하 분산 (Load Balancing)을 지원합니다.
내장 결제 시스템 (Built-in Payment System): Alipay, WeChat Pay, Stripe 등을 네이티브로 지원하여 사용자가 자율적으로 충전할 수 있습니다.
동시성 및 속도 제한 (Concurrency & Rate Limiting): 리소스를 보호하기 위해 사용자별 및 계정별 제한을 구성할 수 있습니다.
관리자 대시보드 (Admin Dashboard): 실시간 모니터링 및 관리를 위한 직관적인 웹 UI (Web UI)를 제공합니다.

빠른 시작 (Quick Start)
방법 1: 원클릭 스크립트 설치 (권장)
깨끗한 Ubuntu/Debian 시스템에 권장됩니다:
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash

참고 사항: PostgreSQL 15 이상 및 Redis 7 이상이 사전에 설치되어 있어야 합니다. 스크립트는 바이너리를 /opt/sub2api에 설치하고 systemd 서비스를 생성합니다.

방법 2: Docker Compose 배포

# 배포 디렉토리 생성
mkdir -p sub2api-deploy && cd sub2api-deploy

# 배포 준비 스크립트 다운로드 및 실행
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

# 서비스 실행
docker compose up -d

설치가 완료되면 http://YOUR_SERVER_IP:8080 에서 관리자 대시보드에 접속할 수 있습니다.

상세 분석

아키텍처: 왜 이것이 단순한 리버스 프록시 (Reverse Proxy) 이상인가?

Sub2API의 설계 우선순위는 "계정 상태 관리 (Account State Management)"입니다. 전통적인 리버스 프록시 도구(Nginx 등)는 애플리케이션 계층의 세션 (Session)을 이해하는 능력이 부족합니다.

• 스티키 세션 (Sticky Sessions): 문맥의 연속성이 필요한 Claude Code와 같은 도구를 위해, Sub2API는 헤더 (Header)의 session_id를 사용하여 요청을 특정 업스트림 (Upstream) 계정에 고정함으로써, 계정 전환으로 인해 대화가 중단되지 않도록 보장합니다.
  참고: Nginx를 리버스 프록시로 사용하는 경우, 세션 헤더를 지원하기 위해 underscores_in_headers on; 설정이 활성화되어 있는지 확인하십시오.
• 풀링 로직 (Pooling Logic): 시스템은 여러 계정을 하나의 "리소스 풀 (Resource Pool)"로 추상화합니다. 특정 계정이 속도 제한 (Rate Limit)에 도달하면, 스케줄러가 자동으로 해당 계정으로부터 트래픽을 우회시켜 가동 시간을 극대화합니다.
• 통합된 생태계 (Integrated Ecosystem): 대부분의 중계 도구는 외부 결제 게이트웨이 (Payment Gateway)를 필요로 하지만, Sub2API의 내장 통합 기능은 소규모 팀이나 커뮤니티 주도의 "카풀 (Carpools)" 운영 복잡성을 크게 줄여줍니다.

기술 스택

• 백엔드 (Backend): Go 언어를 사용하여 높은 동시성 (Concurrency) 처리와 배포 용이성을 보장합니다.
• 데이터베이스 (Database): PostgreSQL이 복잡한 관계 및 결제 기록을 처리합니다.
• 캐시 (Cache): Redis가 속도 제한 (Rate Limiting) 및 실시간 상태 동기화를 관리합니다.

주소 및 리소스

공식 리소스
🌟 GitHub : Wei-Shaw/sub2api
📖 문서 (Documentation) : 배포, 결제 설정 및 API 사용에 관한 상세 가이드를 저장소에서 확인할 수 있습니다.
🖥️ 데모 (Demo) : https://demo.sub2api.org/

타겟 대상
카풀 리더 (Carpool Leads) : Claude/OpenAI Plus 비용을 분담하고자 하는 운영자.

개발자 / 파워 유저 (Developers / Power Users) : 네이티브 CLI 도구를 위해 여러 계정의 할당량 (Quota)을 통합하고자 하는 개인.

사내 엔터프라이즈 팀 (Internal Enterprise Teams) : AI 리소스 사용량을 내부적으로 배포하고 감사 (Audit)해야 하는 팀.

요약 및 전망
핵심 요약

• 명확한 집중 (Clear Focus) : 구독 기반의 할당량을 표준 API 서비스로 변환하는 데 특화됨.
• 올인원 (All-in-One) : 관리, 스케줄링, 과금 및 결제를 위한 폐쇄 루프 (Closed-loop) 제공.
• 친화적인 배포 (Deployment Friendly) : 스크립트 기반 및 Docker 기반 설정을 포함한 다양한 옵션 제공.
• 신뢰할 수 있는 성능 (Reliable Performance) : 중대규모 배포에 적합한 견고한 Go/PostgreSQL/Redis 기반 구축.

한 줄 평
Sub2API는 현재 "리소스 집약 (Resource Aggregation)"과 "상업적 모델 (Commercial Model)"을 결합한 가장 긴밀하게 통합된 오픈 소스 솔루션으로, "구독으로부터의 자유"를 달성하기 위한 강력한 도구입니다.

더 유용한 통찰과 흥미로운 제품들을 확인하시려면 제 홈페이지를 방문해 주세요.