[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1161":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},1161,"cpa-usage-keeper","Willxup\u002Fcpa-usage-keeper","Willxup","Standalone Cli-Proxy-API usage tracker with SQLite persistence and built-in dashboard.","",null,"Go",721,78,323,19,0,36,67,266,108,99.69,"MIT License",false,"main",true,[],"2026-06-12 04:00:08","# CPA Usage Keeper\n\n[English README](.\u002FREADME.en.md)\n\n`CPA Usage Keeper` 是一个独立的 CPA 用量持久化与可视化服务。\n\n它依赖 [CLIProxyAPI（CPA）](https:\u002F\u002Fgithub.com\u002Frouter-for-me\u002FCLIProxyAPI) 作为后端 CPA 数据来源，目标是在 CPA 之上补充持久化存储与统计分析能力。服务会从 CPA Redis usage 队列消费事件并写入 SQLite，定时拉取 CPA metadata，暴露聚合 API，并提供内置 Web Dashboard 用于查看 usage、pricing、request health 和 model\u002FAPI 维度的统计信息。\n\n![cpa-usage-keeper-screenshot](https:\u002F\u002Fimages.bitskyline.com\u002Fi\u002F2026\u002F05\u002F1pmg6l.png)\n\n## 功能特性\n\n- CPA usage 数据持久化到 SQLite\n- usage 聚合 API 与 pricing API\n- 内置 React Dashboard\n- 可选密码登录保护\n- SQLite 数据库本地备份与保留策略\n- Linux systemd 服务文件\n- Docker \u002F Docker Compose 部署\n\n## 项目结构\n\n```text\ncmd\u002F                 应用入口\ninternal\u002Fapi\u002F        HTTP 路由与处理器\ninternal\u002Fapp\u002F        应用装配与启动\ninternal\u002Fauth\u002F       内存 session 鉴权\ninternal\u002Fbackup\u002F     SQLite 数据库备份管理\ninternal\u002Fconfig\u002F     环境配置加载\ninternal\u002Fcpa\u002F        CPA 客户端与类型定义\ninternal\u002Fmodels\u002F     GORM 模型\ninternal\u002Fpoller\u002F     后台同步轮询\ninternal\u002Frepository\u002F SQLite 访问与聚合逻辑\ninternal\u002Fservice\u002F    同步、usage 与 pricing 服务\nweb\u002F                 React + TypeScript 前端\n```\n\n## 配置\n\n复制配置模板：\n\n```bash\ncp .env.example .env\n```\n\n| 变量 | 必填 | 默认值 | 说明 |\n| --- | --- | --- | --- |\n| `CPA_BASE_URL` | 是 | - | CPA 服务地址 |\n| `CPA_MANAGEMENT_KEY` | 是 | - | CPA management key |\n| `AUTH_ENABLED` | 否 | `false` | 是否启用登录保护 |\n| `LOGIN_PASSWORD` | 鉴权启用时必填 | - | 登录密码 |\n| `AUTH_SESSION_TTL` | 否 | `168h` | Session 生命周期 |\n| `APP_PORT` | 否 | `8080` | HTTP 监听端口 |\n| `APP_BASE_PATH` | 否 | 根路径 | 子路径部署前缀，例如 `\u002Fcpa`；留空表示 `\u002F` |\n| `TZ` | 否 | `Asia\u002FShanghai` | 项目业务时区，影响 Today、按天聚合、定时任务和日志时间 |\n| `REDIS_QUEUE_ADDR` | 否 | `CPA_BASE_URL` 主机名 + `8317` | CPA Redis\u002FRESP TCP 地址；留空时会使用 `CPA_BASE_URL` 的主机名和默认端口 `8317`，且当 `CPA_BASE_URL` 为 https 时自动启用 TLS；非默认端口时填写 `host:port` |\n| `REDIS_QUEUE_TLS` | 否 | `false` | 是否使用 TLS 连接 Redis 队列；仅在 `REDIS_QUEUE_ADDR` 留空且 `CPA_BASE_URL` 为 https 时自动启用；如果显式设置了 `REDIS_QUEUE_ADDR`，需手动设为 `true` |\n| `REDIS_QUEUE_BATCH_SIZE` | 否 | `1000` | 每次最多拉取的队列记录数 |\n| `REDIS_QUEUE_IDLE_INTERVAL` | 否 | `1s` | 队列为空时的检查间隔 |\n| `REQUEST_TIMEOUT` | 否 | `30s` | CPA 请求超时 |\n| `TLS_SKIP_VERIFY` | 否 | `false` | 跳过 CPA HTTPS 和 Redis 队列 TLS 的证书验证；仅在使用自签名证书时启用 |\n| `WORK_DIR` | 否 | `.\u002Fdata` | 应用工作目录；数据库、日志和备份默认分别写入 `app.db`、`logs\u002F`、`backups\u002F` |\n| `LOG_LEVEL` | 否 | `info` | 日志级别 |\n| `LOG_FILE_ENABLED` | 否 | `true` | 是否写入持久化日志文件 |\n| `LOG_RETENTION_DAYS` | 否 | `7` | 日志保留天数；`0` 表示不自动清理 |\n| `BACKUP_ENABLED` | 否 | `true` | 是否启用 SQLite 数据库备份 |\n| `BACKUP_INTERVAL` | 否 | `24h` | 数据库备份间隔 |\n| `BACKUP_RETENTION_DAYS` | 否 | `7` | 备份保留天数 |\n\n`APP_BASE_PATH` 必须为空或以 `\u002F` 开头；例如 `\u002Fcpa`，`\u002Fcpa\u002F` 会规范为 `\u002Fcpa`。\n\n安全与数据说明：\n\n- SQLite 数据库备份会保存应用数据库中的原始数据，备份文件不做加密。\n- 面向浏览器的 API 会对 key-like source\u002Flookup 字段做脱敏或稳定公开标识映射，但不会修改数据库原始值。\n- 公开部署建议开启 `AUTH_ENABLED=true`，并在反向代理层配置 HTTPS。\n- 登录 session 存在服务进程内存中，服务重启后已登录 session 会失效。\n- Redis inbox 原始消息会自动清理：成功数据保留到当天结束后清理，失败数据保留 7 天。\n\n## 本地开发\n\n### 前置依赖\n\n- Go 1.22+\n- Node.js 22+\n- npm\n- 已运行的 [CLIProxyAPI（CPA）](https:\u002F\u002Fgithub.com\u002Frouter-for-me\u002FCLIProxyAPI)\n\n### 本地启动\n\n1. 复制本地配置：\n\n```bash\ncp .env.example .env\n```\n\n2. 启动后端：\n\n```bash\ngo run .\u002Fcmd\u002Fserver\u002Fmain.go\n```\n\n3. 在另一个终端安装前端依赖并启动开发服务器：\n\n```bash\nnpm --prefix .\u002Fweb ci\nnpm --prefix .\u002Fweb run dev -- --host 127.0.0.1\n```\n\n4. 构建前端生产产物：\n\n```bash\nnpm --prefix .\u002Fweb run build\n```\n\n### 测试\n\n运行完整的本地验证基线：\n\n```bash\nmake verify\n```\n\n也可以单独运行各项检查：\n\n```bash\ngo test .\u002Fcmd\u002F... .\u002Finternal\u002F...\nnpm --prefix .\u002Fweb run test\nnpm --prefix .\u002Fweb run lint\nnpm --prefix .\u002Fweb run typecheck\nnpm --prefix .\u002Fweb run build\n```\n\n## Linux 二进制运行\n\n### 下载\n\n在 [Releases](https:\u002F\u002Fgithub.com\u002FWillxup\u002Fcpa-usage-keeper\u002Freleases\u002Flatest) 下载对应架构的 Linux 二进制包，或使用命令行下载：\n\n```bash\ncurl -L -o cpa-usage-keeper.tar.gz \"\u003C替换为 Linux 二进制包下载地址>\"\nmkdir -p cpa-usage-keeper\ntar -xzf cpa-usage-keeper.tar.gz -C cpa-usage-keeper --strip-components=1\ncd cpa-usage-keeper\n```\n\n请在 Releases 页面复制 `linux_amd64` 或 `linux_arm64` 包的下载地址，并替换上面命令中的占位符。\n\n### 配置\n\n复制配置模板并编辑，具体配置项参考上方“配置”章节：\n\n```bash\ncp .env.example .env\nvim .env\n```\n\n### 直接运行\n\n```bash\n.\u002Fcpa-usage-keeper\n```\n\n### systemd 常驻运行\n\nLinux 二进制包内置 `cpa-usage-keeper.service`，可直接注册为 `systemd` 服务。启动后进程由 systemd 托管，关闭 SSH 或终端不会结束进程。\n\n`systemd` 的 `WorkingDirectory` 需要绝对路径。下面的 `sed` 命令会把当前目录自动写入 service 文件：\n\n```bash\nsudo cp cpa-usage-keeper.service \u002Fetc\u002Fsystemd\u002Fsystem\u002Fcpa-usage-keeper.service # 复制 service 文件到 systemd 目录\nsudo sed -i \"s|__CPA_USAGE_KEEPER_DIR__|$(pwd)|g\" \u002Fetc\u002Fsystemd\u002Fsystem\u002Fcpa-usage-keeper.service # 写入当前目录作为 WorkingDirectory\nsudo systemctl daemon-reload # 重新加载 systemd 配置\nsudo systemctl enable --now cpa-usage-keeper # 设置开机自启并立即启动服务\n```\n\n常用命令：\n\n```bash\nsudo systemctl status cpa-usage-keeper # 查看服务状态\nsudo journalctl -u cpa-usage-keeper -f # 实时查看服务日志\nsudo systemctl restart cpa-usage-keeper # 重启服务\n```\n\n## Docker\n\n如果 CPA 已在宿主机运行：\n\n```bash\n# TZ 设置容器时区，日志时间会按该时区显示。\ndocker run -d \\\n  --name cpa-usage-keeper \\\n  --add-host=host.docker.internal:host-gateway \\\n  -p 8080:8080 \\\n  -v \"$(pwd)\u002Fkeeper\u002Fdata:\u002Fdata\" \\\n  -e TZ=Asia\u002FShanghai \\\n  -e CPA_BASE_URL=http:\u002F\u002Fhost.docker.internal:8317 \\\n  -e CPA_MANAGEMENT_KEY=replace-with-your-management-key \\\n  -e REDIS_QUEUE_ADDR=host.docker.internal:8317 \\\n  -e AUTH_ENABLED=true \\\n  -e LOGIN_PASSWORD=replace-with-your-login-password \\\n  ghcr.io\u002Fwillxup\u002Fcpa-usage-keeper:latest\n```\n\n`\u002Fdata` 用于保存 SQLite 数据库、备份文件和日志文件，请挂载到持久化目录。\n\n## Docker Compose\n\n仓库提供了一个最简 `docker-compose.yaml` 示例，用于同时部署 CPA 和 CPA Usage Keeper：\n\n```yaml\nservices:\n  cli-proxy-api:\n    image: eceasy\u002Fcli-proxy-api:latest\n    container_name: cli-proxy-api\n    restart: unless-stopped\n    ports:\n      - \"8317:8317\"\n      - \"1455:1455\"\n    volumes:\n      - .\u002Fcpa\u002Fconfig.yaml:\u002FCLIProxyAPI\u002Fconfig.yaml\n      - .\u002Fcpa\u002Fauths:\u002Froot\u002F.cli-proxy-api\n      - .\u002Fcpa\u002Flogs:\u002FCLIProxyAPI\u002Flogs\n    networks:\n      - cpa-network\n\n  cpa-usage-keeper:\n    image: ghcr.io\u002Fwillxup\u002Fcpa-usage-keeper:latest\n    container_name: cpa-usage-keeper\n    restart: unless-stopped\n    depends_on:\n      - cli-proxy-api\n    ports:\n      - \"8080:8080\"\n    environment:\n      TZ: Asia\u002FShanghai # 设置容器时区，日志时间会按该时区显示。\n      CPA_BASE_URL: http:\u002F\u002Fcli-proxy-api:8317\n      CPA_MANAGEMENT_KEY: replace-with-your-management-key\n      REDIS_QUEUE_ADDR: cli-proxy-api:8317\n      AUTH_ENABLED: true\n      LOGIN_PASSWORD: replace-with-your-login-password\n    volumes:\n      - .\u002Fkeeper:\u002Fdata\n    networks:\n      - cpa-network\n\nnetworks:\n  cpa-network:\n    driver: bridge\n```\n\n启动：\n\n```bash\ndocker compose up -d\n```\n\n停止：\n\n```bash\ndocker compose down\n```\n\nCPA 文件放在 `.\u002Fcpa`，CPA Usage Keeper 数据放在 `.\u002Fkeeper`。\n\n## 子路径反代\n\n部署到 `\u002Fcpa` 时设置 `APP_BASE_PATH=\u002Fcpa`，并在反向代理中保留该前缀：\n\n```nginx\nlocation \u002Fcpa\u002F {\n    proxy_pass http:\u002F\u002F127.0.0.1:8080;\n    proxy_set_header Host $host;\n    proxy_set_header X-Forwarded-Proto $scheme;\n    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n}\n```\n","CPA Usage Keeper 是一个独立的 Cli-Proxy-API 用量追踪与展示服务，旨在为 CPA 提供持久化存储和统计分析能力。该项目使用 Go 语言开发，核心功能包括从 CPA Redis usage 队列消费事件并写入 SQLite 数据库，提供聚合 API 和 pricing API，并内置了一个基于 React 的 Web Dashboard 来可视化展示 usage、pricing、请求健康状况以及模型\u002FAPI 维度的统计信息。此外，还支持可选密码登录保护、本地数据库备份与保留策略等特性。适合需要对 CLIProxyAPI 使用情况进行监控和管理的场景，如企业内部工具链维护或开发者个人项目跟踪。",2,"2026-06-11 02:41:59","CREATED_QUERY"]