CPA Helper

<div align="center"> <img src="frontend/public/logo.png" alt="CPA-Helper Logo" width="104" height="104" /> <h1>CPA-Helper</h1> <p><strong>A local self-hosted multi-user admin panel for CLIProxyAPI</strong></p> <p>Usage analytics · Request tracing · User balances · API key management · Model pricing maintenance · Codex auth file inspection</p> <p> <strong>English</strong> <span> · </span> <a href="README.zh-CN.md">中文</a> </p> <p> <a href="https://go.dev/"><img src="https://img.shields.io/badge/Go-1.25+-00ADD8?logo=go&logoColor=white" alt="Go 1.25+" /></a> <a href="https://vuejs.org/"><img src="https://img.shields.io/badge/Vue-3.5+-42b883?logo=vuedotjs&logoColor=white" alt="Vue 3.5+" /></a> <a href="https://vitejs.dev/"><img src="https://img.shields.io/badge/Vite-5.4+-646cff?logo=vite&logoColor=white" alt="Vite 5.4+" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License" /></a> <a href="https://linux.do"><img src="https://shorturl.at/ggSqS" alt="LINUX DO" /></a> </p> </div>

---

CPA-Helper is a local self-hosted multi-user administration panel for CLIProxyAPI / CPA users. It centralizes usage analytics, request records, user accounts, API keys, model pricing, available models and Codex auth file inspection.

It separates API keys and usage data by user: each user can create and manage their own keys and inspect their own requests, tokens and cost statistics, while administrators can create or disable regular accounts and review global plus per-user usage. It is built with Go, SQLite, Vue 3 and Vite, with runtime data stored in the root-level data/ directory by default.

For clarity, model requests initiated by an Agent are still sent directly from that Agent to CPA. CPA-Helper does not proxy or relay those requests; it only calls CPA management-style interfaces such as the usage queue, API key creation and deletion, and credential management for usage views, key management and credential maintenance.

Table of Contents

• Features
• Screenshots
• Tech Stack
• Project Structure
• Requirements
• Quick Start
• Configuration
• Development and Checks
• Contributing
• Acknowledgements
• License

Features

• Usage analytics and cost estimation: Track requests, tokens, success rate, latency, model distribution and estimated cost from global, per-user and current-account views.
• Request record tracing: Admins can filter global request events by time, user, API key description, provider, model, endpoint and failure state; regular users inspect only their own account records.
• User and permission management: Provide administrator and regular-user views; admins can create or disable regular accounts and manage nicknames, login accounts, passwords and roles.
• User balances and automatic key pause: Users are unlimited by default; admins can configure monthly balance and lifetime balance, usage is priced in USD with current model prices, monthly balance is consumed first, and exhausted users only have their CPA API keys paused.
• API key lifecycle management: Each user can independently create, edit, copy and delete their own API keys and synchronize them to CPA, with usage counted per user and per-key request guidance plus live request testing.
• Model pricing maintenance: Maintain token-model input, output and cache prices in USD per million tokens; models whose name contains image are charged by a fixed USD price per successful request, with CPA model comparison for quickly filling LiteLLM / manual prices.
• Card shop index: Admins can browse real-time public card-shop and product snapshots, search by product title, use popular tags, sort results and favorite shops for faster lookup. This is only a public information index and does not participate in transactions.
• Available model aggregation: Query available models through the current account's bound CPA API keys and enrich them with local pricing data.
• CLIProxyAPI / CPAMC integration: Configure the service URL, management key, usage queue and local collector options to persist remote usage events into SQLite.
• Codex auth file inspection: Support Cron scheduling, quota thresholds, check-only mode, conditional scanning, concurrent workers, priority rules, account enable/disable and deletion.
• Local-first data storage: Use SQLite and the data/ directory by default, with CPA_HELPER_DATA_DIR available for overriding the runtime data path.
• Modern admin interface: Built with Vue 3, Naive UI, ECharts and lucide icons, with light, dark and system theme modes.

Screenshots

Admin

Usage dashboard

Admins can inspect global request volume, tokens, cost, trends and distributions by time range, user, model and endpoint.

Request records

Admins can filter global request events, while regular users can inspect records scoped to their own account, with drawer-based detail views.

User management

Admins can create or disable regular accounts, manage nicknames, roles and enabled status, and review per-user daily usage, monthly balance and lifetime balance.

Model pricing

Compare CPA's currently available models with the local price catalog, quickly price missing models, and recalculate historical request costs using the latest configured prices.

Card shop index

Browse public card-shop and product snapshots, search by product title, use popular tags, sort results and favorite shops for follow-up lookup.

System settings

Configure the CLIProxyAPI / CPAMC endpoint, model request URL, management key, local collector and polling options.

Account Inspection

Inspection settings

Configure Codex auth file inspection with Cron schedules, quota thresholds, conditional scanning, timeouts, retries, worker count and priority rules.

Account status

Review auth file health, quota windows, account types, priorities and the latest inspection actions.

Account Views

My usage

Each user can review their own requests, tokens, costs, trends, model usage and current balance state.

My records

Each user can inspect request events and details scoped to their own account, separated from other users.

API keys

Each account can independently create and manage its own API keys, review daily request, token, cost and balance summaries, and generate examples or run a live test request for each key.

Available models

Query available models through bound CPA API keys and display availability plus local pricing information.

Account settings

View the current signed-in account and update the password.

Tech Stack

• Backend: Go standard-library HTTP server, SQLite, robfig/cron and modernc.org/sqlite.
• Frontend: Vue 3, Vite, TypeScript, Vue Router, Naive UI, ECharts and lucide-vue-next.
• Runtime data: Stored in root-level data/ by default; the SQLite database is data/db/cpa_helper.sqlite3.
• API shape: The backend exposes /api/*; the Vite development server proxies API calls to http://127.0.0.1:18317.

Project Structure

CPA-Helper/
├── backend/                 # Go backend project
│   ├── cmd/cpa-helper/      # Application entrypoint
│   ├── internal/app/        # App composition, routes, business logic and database access
│   ├── internal/httpserver/ # HTTP server lifecycle and graceful shutdown
│   ├── internal/platform/   # External-system infrastructure adapters
│   ├── internal/security/   # Password, session and API-key security helpers
│   ├── migrations/          # Embedded goose SQLite migrations
│   ├── go.mod
│   └── go.sum
├── frontend/                # Vue + Vite frontend project
│   ├── src/                 # App, feature modules, shared utilities and styles
│   ├── public/              # Static assets
│   └── package.json         # Frontend dependencies and scripts
├── pictures/                # README screenshots
├── docs/                    # Reference documentation
├── data/                    # Runtime data, ignored by Git by default
├── VERSION                  # Shared app version for Docker tags and frontend display
├── README.md
├── README.zh-CN.md
└── LICENSE

Requirements

• Go 1.25 or newer.
• Node.js 20 or newer.
• npm.
• An accessible CLIProxyAPI / CPA service. The default URL is http://127.0.0.1:8317.

Quick Start

1. Docker Compose deployment (recommended)

Create docker-compose.yml in the deployment directory:

services:
  cpa-helper:
    image: walkingd/cpa-helper:latest
    container_name: cpa-helper
    restart: always
    # 如需改为bridge,需将容器内部端口 18317 映射至主机
    # 程序默认访问地址为 `http://127.0.0.1:18317`
    network_mode: host
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./data:/app/data

Then pull the image and start the service:

docker compose pull
docker compose up -d

Open:

http://127.0.0.1:18317

On first visit, the application guides you through creating the first administrator account.

2. Clone the repository

git clone <your-repo-url>
cd CPA-Helper

3. Start the backend

Run all backend commands from backend/:

cd backend
go mod download
go run ./cmd/cpa-helper

The binary also exposes explicit operationa