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. 배포 디렉토리 준비

```bash
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

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

```yaml
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
```

또는 공식 이미지 사용:

```yaml
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`을 기반으로 작성합니다.

### 최소 설정 예시

```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 키 사용 시 추가

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

### Gemini API 키 사용 시 추가

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

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

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

## 5. 배포 실행

```bash
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. 확인

```bash
# 컨테이너 상태 확인
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에서 사용

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

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

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

## 8. 관리 & 운영

```bash
# 컨테이너 중지
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 외부 접근 시 방화벽/포트포워딩 설정 필요

## 업데이트 이력

| 날짜 | 버전 | 비고 |
|------|------|------|
| 2026-04-26 | v6.9.38 | Protocol multiplexer + Redis queue 도입, 관리키/Redis AUTH 반복 실패 시 IP 차단 추가. 무중단 업데이트, 재인증 불필요 |
| 2026-04-23 | v6.9.34 | `docker compose pull && docker compose up -d`로 무중단 업데이트. Auth 파일 형식 변경 없어 재인증 불필요 |
| 2026-04-01 | v6.9.7 | 최초 배포 |

### 업데이트 절차

```bash
ssh airkjw@nas.gru.farm
cd /volume2/docker/CLIProxyAPI
sudo /usr/local/bin/docker compose pull
sudo /usr/local/bin/docker compose up -d
```

`auths/` 볼륨이 외부에 마운트되어 있어 컨테이너 교체 시 OAuth 토큰이 유지됩니다.