Sub2API 배포 가이드: AI API 프록시 서버 구축하기

짧은 요약

직접 쓸 수 있는 API 프록시를 돌리고 싶다면 Sub2API 같은 오픈소스 프로젝트로 충분한 경우가 많습니다. 핵심 흐름은 단순합니다. Linux 서버를 준비하고, 서비스를 배포하고, 데이터베이스와 관리자 계정을 초기화한 뒤, 이용자에게 외부 Base URL과 API Key를 줍니다.

맞는 사용 사례

Sub2API는 다음을 원하는 사람에게 더 맞습니다.

• 여러 업스트림 계정을 한곳에서 관리
• 팀원에게 통합 API 키를 발급
• 충전, 권한, 전달 규칙을 직접 제어
• 더 복잡한 플랫폼에 묶이기 전에 쓸 수 있는 비공개 프록시를 운영

인터페이스를 잠시 시험만 하려면 데모 환경으로 흐름을 이해할 수 있습니다. 실제로 쓰려면 자체 배포가 더 나은 선택입니다.

배포 전

먼저 세 가지를 준비합니다.

1. Linux 클라우드 서버. 가능하면 AMD64 또는 ARM64
2. PostgreSQL과 Redis, 또는 둘을 포함한 Docker Compose 구성
3. 서버로 연결되는 도메인. 인증서를 붙이고 관리 패널에 깨끗하게 접근할 수 있습니다

Nginx로 리버스 프록시를 쓸 계획이면 http 블록에서 underscores_in_headers on;을 켭니다. 그렇지 않으면 헤더가 빠져 일부 다중 계정 시나리오가 실패할 수 있습니다.

권장 배포 방법

Sub2API 문서는 보통 두 경로를 안내합니다.

• 원클릭 설치 스크립트: 빠르게 올리기 좋습니다. 스크립트가 바이너리를 받고, 서비스를 만들고, 디렉터리 구조를 초기화합니다.
• Docker Compose: 데이터 디렉터리, 마이그레이션, 백업을 더 분명히 통제하고 싶을 때 맞습니다.

첫 배포에서는 보통 Docker가 이해하기 쉽습니다. 운영형 systemd 관리를 원하면 설치 스크립트도 편리합니다.

옵션 1: Docker 배포

대략적인 흐름은 다음과 같습니다.

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

스크립트는 보통 다음을 준비합니다.

• docker-compose.local.yml
• .env
• 보안 키
• 로컬 데이터 디렉터리

구성 전체를 함께 묶을 수 있어 이후 서버 이전도 쉬워집니다.

런타임 로그를 보려면:

docker compose logs -f sub2api

옵션 2: 설치 스크립트

직접 systemd 서비스를 원하면 공식 원클릭 설치 스크립트를 쓰세요. 프로그램과 서비스를 설치하고 초기화 마법사를 시작합니다.

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

설치 후 초기화 페이지는 보통 http://server-ip:8080에서 열립니다. 이어서 데이터베이스, Redis, 관리자 계정을 설정합니다.

초기화 때 확인할 것

설정 패널에서 다음을 확인합니다.

• 데이터베이스 연결이 됩니다
• Redis가 정상입니다
• 관리자 계정이 만들어졌습니다
• 포트가 외부에 열려 있습니다
• 도메인과 리버스 프록시가 이미 연결됐습니다

다른 사람이 서비스를 쓴다면 초기화 때 관리자와 일반 이용자의 경계를 정하세요. 나중에 다시 설계하는 일이 훨씬 번거롭습니다.

이용자에게 접근 권한 주기

패널이 돌아가면 이용자에게 보통 두 값이 필요합니다.

• Base URL
• API Key

이용자는 이 값을 Claude Code, Codex, Cursor, 또는 호환 도구에 넣을 수 있습니다. 요청은 먼저 프록시로 가고, 프록시가 업스트림 서비스로 전달합니다.

이런 프록시가 실제로 하는 일

중간 계층으로 생각하면 됩니다.

이용자는 프록시에 요청을 보냅니다. 프록시는 설정한 업스트림 계정, 모델, 규칙에 따라 그 요청을 전달합니다. 이렇게 계정, 권한, 과금, 배포를 한곳에서 관리할 수 있습니다.

흔한 함정

• Nginx가 헤더를 떨어뜨림: 리버스 프록시를 쓰면 밑줄 헤더를 보존하세요.
• 데이터베이스 또는 Redis가 다운: 초기화 패널이 열린다고 모든 백엔드 의존성이 건강한 것은 아닙니다.
• 도메인이 불완전: 패널에 들어갈 수 있어도 외부 API 주소가 된다고 보장되지 않습니다.
• 계정 인증 실패: 먼저 브라우저 세션, 프록시 설정, 콜백 URL, 업스트림 계정 상태를 확인하세요.

마무리 조언

첫 프록시 배포라면 지나치게 복잡한 구조부터 시작하지 마세요. 쓸 수 있는 최소 버전을 먼저 돌립니다. 패널, 계정, 전달, API 호출이 모두 되는 것을 확인한 뒤 도메인, 인증서, 리버스 프록시 규칙, 업스트림 계정을 단계적으로 추가하세요.