Skip to content

Home

Jump to bottom
seakee edited this page May 19, 2026 · 5 revisions

CPA-Manager Wiki

CPA-Manager is a Web UI for CLIProxyAPI. It helps manage CPA configuration, AI providers, auth files, quotas, logs, request monitoring, usage analytics, account inspection, and related operational tasks.

This wiki is the operational documentation hub. Use it to choose a deployment mode, configure Usage Service, solve reverse-proxy issues, and troubleshoot monitoring or data problems.

Start Here

Scenario Recommended guide
New deployment, simplest path Docker Deployment
Chinese Docker guide Docker 部署 CPA-Manager
Deploy without Docker Native Binary Deployment for CPA-Manager / Usage Service
中文二进制部署 二进制部署 CPA-Manager / Usage Service
Keep CPA-hosted /management.html CPA Panel Mode
Need persistent request monitoring or historical usage Usage Service Guide
中文 Usage Service 指南 Usage Service 使用指南
Put CPA and CPA-Manager behind one domain Reverse Proxying CPA and CPA-Manager Under a Single Domain
中文同域名反代指南 用同一个域名反代 CPA 与 CPA-Manager
Something is broken FAQ and Troubleshooting
中文常见问题 CPA-Manager 常见问题与解决方案

Choose a Deployment Mode

Mode Entry URL Best for Notes
Full Docker Mode http://<host>:18317/management.html New deployments, one entry point, fewer CORS issues Usage Service hosts the panel, stores CPA connection settings, and proxies CPA Management API.
CPA Panel Mode http://<cpa-host>:8317/management.html Existing CPA deployments that keep CPA-hosted panel loading Deploy Usage Service separately, then configure its browser-accessible URL in CPA-Manager configuration.
Native Binary Mode http://<host>:18317/management.html or external Usage Service URL Small VPS, no Docker, systemd management Same Usage Service behavior as Full Docker Mode, but runs as a native binary.
Frontend-only development Vite dev server or dist/index.html Local UI development Connect to CPA directly and optionally configure Usage Service.

Full Docker Mode does not include CPA itself. CPA still runs as the upstream service.

Feature Map

Area What CPA-Manager covers
Dashboard Connection state, backend version, quick health summary
Configuration Visual and source editing for CPA config, plus separate CPA-Manager settings
AI Providers Gemini, Codex, Claude, Vertex, OpenAI-compatible providers, and Ampcode
Auth Files Upload, download, delete, status, OAuth exclusions, model aliases, Project ID display
OAuth Provider login flows, including optional Gemini CLI Google Cloud Project ID handling
Quota Provider-specific quota views and account quota summaries
Request Monitoring Persisted KPIs, realtime request table, account/model/channel breakdowns, failure analysis
Model Pricing SQLite-backed model prices and LiteLLM price sync
API Key Aliases SQLite-backed aliases for usage/account attribution
Codex Account Inspection Batch probing and cleanup suggestions for Codex auth pools
Logs Incremental log reading and filtering
System Model list, version checks, local state tools

The wiki currently focuses on deployment, Usage Service, reverse proxying, and troubleshooting. Feature-specific UI behavior is summarized here and in the project README.

Usage Service Highlights

Usage Service is the long-running backend used for persistent usage analytics and request monitoring.

It provides:

  • SQLite-backed request event storage
  • Panel-compatible usage APIs
  • Model pricing APIs and price sync
  • JSONL / NDJSON export and import
  • Legacy usage JSON import when request-level details exist
  • CPA Management API proxying in Full Docker / Native Full mode
  • API Key alias storage
  • Auth attribution snapshots, including auth_project_id_snapshot

Collection mode:

auto -> subscribe -> HTTP usage queue -> RESP polling

Notes:

  • CPA v7.1.0+ is recommended.
  • CPA v7.0.7+ can use Redis Pub/Sub subscription when Usage Service can reach the CPA API port.
  • CPA v6.10.8+ provides the HTTP usage queue endpoint for normal HTTP reverse proxies.
  • RESP mode must directly reach the CPA API port and cannot pass through a regular HTTP reverse proxy.
  • Only one Usage Service should consume the same CPA usage queue.

Read more:

Reverse Proxy

Use the reverse-proxy guides when CPA and CPA-Manager share one domain, or when Usage Service sits behind Nginx, Caddy, Cloudflare, or another proxy.

Common route shape:

https://example.com/management.html      -> CPA panel
https://example.com/cpam/                -> CPA-Manager Usage Service
https://example.com/v0/management        -> CPA Management API

Keep these URLs conceptually separate:

  • Browser-accessible URL
  • CPA internal service URL
  • Usage Service URL
  • Reverse proxy upstream URL

Read more:

Troubleshooting

Start with the FAQ when:

  • Request monitoring is empty
  • /status shows collector errors
  • Usage Service returns 401
  • Docker rebuilds lose historical data
  • CPA Panel Mode has CORS errors
  • unsupported RESP prefix 'H' appears
  • Model pricing cannot sync
  • Codex inspection returns many 401 results
  • Reverse proxy or HTTPS routing behaves differently from browser access

Read:

Recommended Reading Order

For new users:

  1. Read the project README first.
  2. Choose Full Docker Mode unless you have a reason not to.
  3. Complete Docker Deployment or Docker 部署 CPA-Manager.
  4. Open /management.html, complete setup, and enable request monitoring if needed.
  5. Check FAQ and Troubleshooting if no data appears.

For existing CPA users:

  1. Keep your current CPA deployment.
  2. Deploy Usage Service with Docker or native binary.
  3. Open CPA's original /management.html.
  4. Configure Usage Service URL under Configuration -> CPA-Manager Configuration.
  5. Enable request monitoring if needed.

For reverse-proxy deployments:

  1. Choose whether the browser should enter through CPA, Usage Service, or a shared domain.
  2. Read the relevant reverse-proxy guide.
  3. Verify /health, /usage-service/info, /models, and /v0/management/* routes.
  4. Keep RESP mode on direct CPA API addresses only.

All Wiki Pages

Deployment

Usage Service

Reverse Proxy

FAQ

Project Links

Clone this wiki locally