From c4034c6467d5efbe933f418361e5fac95757dc5f Mon Sep 17 00:00:00 2001 From: Supra4E8C Date: Sat, 13 Dec 2025 17:27:00 +0800 Subject: [PATCH] Update README.md --- README.md | 190 +++++++++++++++++++++++++++++++++++++++++++++++++++ README_CN.md | 190 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 380 insertions(+) create mode 100644 README.md create mode 100644 README_CN.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c6f333e --- /dev/null +++ b/README.md @@ -0,0 +1,190 @@ +# CLI Proxy API Management Center + +A modern React-based WebUI for managing the CLI Proxy API, completely refactored with a modern tech stack for enhanced maintainability, type safety, and user experience. + +[中文文档](README_CN.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. + +## Features + +### Core Capabilities + +- **Login & Authentication**: Auto-detects current address (manual override supported), encrypted auto-login with secure localStorage, session persistence +- **Basic Settings**: Debug mode, proxy URL, request retries with custom config, quota fallback (auto-switch project/preview models), usage statistics toggle, request logging & file logging, WebSocket `/ws/*` authentication +- **API Keys Management**: Manage proxy auth keys with add/edit/delete operations +- **AI Providers**: Configure Gemini/Codex/Claude settings, OpenAI-compatible providers with custom base URLs/headers/proxy/model aliases, Vertex AI credential import from service-account JSON +- **Auth Files & OAuth**: Upload/download/search/paginate JSON credentials; type filters (Qwen/Gemini/GeminiCLI/AIStudio/Claude/Codex/Antigravity/iFlow/Vertex/Empty); bulk delete; OAuth/Device flows for multiple providers +- **Logs Viewer**: Real-time log viewer with auto-refresh, download and clear capabilities (appears when logging-to-file is enabled) +- **Usage Analytics**: Overview cards, hourly/daily toggles, interactive charts with multiple model lines, per-API statistics table +- **Config Management**: In-browser YAML editor for `/config.yaml` with syntax highlighting, reload/save functionality +- **System Information**: Connection status, config cache, server version/build date, UI version in footer + +### User Experience + +- **Responsive Design**: Full mobile support with collapsible sidebar +- **Theme System**: Light/dark mode with persistent preference +- **Internationalization**: English and Simplified Chinese (zh-CN) with seamless switching +- **Real-time Feedback**: Toast notifications for all operations +- **Security**: Masked secrets, encrypted local storage + +## Tech Stack + +- **Frontend Framework**: React 19 with TypeScript +- **Build Tool**: Vite 7 with single-file output ([vite-plugin-singlefile](https://github.com/nicknisi/vite-plugin-singlefile)) +- **State Management**: [Zustand](https://github.com/pmndrs/zustand) for global stores +- **Routing**: React Router 7 with HashRouter +- **HTTP Client**: Axios with interceptors for auth & error handling +- **Internationalization**: i18next + react-i18next +- **Styling**: SCSS with CSS Modules, CSS Variables for theming +- **Charts**: Chart.js + react-chartjs-2 +- **Code Editor**: @uiw/react-codemirror with YAML support + +## Getting Started + +### Prerequisites + +- Node.js 18+ (LTS recommended) +- npm 9+ + +### Installation + +```bash +# Clone the repository +git clone https://github.com/router-for-me/Cli-Proxy-API-Management-Center.git +cd Cli-Proxy-API-Management-Center + +# Install dependencies +npm install +``` + +### Development + +```bash +npm run dev # Start Vite dev server (default: http://localhost:5173) +``` + +### Build + +```bash +npm run build # TypeScript check + Vite production build +``` + +The build outputs a single `dist/index.html` file with all assets inlined. + +### Other Commands + +```bash +npm run preview # Preview production build locally +npm run lint # ESLint with strict mode (--max-warnings 0) +npm run format # Prettier formatting for src/**/*.{ts,tsx,css,scss} +npm run type-check # TypeScript type checking only (tsc --noEmit) +``` + +## Usage + +### Access Methods + +1. **Integrated with CLI Proxy API (Recommended)** + After starting the CLI Proxy API service, visit `http://your-server:8317/management.html` + +2. **Standalone (Built file)** + Open the built `dist/index.html` directly in a browser, or host it on any static file server + +3. **Development Server** + Run `npm run dev` and open `http://localhost:5173` + +### Initial Configuration + +1. The login page auto-detects the current address; you can modify it if needed +2. Enter your management key +3. Click Connect to authenticate +4. Credentials are encrypted and saved locally for auto-login + +> **Tip**: The Logs navigation item appears only after enabling "Logging to file" in Basic Settings. + +## Project Structure + +``` +├── src/ +│ ├── components/ +│ │ ├── common/ # Shared components (NotificationContainer) +│ │ ├── layout/ # App shell (MainLayout with sidebar) +│ │ └── ui/ # Reusable UI primitives (Button, Input, Modal, etc.) +│ ├── hooks/ # Custom hooks (useApi, useDebounce, usePagination, etc.) +│ ├── i18n/ +│ │ ├── locales/ # Translation files (zh-CN.json, en.json) +│ │ └── index.ts # i18next configuration +│ ├── pages/ # Route page components with co-located .module.scss +│ ├── router/ # ProtectedRoute wrapper +│ ├── services/ +│ │ ├── api/ # API layer (client.ts singleton, feature modules) +│ │ └── storage/ # Secure storage utilities +│ ├── stores/ # Zustand stores (auth, config, theme, language, notification) +│ ├── styles/ # Global SCSS (variables, mixins, themes, components) +│ ├── types/ # TypeScript type definitions +│ ├── utils/ # Utility functions (constants, format, validation, etc.) +│ ├── App.tsx # Root component with routing +│ └── main.tsx # Entry point +├── dist/ # Build output (single-file bundle) +├── vite.config.ts # Vite configuration +├── tsconfig.json # TypeScript configuration +└── package.json +``` + +### Key Architecture Patterns + +- **Path Alias**: Use `@/` to import from `src/` (configured in vite.config.ts and tsconfig.json) +- **API Client**: Singleton `apiClient` in `src/services/api/client.ts` with auth interceptors +- **State Management**: Zustand stores with localStorage persistence for auth/theme/language +- **Styling**: SCSS variables auto-injected; CSS Modules for component-scoped styles +- **Build Output**: Single-file bundle for easy distribution (all assets inlined) + +## Troubleshooting + +### Connection Issues + +1. Confirm the CLI Proxy API service is running +2. Check if the API address is correct +3. Verify that the management key is valid +4. Ensure your firewall allows the connection + +### Data Not Updating + +1. Click the "Refresh All" button in the header +2. Check your network connection +3. Open browser DevTools console for error details + +### Logs & Config Editor + +- **Logs**: Requires server-side logging-to-file enabled; 404 indicates old server version or logging disabled +- **Config Editor**: Requires `/config.yaml` endpoint; ensure valid YAML syntax before saving + +### Usage Statistics + +- If charts are empty, enable "Usage statistics" in settings; data resets on server restart + +## Contributing + +We welcome Issues and Pull Requests! Please follow these guidelines: + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes with clear messages +4. Push to your branch +5. Open a Pull Request + +### Development Guidelines + +- Run `npm run lint` and `npm run type-check` before committing +- Follow existing code patterns and naming conventions +- Use TypeScript strict mode +- Write meaningful commit messages + +## License + +This project is licensed under the MIT License. diff --git a/README_CN.md b/README_CN.md new file mode 100644 index 0000000..9964d9f --- /dev/null +++ b/README_CN.md @@ -0,0 +1,190 @@ +# CLI Proxy API 管理中心 + +用于管理 CLI Proxy API 的现代化 React Web 界面，采用全新技术栈重构，提供更好的可维护性、类型安全性和用户体验。 + +[English](README.md) + +**主项目**: https://github.com/router-for-me/CLIProxyAPI +**示例地址**: https://remote.router-for.me/ +**最低版本要求**: ≥ 6.3.0（推荐 ≥ 6.5.0） + +自 6.0.19 版本起，WebUI 已集成到主程序中，启动服务后可通过 `/management.html` 访问。 + +## 功能特点 + +### 核心功能 + +- **登录与认证**: 自动检测当前地址（支持手动修改），加密自动登录，会话持久化 +- **基础设置**: 调试模式、代理 URL、请求重试配置、配额溢出自动切换项目/预览模型、使用统计开关、请求日志与文件日志、WebSocket `/ws/*` 鉴权 +- **API 密钥管理**: 管理代理认证密钥，支持添加/编辑/删除操作 +- **AI 提供商**: 配置 Gemini/Codex/Claude，OpenAI 兼容提供商（自定义 Base URL/Headers/代理/模型别名），Vertex AI 服务账号 JSON 导入 +- **认证文件与 OAuth**: 上传/下载/搜索/分页 JSON 凭据；类型筛选（Qwen/Gemini/GeminiCLI/AIStudio/Claude/Codex/Antigravity/iFlow/Vertex/Empty）；批量删除；多提供商 OAuth/设备码流程 +- **日志查看**: 实时日志查看，支持自动刷新、下载和清空（启用"写入日志文件"后显示） +- **使用统计**: 概览卡片、小时/天切换、多模型交互式图表、按 API 统计表格 +- **配置管理**: 内置 YAML 编辑器，支持 `/config.yaml` 语法高亮、重载/保存 +- **系统信息**: 连接状态、配置缓存、服务器版本/构建时间、底栏显示 UI 版本 + +### 用户体验 + +- **响应式设计**: 完整移动端支持，可折叠侧边栏 +- **主题系统**: 明/暗模式切换，偏好持久化 +- **国际化**: 简体中文和英文，无缝切换 +- **实时反馈**: 所有操作的消息通知 +- **安全性**: 密钥遮蔽、加密本地存储 + +## 技术栈 + +- **前端框架**: React 19 + TypeScript +- **构建工具**: Vite 7，单文件输出（[vite-plugin-singlefile](https://github.com/nicknisi/vite-plugin-singlefile)） +- **状态管理**: [Zustand](https://github.com/pmndrs/zustand) +- **路由**: React Router 7 (HashRouter) +- **HTTP 客户端**: Axios，带认证和错误处理拦截器 +- **国际化**: i18next + react-i18next +- **样式**: SCSS + CSS Modules，CSS 变量主题 +- **图表**: Chart.js + react-chartjs-2 +- **代码编辑器**: @uiw/react-codemirror（YAML 支持） + +## 快速开始 + +### 环境要求 + +- Node.js 18+（推荐 LTS 版本） +- npm 9+ + +### 安装 + +```bash +# 克隆仓库 +git clone https://github.com/router-for-me/Cli-Proxy-API-Management-Center.git +cd Cli-Proxy-API-Management-Center + +# 安装依赖 +npm install +``` + +### 开发 + +```bash +npm run dev # 启动 Vite 开发服务器（默认: http://localhost:5173） +``` + +### 构建 + +```bash +npm run build # TypeScript 检查 + Vite 生产构建 +``` + +构建输出单个 `dist/index.html` 文件，所有资源已内联。 + +### 其他命令 + +```bash +npm run preview # 本地预览生产构建 +npm run lint # ESLint 严格模式（--max-warnings 0） +npm run format # Prettier 格式化 src/**/*.{ts,tsx,css,scss} +npm run type-check # 仅 TypeScript 类型检查（tsc --noEmit） +``` + +## 使用方法 + +### 访问方式 + +1. **与 CLI Proxy API 集成使用（推荐）** + 启动 CLI Proxy API 服务后，访问 `http://您的服务器:8317/management.html` + +2. **独立使用（构建后文件）** + 直接在浏览器打开构建的 `dist/index.html`，或部署到任意静态文件服务器 + +3. **开发服务器** + 运行 `npm run dev` 后打开 `http://localhost:5173` + +### 初始配置 + +1. 登录页会自动检测当前地址，可根据需要修改 +2. 输入管理密钥 +3. 点击连接进行认证 +4. 凭据会加密保存到本地，下次自动登录 + +> **提示**: 只有在"基础设置"中启用"写入日志文件"后，才会显示"日志查看"导航项。 + +## 项目结构 + +``` +├── src/ +│ ├── components/ +│ │ ├── common/ # 公共组件（NotificationContainer） +│ │ ├── layout/ # 应用外壳（MainLayout 侧边栏布局） +│ │ └── ui/ # 可复用 UI 组件（Button、Input、Modal 等） +│ ├── hooks/ # 自定义 Hooks（useApi、useDebounce、usePagination 等） +│ ├── i18n/ +│ │ ├── locales/ # 翻译文件（zh-CN.json、en.json） +│ │ └── index.ts # i18next 配置 +│ ├── pages/ # 路由页面组件，配套 .module.scss 样式 +│ ├── router/ # ProtectedRoute 路由守卫 +│ ├── services/ +│ │ ├── api/ # API 层（client.ts 单例，功能模块） +│ │ └── storage/ # 安全存储工具 +│ ├── stores/ # Zustand 状态管理（auth、config、theme、language、notification） +│ ├── styles/ # 全局 SCSS（variables、mixins、themes、components） +│ ├── types/ # TypeScript 类型定义 +│ ├── utils/ # 工具函数（constants、format、validation 等） +│ ├── App.tsx # 根组件与路由 +│ └── main.tsx # 入口文件 +├── dist/ # 构建输出（单文件打包） +├── vite.config.ts # Vite 配置 +├── tsconfig.json # TypeScript 配置 +└── package.json +``` + +### 核心架构模式 + +- **路径别名**: 使用 `@/` 导入 `src/` 目录（在 vite.config.ts 和 tsconfig.json 中配置） +- **API 客户端**: `src/services/api/client.ts` 单例，带认证拦截器 +- **状态管理**: Zustand stores，auth/theme/language 持久化到 localStorage +- **样式**: SCSS 变量自动注入；CSS Modules 实现组件作用域样式 +- **构建输出**: 单文件打包，便于分发（所有资源内联） + +## 故障排除 + +### 连接问题 + +1. 确认 CLI Proxy API 服务正在运行 +2. 检查 API 地址是否正确 +3. 验证管理密钥是否有效 +4. 确认防火墙设置允许连接 + +### 数据不更新 + +1. 点击顶栏的"刷新全部"按钮 +2. 检查网络连接 +3. 打开浏览器开发者工具控制台查看错误信息 + +### 日志与配置编辑 + +- **日志**: 需要服务端启用写文件日志；返回 404 说明服务器版本过旧或未启用日志 +- **配置编辑**: 依赖 `/config.yaml` 接口；保存前请确保 YAML 语法正确 + +### 使用统计 + +- 若图表为空，请在设置中启用"使用统计"；数据在服务重启后会清空 + +## 贡献 + +欢迎提交 Issue 和 Pull Request！请遵循以下指南： + +1. Fork 本仓库 +2. 创建功能分支（`git checkout -b feature/amazing-feature`） +3. 提交更改，使用清晰的提交信息 +4. 推送到分支 +5. 开启 Pull Request + +### 开发规范 + +- 提交前运行 `npm run lint` 和 `npm run type-check` +- 遵循现有代码模式和命名规范 +- 使用 TypeScript 严格模式 +- 编写有意义的提交信息 + +## 许可证 + +本项目采用 MIT 许可证。