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