CPA-Helper is a local, self-hosted multi-user management panel designed for CLIProxyAPI users. It features independent API keys per user, isolated usage statistics, detailed request tracking, model pricing maintenance, available model querying, administrator account management, and Codex account inspection.

CPA‑Helper – CLIProxyAPI용 로컬 관리 대시보드

무엇인가요 – CPA‑Helper는 여러 사용자가 하나의 장소에서 CLIProxyAPI(CPA) 계정을 관리할 수 있는 자체 호스팅 웹 대시보드입니다. 사용량을 기록하고 비용 추정치를 표시하며, 관리자는 사용자 계정을 생성하거나 비활성화할 수 있으며, 사용자별 API 키 관리, 모델 가격 설정, Codex 인증 파일의 건강 상태 점검을 제공합니다. 모든 데이터는 로컬 SQLite에 저장됩니다.

핵심 기능

기능	수행 가능한 작업
사용 분석 및 비용 추정	전체, 사용자별, API 키별로 요청 수, 토큰 사용량, 지연 시간, 성공률 및 추정 USD 비용을 확인할 수 있습니다.
요청 추적	시간, 사용자, 모델, 엔드포인트, 키 설명 또는 실패 상태로 요청 로그를 필터링할 수 있습니다.
사용자 및 역할 관리	관리자는 사용자 생성, 비활성화, 이름 변경 및 "관리자" 또는 "일반 사용자" 역할 할당이 가능합니다.
잔액 및 키 일시 정지	사용자당 월별 및 평생 USD 잔액을 설정할 수 있으며, 잔액이 소진되면 사용자의 CPA 키가 자동으로 일시 정지됩니다.
API 키 라이프사이클	사용자는 키 생성, 편집, 복사, 삭제가 가능하며, 하위 CPA 서비스에 동기화할 수 있습니다. 각 키는 UI에서 실시간 요청으로 테스트할 수 있습니다.
모델 가격 카탈로그	입력/출력/캐시에 대한 100만 토큰당 가격 또는 이미지 모델에 대한 고정 가격을 저장할 수 있습니다. 가격은 비용 계산 및 잔액 차감에 사용됩니다.
카드숍 인덱스	공개된 카드숍 제품 스냅샷을 읽기 전용으로 브라우징할 수 있습니다. 거래용이 아니라 참고용입니다.
사용 가능한 모델 보기	연결된 CPA 키가 접근 가능한 모델을 쿼리하고, 로컬 가격 데이터를 겹쳐 표시할 수 있습니다.
Codex 인증 파일 검사	크론 작업을 스케줄링하여 Codex 인증 파일을 스캔하고, 할당량 한도를 강제하며, 계정 우선순위를 조정할 수 있습니다.
로컬 우선 저장소	모든 데이터는 `data/` 폴더 내 SQLite 파일에 저장됩니다 (또는 `CPA_HELPER_DATA_DIR` 환경 변수로 커스텀 디렉터리 지정 가능).
현대적인 UI	Vue 3 + Naive UI로 구축, 라이트/다크/시스템 테마, 차트(ECharts), 아이콘을 지원합니다.

아키텍처 개요

백엔드 – Go(표준 라이브러리 HTTP 서버) + SQLite(modernc.org/sqlite를 통해). /api/* 경로의 API 라우트 처리, 내장 Goose를 사용한 마이그레이션 실행, 선택적으로 CPA 사용 큐를 풀링합니다.
프론트엔드 – Vue 3 + Vite + TypeScript, Naive UI, ECharts, lucide‑vue‑next 사용.
데이터 – SQLite 데이터베이스 data/db/cpa_helper.sqlite3; 전체 data/ 폴더는 Git에서 무시됩니다.
통합 포인트 – CPA 관리 스타일 엔드포인트(사용 큐, 키 생성/삭제, 자격 증명 쿼리)만 호출합니다. 실제 모델 요청은 프록시하지 않으며, 에이전트에서 CPA로 직접 전달됩니다.

시작하기 (빠른 시작)

1. Docker-Compose (권장)

services:
  cpa-helper:
    image: walkingd/cpa-helper:latest
    container_name: cpa-helper
    restart: always
    network_mode: host   # http://127.0.0.1:18317 노출
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./data:/app/data

docker compose pull
docker compose up -d   # UI는 http://127.0.0.1:18317에서 사용 가능

처음 방문 시 초기 관리자 계정 생성 절차가 안내됩니다.

2. 소스에서 실행

백엔드

cd backend
go mod download
go run ./cmd/cpa-helper   # 마이그레이션 실행 후 :18317에서 제공
# 헬스 체크
curl http://127.0.0.1:18317/api/health

프론트엔드 (개발 모드)
```
cd frontend
npm install
npm run dev   # 기본적으로 http://127.0.0.1:5173
```
백엔드가 18317를 사용 중이라면, npm run dev 전에 CPA_HELPER_PROXY_TARGET를 다른 포트로 설정하세요.

단일 서비스 빌드 (백엔드가 정적 파일 제공)

cd frontend && npm run build   # frontend/dist 생성
cd ../backend && go run ./cmd/cpa-helper   # :18317에서 UI + API 제공

설정 요약

CLIProxyAPI / CPAMC URL – 기본값 http://127.0.0.1:8317; 시스템 설정에서 변경 가능.
관리 키 – CPA의 관리 API를 호출하기 위해 필요합니다.
로컬 수집기 – 활성화 시 백엔드가 CPA 큐에서 사용 이벤트를 가져와 SQLite에 기록합니다.
잔액 – 기본적으로 무제한입니다. 관리자는 월별/생애 주기 USD 제한을 설정할 수 있습니다. 잔액 소진 시 사용자의 CPA 키가 일시 정지됩니다.
모델 가격 – 토큰 기반(1M 토큰당 USD) 또는 이미지 모델의 고정 가격; LiteLLM에서 동기화 가능.
데이터 디렉터리 – CPA_HELPER_DATA_DIR를 설정하여 기본 ./data를 재정의할 수 있습니다.
Codex 검사 – 크론 표현식, 할당량 한도, 체크 전용 모드, 워커 수, 우선순위 규칙.

누가 사용할 수 있나요?

공유 CPA 서비스를 사용하는 여러 에이전트를 운영하는 팀으로, 사용자별 회계가 필요한 경우.
운영/DevOps 엔지니어로, 사용량을 모니터링하고 예산을 강제하며 API 키를 회전시키고 싶은 경우.
자체 호스팅 AI 스택(예: 사내 LLM 배포)의 관리자로, CLIProxyAPI 호환 인터페이스를 노출하는 경우.

라이선스

MIT – 자유롭게 사용, 수정, 재배포 가능.

결론: CPA‑Helper는 CLIProxyAPI/CPA 관리 인터페이스를 구현하는 모든 서비스를 위한 가벼운, Go 기반, Vue 프론트엔드 관리 콘솔입니다. 온프레미스 배포를 목적으로 하며, Go 1.25+, Node 20+, 실행 중인 CPA 엔드포인트만 필요하며, 모든 데이터를 로컬 SQLite에 저장합니다.

walkingddd/CPA-Helper