Willxup/cpa-usage-keeper

CPA Usage Keeper – 무엇을 하는 도구인가

목적 – CPA Usage Keeper는 AI 모델(OpenAI, Anthropic 등)과 통신하는 명령줄 프록시인 CLIProxyAPI (CPA) 용 모니터링 대시보드입니다. CPA가 전달하는 모든 요청을 기록하고, 데이터를 로컬 SQLite 데이터베이스에 저장하며, 웹 UI로 정보를 표시하여 지출 금액, 모델 응답 속도, API 키 할당량이 소진되는지 여부를 확인할 수 있습니다.

주요 기능

• 기록 영속성 – CPA 요청 로그는 SQLite에 기록되고 자동으로 백업됩니다.
• 비용 분석 – 모델, 공급자, API 키별로 사용량을 분류하고, 예상 비용과 캐시 적중률을 확인할 수 있습니다.
• 요청 진단 – 개별 요청 세부 정보를 보고 내보내고, 성공률, 첫 토큰까지의 시간(TTFT), 총 대기 시간과 같은 지표를 검사할 수 있습니다.
• 할당량 추적 – 각 자격 증명의 남은 할당량을 모니터링하고, 할당량 정보를 새로 고치고, 과거 할당량 변경 사항(예: Codex 할당량)을 확인할 수 있습니다.
• 읽기 전용 공유 – 팀원과 공유할 수 있는 범위가 지정된 읽기 전용 보기를 생성할 수 있습니다.
• 선택적 커뮤니티 순위 – 모델/자격 증명에 대한 커뮤니티 생성 순위를 가져옵니다.

배포 방식

• 공식 Docker-Compose 템플릿과 함께 제공되는 Docker 이미지(GHCR)로, 전체 CPA + Keeper 스택 또는 Keeper 전용 스택을 지원합니다.
• macOS용 Homebrew formula.
• 사전 빌드된 Linux 및 Windows 바이너리(Linux용 systemd 서비스 템플릿 포함).
• 모든 배포에는 로그인 비밀번호가 포함됩니다(기본적으로 인증 활성화).

일반적인 워크플로우

1. CPA 구성에서 사용 통계를 활성화합니다(observability.usage.usage-statistics-enabled: true).
2. Keeper를 배포합니다(Docker-Compose 권장). .env를 통해 CPA 기본 URL, CPA 관리 키, Keeper 로그인 비밀번호를 지정합니다.
3. http://<host>:8080을 열고 로그인합니다.
4. 대시보드에는 개요(총 요청 수, 비용), 실시간 진단(실시간 요청 속도), 사용량 분석(모델/API 키별 비용), 요청 이벤트(개별 호출 목록), 할당량 기록이 표시됩니다.

기술 개요

• 백엔드: Go 1.26 이상; HTTP API는 표준 라이브러리로 구축, SQLite로 영속화, CPA 사용량 및 할당량 데이터를 동기화하는 백그라운드 폴러가 있습니다.
• 프론트엔드: React + TypeScript, Go 서버에서 제공.
• 환경 변수(APP_HOST, APP_PORT, APP_BASE_PATH, TRUSTED_PROXY_CIDRS 등)를 통해 확장 가능.
• 고처리량 설정을 위한 선택적 Redis 큐 지원.

사용 대상

• 자체 호스팅 CPA 인스턴스를 운영하며 모델 지출과 할당량 상태에 대한 가시성이 필요한 팀.
• 커스텀 로깅을 구축하지 않고 AI API 사용량을 감사할 수 있는 빠르고 자체 포함된 UI를 원하는 개발자.
• Docker 또는 Homebrew 배포를 선호하고 가볍고 비밀번호로 보호된 대시보드를 원하는 운영 팀.

시작하기 – README의 "빠른 시작" 섹션에서 Docker-Compose 명령, Homebrew 설치 또는 바이너리 다운로드를 참조하세요. 프로젝트는 단위 테스트와 린팅을 실행하기 위한 make verify 타겟도 제공합니다.

---

모든 세부 사항은 저장소의 README에서 직접 가져온 것이며, 추가 기능은 추측되지 않습니다.