CLIProxyAPI/DOCKER_DEPLOY.md

CLIProxyAPI Docker 배포 가이드

NAS(nas.gru.farm)에 Docker로 CLIProxyAPI를 배포하는 방법을 정리합니다.

사전 조건

항목	내용
NAS 접속	ssh airkjw@nas.gru.farm -p 22
Docker	sudo /usr/local/bin/docker (NOPASSWD)
Docker Compose	sudo /usr/local/bin/docker compose
NAS 내부 IP	192.168.0.17

1. 배포 디렉토리 준비

ssh airkjw@nas.gru.farm

# 배포 디렉토리 생성
mkdir -p ~/docker/cli-proxy-api
cd ~/docker/cli-proxy-api

2. 필요 파일 구성

NAS에 아래 파일들이 필요합니다:

~/docker/cli-proxy-api/
├── docker-compose.yml    # 컨테이너 설정
├── config.yaml           # 서비스 설정 (API 키, 포트 등)
├── auths/                # OAuth 인증 데이터 (자동 생성)
└── logs/                 # 로그 디렉토리 (자동 생성)

3. docker-compose.yml

로컬 빌드 방식 (소스에서 직접 빌드):

services:
  cli-proxy-api:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: cli-proxy-api
    ports:
      - "8317:8317"       # 메인 API 포트
      # 필요시 추가 포트 오픈
      # - "8085:8085"
    volumes:
      - ./config.yaml:/CLIProxyAPI/config.yaml
      - ./auths:/root/.cli-proxy-api
      - ./logs:/CLIProxyAPI/logs
    environment:
      - TZ=Asia/Seoul
    restart: unless-stopped

또는 공식 이미지 사용:

services:
  cli-proxy-api:
    image: eceasy/cli-proxy-api:latest
    container_name: cli-proxy-api
    ports:
      - "8317:8317"
    volumes:
      - ./config.yaml:/CLIProxyAPI/config.yaml
      - ./auths:/root/.cli-proxy-api
      - ./logs:/CLIProxyAPI/logs
    environment:
      - TZ=Asia/Seoul
    restart: unless-stopped

4. config.yaml 설정

config.example.yaml을 기반으로 작성합니다.

최소 설정 예시

# 서버 바인딩
host: ""
port: 8317

# API 키 (클라이언트 인증용, 원하는 값으로 설정)
api-keys:
  - "my-secret-api-key-1"

# 디버그 (초기 설정 시 true 권장, 안정화 후 false)
debug: false

# 로그를 파일로 기록
logging-to-file: true
logs-max-total-size-mb: 100

# 재시도 설정
request-retry: 3

Claude API 키 사용 시 추가

claude-api-key:
  - api-key: "sk-ant-xxxxx"
    # base-url: "https://api.anthropic.com"  # 기본값이므로 생략 가능

Gemini API 키 사용 시 추가

gemini-api-key:
  - api-key: "AIzaSy..."

Management UI 활성화 (웹 관리 패널)

remote-management:
  allow-remote: true
  secret-key: "my-management-password"
  disable-control-panel: false

5. 배포 실행

cd ~/docker/cli-proxy-api

# 공식 이미지 사용 시
sudo /usr/local/bin/docker compose up -d

# 소스 빌드 시 (Gitea에서 소스 가져와서)
git clone http://nas.gru.farm:3001/airkjw/CLIProxyAPI.git src
sudo /usr/local/bin/docker compose -f src/docker-compose.yml up -d --build

6. 확인

# 컨테이너 상태 확인
sudo /usr/local/bin/docker ps | grep cli-proxy-api

# 로그 확인
sudo /usr/local/bin/docker logs cli-proxy-api

# API 응답 테스트
curl http://localhost:8317/
curl http://192.168.0.17:8317/

# 모델 목록 확인 (API 키 인증)
curl -H "Authorization: Bearer my-secret-api-key-1" http://localhost:8317/v1/models

7. 클라이언트 연결

CLIProxyAPI가 실행되면 각 AI CLI 도구에서 프록시 주소로 연결합니다.

Claude Code에서 사용

# 환경변수 설정
export ANTHROPIC_BASE_URL=http://192.168.0.17:8317
export ANTHROPIC_API_KEY=my-secret-api-key-1

OpenAI 호환 클라이언트에서 사용

export OPENAI_BASE_URL=http://192.168.0.17:8317/v1
export OPENAI_API_KEY=my-secret-api-key-1

8. 관리 & 운영

# 컨테이너 중지
sudo /usr/local/bin/docker compose down

# 설정 변경 후 재시작
sudo /usr/local/bin/docker compose restart

# 이미지 업데이트 (공식 이미지 사용 시)
sudo /usr/local/bin/docker compose pull
sudo /usr/local/bin/docker compose up -d

# 로그 실시간 모니터링
sudo /usr/local/bin/docker logs -f cli-proxy-api

포트 목록

포트	용도	필수 여부
8317	메인 API	필수
8085	추가 API	선택
1455	추가 서비스	선택
54545	추가 서비스	선택
51121	추가 서비스	선택
11451	추가 서비스	선택

기본적으로 8317 포트만 열면 됩니다. 나머지는 특정 기능 사용 시 필요합니다.

주의사항

• config.yaml은 .gitignore에 포함되어 있어 Git에 커밋되지 않음 (API 키 보호)
• OAuth 인증(Claude, Gemini 등)은 최초 1회 브라우저 로그인 필요
• auths/ 디렉토리를 볼륨으로 마운트하면 컨테이너 재생성 시에도 인증 유지
• NAS 외부 접근 시 방화벽/포트포워딩 설정 필요