BenedictKing/ccx

English | 简体中文

CCX는 Claude, OpenAI Chat, OpenAI Images, Codex Responses, 그리고 Gemini를 위한 고성능 AI API 프록시 (Proxy) 및 프로토콜 변환 게이트웨이 (Gateway)입니다. 통합 엔트리포인트 (Entrypoint), 내장 웹 관리 기능, 채널 오케스트레이션 (Orchestration), 페일오버 (Failover), 멀티 키 관리 (Multi-key management), 그리고 모델 라우팅 (Model routing)을 제공합니다.

• 단일 포트 배포가 가능한 통합 백엔드 (Backend) + 프론트엔드 (Frontend) 아키텍처
• PROXY_ACCESS_KEY를 이용한 이중 키 인증 및 선택 사항인 ADMIN_ACCESS_KEY 지원
• 채널 관리, 테스트, 로그 및 모니터링을 위한 웹 관리 콘솔 (Web admin console)
• Claude Messages, OpenAI Chat Completions, OpenAI Images, Codex Responses, 그리고 Gemini API 지원
• 우선순위, 프로모션 윈도우 (Promotion windows), 상태 확인 (Health checks), 페일오버 (Failover), 그리고 회로 복구 (Circuit recovery)를 포함한 스마트 스케줄링 (Smart scheduling)
• 채널별 API 키 로테이션 (Rotation), 프록시 (Proxy) 지원, 커스텀 헤더 (Custom headers), 모델 허용 목록 (Model allowlists), 그리고 라우트 접두사 (Route prefixes)
• 멀티 턴 (Multi-turn) 워크플로우를 위한 응답 세션 추적 (Responses session tracking)
• 간단한 바이너리 (Binary) 배포를 위한 임베디드 프론트엔드 에셋 (Frontend assets)

드래그 앤 드롭 (Drag-and-drop) 우선순위 조정 및 실시간 상태 모니터링을 통한 시각적 채널 관리.

다양한 업스트림 (Upstream) 서비스 유형과 유연한 API 키, 모델 매핑, 그리고 요청 파라미터 (Request parameter) 설정을 지원합니다.

채널별 요청 트래픽, 성공률, 그리고 지연 시간 (Latency)에 대한 실시간 모니터링.

CCX는 하나의 백엔드 엔트리포인트를 노출합니다:

Client -> backend :3000 ->
|- / -> Web UI
|- /api/* -> Admin API
...

이미지 (Images) 엔드포인트 (Endpoints)에는 현재 다음이 포함됩니다:

POST /v1/images/generations

POST /v1/images/edits

POST /v1/images/variations

상세 설계는 ARCHITECTURE.md를 참조하세요.

• Releases에서 최신 바이너리를 다운로드하세요.
• 바이너리 옆에 .env 파일을 생성하세요:

PROXY_ACCESS_KEY=your-proxy-access-key
PORT=3000
ENABLE_WEB_UI=true
...

• 바이너리를 실행하고 http://localhost:3000을 여세요.

Windows에서 클라이언트가 cmd, PowerShell, WSL 또는 Docker에서 실행 중이고 localhost가 CCX에 도달하지 않는 경우, 대신 Windows 호스트 IPv4 주소를 사용하세요 (예: http://192.168.1.23:3000). CCX는 기본적으로 :PORT를 통해 모든 인터페이스에서 대기합니다.

Docker 없이 백그라운드에서 시작하려면 Service Startup (서비스 시작)을 참조하세요.

docker run -d \
--name ccx \
-p 3000:3000 \
...

Docker Compose를 사용하여 백그라운드에서 실행:

docker compose up -d

Watchtower 자동 업데이트 활성화:

docker compose -f docker-compose.yml -f docker-compose.watchtower.yml up -d

필요한 경우 설정 직후 최신 이미지를 가져오기 (Pull):

docker compose pull ccx
docker compose up -d ccx

git clone https://github.com/BenedictKing/ccx
cd ccx
cp backend-go/.env.example backend-go/.env
...

유용한 명령어:

make dev
make run
make build
...

PORT=3000
ENV=production
ENABLE_WEB_UI=true
...

• Web UI:
  GET /

• Health (상태 확인):
  GET /health

• Admin API (관리자 API):
  /api/*

• Claude Messages (Claude 메시지):
  POST /v1/messages

• OpenAI Chat (OpenAI 채팅):
  POST /v1/chat/completions

• Codex Responses (Codex 응답):
  POST /v1/responses

• OpenAI Images (OpenAI 이미지):
  POST /v1/images/generations

,POST /v1/images/edits

,POST /v1/images/variations

• Gemini:
  POST /v1beta/models/{model}:generateContent

• Models API (모델 API):
  GET /v1/models

권장되는 로컬 워크플로우 (Workflow):

make dev

프론트엔드 (Frontend) 전용:

cd "frontend"
bun install
bun run dev

백엔드 (Backend) 전용:

cd "backend-go"
make dev

• README.zh-CN.md
• backend-go/README.md
• ARCHITECTURE.md
• DEVELOPMENT.md
• ENVIRONMENT.md
• docs/service/README.md - non-Docker 서비스 시작
• RELEASE.md

토론을 위해 QQ 그룹에 참여하세요: 642217364

MIT