Sub2API는 여러 AI 제공업체(providers)와 계정 앞에 하나의 Base URL을 둘 수 있습니다. 클라이언트는 귀하가 발급한 키를 사용하며, 게이트웨이는 인증(authentication), 라우팅(routing), 사용량 계산(usage accounting) 및 동시성 제한(concurrency limits)을 처리합니다.

컨테이너를 온라인 상태로 만드는 것은 쉬운 부분입니다. 게이트웨이가 실행되면 귀하는 데이터베이스, Redis 인스턴스, TLS 엔드포인트, 자격 증명(credentials), 로그, 백업 및 업그레이드까지 모두 관리하게 됩니다.

이 가이드는 가장 작고 유용한 개인용 설정을 구축하고, 다른 사람에게 액세스 권한을 부여하기 전에 무엇을 확인해야 하는지 보여줍니다.

Sub2API가 추가하는 기능

요청 경로(request path)는 다음과 같습니다:

Sub2API는 현재 다양한 업스트림(upstream) 계정 유형, 플랫폼 API 키, 토큰 레벨 사용량 계산(token-level usage accounting), 스티키 세션 스케줄링(sticky-session scheduling), 사용자 및 계정별 동시성 제어(concurrency controls), 속도 제한(rate limits), 복합 그룹(composite groups) 및 관리자 대시보드를 지원합니다.

이것이 귀하를 업스트림 제공업체로부터 독립시켜 주는 것은 아닙니다. 업스트림 계정이 정지되거나, 과부하가 걸리거나, 요청과 호환되지 않는 경우, 게이트웨이는 용량이나 모델 액세스를 임의로 만들어낼 수 없습니다.

프로젝트 README에서도 AI 구독의 할당량(quota)을 배포하는 것이 업스트림 서비스 약관을 위반할 수 있다고 경고합니다. 첫 배포는 비공개로 유지하고, 권한이 있는 계정을 사용하며, 액세스 권한을 공유하거나 판매하기 전에 제공업체의 약관을 검토하십시오.

셀프 호스팅을 해야 할까요?

Sub2API는 다음과 같은 상황에서 유용합니다:

• 업스트림 자격 증명(credentials)을 개발자 기기에 두지 않아야 할 때
• 사용자 또는 프로젝트에 별도의 취소 가능한 키를 발급해야 할 때
• 예산, 속도 제한(rate limits) 및 동시성 제한(concurrency limits)을 중앙에서 설정해야 할 때
• 모든 클라이언트를 재설정하지 않고 업스트림을 전환해야 할 때
• 자체 대시보드에서 사용량 및 게이트웨이 실패를 확인해야 할 때

만약 한 사람이 하나의 공식 API를 호출한다면, 게이트웨이를 추가하는 것은 대개 시스템을 더 취약하게 만듭니다. 액세스 관리 (Access Management) 및 라우팅 (Routing)이 이미 조율의 문제로 변하기 시작할 때 셀프 호스팅 (Self-hosting)의 가치가 나타나기 시작합니다.

가장 작고 유용한 설정 배포하기

Docker 경로를 이용하려면 Linux 서버, Docker 20.10 이상, Docker Compose v2, 도메인, 그리고 최소 하나 이상의 인증된 업스트림 (Upstream) 계정 또는 API 키가 필요합니다. PostgreSQL과 Redis는 공식 Compose 스택에 포함되어 있습니다.

프로젝트는 배포 준비 스크립트를 제공합니다. 실행될 내용을 검토할 수 있도록 먼저 다운로드하세요:

mkdir -p sub2api-deploy
cd sub2api-deploy

...

이 스크립트는 Compose 정의를 docker-compose.yml로 저장하고, .env 파일을 생성하며, PostgreSQL 비밀번호와 애플리케이션 비밀값 (Secrets)을 생성하고, 로컬 데이터 디렉토리를 준비합니다. 생성된 자격 증명 (Credentials)이 터미널에 출력되므로, 해당 출력 내용을 이슈(Issue)나 채팅에 붙여넣지 마세요.

스택을 시작하기 전에 .env 파일을 편집하세요. 만약 Nginx 또는 Caddy가 동일한 서버에서 실행된다면, 8080 포트가 직접 노출되지 않도록 Sub2API를 루프백 (Loopback)에 바인딩하세요:

BIND_HOST=127.0.0.1
SERVER_PORT=8080
ADMIN_EMAIL=you@example.com
...

생성된 JWT_SECRET, TOTP_ENCRYPTION_KEY, POSTGRES_PASSWORD를 안정적으로 유지하세요. 나중에 이를 변경하면 세션이 무효화되거나, 기존 2FA (2단계 인증) 설정이 깨지거나, 데이터베이스 연결이 끊어질 수 있습니다.

서비스를 시작하고 상태를 확인하세요:

docker compose up -d
docker compose ps
docker compose logs -f sub2api

다른 셸 (Shell)에서 로컬 헬스 엔드포인트 (Health Endpoint)를 확인하세요:

curl -i http://127.0.0.1:8080/health

Sub2API, PostgreSQL, Redis 컨테이너가 정상(Healthy)인지 확인하세요. 로그인 페이지가 보이는 것만으로는 종속성 (Dependencies)들이 제대로 작동하고 있다는 것을 증명하기에 충분하지 않습니다.

앞에 HTTPS 배치하기

공용 Base URL에는 도메인과 HTTPS를 사용하세요. Sub2API는 장기 지속되는 SSE (Server-Sent Events) 및 WebSocket 트래픽을 처리하므로, 리버스 프록시 (Reverse Proxy)는 해당 응답을 버퍼링하거나 너무 일찍 닫는 것을 피해야 합니다.

Nginx 설정의 관련 부분은 다음과 같습니다:

# 이 지시어들을 http 블록에 배치하세요.
underscores_in_headers on;
map $http_upgrade $connection_upgrade {
...

underscores_in_headers on; 설정이 중요한 이유는, 그렇지 않으면 Nginx가 Sub2API에서 스티키 세션 라우팅 (sticky-session routing)을 위해 사용하는 session_id와 같은 헤더를 삭제하기 때문입니다.

서버 앞에 CDN을 배치하는 경우, 모든 클라이언트로부터 전달된 IP 헤더를 수락하는 대신 오리진 (origin) 액세스를 제한하고 신뢰할 수 있는 프록시 범위 (trusted proxy ranges)를 구성하십시오. 프로젝트의 edge security guide에서 해당 설정을 더 자세히 다룹니다.

공개 경로 (public route)를 별도로 확인하세요:

curl -i https://api.example.com/health

업스트림(upstream) 하나와 클라이언트 키 하나 추가하기

처음에는 처음부터 끝까지 전체 과정을 이해할 수 있는 하나의 경로로 시작하세요. 대시보드 레이블은 릴리스에 따라 변경될 수 있지만, 설정 과정은 대략 다음과 같습니다:

1. Account Management에서 업스트림 (upstream) 계정 또는 API 키를 하나 추가합니다.
2. 그룹을 생성하고 해당 계정을 그룹에 연결합니다.
3. 해당 그룹을 통해 하나의 모델 별칭 (model alias)을 노출합니다.
4. 적은 잔액 또는 할당량 (quota)을 가진 비관리자 테스트 사용자를 생성합니다.
5. 해당 사용자를 위한 Sub2API 키를 생성하고 이를 해당 그룹으로 제한합니다.

이 설정에는 두 가지 서로 다른 자격 증명 (credentials)이 있습니다:

Upstream credential  -> Sub2API가 제공업체(provider)를 호출할 때 사용합니다.
Sub2API key          -> 클라이언트가 게이트웨이(gateway)를 호출할 때 사용합니다.

클라이언트에게는 두 번째 키를 제공하십시오. 클라이언트는 업스트림 자격 증명을 가질 필요가 없습니다.

200 응답 이상의 결과 확인하기

OpenAI 응답 호환 (OpenAI Responses-compatible) 경로의 경우, 테스트 사용자의 키로 작은 요청을 보내보세요:

export OPENAI_BASE_URL="https://api.example.com/v1"
export OPENAI_API_KEY="your-sub2api-key"

...

Claude Code는 일반적으로 다음과 같이 사용합니다:

export ANTHROPIC_BASE_URL="https://api.example.com"
export ANTHROPIC_AUTH_TOKEN="your-sub2api-key"
claude

Codex의 경우, 깨끗한 셸 (clean shell)에서 시작하세요:

export OPENAI_BASE_URL="https://api.example.com/v1"
export OPENAI_API_KEY="your-sub2api-key"
codex

첫 번째 요청을 보낸 후, 대시보드를 열어 기록을 확인하세요. 예상했던 사용자(user), 키(key), 그룹(group), 계정(account), 모델(model), 토큰 수(token count), 그리고 비용(charge)이 사용되었는지 확인합니다.

그 다음, 실제 클라이언트가 의존하는 동작들을 테스트하세요:

• 스트리밍 (streaming) 및 긴 응답 (long responses)
• 도구 호출 (tool calls)
• 모델 별칭 매핑 (model alias mapping)
• 사용량 및 캐시 계정 처리 (usage and cache accounting)
• 동시성 제한 (concurrency limits)
• 업스트림 오류 전파 (upstream error propagation)

또한, 잘못된 키, 잔액이 없는 사용자, 그리고 사용 불가능한 업스트림(upstream)도 시도해 보세요. 이러한 테스트를 통해 액세스가 깔끔하게 차단되는지, 그리고 오류가 조용히 잘못된 모델로 전달되지는 않는지 확인할 수 있습니다.

유지보수성 유지하기

게이트웨이를 실제 업무에 사용하기 전에 다음 사항을 준수하세요:

• latest 태그를 무심코 업그레이드하는 대신, 테스트를 마친 Sub2API 이미지 태그를 고정(Pin)하여 사용하세요.
• 관리자 계정을 API 사용 계정과 분리하고 2단계 인증 (2FA)을 활성화하세요.
• 해당 사용자나 프로젝트가 더 이상 액세스가 필요하지 않을 때는 사용자의 Sub2API 키를 교체(Rotate)하세요.
• /health 엔드포인트, 컨테이너 재시작, 디스크 공간, 업스트림 오류, 지연 시간 (latency), 그리고 인증서 만료 여부를 모니터링하세요.
• .env 파일, Compose 파일, 애플리케이션 데이터, 그리고 PostgreSQL을 백업하세요.

실행 중인 PostgreSQL 데이터 디렉토리를 그대로 복사하여 데이터 일관성이 유지된다고 가정하지 마세요. pg_dump를 사용하거나, 데이터베이스를 인식하는 스토리지 스냅샷을 사용하거나, 파일 시스템 아카이브를 생성하기 전에 스택을 중지하세요. 백업 파일은 암호화하고, 다른 머신에서 복구 테스트를 수행하세요.

셀프 호스팅할 것인가, 타인에게 맡길 것인가

게이트웨이 정책을 직접 소유하고 싶고 이를 지원하는 인프라를 운영할 의사가 있다면 Sub2API는 합리적인 선택입니다.

만약 PostgreSQL, Redis, TLS, 백업, 보안, 그리고 업스트림 계정 관리를 직접 하고 싶지 않다면, 단순히 코드가 공개되어 있다는 이유만으로 셀프 호스팅을 결정하지 마세요. CCNavX에서 Sub2API로 구축된 서비스를 포함하여 기존의 AI API 릴레이 서비스들을 비교해 볼 수 있습니다.

출처

출처

• Sub2API repository and project notice
• Official Sub2API deployment documentation
• Official edge and HTTP ingress security guide
• Sub2API releases