Wei-Shaw/sub2api

Sub2API 는 공식적으로 도메인 sub2api.org 와 pincc.ai 만 사용합니다.

다른 웹사이트는 Sub2API 이름이 붙은 제 3 자 배포 또는 서비스일 수 있으며, 이 프로젝트와 무관할 수 있습니다. 확인과 판단을 스스로 하십시오.

Sub2API 를 온라인에서 시도해 보십시오: https://demo.sub2api.org/

데모 인증 정보 (공유 데모 환경; 자주 호스팅 설치용 자동 생성하지 않음):

비밀번호
admin@sub2api.org	admin123

Sub2API 는 AI 제품 구독에서 API 쿼터를 배포하고 관리하기 위해 설계된 AI API 게이트웨이 플랫폼입니다. 사용자가 플랫폼 생성 API 키를 통해 상류 AI 서비스에 접근할 수 있으며, 플랫폼은 인증, 청구, 로드 밸런싱 및 요청 포워딩을 처리합니다.

멀티 계정 관리- 다중 상류 계정 유형 지원 (OAuth, API Key)
API 키 배포- 사용자용 API 키 생성 및 관리
정밀 청구- 토큰 수준 사용 추적 및 비용 계산
스마트 스케줄링- 스티키 세션과 함께 지능형 계정 선택
동시성 제어- 사용자별 및 계정별 동시성 제한
리이트 리미팅- 구성 가능한 요청 및 토큰 리이트 제한
내장 결제 시스템- EasyPay, Alipay, WeChat Pay, Stripe 를 지원하여 사용자 자체 서비스 충전 가능, 별도의 결제 서비스 불필요 (구성 가이드)
관리 대시보드- 모니터링 및 관리를 위한 웹 인터페이스
외부 시스템 통합- iframe 을 통해 외부 시스템 (예: 티켓팅) 임베딩으로 관리자 대시보드 확장

PinCC 는 Sub2API 를 기반으로 구축된 공식 릴레이 서비스로, Claude Code, Codex, Gemini 등 인기 있는 모델에 안정적인 접근을 제공합니다. 배포 및 유지보수가 필요 없습니다. |

| PackyCode 에 감사드립니다! 이 프로젝트를 후원해주신 PackyCode 는 Claude Code, Codex, Gemini 등 다양한 모델을 위한 신뢰할 수 있고 효율적인 API 릴레이 서비스 제공자입니다. 소프트웨어 사용자들에게 특별한 할인 혜택을 제공합니다: 이 링크를 통해 등록하고 첫 충전 시 "sub2api" 프로모션 코드를 입력하면 10% 할인을 받으세요. |

| Poixe AI 에 감사드립니다! 이 프로젝트를 후원해주신 Poixe AI 는 신뢰할 수 있는 LLM API 서비스를 제공합니다. 플랫폼의 API 엔드포인트를 활용하여 원활하게 AI 기반 제품을 구축할 수 있습니다. 또한, 플랫폼에 AI API 리소스를 제공하여 벤더가 되며 수익을 창출할 수도 있습니다. 독점 sub2api 추천 링크를 통해 등록하고 첫 충전 시 $5 USD 보너스를 받으세요. |

| CTok.ai 에 감사드립니다! 이 프로젝트를 후원해주신 CTok.ai 는 일괄 AI 프로그래밍 도구 서비스 플랫폼 구축에 전념하고 있습니다. 우리는 전문 Claude Code 패키지와 기술 커뮤니티 서비스를 제공하며, Google Gemini 와 OpenAI Codex 을 지원합니다. 세밀하게 설계된 플랜과 전문 기술 커뮤니티를 통해 개발자들에게 신뢰할 수 있는 서비스 보장과 지속적인 기술 지원을 제공하여, AI 기반 프로그래밍을 진정한 생산성 도구로 만듭니다. 등록하려면 여기 클릭하세요! |

| ... |

Sub2API 와 연동하거나 확장하는 커뮤니티 프로젝트:

프로젝트	설명	기능
Now Built-in — Payment 는 Sub2API 에 통합되었으며, 별도의 배포가 필요 없습니다. Payment Configuration Guide 를 참조하세요
sub2-mobile	모바일 관리 콘솔	사용자 관리, 계정 관리, 모니터링 대시보드 및 다중 백엔드 전환을 위한 크로스 플랫폼 앱 (iOS/Android/Web); Expo + React Native 로 구축됨

컴포넌트	기술
Backend	Go 1.25.7, Gin, Ent
...

Sub2API (또는 CRS) 를 Nginx 가 역프록시로 사용할 때 Codex CLI 와 함께 다음을 Nginx 설정의 http 블록에 추가하세요:

underscores_in_headers on;

Nginx 는 기본적으로 underscores 를 포함하는 헤더를 제거합니다 (예: session_id), 이는 다중 계정 설정에서 스티키 세션 라우팅을 방해합니다.

GitHub Releases 에서 미리 구축된 바이너리를 다운로드하는 한 번 클릭 설치 스크립트.

• Linux 서버 (amd64 또는 arm64)
• PostgreSQL 15+ (설치 및 실행됨)
• Redis 7+ (설치 및 실행됨)
• 루트 권한

본문을 번역합니다.

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash

스크립트는 다음 작업을 수행합니다:

• 시스템 아키텍처 감지
• 최신 릴리스 다운로드
• 바이너리 설치 위치 /opt/sub2api
• systemd 서비스 생성
• 시스템 사용자 및 권한 설정

# 1. 서비스 시작
sudo systemctl start sub2api
# 2. 부팅 시 자동 시작 활성화
...

설치 마법사는 다음을 안내합니다:

• 데이터베이스 구성
• Redis 구성
• 관리자 계정 생성

관리자 대시보드 (Admin Dashboard) 의 왼쪽 상단의 업데이트 확인 (Check for Updates) 버튼을 클릭하여 직접 업그레이드할 수 있습니다.

웹 인터페이스는 다음 기능을 제공합니다:

• 새 버전 자동 확인
• 한 번의 클릭로 다운로드 및 적용
• 필요 시 롤백 지원

# 상태 확인
sudo systemctl status sub2api
# 로그 보기
...

Docker Compose 로 배포, PostgreSQL 와 Redis 컨테이너 포함.

• Docker 20.10+
• Docker Compose v2+

자동 배포 스크립트를 사용하여 쉬운 설정:

# 배포 디렉토리 생성
mkdir -p sub2api-deploy && cd sub2api-deploy
# 배포 준비 스크립트 다운로드 및 실행
...

스크립트가 수행하는 작업:

• docker-compose.local.yml 다운로드 (저장 위치: docker-compose.yml)
• .env.example 파일
• 안전한 자격 증명 생성 (JWT_SECRET, TOTP_ENCRYPTION_KEY, POSTGRES_PASSWORD)
• 자동 생성된 비밀로 구성된 .env 파일 생성 - 데이터 디렉토리 생성 (지역 디렉토리를 사용하여 쉬운 백업/이동 지원)
• 생성된 자격 증명을 표시하여 참조용

수동 설정을 선호하는 경우:

# 1. 저장소 클론
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api/deploy
...

.env 파일에 필요한 구성:

# PostgreSQL 비밀번호 (필수)
POSTGRES_PASSWORD=your_secure_password_here
# JWT 비밀 (권장 - 재시작 후 사용자의 로그인 유지)
...

안전한 비밀 생성:

# JWT_SECRET 생성
openssl rand -hex 32
# TOTP_ENCRYPTION_KEY 생성
...

# 4. 데이터 디렉토리 생성 (지역 버전용)
mkdir -p data postgres_data redis_data
# 5. 모든 서비스 시작
...

버전	데이터 저장	마이그레이션	권장 대상
docker-compose.local.yml	지역 디렉토리	✅ 쉬운 (전체 디렉토리 tar)	프로덕션, 빈번한 백업
docker-compose.yml	네이밍 볼륨	간단한 설정

권장: 스크립트로 배포된 docker-compose.local.yml 을 사용하여 데이터 관리 용이.

브라우저에서 http://YOUR_SERVER_IP:8080을 엽니다.

관리자 비밀번호가 자동 생성된 경우 로그에서 확인하세요:

docker compose -f docker-compose.local.yml logs sub2api | grep "admin password"

# 최신 이미지 다운로드 및 컨테이너 재시작
docker compose -f docker-compose.local.yml pull
docker compose -f docker-compose.local.yml up -d

docker-compose.local.yml 사용 시:

새 서버로 쉽게 마이그레이션하세요:

# 원본 서버에서
docker compose -f docker-compose.local.yml down
cd ..
...

# 모든 서비스 중지
docker compose -f docker-compose.local.yml down
# 재시작
...

소스 코드로 빌드 및 실행 (개발 또는 커스터마이징용):

• Go 1.21+
• Node.js 18+
• PostgreSQL 15+
• Redis 7+

# 1. 저장소 클론
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api
...

참고: -tags embed 플래그는 프론트엔드를 바이너리에 임베딩합니다. 이 플래그를 사용하지 않으면 바이너리는 프론트엔드 UI 를 제공하지 않습니다.

config.yaml 의 주요 설정:

server:
host: "0.0.0.0"
port: 8080
...

⚠️ Sora 관련 기능은 업스트림 통합 및 미디어 전달의 기술적 문제 때문에 일시적으로 사용할 수 없습니다. 현재는 프로덕션에서 Sora 를 신뢰하지 마세요. 기존 gateway.sora_* 설정 키는 예약되어 있으며, 이러한 문제가 해결될 때까지 효과가 없을 수 있습니다.

추가 보안 옵션은 config.yaml 에서 제공됩니다:

cors.allowed_origins: CORS 허용 목록
security.url_allowlist: 업스트림/가격/CRS 호스트 허용 목록
security.url_allowlist.enabled: URL 유효성 검사 비활성화 (주의 사용)
security.url_allowlist.allow_insecure_http: 유효성 검사가 비활성화되었을 때 HTTP URL 허용
security.url_allowlist.allow_private_hosts: 프라이빗/로컬 IP 주소 허용
security.response_headers.enabled: 설정 가능한 응답 헤더 필터링 활성화 (비활성화는 기본 허용 목록 사용)
security.csp: Content-Security-Policy 헤더 제어
billing.circuit_breaker: 결제 오류 시 폐쇄 실패
server.trusted_proxies: X-Forwarded-For 파싱 활성화
turnstile.required: 릴리스 모드에서 Turnstile 요구

security.url_allowlist.enabled=false 일 때, 시스템은 기본적으로 최소 URL 유효성 검사를 수행하며, HTTP URL 을 거부하고 HTTPS 만 허용합니다. HTTP URL 을 허용하려면 (예: 개발 또는 내부 테스트용) 명시적으로 설정해야 합니다:

security:
url_allowlist:
enabled: false # 허용 목록 검사 비활성화
...

또는 환경 변수를 통해:

SECURITY_URL_ALLOWLIST_ENABLED=false
SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTP=true

HTTP 허용의 위험:

• API 키와 **명시문 (plaintext)**으로 전송되는 데이터 (감청에 취약) - 맨-인-더-미들 (MITM) 공격에 취약 - 프로덕션 환경에는 적합하지 않음

HTTP 사용 시점:

• ✅ 로컬 서버 개발/테스트 (http://localhost)
• ✅ 신뢰할 수 있는 엔드포인트를 가진 내부 네트워크
• ✅ HTTPS 획득 전 계정 연결성 테스트
• ❌ 프로덕션 환경 (HTTPS 만 사용)

이 설정 없이 발생하는 예외 오류:

Invalid base URL: invalid url scheme: http

URL 검증 또는 응답 헤더 필터링을 비활성화하면 네트워크 계층을 강화하세요:

• 업스트림 도메인/IP 에 대한 출구 허용 목록 강제
• 사설/루프백/링크 로컬 범위를 차단
• TLS 만의 외부 트래픽 강제
• 프록시에서 민감한 업스트림 응답 헤더 제거

# 6. 애플리케이션 실행
./sub2api

# 백엔드 (핫 리로드 포함)
cd backend
go run ./cmd/server
...

backend/ent/schema 편집 시 Ent + Wire 재생성:

cd backend
go generate ./ent
go generate ./cmd/server

Simple Mode 는 전체 SaaS 기능을 갖추지 않고도 빠른 접근을 원하는 개인 개발자 또는 내부 팀에 설계되었습니다.

• 활성화: 환경 변수 설정
  RUN_MODE=simple

• 차이점: SaaS 관련 기능을 숨기고 청구 프로세스를 건너뛰기

• 보안 주의사항: 프로덕션에서는 SIMPLE_MODE_CONFIRM=true 도 함께 설정하여 시작을 허용해야 함

Sub2API 는 Antigravity 계정을 지원합니다. 인증 후 Claude 및 Gemini 모델 전용 엔드포인트가 제공됩니다.

엔드포인트	모델
/antigravity/v1/messages	Claude 모델
/antigravity/v1beta/	Gemini 모델

export ANTHROPIC_BASE_URL="http://localhost:8080/antigravity"
export ANTHROPIC_AUTH_TOKEN="sk-xxx"

Antigravity 계정은 선택적 하이브리드 스케줄링을 지원합니다. 활성화 시 일반 엔드포인트 /v1/messages 와 /v1beta/ 도 Antigravity 계정에 요청 라우팅됩니다.

: Anthropic Claude 와 Antigravity Claude⚠️ 경고는 동일한 대화 컨텍스트에서 혼합할 수 없습니다. 그룹을 사용하여 적절히 격리하세요.

Claude Code 에서 Plan Mode 는 자동으로 종료되지 않습니다. (일반적으로 네이티브 Claude API 를 사용할 때, 계획 완료 후 Claude Code 는 사용자에게 계획을 승인 또는 거부할 옵션을 표시합니다.)

대응책: Shift + Tab 을 눌러 Plan Mode 를 수동으로 종료한 후, 계획에 대해 승인 또는 거부를 위해 응답을 입력하세요.

sub2api/
├── backend/ # Go 백엔드 서비스
│ ├── cmd/server/ # 애플리케이션 진입점
...