refactor(docs): update README files with improved structure, feature descriptions, and usage instructions for better clarity and accessibility

2026-02-03 03:10:50 +08:00 · 2025-11-23 21:48:55 +08:00
parent efc6cb3863
commit 02faf18ceb
2 changed files with 120 additions and 320 deletions
--- a/README.md
+++ b/README.md
@@ -1,150 +1,49 @@
 # Cli-Proxy-API-Management-Center
-This is a modern web interface for managing the CLI Proxy API.
+This is the modern WebUI for managing the CLI Proxy API.

 [中文文档](README_CN.md)

-Main Project:
-https://github.com/router-for-me/CLIProxyAPI
+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)

-Example URL:
-https://remote.router-for.me/
-
-Minimum required version: ≥ 6.0.0
-Recommended version: ≥ 6.2.32
-
-Since version 6.0.19, the WebUI has been rolled into the main program. You can access it by going to `/management.html` on the external port after firing up the main project.
+Since 6.0.19 the WebUI ships with the main program; access it via `/management.html` on the API port once the service is running.

 ## Features

-### Authentication Management
- Supports management key authentication
- Configurable API base address
- Real-time connection status detection
- Auto-login with saved credentials
- Language and theme switching
-
-### Basic Settings
- **Debug Mode**: Enable/disable debugging
- **Proxy Settings**: Configure proxy server URL
- **Request Retries**: Set the number of request retries
- **Quota Management**: Configure behavior when the quota is exceeded
-  - Auto-switch project when quota exceeded
-  - Switch to preview models when quota exceeded
-
-### API Key Management
- **Proxy Service Authentication Key**: Manage API keys for the proxy service
- **Gemini API**: Manage Google Gemini generative language API keys
- **Codex API**: Manage OpenAI Codex API configuration
- **Claude API**: Manage Anthropic Claude API configuration
- **OpenAI-Compatible Providers**: Manage OpenAI-compatible third-party providers
-
-### Authentication File Management
- Upload authentication JSON files
- Download existing authentication files
- Delete single or all authentication files
- Display file details
-
-### Usage Statistics
- **Real-time Analytics**: Track API usage with interactive charts
- **Request Trends**: Visualize request patterns by hour/day
- **Token Usage**: Monitor token consumption over time
- **API Details**: Detailed statistics for each API endpoint
- **Success/Failure Rates**: Track API reliability metrics
-
-### System Information
- **Connection Status**: Real-time connection monitoring
- **Configuration Status**: Track configuration loading state
- **Server Information**: Display server address and management key
- **Last Update**: Show when data was last refreshed
-
+### Capabilities
+- **Login & UX**: Auto-detects the current address (manual override/reset supported), encrypted auto-login, language/theme toggles, responsive layout with mobile sidebar.
+- **Basic Settings**: Debug, proxy URL, request retries, quota fallback (auto-switch project/preview models), usage-statistics toggle, request logging & logging-to-file switches, WebSocket `/ws/*` auth switch.
+- **Keys & Providers**: Manage proxy auth keys, Gemini/Codex/Claude configs, OpenAI-compatible providers (custom base URLs/headers/proxy/model aliases), Vertex AI credential import from service-account JSON with optional location.
+- **Auth Files & OAuth**: Upload/download/search/paginate JSON credentials; type filters (Qwen/Gemini/GeminiCLI/AIStudio/Claude/Codex/Antigravity/iFlow/Vertex/Empty); delete-all; OAuth/Device flows for Codex, Anthropic (Claude), Antigravity (Google), Gemini CLI (optional project), Qwen; iFlow OAuth and cookie login.
+- **Logs**: Live viewer with auto-refresh/incremental updates, download and clear; section appears when logging-to-file is enabled.
+- **Usage Analytics**: Overview cards, hourly/daily toggles, up to three model lines per chart, per-API stats table (Chart.js).
+- **Config Management**: In-browser CodeMirror YAML editor for `/config.yaml` with reload/save, syntax highlighting, and status feedback.
+- **System Info & Versioning**: Connection/config cache status, last refresh time, server version/build date, and UI version in the footer.
+- **Security & Preferences**: Masked secrets, secure local storage, persistent theme/language/sidebar state, real-time status feedback.

 ## How to Use

-### 1. Using After CLI Proxy API Program Launch (Recommended)
-Once the CLI Proxy API program is up and running, you can access the WebUI at `http://your-server-IP:8317/management.html`.
+1) **After CLI Proxy API is running (recommended)**  
+   Visit `http://your-server:8317/management.html`.

-### 2. Direct Use
-Simply open the `index.html` file directly in your browser to use it.
+2) **Direct static use**  
+   Open `index.html` (or the bundled `dist/index.html` from `npm run build`) directly in your browser.

-### 3. Use a Local Server
-
-#### Option A: Using Node.js (npm)
+3) **Local server**
 ```bash
-# Install dependencies
 npm install
-
-# Start the server on the default port (3000)
-npm start
-```
-
-#### Option B: Using Python
-```bash
-# Python 3.x
+npm start        # http://localhost:3000
+npm run dev      # optional dev port: 3090
+# or
 python -m http.server 8000
-
 ```
+   Then open the corresponding localhost URL.

-Then open `http://localhost:8000` in your browser.
+4) **Configure connection**  
+   The login page shows the detected address; you can override it, enter the management key, and click Connect. Saved credentials use encrypted local storage for auto-login.

-### 3. Configure Connection
-1. Open the management interface.
-2. On the login screen, enter:
-   - **Remote Address**: The current version automatically picks up the remote address from where you're connecting. But you can also set your own address if you prefer.
-   - **Management Key**: Your management key
-3. Click the "Connect" button.
-4. Once connected successfully, all features will be available.
-
-## Interface Description
-
-### Navigation Menu
- **Basic Settings**: Basic configurations like debugging, proxy, retries, etc.
- **API Keys**: Management of keys for various API services.
- **AI Providers**: Configuration for AI service providers.
- **Auth Files**: Upload and download management for authentication files.
- **Usage Stats**: Real-time analytics and usage statistics with interactive charts.
- **System Info**: Connection status and system information.
-
-### Login Interface
- **Auto-connection**: Automatically attempts to connect using saved credentials
- **Custom Connection**: Manual configuration of API base address
- **Current Address Detection**: Automatically detects and uses current access address
- **Language Switching**: Support for multiple languages (English/Chinese)
- **Theme Switching**: Light and dark theme support
-
-## Feature Highlights
-
-### Modern UI
- Responsive design, supports all screen sizes
- Beautiful gradient colors and shadow effects
- Smooth animations and transition effects
- Intuitive icons and status indicators
- Dark/Light theme support with system preference detection
- Mobile-friendly sidebar with overlay
-
-### Real-time Updates
- Configuration changes take effect immediately
- Real-time status feedback
- Automatic data refresh
- Live usage statistics with interactive charts
- Real-time connection status monitoring
-
-### Security Features
- Masked display for keys
- Secure credential storage
- Auto-login with encrypted local storage
-
-### Responsive Design
- Perfectly adapts to desktop and mobile devices
- Adaptive layout with collapsible sidebar
- Touch-friendly interactions
- Mobile menu with overlay
-
-### Analytics & Monitoring
- Interactive charts powered by Chart.js
- Real-time usage statistics
- Request trend visualization
- Token consumption tracking
- API performance metrics
+Tip: The Logs navigation item appears after enabling "Logging to file" in Basic Settings.

 ## Tech Stack

@@ -152,11 +51,17 @@ Then open `http://localhost:8000` in your browser.
 - **Styling**: CSS3 + Flexbox/Grid with CSS Variables
 - **Icons**: Font Awesome 6.4.0
 - **Charts**: Chart.js for interactive data visualization
+- **Editor/Parsing**: CodeMirror + js-yaml
 - **Fonts**: Segoe UI system font
- **API**: RESTful API calls with automatic authentication
- **Internationalization**: Custom i18n system with English/Chinese support
- **Theme System**: CSS custom properties for dynamic theming
- **Storage**: LocalStorage for user preferences and credentials
+- **Internationalization**: Custom i18n (EN/CN) and theme system (light/dark)
+- **API**: RESTful management endpoints with automatic authentication
+- **Storage**: LocalStorage with lightweight encryption for preferences/credentials
+
+## Build & Development
+
+- `npm run build` bundles everything into `dist/index.html` via webpack (`build.cjs`, `bundle-entry.js`, `build-scripts/prepare-html.js`).
+- External CDNs remain for Font Awesome, Chart.js, and CodeMirror to keep the bundle lean.
+- Development servers: `npm start` (3000) or `npm run dev` (3090); Python `http.server` also works for static hosting.

 ## Troubleshooting

@@ -171,38 +76,33 @@ Then open `http://localhost:8000` in your browser.
 2. Check your network connection.
 3. Check the browser's console for any error messages.

-## Development Information
+### Logs & Config Editor
+- Logs: Requires server-side logging-to-file; 404 indicates the server build is too old or logging is disabled.
+- Config editor: Requires `/config.yaml` endpoint; keep YAML valid before saving.

-### File Structure
+### Usage Stats
+- Enable "Usage statistics" if charts stay empty; data resets on server restart.
+
+## Project Structure
 ```
-webui/
-├── index.html          # Main page with responsive layout
-├── styles.css          # Stylesheet with theme support
-├── app.js              # Application logic and API management
-├── i18n.js             # Internationalization support (EN/CN)
-├── package.json        # Project configuration
-├── build.js            # Build script for production
-├── bundle-entry.js     # Entry point for bundling
+├── index.html
+├── styles.css
+├── app.js
+├── i18n.js
+├── src/                # Core/modules/utils source code
+├── build.cjs           # Webpack build script
+├── bundle-entry.js     # Bundling entry
 ├── build-scripts/      # Build utilities
-│   └── prepare-html.js # HTML preparation script
-├── logo.jpg            # Application logo
-├── LICENSE             # MIT License
-├── README.md           # English documentation
-├── README_CN.md        # Chinese documentation
-└── BUILD_RELEASE.md    # Build and release notes
+│   └── prepare-html.js
+├── dist/               # Bundled single-file output
+├── api.md
+├── management-guide_CN.md
+├── BUILD_RELEASE.md
+├── LICENSE
+├── README.md
+└── README_CN.md
 ```

-### API Calls
-All API calls are handled through the `makeRequest` method of the `ManagerAPI` class, which includes:
- Automatic addition of authentication headers
- Error handling
- JSON response parsing
-
-### State Management
- API address and key are saved in local storage
- Connection status is maintained in memory
- Real-time data refresh mechanism
-
 ## Contributing
 We welcome Issues and Pull Requests to improve this project! We encourage more developers to contribute to the enhancement of this WebUI!

--- a/README_CN.md
+++ b/README_CN.md
@@ -1,149 +1,49 @@
 # Cli-Proxy-API-Management-Center
 这是一个用于管理 CLI Proxy API 的现代化 Web 界面。

-主项目
-https://github.com/router-for-me/CLIProxyAPI
+[English](README.md)

-示例网站:
-https://remote.router-for.me/
+主项目: https://github.com/router-for-me/CLIProxyAPI  
+示例网站: https://remote.router-for.me/  
+最低版本 ≥ 6.3.0（推荐 ≥ 6.5.0）

-最低可用版本 ≥ 6.0.0
-
-推荐版本 ≥ 6.2.32
-
-自6.0.19起WebUI已经集成在主程序中 可以通过主项目开启的外部端口的`/management.html`访问
+自 6.0.19 起 WebUI 已集成到主程序中，启动后可通过 `/management.html` 访问。

 ## 功能特点

-### 认证管理
- 支持管理密钥认证
- 可配置 API 基础地址
- 实时连接状态检测
- 自动登录保存的凭据
- 语言和主题切换
-
-### 基础设置
- **调试模式**: 开启/关闭调试功能
- **代理设置**: 配置代理服务器 URL
- **请求重试**: 设置请求重试次数
- **配额管理**: 配置超出配额时的行为
-  - 超出配额时自动切换项目
-  - 超出配额时切换到预览模型
-
-### API 密钥管理
- **代理服务认证密钥**: 管理用于代理服务的 API 密钥
- **Gemini API**: 管理 Google Gemini 生成式语言 API 密钥
- **Codex API**: 管理 OpenAI Codex API 配置
- **Claude API**: 管理 Anthropic Claude API 配置
- **OpenAI 兼容提供商**: 管理 OpenAI 兼容的第三方提供商
-
-### 认证文件管理
- 上传认证 JSON 文件
- 下载现有认证文件
- 删除单个或所有认证文件
- 显示文件详细信息
-
-### 使用统计
- **实时分析**: 通过交互式图表跟踪 API 使用情况
- **请求趋势**: 按小时/天可视化请求模式
- **Token 使用**: 监控 Token 消耗随时间变化
- **API 详情**: 每个 API 端点的详细统计
- **成功率/失败率**: 跟踪 API 可靠性指标
-
-### 系统信息
- **连接状态**: 实时连接监控
- **配置状态**: 跟踪配置加载状态
- **服务器信息**: 显示服务器地址和管理密钥
- **最后更新**: 显示数据最后刷新时间
-
+### 主要能力
+- **登录与体验**: 自动检测当前地址（可自定义/重置），加密自动登录，语言/主题切换，响应式布局与移动端侧边栏。
+- **基础设置**: 调试、代理 URL、请求重试，配额溢出自动切换项目/预览模型，使用统计开关，请求日志与文件日志开关，WebSocket `/ws/*` 鉴权开关。
+- **密钥与提供商**: 管理代理服务密钥，Gemini/Codex/Claude 配置，OpenAI 兼容提供商（自定义 Base URL/Headers/Proxy/模型别名），Vertex AI 服务账号导入（可选区域）。
+- **认证文件与 OAuth**: 上传/下载/搜索/分页 JSON 凭据，类型筛选（Qwen/Gemini/GeminiCLI/AIStudio/Claude/Codex/Antigravity/iFlow/Vertex/Empty），一键删除全部；Codex、Anthropic(Claude)、Antigravity(Google)、Gemini CLI（可选项目）、Qwen 设备码、iFlow OAuth 与 Cookie 登录。
+- **日志**: 实时查看并增量刷新，支持下载和清空；启用“写入日志文件”后出现日志栏目。
+- **使用统计**: 概览卡片、小时/天切换、最多三条模型曲线、按 API 统计表（Chart.js）。
+- **配置管理**: 内置 CodeMirror YAML 编辑器，在线读取/保存 `/config.yaml`，语法高亮与状态提示。
+- **系统与版本**: 连接/配置缓存状态、最后刷新时间，底栏显示服务版本、构建时间与 UI 版本。
+- **安全与偏好**: 密钥遮蔽、加密本地存储，主题/语言/侧边栏状态持久化，实时状态反馈。

 ## 使用方法

-### 1. 在CLI Proxy API程序启动后使用 （推荐）
-在启动了CLI Proxy API程序后 访问`http://您的服务器IP:8317/management.html`使用
+1) **主程序启动后使用（推荐）**  
+   访问 `http://您的服务器:8317/management.html`。

-### 2. 直接使用
-直接用浏览器打开 `index.html` 文件即可使用。
+2) **直接静态打开**  
+   浏览器打开 `index.html`（或 `npm run build` 生成的 `dist/index.html` 单文件）。

-### 3. 使用本地服务器
-
-#### 方法A：使用 Node.js (npm)
+3) **本地服务器**
 ```bash
-# 安装依赖
 npm install
-
-# 使用默认端口(3000）
-npm start
-```
-
-#### 方法B：使用 Python
-```bash
-# Python 3.x
+npm start        # 默认 http://localhost:3000
+npm run dev      # 可选开发端口 3090
+# 或
 python -m http.server 8000
-
 ```
+   然后在浏览器打开对应的 localhost 地址。

-然后在浏览器中打开 `http://localhost:8000`。
+4) **配置连接**  
+   登录页会显示自动检测的地址，可自行修改，填入管理密钥后点击连接。凭据将加密保存以便下次自动登录。

-### 3. 配置连接
-1. 打开管理界面
-2. 在登录界面上输入：
-   - **远程地址**: 现版本远程地址将会自动从您的访问地址中获取 当然您也可以自定义
-   - **管理密钥**: 您的管理密钥
-3. 点击"连接"按钮
-4. 连接成功后即可使用所有功能
-
-## 界面说明
-
-### 导航菜单
- **基础设置**: 调试、代理、重试等基本配置
- **API 密钥**: 各种 API 服务的密钥管理
- **AI 提供商**: AI 服务提供商配置
- **认证文件**: 认证文件的上传下载管理
- **使用统计**: 实时分析和使用统计，包含交互式图表
- **系统信息**: 连接状态和系统信息
-
-### 登录界面
- **自动连接**: 使用保存的凭据自动尝试连接
- **自定义连接**: 手动配置 API 基础地址
- **当前地址检测**: 自动检测并使用当前访问地址
- **语言切换**: 支持多种语言（英文/中文）
- **主题切换**: 支持明暗主题
-
-## 特性亮点
-
-### 现代化 UI
- 响应式设计，支持各种屏幕尺寸
- 美观的渐变色彩和阴影效果
- 流畅的动画和过渡效果
- 直观的图标和状态指示
- 明暗主题支持，自动检测系统偏好
- 移动端友好的侧边栏和遮罩
-
-### 实时更新
- 配置更改立即生效
- 实时状态反馈
- 自动数据刷新
- 实时使用统计和交互式图表
- 实时连接状态监控
-
-### 安全特性
- 密钥遮蔽显示
- 安全凭据存储
- 加密本地存储自动登录
-
-### 响应式设计
- 完美适配桌面和移动设备
- 自适应布局，可折叠侧边栏
- 触摸友好的交互
- 移动端菜单和遮罩
-
-### 分析与监控
- Chart.js 驱动的交互式图表
- 实时使用统计
- 请求趋势可视化
- Token 消耗跟踪
- API 性能指标
+提示: 开启“写入日志文件”后才会显示“日志查看”导航。

 ## 技术栈

@@ -151,11 +51,16 @@ python -m http.server 8000
 - **样式**: CSS3 + Flexbox/Grid，支持 CSS 变量
 - **图标**: Font Awesome 6.4.0
 - **图表**: Chart.js 交互式数据可视化
- **字体**: Segoe UI 系统字体
- **API**: RESTful API 调用，自动认证
- **国际化**: 自定义 i18n 系统，支持中英文
- **主题系统**: CSS 自定义属性动态主题
- **存储**: LocalStorage 用户偏好和凭据存储
+- **编辑/解析**: CodeMirror + js-yaml
+- **国际化**: 自定义 i18n（中/英）与主题系统（明/暗）
+- **API**: RESTful 管理接口，自动附加认证
+- **存储**: LocalStorage 轻量加密存储偏好与凭据
+
+## 构建与开发
+
+- `npm run build` 通过 webpack（`build.cjs`、`bundle-entry.js`、`build-scripts/prepare-html.js`）打包为 `dist/index.html`。
+- Font Awesome、Chart.js、CodeMirror 仍走 CDN，减小打包体积。
+- 开发可用 `npm start` (3000) / `npm run dev` (3090) 或 `python -m http.server` 静态托管。

 ## 故障排除

@@ -170,39 +75,34 @@ python -m http.server 8000
 2. 检查网络连接
 3. 查看浏览器控制台错误信息

-## 开发说明
+### 日志与配置编辑
+- 日志: 需要服务端开启写文件日志；返回 404 说明版本过旧或未启用。
+- 配置编辑: 依赖 `/config.yaml` 接口，保存前请确保 YAML 语法正确。

-### 文件结构
+### 使用统计
+- 若图表为空，请开启“使用统计”；数据在服务重启后会清空。
+
+## 项目结构
 ```
-webui/
-├── index.html          # 主页面，响应式布局
-├── styles.css          # 样式文件，支持主题
-├── app.js              # 应用逻辑和 API 管理
-├── i18n.js             # 国际化支持（中英文）
-├── package.json        # 项目配置
-├── build.js            # 生产环境构建脚本
-├── bundle-entry.js     # 打包入口文件
+├── index.html
+├── styles.css
+├── app.js
+├── i18n.js
+├── src/                # 核心/模块/工具源码
+├── build.cjs           # Webpack 构建脚本
+├── bundle-entry.js     # 打包入口
 ├── build-scripts/      # 构建工具
-│   └── prepare-html.js # HTML 准备脚本
-├── logo.jpg            # 应用图标
-├── LICENSE             # MIT 许可证
-├── README.md           # 英文文档
-├── README_CN.md        # 中文文档
-└── BUILD_RELEASE.md    # 构建和发布说明
+│   └── prepare-html.js
+├── dist/               # 打包输出单文件
+├── api.md
+├── management-guide_CN.md
+├── BUILD_RELEASE.md
+├── LICENSE
+├── README.md
+└── README_CN.md
 ```

-### API 调用
-所有 API 调用都通过 `ManagerAPI` 类的 `makeRequest` 方法处理，包含：
- 自动添加认证头
- 错误处理
- JSON 响应解析
-
-### 状态管理
- 本地存储保存 API 地址和密钥
- 内存中维护连接状态
- 实时数据刷新机制
-
 ## 贡献
-欢迎提交 Issue 和 Pull Request 来改进这个项目！我们欢迎更多的大佬来对这个WebUI进行更新！
+欢迎提交 Issue 和 Pull Request 来改进这个项目！我们欢迎更多的大佬来对这个 WebUI 进行更新！

-本项目采用MIT许可
+本项目采用 MIT 许可。