원클릭 Claude Code 중계 서버 구축 튜토리얼: 주거용 IP + Docker Compose 초간단 배포

이용 VoyraCloud 주거 IP VPS（실제 주거 네트워크, 계정 차단 방지, 안정적이고 고속），Docker Compose를 통해 현재 가장 성숙하고 안정적인 오픈 소스 Claude 중계 서비스인 Claude Relay Service（약칭 CRS, GitHub 프로젝트 Wei-Shaw/claude-relay-service）를 원클릭으로 배포합니다.

본 방안은 다음을 지원합니다：

Claude API 완전 프록시
다중 계정 로드 밸런싱（속도 제한 방지）
카풀 공유（하위 키 생성）
사용량 통계
웹 관리 패널

공식 Claude Code CLI 도구에 완벽하게 적합하여 로컬에서 고속, 안정적인 Claude 인코딩 경험을 누릴 수 있습니다.

왜 주거 IP를 선택해야 할까요? 핵심 장점이 한눈에 들어옵니다

Anthropic（Claude）의 리스크 관리는 주로 데이터 센터 IP를 대상으로 하며, 주거 IP를 사용하면 계정 차단 위험을 크게 줄일 수 있습니다. CRS는 현재 커뮤니티에서 인정받는 가장 인기 있고 안정적인 Claude 중계 오픈 소스 프로젝트입니다（Docker Hub 공식 이미지 다운로드 수가 높고 성공 사례가 무수히 많습니다）。 Docker Compose 배포 방식은 Redis를 기본으로 포함하고 있어 수동으로 의존성을 설치할 필요가 없으며, 공식 및 커뮤니티에서 추천하는 생산급 솔루션입니다.📖 연장 읽기：왜 Anthropic과 OpenAI가 주거 IP에 우호적이고 데이터 센터 IP에 방어를 하는지 완전히 이해하지 못하셨나요? 이 글 《주거 IP VPS란 무엇인가: 2026 권위 가이드》는 IP 공급망, ASN 분류, 반탐지 메커니즘 세 가지 차원에서 기본 원리를 설명합니다——모든 “내 Claude Code가 왜 리스크 관리에 걸리는가” 문제의 답입니다.

💡 아직도 고민 중인가요: 주거 프록시 + 저렴한 데이터 센터 VPS가 주거 IP VPS를 대체할 수 있을까요? 짧은 답변: 작동할 수는 있지만 비용이 5-10배 비쌀 것이며, WebSocket/HTTP/2 장기 연결이 자주 끊깁니다（Claude Code가 이를 강하게 의존하고 있습니다）。 전체 비교 및 비용 산정은 《주거 IP VPS vs 주거 프록시: 2026 완전 비교》에서 확인하세요.

첫 번째 단계: VoyraCloud 주거 IP 서버 구매 및 로그인

VoyraCloud 주거 IP VPS 구매 페이지에 방문하여 로스앤젤레스 또는 워싱턴 노드를 선택하는 것을 추천합니다.
- 개인/소규모 팀: 2코어부터 시작 가능합니다.
- 카풀 공유: 4코어 이상을 추천합니다.
시스템 선택 Ubuntu 24.04（가장 호환성이 좋습니다）.
구매 완료 후 IP, 사용자 이름（ubuntu）, 비밀번호를 받습니다.
SSH로 로그인합니다:
- Windows: PuTTY 또는 Windows Terminal을 추천합니다.
- Mac/Linux: 터미널에서 ssh ubuntu@당신의VPS_IP를 실행합니다.

단계 1: Docker 설치

VPS에 로그인한 후, 원클릭으로 실행합니다：

sudo mkdir -p /etc/apt/sources.list.d && curl -fsSL https://get.docker.com -o get-docker.sh && sudo sh get-docker.sh && sudo systemctl restart docker && sudo systemctl enable docker

성공 여부를 확인합니다：

docker --version

버전 번호가 표시되면 설치가 완료된 것입니다.

단계 2: Docker Compose 설치

DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker} && mkdir -p $DOCKER_CONFIG/cli-plugins && curl -SL https://github.com/docker/compose/releases/download/v5.0.1/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose && chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose

확인합니다：

docker compose version

v5.0.1（또는 그 이상）이 표시되면 성공입니다.

단계 3: Docker 권한 수정

sudo usermod -aG docker ubuntu && newgrp docker

단계 4: 배포 디렉토리 생성

mkdir ~/crs && cd ~/crs

단계 5: docker-compose.yml 구성 파일 생성

nano docker-compose.yml

다음 내용을 붙여넣습니다（두 곳의 키를 반드시 수정하세요）：

services:
  claude-relay:
    image: weishaw/claude-relay-service:latest
    container_name: claude-relay-service
    restart: unless-stopped
    ports:
      - "8080:3000"   # 호스트 포트는 필요에 따라 수정할 수 있습니다
    environment:
      - PORT=3000
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - JWT_SECRET=Your super long random key 1      # 최소 60자, 영숫자 기호 혼합
      - ENCRYPTION_KEY=Your super long random key 2  # 
위와 동일, 다를 것
    depends_on:
      redis:
        condition: service_healthy
    volumes:
      - ./logs:/app/logs
      - ./data:/app/data

  redis:
    image: redis:7-alpine
    container_name: claude-relay-redis
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 3s
      timeout: 2s
      retries: 30
    volumes:
      - redis_data:/data

volumes:
  redis_data:

Ctrl+O로 저장하고, Ctrl+X로 종료합니다.

파일을 검증합니다：

cat docker-compose.yml

단계 6: 서비스 시작

docker compose up -d

이미지를 다운로드하는 데 2-15분 정도 기다립니다.

상태를 확인합니다：

docker compose ps

두 개의 컨테이너가 모두 Up으로 표시되면 성공입니다.

정상 여부를 확인하기 위해 로그를 확인합니다：

docker compose logs -f claude-relay

반복적으로 나타나는 health-check completed 로그가 서비스가 건강하다는 것을 나타냅니다（Ctrl+C로 종료합니다）。

단계 7: 웹 관리 패널에 접근하고 계정 구성

브라우저에서 열기：http://VPS_IP:8080/web

처음 방문하면 관리자 계정이 자동으로 생성되며, 확인 방법은：

cat data/init.json

로그인 후 작업：

“계정 추가” 클릭 → “Anthropic API” 또는 “Claude Console” 선택
당신의 Claude Pro/Max 계정 비밀번호 또는 공식 API Key 입력
여러 계정을 추가하여 자동 회전 로드 밸런싱을 구현할 수 있습니다
친구와 카풀 공유를 위해 하위 API Key를 생성하여 비용을 절감할 수 있습니다

단계 8: 로컬에서 Claude Code 사용 중계소 구성

Claude Code를 전역적으로 설치합니다：

npm install -g @anthropic-ai/claude-code

환경 변수를 구성합니다（패널에서 생성된 하위 키 사용을 추천합니다）：

Mac/Linux：

export ANTHROPIC_BASE_URL="http://VPS_IP:8080/v1"
export ANTHROPIC_API_KEY="패널에서 생성된 하위 키（또는 임의의 문자열）"

Windows PowerShell：

$env:ANTHROPIC_BASE_URL="http://VPS_IP:8080/v1"
$env:ANTHROPIC_API_KEY="패널에서 생성된 하위 키（또는 임의의 문자열）."

테스트：

claude --version
claude "hello, world"

정상적으로 응답하면 성공입니다!

이제 당신은 순수 주거 IP, 고속 안정, 개인 전용 Claude Code 중계소를 갖게 되었으며, 비용을 쉽게 나눌 수 있습니다.

자주 사용하는 유지 관리 명령어

서비스 업데이트: cd ~/crs && docker compose pull && docker compose up -d
서비스 재시작: docker compose restart
완전 초기화（주의）：docker compose down -v && rm -rf logs data

자주 묻는 질문 해결

웹 패널에 접근할 수 없나요? 방화벽 확인: sudo ufw allow 8080 && sudo ufw reload
서비스 시작 실패? 로그 확인: docker compose logs -f, 일반적인 원인은 키가 수정되지 않았거나 네트워크 문제이며, 재시작하면 됩니다: docker compose restart
서비스 업데이트docker compose pull
docker compose up -d

고급: Claude Code 외의 AI 에이전트도 같은 주거 IP VPS에서 실행하기

CRS가 작동한 후, 이 주거 IP VPS의 가치는 단순한 중계소에 그치지 않습니다. 동일한 IP, 동일한 Docker 환경에서 동시에 실행할 수 있습니다：

AI 브라우저 에이전트（Claude Computer Use / Browser Use / OpenAI Operator 스타일 자가 호스팅 에이전트）——참고: 《AI 브라우저 에이전트를 7×24 운영하는 방법》
n8n / Dify / MCP 서버 자가 호스팅 자동화
다중 계정 TikTok / Instagram 운영（一 대 VPS = 한 계정）

주거 IP VPS는 2026년 AI 개발자들이 가장 과소평가하는 "인프라 원클릭 잠금 해제 카드"입니다——한 번의 배포로 여러 시나리오에서 공유할 수 있습니다.

지금 시작하세요 → VoyraCloud 주거 IP 추천

VoyraCloud 주거 IP VPS 구매 클릭

주거 IP는 현재 Claude를 사용하는 가장 안정적이고 안전한 솔루션으로, 강력히 추천합니다!