CPA Usage KeeperはCLIProxyAPIの利用量をSQLiteで記録する

CPAの外側に置く記録層

CPA Usage KeeperはCLIProxyAPIの使用量を収集してSQLiteへ保存し、Webダッシュボードで費用、リクエスト健康度、クォータ、モデルやAPIキーの統計を見るためのスタンドアロンツールです。CPAの代替ではなく、CPAが持つ利用データを永続化・分析するコンパニオンです。

利用前にCPA側でusage-statistics-enabled: trueを有効にします。複数の収集器が一つのCPAを読む場合は、READMEの注意どおり全てをsubscription modeにそろえないと収集が停止したり不完全になったりします。

ダッシュボードの集計軸

保存されたデータは期間、モデル、API Key、source、resultで絞り込めます。リクエスト単位のイベントは列を設定して検査・エクスポートでき、使用傾向、費用構成、モデルとプロバイダーの組み合わせ、時間帯ヒートマップ、レイテンシ診断へ展開できます。Auth FilesとAI Providersの画面では利用量、ヘルス確認、クォータ更新を扱います。

コミュニティランキングはスコア、トークン、リクエスト、キャッシュ率、平均TTFTやレイテンシ、ピークTPM/RPMなどへの参加を選べます。ランキング共有が不要な環境では、オプトインの範囲と公開する集計値を先に決めます。

CPAとの接続設定

必須設定はCPA_BASE_URLとCPA_MANAGEMENT_KEYです。Webの待受はAPP_HOST、APP_PORT、サブパスはAPP_BASE_PATH、公開CPAの戻り先はCPA_PUBLIC_URLで指定します。認証はAUTH_ENABLEDが既定でtrueで、LOGIN_PASSWORDとAUTH_SESSION_TTLを組み合わせます。

リクエストのタイムアウトとTLS検証、作業ディレクトリ、ログレベル、バックアップの有無・間隔・保持日数も設定できます。CPA_MANAGEMENT_KEYは読み取り用途の権限と保管場所を確認し、公開ネットワークへ置く前にリバースプロキシとHTTPSの責任分界を決めます。

デプロイ経路と前提

推奨はDocker Composeです。CPAとKeeperを一緒に置くフルスタックと、既存CPAへKeeperだけを接続する構成が用意されています。linux/amd64とlinux/arm64をサポートし、Docker CLI、macOS Homebrew、LinuxとWindowsのamd64/arm64バイナリ、systemdテンプレートも選べます。

新規構成ではCPAの統計設定、Keeperのログインパスワード、データボリュームを同時に定義します。既存CPAへ接続する場合は、管理APIの到達性、キーの権限、時刻、リクエスト量の欠落を最小ケースで確認し、ダッシュボードの集計期間とCPA側の記録を照合します。

SQLiteに残る情報と保護

READMEは、ブラウザAPIではキーに似たフィールドを編集できても、SQLiteデータベースと暗号化されていないバックアップには元データが含まれると説明します。認証を無効にする場合は、デプロイ境界でアクセスを制限し、公開HTTPSをリバースプロキシで終端する必要があります。セッションハッシュはログアウトまたはTTLまでSQLiteに残ります。

Redisの受信箱メッセージ、90日を超えたusage_eventsのアーカイブなど保持挙動も確認します。ライセンスはMITですが、これは保存データの扱いを決めません。実データを入れる前にバックアップファイルの権限、復元時のパスワード、削除手順を実測してください。

収集の検証では、CPA側で成功、失敗、ストリーミング、キャッシュ利用を含むリクエストを発生させ、Keeperのイベント件数とトークン・費用集計を照合します。APIキー、モデル、AIプロバイダー、時刻フィルターを切り替えた結果が期待した行だけになるかを確認します。CPA_MANAGEMENT_KEYを無効化した場合のエラーと、Keeper再起動後の未送信データも観察します。SQLiteとバックアップを別の権限で保護し、LOGIN_PASSWORD、AUTH_SESSION_TTL、APP_BASE_PATHを設定したときのアクセス経路を外部から試験します。

CPA Usage Keeperの集計はCPAの原ログと突き合わせます。日付境界、タイムゾーン、バックアップ保持期間を変えた試験も行い、画面の数字だけを請求や監査の根拠にしません。

日次集計とリクエスト単位のイベントを同じ期間で比較します。Keeperのバックアップを別の作業ディレクトリへ復元し、認証を保ったまま画面が読めることを試します。

CPA Usage KeeperはCLIProxyAPIの利用量をSQLiteで記録するを受け入れる前に、README記載の入力、実行、出力を一つの記録へまとめます。成功した操作だけでなく、失敗した操作、未確認の機能、利用した版、設定値、保存したログの場所も残します。担当者が同じ環境を作り直し、同じ確認結果を再現できることを条件にします。性能や互換性について数値を扱う場合は、データ量、実行時間、エラー数、資源使用量を測定条件とともに記録します。READMEにない保証は採用理由へ加えず、未確認事項として次の検証に回します。

CPA Usage Keeperでは、画面の期間集計とイベント一覧を同じリクエスト群で照合します。バックアップの暗号化状態、保存先の権限、ログインセッションの期限も確認し、管理キーを含むログが残らないことを調べます。

編集部の結論

CLIProxyAPIを運用し、モデル別のトークン、費用、レイテンシ、認証ファイルの状態を一か所で追いたい利用者に向きます。CPAなしで単独利用するものではなく、SQLiteとバックアップに原データが残る点を無視できません。まずusage-statistics-enabled: trueを確認し、CPA_MANAGEMENT_KEYとCPA_BASE_URLを限定環境で設定して、収集、集計、ログイン保護、バックアップ復元を試してください。

公式情報源

1. Official README
2. Project repository
3. Release notes