[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-79124":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":27,"readmeContent":28,"aiSummary":29,"trendingCount":16,"starSnapshotCount":16,"syncStatus":30,"lastSyncTime":31,"discoverSource":32},79124,"CPA-Manager-Plus","seakee\u002FCPA-Manager-Plus","seakee","Management panel for CLI Proxy API with a Docker-ready Manager Server, SQLite usage analytics, request monitoring, model pricing, quota views, and Codex inspection.","",null,"TypeScript",668,73,22,17,0,18,356,632,235,9.61,"MIT License",false,"main",true,[],"2026-06-12 02:03:49","# CPA Manager Plus\n\n[中文文档](README_CN.md)\n\nA single-file Web UI for **CLI Proxy API (CPA)** plus a **Manager Server** for persistent usage analytics and panel hosting.\n\nSince v6.10.0, CPA no longer includes built-in usage statistics. This project now supports usage analytics through a long-running Manager Server that consumes the CPA usage queue, persists request events to SQLite, and exposes panel-compatible usage APIs.\n\nCPA Manager Plus is the recommended successor to CPA-Manager. It combines the CPA management panel with a Docker-ready Manager Server, admin-key protected full-panel mode, encrypted CPA Management Key storage, server-backed analytics, model pricing, API key aliases, dashboard cards, and Codex account inspection.\n\n- **CPA Main project**: https:\u002F\u002Fgithub.com\u002Frouter-for-me\u002FCLIProxyAPI\n- **Recommended CPA version**: >= v7.1.0\n- **Minimum CPA version for HTTP usage queue**: >= v6.10.8\n\n## Panel Preview\n\n![Home dashboard showing traffic overview, collector status, usage metrics, health alerts, and version information](img\u002Fhome.jpg)\n![Monitoring center showing usage analytics, realtime request events, account overview, API key breakdowns, and model cost statistics](img\u002Fmonitoring.jpg)\n![Codex account inspection showing probe progress, account status, cleanup recommendations, and execution logs](img\u002Fcodex-inspection.png)\n\n## What This Provides\n\n- A single-file React management panel for CPA Management API (`\u002Fv0\u002Fmanagement`)\n- A Dockerized Manager Server for SQLite-backed usage persistence and built-in panel hosting\n- Native `amd64` and `arm64` packages for Windows, macOS, and Linux with the panel embedded\n- Two deployment modes:\n  - **Full Docker mode**: open the built-in panel from Manager Server; first startup logs an admin key, first setup uses that admin key to save the CPA connection, and later logins use the admin key to manage the whole panel\n  - **CPA panel mode**: keep using CPA's `\u002Fmanagement.html`, then configure a separately deployed Manager Server inside the panel\n- Runtime monitoring, account\u002Fmodel\u002Fchannel breakdowns, model pricing, estimated token cost, imports\u002Fexports, auth-file operations, quota views, logs, config editing, and system utilities\n\n## Choose a Deployment Mode\n\n| Mode | Entry URL | What the user configures | Best for |\n|---|---|---|---|\n| Full Docker mode | `http:\u002F\u002F\u003Chost>:18317\u002Fmanagement.html` | First startup log provides the admin key; first setup: admin key + CPA URL + CPA Management Key; later login: admin key | New deployments, one entry point, least browser\u002FCORS complexity |\n| CPA panel mode | `http:\u002F\u002F\u003Ccpa-host>:8317\u002Fmanagement.html` | Log in to CPA with the CPA Management Key first, then set the Manager Server URL under **Configuration -> CPA Manager Plus Configuration** | Existing CPA automatic panel loading |\n| Frontend only | Vite dev server or `apps\u002Fweb\u002Fdist\u002Findex.html` | CPA URL, optionally Manager Server URL | Development |\n\nFull Docker mode does not bundle CPA itself. CPA still runs as the upstream service; the Docker image provides the Manager Server plus an embedded copy of this management panel.\n\n## CPA Prerequisites\n\nRequest statistics require the CPA usage queue:\n\n- CPA Management must be enabled because the usage queue uses the same availability and CPA Management Key as `\u002Fv0\u002Fmanagement`.\n- Request monitoring requires CPA usage publishing: set `usage-statistics-enabled: true`, or submit `{ \"value\": true }` to `PUT \u002Fusage-statistics-enabled`. CPA Manager Plus enables this automatically when request monitoring is enabled during setup or configuration save.\n- Disabling CPAM request monitoring only stops the Manager Server collector. It does not automatically disable CPA usage publishing or clear the CPA usage queue. If CPA usage publishing remains enabled, re-enabling request monitoring within the queue retention window may collect events retained while the collector was stopped.\n- CPA `v7.1.0+` is recommended for current panel capabilities. CPA `v6.10.8+` already exposes the HTTP usage queue endpoint `\u002Fv0\u002Fmanagement\u002Fusage-queue`, which can pass through regular HTTP reverse proxies.\n- Manager Server `auto` mode tries RESP Pub\u002FSub (`subscribe`) first, then the HTTP usage queue, then RESP pop mode for older CPA versions. RESP transports listen on the CPA API port, usually `8317`, and cannot pass through a regular HTTP reverse proxy.\n- CPA keeps queue items in memory for `redis-usage-queue-retention-seconds`, default `60` seconds and maximum `3600` seconds. Keep Manager Server running continuously.\n- Manager Server `pollIntervalMs` must be less than or equal to the CPA queue retention window converted to milliseconds. Saves are rejected when the collector would poll too slowly and risk expired queue items.\n- Exactly one Manager Server should consume the same CPA usage queue.\n\n## Architecture\n\n### Full Docker Mode\n\n```text\nBrowser\n  -> Manager Server :18317\n      -> built-in management.html\n      -> \u002Fv0\u002Fmanagement\u002Fusage and \u002Fv0\u002Fmanagement\u002Fmodel-prices from SQLite\n      -> other \u002Fv0\u002Fmanagement\u002F* proxied to CPA\n      -> HTTP\u002FRESP\u002FPubSub consumer -> CPA API port\n      -> SQLite \u002Fdata\u002Fusage.sqlite\n```\n\nOn first startup, if `CPA_MANAGER_ADMIN_KEY` \u002F `CPA_MANAGER_ADMIN_KEY_FILE` is not provided, Manager Server generates a `cmp_admin_...` admin key and prints it to the startup log only once. The login page calls `GET \u002Fusage-service\u002Finfo` and detects that it is hosted by Manager Server. If the response is not configured yet, it shows the setup wizard: you first enter the admin key, then the CPA URL, CPA Management Key, and choose whether to enable request monitoring. When monitoring is enabled, you also set the collector polling interval; Manager Server validates the CPA Management API, enables CPA usage publishing, checks that the poll interval does not exceed the CPA queue retention window, stores CPA Manager Plus configuration in SQLite, starts the collector with the configured mode (`auto` by default: RESP Pub\u002FSub, then HTTP queue, then RESP pop fallback), and serves the panel from the same origin. When monitoring is disabled, the CPA connection is still saved for Management API proxying, but CPA usage publishing and the collector stay off.\n\nAfter Manager Server is configured, a new browser opening the same URL uses the normal login form. Full Docker mode uses the admin key as the login credential; the CPA Management Key is stored server-side and is only used by Manager Server when it talks to CPA upstream.\n\n### CPA Panel Mode\n\n```text\nBrowser\n  -> CPA \u002Fmanagement.html\n      -> normal CPA Management API calls stay on CPA\n      -> usage calls go to configured Manager Server URL\n\nManager Server\n  -> HTTP\u002FRESP\u002FPubSub consumer -> CPA API port\n  -> SQLite \u002Fdata\u002Fusage.sqlite\n```\n\nUse this when CPA still auto-downloads and serves the panel. This mode is served by CPA, so it does not show the full Docker setup wizard and does not require the user to enter the Manager Server admin key inside the CPA panel. Request monitoring is optional; when Manager Server is not deployed, the panel hides the request monitoring entry and direct visits to the monitoring page show a setup hint. To use request monitoring, log in to CPA with the CPA Management Key first, deploy Manager Server separately, then open **Configuration -> CPA Manager Plus Configuration**, enable it, enter the Manager Server URL, and save. This is a subtractive version of full Docker mode: no hosted primary entry point, no initialization page, and no takeover of regular CPA management APIs.\n\n### Manager Server Backend\n\nThe Go backend lives under the `github.com\u002Fseakee\u002Fcpa-manager-plus\u002Fapps\u002Fmanager-server` module. It still exposes the compatible `\u002Fusage-service\u002F*` management endpoints. Its request path follows a layered shape:\n\n```text\nmodel -> repository -> service -> controller -> router\n```\n\n- `internal\u002Fmodel` defines persisted and API-facing data structures.\n- `internal\u002Frepository` owns SQLite access and schema migration while keeping the existing tables compatible.\n- `internal\u002Fservice` contains setup, manager config, usage, model price, API key alias, proxy, panel, and collector lifecycle rules.\n- `internal\u002Fhttp\u002Fcontroller`, `internal\u002Fhttp\u002Fmiddleware`, and `internal\u002Fhttp\u002Frouter` keep HTTP decoding, CORS\u002Fauth\u002Frecovery, Gin routing, and response writing at the edge.\n- `internal\u002Fhttpapi` remains a compatibility wrapper for the current `cmd\u002Fcpa-manager-plus` entrypoint.\n- `internal\u002Fworker` coordinates collector startup\u002Frestart\u002Fstop without changing the existing HTTP, RESP Pub\u002FSub, RESP pop, and auto queue consumers.\n\n## Quick Start: Full Docker Mode\n\n### Container Images\n\nPublic multi-arch images are published to both registries:\n\n- Docker Hub: `seakee\u002Fcpa-manager-plus`\n- GitHub Container Registry: `ghcr.io\u002Fseakee\u002Fcpa-manager-plus`\n\n```bash\ndocker run -d \\\n  --name cpa-manager-plus \\\n  --restart unless-stopped \\\n  -p 18317:18317 \\\n  -v cpa-manager-plus-data:\u002Fdata \\\n  seakee\u002Fcpa-manager-plus:latest\n```\n\nOpen:\n\n```text\nhttp:\u002F\u002F\u003Chost>:18317\u002Fmanagement.html\n```\n\nOn first setup, enter:\n\n- Admin key: `CPA Manager Plus admin key generated: cmp_admin_...` from the first startup log\n- CPA URL:\n  - Docker Desktop host CPA: `http:\u002F\u002Fhost.docker.internal:8317` (default suggestion unless the panel was built with `VITE_DEFAULT_CPA_BASE_URL`)\n  - Same compose network: `http:\u002F\u002Fcli-proxy-api:8317`\n  - Remote CPA: `https:\u002F\u002Fyour-cpa.example.com`\n- CPA Management Key\n\nYou can read the generated admin key with `docker logs cpa-manager-plus`. After setup, the same entry URL uses the saved CPA connection from Manager Server SQLite. New browsers only need the admin key on the login page.\n\nThe published image supports `linux\u002Famd64` and `linux\u002Farm64`. Docker examples use Docker Hub by default. To pull from GitHub Container Registry instead, replace `seakee\u002Fcpa-manager-plus:latest` with `ghcr.io\u002Fseakee\u002Fcpa-manager-plus:latest`.\n\n### Native Packages\n\nGitHub Releases also provide native packages with the panel embedded:\n\n- `cpa-manager-plus_\u003Cversion>_linux_amd64.tar.gz`\n- `cpa-manager-plus_\u003Cversion>_linux_arm64.tar.gz`\n- `cpa-manager-plus_\u003Cversion>_darwin_amd64.tar.gz`\n- `cpa-manager-plus_\u003Cversion>_darwin_arm64.tar.gz`\n- `cpa-manager-plus_\u003Cversion>_windows_amd64.zip`\n- `cpa-manager-plus_\u003Cversion>_windows_arm64.zip`\n\nmacOS\u002FLinux:\n\n```bash\ntar -xzf cpa-manager-plus_vX.Y.Z_linux_amd64.tar.gz\ncd cpa-manager-plus_vX.Y.Z_linux_amd64\n.\u002Fcpa-manager-plus\n```\n\nThe tar archives preserve execute permissions, so no extra `chmod +x` is normally required after extraction. If macOS blocks the unsigned binary, run `xattr -dr com.apple.quarantine .` in the extracted directory and start it again.\n\nWindows PowerShell:\n\n```powershell\nExpand-Archive .\\cpa-manager-plus_vX.Y.Z_windows_amd64.zip -DestinationPath .\ncd .\\cpa-manager-plus_vX.Y.Z_windows_amd64\n.\\cpa-manager-plus.exe\n```\n\nYou can double-click `cpa-manager-plus.exe` on Windows, but PowerShell is recommended because it keeps logs and startup errors visible.\n\nThen open:\n\n```text\nhttp:\u002F\u002F\u003Chost>:18317\u002Fmanagement.html\n```\n\nNative packages do not include CPA itself. Run CPA separately, then enter the admin key, CPA URL, and CPA Management Key during first setup. After setup, the login page only needs the admin key. Set `USAGE_DATA_DIR` or `USAGE_DB_PATH` only when you want to override the default data location.\n\nOn first start, if `USAGE_DATA_DIR` and `USAGE_DB_PATH` are not set, the native package creates `config.json` next to the binary and writes SQLite data to `data\u002Fusage.sqlite` in the same directory. The extracted package directory therefore contains both the program and its user data.\n\n### Docker Compose\n\n```yaml\nservices:\n  cpa-manager-plus:\n    image: seakee\u002Fcpa-manager-plus:latest\n    restart: unless-stopped\n    ports:\n      - \"18317:18317\"\n    volumes:\n      - cpa-manager-plus-data:\u002Fdata\n\nvolumes:\n  cpa-manager-plus-data:\n```\n\nStart:\n\n```bash\ndocker compose up -d\n```\n\nTo use GitHub Container Registry, replace the compose image with `ghcr.io\u002Fseakee\u002Fcpa-manager-plus:latest`.\n\n### Linux Host CPA\n\nIf CPA runs directly on a Linux host and Manager Server runs in Docker, add a host gateway:\n\n```bash\ndocker run -d \\\n  --name cpa-manager-plus \\\n  --restart unless-stopped \\\n  --add-host=host.docker.internal:host-gateway \\\n  -p 18317:18317 \\\n  -v cpa-manager-plus-data:\u002Fdata \\\n  seakee\u002Fcpa-manager-plus:latest\n```\n\nThen enter `http:\u002F\u002Fhost.docker.internal:8317` as the CPA URL during first setup.\n\n## Quick Start: CPA Panel Mode\n\n1. Start CPA as usual and open:\n\n   ```text\n   http:\u002F\u002F\u003Ccpa-host>:8317\u002Fmanagement.html\n   ```\n\n   Log in to CPA with the CPA Management Key. This entry is served by CPA and does not use the full Docker setup wizard.\n\n2. Deploy Manager Server:\n\n   ```bash\n   docker run -d \\\n     --name cpa-manager-plus \\\n     --restart unless-stopped \\\n     -p 18317:18317 \\\n     -v cpa-manager-plus-data:\u002Fdata \\\n     seakee\u002Fcpa-manager-plus:latest\n   ```\n\n3. In the CPA panel, go to:\n\n   ```text\n   Configuration -> CPA Manager Plus Configuration\n   ```\n\n4. Enable it and enter:\n\n   ```text\n   http:\u002F\u002F\u003Cmanager-server-host>:18317\n   ```\n\n5. Save the CPA Manager Plus configuration.\n\nThe panel sends the current CPA URL and CPA Management Key to the Manager Server. After that, monitoring reads usage data from the Manager Server while other management calls continue to use CPA. In this external mode, Manager Server endpoints accept the CPA Management Key for compatibility; full Docker mode still uses the admin key.\n\n## Build Locally\n\n```bash\ndocker compose -f docker-compose.manager.yml up --build\n```\n\nThis builds the React panel and embeds it into the Go Manager Server binary.\n\n## Manager Server Configuration\n\nMost users can configure CPA URL, CPA Management Key, request monitoring enablement, collection mode, and polling interval from **Configuration -> CPA Manager Plus Configuration**. CPA Manager Plus configuration is persisted in SQLite. Environment variables are mainly for first bootstrap and unattended deployments.\n\nThe variables below are Manager Server runtime settings. Frontend build-time settings are separate: `VITE_DEFAULT_CPA_BASE_URL` sets the default CPA URL shown by the Manager Server-hosted first setup wizard. When it is not set, the Docker-hosted panel suggests `http:\u002F\u002Fhost.docker.internal:8317`.\n\n| Variable | Default | Description |\n|---|---:|---|\n| `CPA_MANAGER_CONFIG` | empty | Optional config file path. When empty, native packages use `config.json` next to the binary |\n| `HTTP_ADDR` | `0.0.0.0:18317` | Manager Server HTTP listen address |\n| `USAGE_DB_PATH` | Docker: `\u002Fdata\u002Fusage.sqlite`; native: `.\u002Fdata\u002Fusage.sqlite` | SQLite database path |\n| `USAGE_DATA_DIR` | Docker: `\u002Fdata`; native: `.\u002Fdata` | Base data directory when `USAGE_DB_PATH` is not overridden |\n| `CPA_MANAGER_ADMIN_KEY` | empty | Optional admin key; when empty, first startup generates and logs one |\n| `CPA_MANAGER_ADMIN_KEY_FILE` | `\u002Frun\u002Fsecrets\u002Fcpa_admin_key` | Optional admin key file |\n| `CPA_MANAGER_DATA_KEY` | empty | Optional data encryption key; when empty, read or generate it through `CPA_MANAGER_DATA_KEY_PATH` |\n| `CPA_MANAGER_DATA_KEY_FILE` | `\u002Frun\u002Fsecrets\u002Fcpa_data_key` | Optional data encryption key file |\n| `CPA_MANAGER_DATA_KEY_PATH` | Docker: `\u002Fdata\u002Fdata.key`; native: `.\u002Fdata\u002Fdata.key` | Auto-generated data encryption key file path |\n| `CPA_UPSTREAM_URL` | empty | Optional CPA base URL for unattended startup |\n| `CPA_MANAGEMENT_KEY` | empty | Optional CPA Management Key for unattended startup |\n| `CPA_MANAGEMENT_KEY_FILE` | `\u002Frun\u002Fsecrets\u002Fcpa_management_key` | Optional file containing the CPA Management Key |\n| `USAGE_COLLECTOR_MODE` | `auto` | Collection mode: `auto` tries RESP Pub\u002FSub, then HTTP usage queue, then RESP pop fallback; `subscribe` forces RESP Pub\u002FSub; `http` forces HTTP; `resp` forces RESP pop |\n| `USAGE_RESP_QUEUE` | `usage` | RESP key argument; CPA currently ignores it, leave the default unless upstream changes |\n| `USAGE_RESP_POP_SIDE` | `right` | `right` uses `RPOP`; `left` uses `LPOP` |\n| `USAGE_BATCH_SIZE` | `100` | Maximum queue records per pop |\n| `USAGE_POLL_INTERVAL_MS` | `500` | Idle polling interval |\n| `USAGE_QUERY_LIMIT` | `50000` | Maximum recent events returned through compatible `\u002Fusage` |\n| `USAGE_CORS_ORIGINS` | `*` | Allowed browser origins for CPA panel mode |\n| `USAGE_RESP_TLS_SKIP_VERIFY` | `false` | Skip TLS verification for RESP connection |\n| `PANEL_PATH` | empty | Serve a custom `management.html` instead of the embedded one |\n\nStartup configuration precedence is: environment variables > `config.json` > program defaults. Relative paths in the config file are resolved from the config file directory. The generated default config is:\n\n```json\n{\n  \"httpAddr\": \"0.0.0.0:18317\",\n  \"dataDir\": \".\u002Fdata\"\n}\n```\n\nIf `CPA_MANAGER_ADMIN_KEY` is set, the service initializes the admin credential from that value and does not log a generated admin key. If `CPA_UPSTREAM_URL` and `CPA_MANAGEMENT_KEY` are set, collection starts automatically on boot and the connection is shown as environment-managed in the panel. Otherwise, use the full Docker setup flow; the result is saved to SQLite `settings.manager_config_v1`. The legacy `settings.setup` value is still written for compatibility and rollback.\n\n### CPA vs CPA Manager Plus Configuration Boundary\n\n- **CPA configuration**: `usage-statistics-enabled`, `redis-usage-queue-retention-seconds`, proxy, logging, routing, auth files, and related fields still belong to CPA and are managed by `\u002Fconfig` \u002F `\u002Fconfig.yaml`.\n- **CPA Manager Plus configuration**: CPA URL, CPA Management Key, request monitoring enablement, Manager Server collection mode, `pollIntervalMs`, `batchSize`, `queryLimit`, and the CPA panel mode Manager Server bootstrap URL are persisted in Manager Server SQLite.\n- The configuration panel shows CPA and CPA Manager Plus settings separately. Saving CPAM settings does not write to CPA `config.yaml`; enabling request monitoring calls CPA Management API to enable usage publishing, while disabling request monitoring only stops the CPAM collector.\n\n### Migration Guide\n\nWhen upgrading from the old CPA-Manager project, read [Migration from CPA-Manager](docs\u002Fmigration-from-cpa-manager.md) first. The core rules are:\n\n1. Stop the old backend service before backup, then back up the old `\u002Fdata` directory or Docker volume, including at least `usage.sqlite`, `usage.sqlite-wal`, and `usage.sqlite-shm`.\n2. Start CPA Manager Plus with the same old `\u002Fdata` volume, or copy the old data into the new `\u002Fdata`. The old project often used `cpa-manager-data`; the Plus examples use `cpa-manager-plus-data`. Do not accidentally start with an empty new volume.\n3. On first Plus startup, the service adds `settings.admin_credential_v1`, `settings.bootstrap_state_v1`, and `\u002Fdata\u002Fdata.key`. From this point forward, backups must include both SQLite files and `data.key`.\n4. Full Docker mode now logs in with the Manager Server admin key, not the CPA Management Key. Prefer setting `CPA_MANAGER_ADMIN_KEY` or `CPA_MANAGER_ADMIN_KEY_FILE` during migration; otherwise save the generated `cmp_admin_...` value from the first startup log.\n5. If an older version already saved CPA URL and CPA Management Key through `\u002Fsetup`, the service migrates from `settings.setup` to `settings.manager_config_v1` and rewrites the old plaintext CPA Management Key as encrypted storage during startup migration.\n6. If you use `CPA_UPSTREAM_URL` \u002F `CPA_MANAGEMENT_KEY`, the connection remains environment-managed. To switch to panel persistence, remove those environment variables, restart, and save from the panel.\n7. In CPA panel mode, the browser still needs the Manager Server URL before it can read that service's SQLite configuration. Once entered, the value is saved to SQLite and kept in local storage as bootstrap data.\n\n## Data and Security Notes\n\n- SQLite data is stored under `\u002Fdata`; mount it to persistent storage.\n- The admin key is not stored in plaintext. SQLite `settings.admin_credential_v1` stores only the salt and HMAC-SHA256 digest. An automatically generated admin key is printed to the first startup log once; use `CPA_MANAGER_ADMIN_KEY_FILE` with Docker Secret or an external secret manager for managed deployments.\n- CPA Management Key is encrypted with the data key before it is stored in SQLite `settings`, so collection and CPA Management API proxying can resume after restart.\n- The data key is provided by `CPA_MANAGER_DATA_KEY` \u002F `CPA_MANAGER_DATA_KEY_FILE`, or generated at `CPA_MANAGER_DATA_KEY_PATH`; Docker defaults to `\u002Fdata\u002Fdata.key` with `0600` permissions.\n- Data key security assessment: AES-GCM prevents a leaked SQLite file alone from directly exposing the CPA Management Key. If an attacker gets both `\u002Fdata\u002Fusage.sqlite` and `\u002Fdata\u002Fdata.key`, the CPA Management Key can still be decrypted. If the data key is lost, encrypted CPA Management Key values cannot be recovered and the CPA connection must be initialized or saved again.\n- New versions prefer SQLite `settings.manager_config_v1`; legacy `settings.setup` is kept as compatibility data.\n- Protect the `\u002Fdata` volume. It contains usage metadata, admin credential digest, the data key file, and the encrypted CPA Management Key.\n- Manager Server redacts key-like fields before storing raw JSON payload snapshots, but request metadata may still expose requested\u002Fresolved models, endpoints, account labels, project snapshots, and token usage.\n- RESP pop queue consumption is destructive. RESP Pub\u002FSub is streaming. Do not run multiple Manager Server consumers against the same CPA instance.\n- If Manager Server is down longer than CPA's queue retention window, that period's usage cannot be recovered without CPA-side persistence.\n- If only the CPAM collector is stopped while CPA usage publishing remains enabled, restarting the collector within the retention window may consume queue items produced while collection was disabled.\n\n## Runtime Endpoints\n\n| Endpoint | Purpose |\n|---|---|\n| `GET \u002Fhealth` | Basic health check |\n| `GET \u002Fstatus` | Collector, SQLite, event count, and error status |\n| `GET \u002Fusage-service\u002Finfo` | Allows the frontend to detect full Docker mode and read `configured` for setup vs login flow |\n| `GET \u002Fusage-service\u002Fconfig` | Reads persistent CPA Manager Plus configuration and CPA usage publishing status |\n| `PUT \u002Fusage-service\u002Fconfig` | Saves CPA Manager Plus configuration and restarts the collector when needed |\n| `POST \u002Fsetup` | Protected by the admin key; saves CPA URL + CPA Management Key and starts collection |\n| `GET \u002Fv0\u002Fmanagement\u002Fusage` | Compatible usage payload for the panel |\n| `GET \u002Fv0\u002Fmanagement\u002Fusage\u002Fexport` | Export usage events as JSONL |\n| `POST \u002Fv0\u002Fmanagement\u002Fusage\u002Fimport` | Import JSONL usage events or legacy JSON snapshots |\n| `GET \u002Fv0\u002Fmanagement\u002Fmodel-prices` | Read SQLite-backed model pricing |\n| `PUT \u002Fv0\u002Fmanagement\u002Fmodel-prices` | Replace saved model pricing |\n| `POST \u002Fv0\u002Fmanagement\u002Fmodel-prices\u002Fsync` | Sync model prices from LiteLLM, OpenRouter, and other pricing metadata sources, including source metadata |\n| `GET \u002Fmodels`, `GET \u002Fv1\u002Fmodels` | Proxy model-list requests to CPA after setup |\n| `\u002Fv0\u002Fmanagement\u002F*` | Proxied to CPA except usage endpoints |\n\nAfter full Docker setup, `\u002Fstatus`, usage, model-pricing, and `\u002Fv0\u002Fmanagement\u002F*` proxy endpoints require the admin key as a Bearer token. In external CPA panel mode, these Manager Server endpoints also accept the CPA Management Key so the CPA panel mode does not need a second Manager Server login.\n\nUsage import accepts two file families: JSONL\u002FNDJSON event files exported by Manager Server, and legacy JSON snapshots produced by older CPA `\u002Fusage\u002Fexport`. Legacy JSON can be converted only when `usage.apis.*.models.*.details[]` request details are present. Files that contain only aggregate totals are rejected because request-level monitoring data cannot be reconstructed. Legacy import is a migration\u002Frecovery path, not a perfect continuation of newly collected Manager Server data: old files may miss metadata such as `api_key_hash`, channel, request ID, method\u002Fpath, latency, cache tokens, or failure reason, so account matching, API Key level analysis, and detail accuracy may be lower. Importing legacy files affects totals, trend charts, and account\u002Fkey breakdowns; use a test or backup database first when accuracy matters.\n\n## Feature Overview\n\n- **Dashboard**: connection state, backend version, quick health summary\n- **Configuration**: visual\u002Fsource editing for CPA configuration and separate CPA Manager Plus configuration\n- **AI Providers**: Gemini, Codex, Claude, Vertex, OpenAI-compatible providers, and Ampcode\n- **Auth Files**: upload, download, delete, status, OAuth exclusions, model aliases\n- **Quota**: quota views for supported providers\n- **Request Monitoring**: persisted usage KPIs, model\u002Fchannel\u002Faccount\u002FAPI-key breakdowns, requested vs resolved model tracking, project snapshots, model pricing, estimated token cost, failure analysis, realtime tables with a readable source label and one prioritized supplemental detail\n- **Codex Account Inspection**: batch probing and cleanup suggestions for Codex auth pools\n- **Logs**: incremental file log reading and filtering\n- **System Info**: model list, version checks, and local state tools\n\n## Development\n\nFrontend:\n\n```bash\nnpm install\nnpm run dev\nnpm run type-check\nnpm run lint\nnpm run build\n```\n\nManager Server:\n\n```bash\ncd apps\u002Fmanager-server\ngo test .\u002F...\ngo test -race .\u002F...\ngo vet .\u002F...\ngo run .\u002Fcmd\u002Fcpa-manager-plus\n```\n\n## Build and Release\n\n- Vite builds a single-file `apps\u002Fweb\u002Fdist\u002Findex.html`.\n- Tagging `vX.Y.Z` or a prerelease tag such as `vX.Y.Z-beta` triggers `.github\u002Fworkflows\u002Frelease.yml`.\n- The release workflow uploads `apps\u002Fweb\u002Fdist\u002Fmanagement.html`, native packages, and `checksums.txt` to GitHub Releases.\n- Native packages are published for `linux`, `darwin`, and `windows` on both `amd64` and `arm64`, with the management panel embedded.\n- The same workflow builds `Dockerfile.manager-server` and pushes public images to Docker Hub and GitHub Container Registry.\n- The Docker image is published for `linux\u002Famd64` and `linux\u002Farm64`.\n- The GitHub Container Registry image is `ghcr.io\u002Fseakee\u002Fcpa-manager-plus`; it uses the workflow `GITHUB_TOKEN` with `packages: write`.\n- The workflow syncs `README.md` to the Docker Hub overview when Docker Hub publishing is enabled.\n- Optional GitHub secrets for Docker Hub publishing:\n  - `DOCKERHUB_USERNAME`\n  - `DOCKERHUB_TOKEN`\n\n## Troubleshooting\n\n- **Cannot connect in full Docker mode**: verify the CPA URL from inside the Manager Server container. For host CPA on Linux, use `--add-host=host.docker.internal:host-gateway`.\n- **Full Docker mode opens the login form instead of setup**: Manager Server is already configured. Enter the admin key; the CPA URL comes from the server-side configuration.\n- **Wrong default CPA URL in first setup**: rebuild the panel with `VITE_DEFAULT_CPA_BASE_URL=\u003Cyour-cpa-url>` or enter the correct CPA URL manually.\n- **Monitoring is empty**: enable CPA usage publishing, verify Manager Server `\u002Fstatus`, and confirm only one consumer is running.\n- **`unsupported RESP prefix 'H'`**: upgrade CPA to `v6.10.8+` or keep `USAGE_COLLECTOR_MODE=http` for reverse-proxied HTTP queue access. RESP Pub\u002FSub\u002FRESP pop modes require the CPA URL to be a container\u002Fhost direct address for port `8317`, not a regular HTTP reverse-proxy domain.\n- **401 from Manager Server**: full Docker mode uses the admin key; external CPA panel mode uses the CPA Management Key.\n- **Docker panel shows stale data**: check `\u002Fstatus` for `lastConsumedAt`, `lastInsertedAt`, and `lastError`.\n- **CPA panel mode has CORS errors**: set `USAGE_CORS_ORIGINS` to the CPA panel origin or keep the default `*` for private deployments.\n- **Data disappears after container rebuild**: mount `\u002Fdata` to a Docker volume or host directory.\n- **Old data is missing after migrating from CPA-Manager**: verify that the Plus container is mounting the old `\u002Fdata` volume, not a newly created empty `cpa-manager-plus-data` volume.\n- **Admin key is lost**: setting `CPA_MANAGER_ADMIN_KEY` does not overwrite an existing `settings.admin_credential_v1`. Follow the offline recovery steps in the migration guide after backing up `\u002Fdata`.\n- **Detailed FAQ**: see [FAQ and Troubleshooting](https:\u002F\u002Fgithub.com\u002Fseakee\u002FCPA-Manager-Plus\u002Fwiki\u002FCPA-Manager-Plus-FAQ-and-Troubleshooting) or the [Chinese FAQ](https:\u002F\u002Fgithub.com\u002Fseakee\u002FCPA-Manager-Plus\u002Fwiki\u002FCPA%E2%80%90Manager-%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98%E4%B8%8E%E8%A7%A3%E5%86%B3%E6%96%B9%E6%A1%88).\n\n## References\n\n- CLIProxyAPI: https:\u002F\u002Fgithub.com\u002Frouter-for-me\u002FCLIProxyAPI\n- Redis usage queue documentation: https:\u002F\u002Fhelp.router-for.me\u002Fmanagement\u002Fredis-usage-queue.html\n- Migration from CPA-Manager: [docs\u002Fmigration-from-cpa-manager.md](docs\u002Fmigration-from-cpa-manager.md)\n- Release checklist: [docs\u002Frelease-checklist.md](docs\u002Frelease-checklist.md)\n\n## Acknowledgements\n\n- Thanks to the upstream projects [CLIProxyAPI](https:\u002F\u002Fgithub.com\u002Frouter-for-me\u002FCLIProxyAPI) and [Cli-Proxy-API-Management-Center](https:\u002F\u002Fgithub.com\u002Frouter-for-me\u002FCli-Proxy-API-Management-Center) for the foundation and inspiration.\n- Thanks to the [Linux.do](https:\u002F\u002Flinux.do\u002F) community for project promotion and feedback.\n\n## License\n\nMIT\n","CPA Manager Plus 是一个用于CLI Proxy API的管理面板，配备了一个支持Docker的Manager Server，提供了SQLite使用分析、请求监控、模型定价、配额视图和Codex检查等功能。项目采用TypeScript开发，通过持久化的Manager Server收集并存储CPA的使用数据到SQLite数据库中，并对外提供面板兼容的API接口。它特别适合需要对CLI Proxy API进行集中管理和监控的场景，如企业级应用或大规模分布式系统中的API调用跟踪与成本控制。此外，该项目还提供了两种部署模式——全Docker模式和CPA面板模式，以适应不同的用户需求和技术环境。",2,"2026-06-11 03:57:28","CREATED_QUERY"]