cpa-usage-keeper：從 README 拆解功能、設定與採用邊界
具有 SQLite 持久性和內建儀表板的獨立 CliProxyAPI 使用情況追蹤器。
秒懂
- 它是什麼？
- Standalone CliProxyAPI usage tracker with SQLite persistence and built-in dashboard.，本文以 README 可核對的功能、命令、版本與限制整理採用判斷。
- 適合誰用？
- CPA Usage Keeper 是 CLIProxyAPI 的配套工具，將用量資料持久化到 SQLite，並透過 Web 儀表板呈現，部署方式涵蓋 Docker Compose、Homebrew 和原生二進位。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 2 天前。
- 用什麼語言寫的？
- 主要是 Go（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月14日）與我們的分析，不構成法律意見。
開源專案深度解析
持久化 CLIProxyAPI 用量的儀表板
CPA Usage Keeper 是一個獨立的 Go 應用程式，連接 CLIProxyAPI（CPA）實例，並將用量資料儲存在 SQLite 中。它拉取 CPA 的設定和憑證資料，然後提供 Web 儀表板，用於檢視用量、成本、請求健康度、配額以及模型/API 統計。倉庫中的前端位於 web/ 目錄，使用 React 和 TypeScript，後端位於 cmd/server 和 internal/ 套件中。README 用「Every flow leaves a trace」作為專案標語，這與它作為 CPA 活動持久記錄的角色相符。
啟動前應先在 CPA 設定 usage-statistics-enabled: true，並確認多個 collector 都使用 subscription mode。接著在 .env 放入 CPA_BASE_URL 與 CPA_MANAGEMENT_KEY，再用 go run ./cmd/server/main.go 啟動後端，另開終端執行 npm --prefix ./web ci 與 npm --prefix ./web run dev -- --host 127.0.0.1。這些步驟可以把資料來源、API 連線和前端代理分開檢查。
在 cpa-usage-keeper 的實際核對中，第 1 節應保留這個專案名稱與對應的文件線索，並把觀察到的結果和 README 的宣告分開記錄。這樣才能知道問題出在設定、輸入、版本，還是工具本身沒有提供該能力。對 cpa-usage-keeper 而言，這項區分會影響後續的部署範圍、回滾方式與責任界線。核對時也要記下第 1 節提到的檔案、指令或設定鍵，讓下一次升級可以重現相同檢查。若輸出和文件不一致，應保留錯誤訊息、作業系統與執行版本，再針對 cpa-usage-keeper 的 issue 或 release 找對應變更。這種記錄方式讓功能判斷落在可觀察結果，而不是倉庫人氣。
儀表板追蹤和顯示的內容
根據 README，追蹤器記錄請求、token、成本、快取使用、成功率、RPM/TPM 和延遲，並支援按時間範圍、模型、API 金鑰、來源和結果進行篩選。它還支援檢查並匯出請求級事件，表格欄位可設定。分析檢視涵蓋用量趨勢、成本構成、模型/API 金鑰/AI 提供者組合、小時熱力圖和延遲診斷。還有針對 Auth Files 和 AI Providers 的監控區，包括健康檢查和配額重新整理。使用者也可以選擇參與社群排名，按總分、token、請求數、快取率、平均 TTFT/延遲或峰值 TPM/RPM 進行排名。
實際部署時，LOGIN_PASSWORD 的要求和 AUTH_ENABLED 的預設值會直接影響暴露面。SQLite 與未加密備份可能含原始資料，不能把瀏覽器端的脫敏畫面當成儲存層保護。WORK_DIR、BACKUP_INTERVAL 與 BACKUP_RETENTION_DAYS 也應配合磁碟容量觀察。
在 cpa-usage-keeper 的實際核對中，第 2 節應保留這個專案名稱與對應的文件線索，並把觀察到的結果和 README 的宣告分開記錄。這樣才能知道問題出在設定、輸入、版本，還是工具本身沒有提供該能力。對 cpa-usage-keeper 而言，這項區分會影響後續的部署範圍、回滾方式與責任界線。核對時也要記下第 2 節提到的檔案、指令或設定鍵，讓下一次升級可以重現相同檢查。若輸出和文件不一致，應保留錯誤訊息、作業系統與執行版本，再針對 cpa-usage-keeper 的 issue 或 release 找對應變更。這種記錄方式讓功能判斷落在可觀察結果，而不是倉庫人氣。
部署方式與推薦路徑
Docker Compose 是推薦的部署方式。倉庫提供了同時執行 CPA 和 Keeper 的完整堆疊範本，以及 CPA 已存在時的 Keeper-only 堆疊範本。兩者均支援 linux/amd64 和 linux/arm64。對於已存在 CPA 但偏好 Docker CLI 的部署，README 給出了 docker run 範例。macOS 上推薦使用 Homebrew，提供 tap 和服務。Linux 的 amd64 和 arm64 二進位可從 Releases 取得，並包含 systemd 服務範本。Windows 也提供 amd64 和 arm64 的 ZIP 包。登入保護預設啟用，因此啟動前應設定 LOGIN_PASSWORD。
在 cpa-usage-keeper 的實際核對中，第 3 節應保留這個專案名稱與對應的文件線索，並把觀察到的結果和 README 的宣告分開記錄。這樣才能知道問題出在設定、輸入、版本，還是工具本身沒有提供該能力。對 cpa-usage-keeper 而言，這項區分會影響後續的部署範圍、回滾方式與責任界線。核對時也要記下第 3 節提到的檔案、指令或設定鍵，讓下一次升級可以重現相同檢查。若輸出和文件不一致，應保留錯誤訊息、作業系統與執行版本，再針對 cpa-usage-keeper 的 issue 或 release 找對應變更。這種記錄方式讓功能判斷落在可觀察結果，而不是倉庫人氣。
關鍵設定變數
有兩個變數是必需的：CPA_BASE_URL，即伺服器端 CPA 地址；CPA_MANAGEMENT_KEY，用於讀取 CPA 管理 API。對於 Web 存取，APP_HOST 和 APP_PORT 控制監聽地址和連接埠（預設 8080），APP_BASE_PATH 可設定子路徑前綴。CPA_PUBLIC_URL 設定公開 CPA URL，用於返回連結和 CPAMC 框架信任。登入保護使用 AUTH_ENABLED（預設 true）、LOGIN_PASSWORD 和 AUTH_SESSION_TTL。時區和請求行為由 TZ、REQUEST_TIMEOUT 和 TLS_SKIP_VERIFY 設定。儲存和備份設定包括 WORK_DIR、LOG_LEVEL、BACKUP_ENABLED、BACKUP_INTERVAL 和 BACKUP_RETENTION_DAYS。README 說大多數其他設定可以保持預設。
在 cpa-usage-keeper 的實際核對中，第 4 節應保留這個專案名稱與對應的文件線索，並把觀察到的結果和 README 的宣告分開記錄。這樣才能知道問題出在設定、輸入、版本，還是工具本身沒有提供該能力。對 cpa-usage-keeper 而言，這項區分會影響後續的部署範圍、回滾方式與責任界線。核對時也要記下第 4 節提到的檔案、指令或設定鍵，讓下一次升級可以重現相同檢查。若輸出和文件不一致，應保留錯誤訊息、作業系統與執行版本，再針對 cpa-usage-keeper 的 issue 或 release 找對應變更。這種記錄方式讓功能判斷落在可觀察結果，而不是倉庫人氣。
安全與資料處理說明
README 指出，瀏覽器 API 會脫敏類似金鑰的欄位，但 SQLite 資料庫及其未加密備份包含原始資料。認證預設啟用；如果顯式停用，則必須在部署邊界限制存取，並在反向代理處終止公共 HTTPS。登入工作階段雜湊會持久化在 SQLite 中，直到登出或 TTL 到期。對於 CPAMC 嵌入，使用獨立的嵌入工作階段。Redis 收件匣訊息在成功後保留到當天，失敗後保留 7 天。每日維護期間，超過 90 個本地日曆日的原始 usage_events 會被移動到永久保留的 usage_events_archive 冷表。
在 cpa-usage-keeper 的實際核對中，第 5 節應保留這個專案名稱與對應的文件線索，並把觀察到的結果和 README 的宣告分開記錄。這樣才能知道問題出在設定、輸入、版本，還是工具本身沒有提供該能力。對 cpa-usage-keeper 而言，這項區分會影響後續的部署範圍、回滾方式與責任界線。核對時也要記下第 5 節提到的檔案、指令或設定鍵，讓下一次升級可以重現相同檢查。若輸出和文件不一致，應保留錯誤訊息、作業系統與執行版本，再針對 cpa-usage-keeper 的 issue 或 release 找對應變更。這種記錄方式讓功能判斷落在可觀察結果，而不是倉庫人氣。
授權條款
該專案以 MIT 授權開源，版權歸 Will（2026 年）所有。授權授予使用、複製、修改、合併、發布、分發、再授權和出售軟體副本的權利，前提是包含版權聲明和許可聲明。軟體按「原樣」提供，不附帶任何明示或暗示的擔保。README 沒有包含額外的保固或支援承諾。
在 cpa-usage-keeper 的實際核對中，第 6 節應保留這個專案名稱與對應的文件線索，並把觀察到的結果和 README 的宣告分開記錄。這樣才能知道問題出在設定、輸入、版本，還是工具本身沒有提供該能力。對 cpa-usage-keeper 而言，這項區分會影響後續的部署範圍、回滾方式與責任界線。核對時也要記下第 6 節提到的檔案、指令或設定鍵，讓下一次升級可以重現相同檢查。若輸出和文件不一致，應保留錯誤訊息、作業系統與執行版本，再針對 cpa-usage-keeper 的 issue 或 release 找對應變更。這種記錄方式讓功能判斷落在可觀察結果，而不是倉庫人氣。
編輯結論
CPA Usage Keeper 是 CLIProxyAPI 的配套工具，將用量資料持久化到 SQLite，並透過 Web 儀表板呈現，部署方式涵蓋 Docker Compose、Homebrew 和原生二進位。
社群筆記