From 6ed2c91a592ea1af89d18f4c30505af558e9b7b4 Mon Sep 17 00:00:00 2001 From: kongkongyo Date: Sat, 17 Jan 2026 01:02:42 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=20README=EF=BC=8C?= =?UTF-8?q?=E6=96=B0=E5=A2=9E=E4=B8=AD=E6=96=87=E8=AF=A6=E7=BB=86=E4=BD=BF?= =?UTF-8?q?=E7=94=A8=E8=AF=B4=E6=98=8E=E4=B8=8E=E7=9B=91=E6=8E=A7=E4=B8=AD?= =?UTF-8?q?=E5=BF=83=E4=BB=8B=E7=BB=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 将 README.md 重构为中英文详细文档，增加中文使用指导 - 介绍本项目基于官方 UI 的二次开发，突出监控中心核心新增功能 - 详细说明 KPI 仪表盘、模型用量分布、趋势分析、渠道统计、失败分析及高级请求日志功能 - 说明配置步骤、工作原理及官方版本功能保持一致的部分 - 补充常见问题解答、界面特性及连接说明 - 更新相关链接及许可证信息，提升文档完整性与易用性 --- README.md | 371 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 277 insertions(+), 94 deletions(-) diff --git a/README.md b/README.md index 0f92cb8..30167b7 100644 --- a/README.md +++ b/README.md @@ -1,130 +1,313 @@ -# CLI Proxy API Management Center +# CLI Proxy API 管理中心 (CPAMC) -A single-file WebUI (React + TypeScript) for operating and troubleshooting the **CLI Proxy API** via its **Management API** (config, credentials, logs, and usage). +> 一个超可爱的 Web 管理界面，这是基于官方仓库**二次创作**的自定义 UI，用来和你的 **CLI Proxy API** 一起愉快地玩耍吧！ -[中文文档](README_CN.md) +[English Documentation](README_EN.md) -**Main Project**: https://github.com/router-for-me/CLIProxyAPI -**Example URL**: https://remote.router-for.me/ -**Minimum Required Version**: ≥ 6.3.0 (recommended ≥ 6.5.0) +--- -Since version 6.0.19, the WebUI ships with the main program; access it via `/management.html` on the API port once the service is running. +## 关于本项目 -## What this is (and isn’t) +本项目是基于官方 [CLI Proxy API WebUI](https://github.com/router-for-me/Cli-Proxy-API-Management-Center) 进行开发的**日志监控**和**数据可视化**管理界面 -- This repository is the WebUI only. It talks to the CLI Proxy API **Management API** (`/v0/management`) to read/update config, upload credentials, view logs, and inspect usage. -- It is **not** a proxy and does not forward traffic. +### 与官方版本的区别 -## Quick start +本版本与官方版本其他功能保持一致，主要差异在于**新增监控中心**，对**日志分析和查看**的增强。 -### Option A: Use the WebUI bundled in CLIProxyAPI (recommended) -1. Start your CLI Proxy API service. -2. Open: `http://:/management.html` -3. Enter your **management key** and connect. +--- -The address is auto-detected from the current page URL; manual override is supported. +## 快速开始 -### Option B: Run the dev server +### 使用本管理界面 -```bash -npm install -npm run dev +CLI Proxy API 支持从自定义 GitHub 仓库获取管理面板，只需简单配置即可使用！ + +#### 配置步骤 + +在你的 `config.yaml` 中添加以下配置： + +```yaml +remote-management: + panel-github-repository: "https://github.com/kongkongyo/CLIProxyAPI-Web-Dashboard" ``` -Open `http://localhost:5173`, then connect to your CLI Proxy API instance. +配置完成后，重启 CLI Proxy API 服务，访问 `http://:/management.html` 就能看到全新的管理界面啦~ -### Option C: Build a single HTML file +#### 工作原理 -```bash -npm install -npm run build +- 后台会定期检查仓库的最新 Release +- 自动查找名为 `management.html` 的资产 +- 下载到静态目录（默认 `static/`，或 `MANAGEMENT_STATIC_PATH` 指定） +- 如资产包含 `digest` 字段（推荐格式：`sha256:`），会进行哈希校验 + +--- + +## 主要功能 + +### 监控中心 - **核心新增功能** + +这是本管理界面相对于官方版本的**唯一新增功能**，提供了全方位的数据可视化和监控能力： + +#### KPI 指标仪表盘 + +实时展示核心运营指标，支持按时间范围筛选： +- **请求数**：总请求数、成功/失败统计、成功率百分比 +- **Token 数**：总 Token 数、输入 Token、输出 Token +- **平均 TPM**：每分钟 Token 使用量 +- **平均 RPM**：每分钟请求数 +- **日均 RPD**：日均请求数 + +所有指标都会根据选择的时间范围（今天/7天/14天/30天）动态计算 + +#### 模型用量分布 + +直观的饼图展示不同模型的使用占比： +- 按请求数分布 +- 按 Token 数分布 +- 可切换查看请求占比或 Token 占比 + +#### 每日趋势分析 + +详细的时间序列图表，展示每日用量变化趋势： +- 请求数趋势曲线 +- 输入 Token 趋势 +- 输出 Token 趋势 +- 思考 Token 趋势（如支持） +- 缓存 Token 趋势 + +#### 每小时分析 + +两个详细的小时级图表，帮助定位高峰时段： + +**每小时模型请求分布** +- 柱状图展示不同模型在各小时的请求数 +- 支持最近 6 小时/12 小时/24 小时/全部视图切换 + +**每小时 Token 用量** +- 堆叠柱状图展示 Token 使用构成 +- 区分输入 Token、输出 Token、思考 Token、缓存 Token + +#### 渠道统计 + +详细表格展示各渠道（API Key/模型）的使用情况： +- 可按全部渠道/特定渠道筛选 +- 可按全部模型/特定模型筛选 +- 可按全部状态/仅成功/仅失败筛选 +- 显示渠道名称、请求数、成功率 +- 点击展开查看该渠道下各模型的详细统计 +- 显示最近请求状态（最近 10 次请求的迷你状态条） +- 最近请求时间 + +#### 失败来源分析 + +帮助定位问题渠道和模型： +- 按渠道统计失败次数 +- 显示最近失败时间 +- 列出主要失败的模型 +- 点击展开查看该渠道下所有失败的请求详情 + +#### 请求日志 - **高级功能** + +功能强大的请求日志表格，支持海量数据流畅浏览： + +**多维度筛选** +- 按 API Key 筛选 +- 按提供商类型筛选（OpenAI/Gemini/Claude 等） +- 按模型名称筛选 +- 按来源渠道筛选 +- 按请求状态筛选（全部/成功/失败） + +**独立时间范围** +- 支持今天/7天/14天/30天/自定义日期范围 +- 与主页面时间范围独立控制 + +**虚拟滚动** +- 支持 10 万+ 条日志流畅浏览 +- 显示当前可见范围统计 +- 性能优化，只渲染可见行 + +**智能信息展示** +- 自动匹配 API Key 到提供商名称（基于配置信息） +- 完整的渠道信息（提供商名称 + 掩码后的密钥） +- 请求类型/模型名称/请求状态 +- 最近 10 次请求的状态可视化（绿点=成功，红点=失败） +- 成功率百分比 +- 总请求数/输入 Token/输出 Token/总 Token +- 请求时间（完整时间戳） + +**自动刷新** +- 支持手动刷新 / 5秒 / 10秒 / 15秒 / 30秒 / 60秒 自动刷新 +- 倒计时显示下次刷新时间 +- 独立数据加载，不阻塞主页面 + +**一键禁用模型** +- 支持直接在日志中禁用某渠道的某个模型 +- 只对支持该操作的渠道类型生效 +- 不支持时显示提示和手动操作指南 + +--- + +## 官方版本功能 + +以下功能与官方版本一致，通过改进的界面提供更好的使用体验： + +### 仪表盘 +- 连接状态实时监控，就像心跳一样跳动 +- 服务器版本和构建信息一目了然 +- 使用数据快速概览，掌握全局 +- 可用模型统计，看看你的 AI 伙伴们 + +### API 密钥管理 +- 添加、编辑、删除 API 密钥 +- 管理你的代理服务认证，安全又方便 + +### AI 提供商配置 +- **Gemini**：API 密钥管理、排除模型、模型前缀 +- **Claude**：API 密钥和配置、自定义模型列表 +- **Codex**：完整配置管理（API 密钥、Base URL、代理） +- **Vertex**：模型映射配置 +- **OpenAI 兼容**：多密钥管理、模型别名导入、连通性测试 +- **Ampcode**：上游集成和模型映射 + +### 认证文件管理 +- 上传、下载、删除 JSON 认证文件 +- 支持多种提供商（Qwen、Gemini、Claude 等） +- 搜索、筛选、分页浏览 +- 查看每个凭证支持的模型 + +### OAuth 登录 +- 一键启动 OAuth 授权流程 +- 支持 Codex、Anthropic、Gemini CLI、Qwen、iFlow 等 +- 自动保存认证文件 +- 支持远程浏览器回调提交 + +### 配额管理 +- Antigravity 额度查询 +- Codex 额度查询（5 小时、周限额、代码审查） +- Gemini CLI 额度查询 +- 一键刷新所有额度 + +### 使用统计 +- 请求/Token 趋势图表 +- 按模型和 API 的详细统计 +- RPM/TPM 实时速率 +- 缓存和推理 Token 分解 +- 成本估算（支持自定义价格） + +### 配置管理 +- 在线编辑 `config.yaml` +- YAML 语法高亮 +- 搜索和导航 +- 保存和重载配置 + +### 日志查看 +- 实时日志流 +- 搜索和过滤 +- 自动刷新 +- 下载错误日志 +- 屏蔽管理端流量 + +### 中心信息 +- 连接状态检查 +- 版本更新检查 +- 可用模型列表展示 +- 快捷链接入口 + +--- + +## 连接说明 + +### API 地址格式 + +以下格式都可以哦，系统会自动识别的： + +``` +localhost:8317 +http://192.168.1.10:8317 +https://example.com:8317 ``` -- Output: `dist/index.html` (all assets are inlined). -- For CLIProxyAPI bundling, the release workflow renames it to `management.html`. -- To preview locally: `npm run preview` +### 管理密钥 -Tip: opening `dist/index.html` via `file://` may be blocked by browser CORS; serving it (preview/static server) is more reliable. +管理密钥是验证管理操作的魔法钥匙，和客户端使用的 API 密钥不一样哦！ -## Connecting to the server +### 远程管理 -### API address +从非本地浏览器访问的时候，记得要在服务器启用远程管理（`allow-remote-management: true`） -You can enter any of the following; the UI will normalize it: +--- -- `localhost:8317` -- `http://192.168.1.10:8317` -- `https://example.com:8317` -- `http://example.com:8317/v0/management` (also accepted; the suffix is removed internally) +## 界面特性 -### Management key (not the same as API keys) +### 主题切换 +- 亮色模式 +- 暗色模式 +- 跟随系统 -The management key is sent with every request as: +### 语言支持 +- 简体中文 +- English -- `Authorization: Bearer ` (default) +### 响应式设计 +- 桌面端完整功能 +- 移动端适配体验 +- 侧边栏可折叠 -This is different from the proxy `api-keys` you manage inside the UI (those are for client requests to the proxy endpoints). +--- -### Remote management +## 常见问题 -If you connect from a non-localhost browser, the server must allow remote management (e.g. `allow-remote-management: true`). -See `api.md` for the full authentication rules, server-side limits, and edge cases. +**Q: 如何使用这个自定义 UI？** -## What you can manage (mapped to the UI pages) - -- **Dashboard**: connection status, server version/build date, quick counts, model availability snapshot. -- **Basic Settings**: debug, proxy URL, request retry, quota fallback (switch project/preview models), usage statistics, request logging, file logging, WebSocket auth. -- **API Keys**: manage proxy `api-keys` (add/edit/delete). -- **AI Providers**: - - Gemini/Codex/Claude key entries (base URL, headers, proxy, model aliases, excluded models, prefix). - - OpenAI-compatible providers (multiple API keys, custom headers, model alias import via `/v1/models`, optional browser-side “chat/completions” test). - - Ampcode integration (upstream URL/key, force mappings, model mapping table). -- **Auth Files**: upload/download/delete JSON credentials, filter/search/pagination, runtime-only indicators, view supported models per credential (when the server supports it), manage OAuth excluded models (supports `*` wildcards). -- **OAuth**: start OAuth/device flows for supported providers, poll status, optionally submit callback `redirect_url`; includes iFlow cookie import. -- **Usage**: requests/tokens charts (hour/day), per-API & per-model breakdown, cached/reasoning token breakdown, RPM/TPM window, optional cost estimation with locally-saved model pricing. -- **Config**: edit `/config.yaml` in-browser with YAML highlighting + search, then save/reload. -- **Logs**: tail logs with incremental polling, auto-refresh, search, hide management traffic, clear logs; download request error log files. -- **System**: quick links + fetch `/v1/models` (grouped view). Requires at least one proxy API key to query models. - -## Build & release notes - -- Vite produces a **single HTML** output (`dist/index.html`) with all assets inlined (via `vite-plugin-singlefile`). -- Tagging `vX.Y.Z` triggers `.github/workflows/release.yml` to publish `dist/management.html`. -- The UI version shown in the footer is injected at build time (env `VERSION`, git tag, or `package.json` fallback). - -## Security notes - -- The management key is stored in browser `localStorage` using a lightweight obfuscation format (`enc::v1::...`) to avoid plaintext storage; treat it as sensitive. -- Use a dedicated browser profile/device for management. Be cautious when enabling remote management and evaluate its exposure surface. - -## Troubleshooting - -- **Can’t connect / 401**: confirm the API address and management key; remote access may require enabling remote management in the server config. -- **Repeated auth failures**: the server may temporarily block remote IPs. -- **Logs page missing**: enable “Logging to file” in Basic Settings; the navigation item is shown only when file logging is enabled. -- **Some features show “unsupported”**: the backend may be too old or the endpoint is disabled/absent (common for model lists per auth file, excluded models, logs). -- **OpenAI provider test fails**: the test runs in the browser and depends on network/CORS of the provider endpoint; a failure here does not always mean the server cannot reach it. - -## Development - -```bash -npm run dev # Vite dev server -npm run build # tsc + Vite build -npm run preview # serve dist locally -npm run lint # ESLint (fails on warnings) -npm run format # Prettier -npm run type-check # tsc --noEmit +A: 在 CLI Proxy API 的配置文件中添加以下配置即可~ +```yaml +remote-management: + panel-github-repository: "https://github.com/kongkongyo/CLIProxyAPI-Web-Dashboard" ``` -## Contributing +**Q: 无法连接到服务器？** -Issues and PRs are welcome. Please include: +A: 请检查这些哦~ +- API 地址是不是写错了？ +- 管理密钥是不是正确？ +- 服务器启动了吗？ +- 远程访问有没有启用？ -- Reproduction steps (server version + UI version) -- Screenshots for UI changes -- Verification notes (`npm run lint`, `npm run type-check`) +**Q: 日志页面不显示？** -## License +A: 需要去"基础设置"里开启"日志记录到文件"功能才行哦~ -MIT +**Q: 某些功能显示"不支持"？** + +A: 可能是服务器版本太旧啦，升级到最新版本的 CLI Proxy API 就可以了！ + +**Q: OpenAI 提供商测试失败？** + +A: 测试是在浏览器端执行的，可能会受到 CORS 限制~ 失败不一定代表服务器端不能用哦，不要担心！ + +**Q: 这个版本和官方版本有什么区别？** + +A: 主要区别有两个： +1. **界面风格**：全新的视觉设计，更加清新可爱，UI 细节更精致 +2. **监控中心**：这是**唯一新增的功能模块**，提供了强大的数据可视化和监控能力，包括 KPI 仪表盘、模型用量分布、趋势分析、小时级图表、渠道统计、失败分析和高级请求日志等功能 + +其他所有功能与官方版本保持一致！ + +--- + +## 相关链接 + +- **官方主程序**: https://github.com/router-for-me/CLIProxyAPI +- **官方 WebUI**: https://github.com/router-for-me/Cli-Proxy-API-Management-Center +- **本仓库**: https://github.com/kongkongyo/CLIProxyAPI-Web-Dashboard +- **示例地址**: https://remote.router-for.me/ +- **最低版本要求**: ≥ 6.3.0（推荐 ≥ 6.5.0） + +## 许可证 + +MIT License + +--- + +*感谢使用这个自定义版管理中心！祝你使用愉快！*