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 是一個自架設的 Web 仪表板，允許多個使用者在一個地方管理他們的 CLIProxyAPI (CPA) 帳戶。它記錄使用情況、顯示成本估算，讓管理員可建立或停用使用者帳戶，並提供使用者級 API 金鑰管理、模型價格設定、以及 Codex 認證檔的健康檢查功能。所有資料均本地儲存在 SQLite 中。

核心功能

功能	可執行操作
使用分析與成本估算	查看請求次數、令牌使用量、延遲、成功率以及估算的美元成本——全域、按使用者或按 API 金鑰。
請求追蹤	按時間、使用者、模型、端點、金鑰描述或失敗狀態過濾請求日誌。
使用者與角色管理	管理員可建立、停用、重新命名使用者，並分配「管理員」或「一般」角色。
餘額與金鑰暫停	為每個使用者設定月度和終身美元餘額；餘額耗盡後，使用者的 CPA 金鑰將自動暫停。
API 金鑰生命週期	使用者可建立、編輯、複製、刪除金鑰，並同步至底層 CPA 服務。每個金鑰均可透過 UI 發起即時請求進行測試。
模型價格目錄	儲存每百萬令牌的價格（輸入、輸出、快取）或影像模型的固定每請求價格；價格用於計算成本和扣除餘額。
卡店索引	一個唯讀瀏覽器，用於檢視公開卡店產品快照——僅用於參考，不適用於交易。
可用模型檢視	查詢綁定 CPA 金鑰可存取的模型，並疊加本地價格資料。
Codex 認證檔檢查	安排 cron 任務掃描 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。
餘額 – 預設無限制；管理員可設定月度/終身美元上限。餘額耗盡後，使用者 CPA 金鑰將暫停。
模型價格 – 基於令牌（每百萬令牌美元）或影像模型的固定價格；可從 LiteLLM 同步。
資料目錄 – 若不想使用預設 ./data，可透過 CPA_HELPER_DATA_DIR 覆蓋。
Codex 檢查 – cron 表達式、配額閾值、僅檢查模式、工作執行緒數、優先權規則。

誰會使用它？

在共享 CPA 服務上運行多個代理的團隊，需要按使用者進行會計核算。
運維/DevOps 工程師，希望有一個簡單 UI 來監控使用情況、強制預算並輪換 API 金鑰。
自架設 AI 堆疊（如私有 LLM 部署）的管理員，其介面與 CLIProxyAPI 兼容。

許可證

MIT – 可自由使用、修改和重新分發。

總結：CPA‑Helper 是一個輕量級、Go 後端、Vue 前端的管理控制台，集中管理任何實作 CLIProxyAPI/CPA 管理介面的服務的分析、計費和憑證管理。專為本地部署設計，僅需 Go 1.25+、Node 20+ 和一個運行中的 CPA 端點，所有資料均本地儲存在 SQLite 中。

walkingddd/CPA-Helper