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/` ディレクトリ内（または `CPA_HELPER_DATA_DIR` 環境変数でカスタムディレクトリ指定）の SQLite ファイルに保存されます。
モダンな 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