工具猿

Appearance

CLI Proxy API Management Center — 项目概览 ​

本文档供 AI Agent 快速了解项目上下文，最后更新：2026-05-27

1. 项目定位 ​

CLI Proxy API Management Center 是一个 纯前端单页应用（SPA），为 CLI Proxy API 提供可视化管理后台。它通过 CLI Proxy API 的 Management API（/v0/management）完成配置管理、凭据上传、日志查看、OAuth 授权等运维操作。

  • 它不是代理本身，不转发任何业务流量。
  • 自 v6.0.19 起，Web UI 随主程序分发，可通过 http://<host>:<api_port>/management.html 访问。
  • 构建产物为 单个内联 HTML 文件（dist/index.html），所有 JS/CSS/图片资源均内联。

2. 技术栈 ​

层面技术选型版本
UI 框架React19.x
语言TypeScript6.0
构建工具Vite（vite-plugin-singlefile）8.x
包管理器Bun1.3.14
状态管理Zustand5.x
HTTP 客户端Axios1.15.2
路由react-router-dom (HashRouter)7.x
动画Motion (原 Framer Motion)12.x
YAML 编辑器CodeMirror 6 (@uiw/react-codemirror)4.x
样式方案SCSS Modules-
国际化i18next + react-i18next26.x / 17.x
YAML 解析yaml2.x
LintESLint + typescript-eslint9.x
格式化Prettier3.x

3. 目录结构 ​

Cli-Proxy-API-Management-Center/
├── .github/                  # CI/CD workflows (release.yml)
├── doc.local/                # 本地文档（本文档所在目录）
├── src/
│   ├── assets/               # 静态资源（logo、SVG 图标）
│   ├── components/
│   │   ├── common/           # 通用组件（通知、确认弹窗、启动屏、页面过渡）
│   │   ├── config/           # 配置编辑器组件（可视化编辑、源码编辑、Diff 预览）
│   │   ├── layout/           # 布局组件（MainLayout）
│   │   ├── modelAlias/       # 模型别名映射图组件
│   │   ├── providers/        # AI Provider 状态栏、工具函数
│   │   ├── quota/            # 配额管理组件
│   │   └── ui/               # 基础 UI 组件（Button, Card, Modal, Input, Select, Table 等）
│   ├── features/
│   │   ├── authFiles/        # Auth Files 功能模块（组件、hooks、状态）
│   │   └── providers/        # AI Providers 功能模块（Workbench 页面、适配器、表单）
│   ├── hooks/                # 全局自定义 hooks（useInterval, useLocalStorage, useMediaQuery 等）
│   ├── i18n/                 # 国际化配置与语言文件（en, zh-CN, zh-TW, ru）
│   ├── pages/                # 页面组件
│   ├── router/               # 路由定义（MainRoutes, ProtectedRoute）
│   ├── services/
│   │   ├── api/              # API 服务层（基于 Axios 的各模块 API 封装）
│   │   └── storage/          # 安全存储（secureStorage，密钥混淆）
│   ├── stores/               # Zustand 状态管理 stores
│   ├── styles/               # 全局样式（变量、主题、mixins、reset）
│   ├── types/                # TypeScript 类型定义
│   └── utils/                # 工具函数
├── index.html                # Vite 入口 HTML
├── package.json
├── tsconfig.json / tsconfig.app.json
├── vite.config.ts            # Vite 配置（未列出但隐含）
├── eslint.config.js
└── .prettierrc

4. 核心功能模块 ​

4.1 Dashboard（仪表盘） ​

  • 路由：/ 或 /dashboard
  • 展示连接状态、服务器版本/构建日期、快速统计、模型可用性快照

4.2 Config（配置管理） ​

  • 路由：/config
  • 可视化编辑器：frontend/src/components/config/VisualConfigEditor.tsx
  • 源码编辑器：frontend/src/components/config/ConfigSourceEditor.tsx（CodeMirror 6 YAML 高亮）
  • Diff 预览：frontend/src/components/config/DiffModal.tsx
  • 支持的配置段：debug, proxy-url, request-retry, quota-exceeded, request-log, logging-to-file, api-keys, ampcode, gemini-api-key, codex-api-key, claude-api-key, vertex-api-key, openai-compatibility, oauth-excluded-models 等

4.3 AI Providers（AI 提供商管理） ​

  • 路由：/ai-providers
  • 功能模块：frontend/src/features/providers/
  • 支持的提供商类型：
    • Gemini — API Key 配置
    • Codex — API Key 配置
    • Claude — API Key 配置
    • Vertex — API Key + 项目配置
    • OpenAI 兼容提供商 — 多 API Key、自定义 Headers、模型别名、连通性测试
    • Ampcode — 上游 URL/Key、模型映射
  • 适配器模式：frontend/src/features/providers/adapters.ts + descriptors.ts
  • 表单组件：frontend/src/features/providers/sheets/forms/

4.4 Auth Files（认证文件管理） ​

  • 路由：/auth-files, /auth-files/oauth-excluded, /auth-files/oauth-model-alias
  • 功能模块：frontend/src/features/authFiles/
  • 支持：上传/下载/删除 JSON 凭据文件、批量操作、过滤/搜索/分页、运行时状态标识、查看每个凭据支持的模型、OAuth 排除模型管理（支持 * 通配符）、OAuth 模型别名映射

4.5 OAuth（OAuth 授权管理） ​

  • 路由：/oauth
  • 支持的 OAuth 流程：
    • Codex — 设备码流程
    • Anthropic/Claude — 设备码流程
    • Antigravity — 设备码流程
    • Gemini CLI — 设备码流程
    • Kimi — 设备码流程
    • xAI/Grok — 设备码流程
  • 功能：启动授权、轮询状态、提交回调 URL、导入 Vertex JSON 凭据、导入 iFlow cookies

4.6 Quota（配额管理） ​

  • 路由：/quota
  • 组件：frontend/src/components/quota/
  • 管理 Claude、Antigravity、Codex、Gemini CLI 等提供商的配额限制和使用情况

4.7 Logs（日志查看） ​

  • 路由：/logs
  • 功能：增量轮询实时日志、自动刷新、搜索过滤、隐藏管理流量、清除日志、下载请求错误日志文件

4.8 System（系统管理） ​

  • 路由：/system
  • 功能：快速链接、版本更新检查、请求日志开关、本地登录数据清理、获取 /v1/models（分组视图）

5. 状态管理（Zustand Stores） ​

Store文件职责
useAuthStorefrontend/src/stores/useAuthStore.ts认证状态（登录/登出、会话恢复、连接状态、API Base/Key 管理）
useConfigStorefrontend/src/stores/useConfigStore.ts配置数据（获取/更新/缓存配置，支持分段获取）
useModelsStorefrontend/src/stores/useModelsStore.ts模型列表数据
useQuotaStorefrontend/src/stores/useQuotaStore.ts配额数据
useThemeStorefrontend/src/stores/useThemeStore.ts主题（亮/暗模式）
useLanguageStorefrontend/src/stores/useLanguageStore.ts语言偏好
useNotificationStorefrontend/src/stores/useNotificationStore.ts全局通知消息

6. API 服务层 ​

基于 Axios 封装的 ApiClient（frontend/src/services/api/client.ts） 类，统一管理 API Base URL、Management Key 注入、错误处理、版本信息提取。

模块文件主要 API
配置frontend/src/services/api/config.ts获取/更新配置、Debug/代理/重试/日志等开关
Providersfrontend/src/services/api/providers.tsGemini/Codex/Claude/Vertex/OpenAI/Ampcode 提供商 CRUD
Auth Filesfrontend/src/services/api/authFiles.ts认证文件上传/下载/删除、OAuth 排除模型、OAuth 模型别名
OAuthfrontend/src/services/api/oauth.tsOAuth 授权 URL 获取、状态轮询、回调提交
Logsfrontend/src/services/api/logs.ts日志获取/清除、错误日志下载
Modelsfrontend/src/services/api/models.ts模型列表获取
Versionfrontend/src/services/api/version.ts版本检查
API Keysfrontend/src/services/api/apiKeys.tsAPI Key 管理
API Key Usagefrontend/src/services/api/apiKeyUsage.tsAPI Key 使用统计
Config Filefrontend/src/services/api/configFile.ts配置文件操作
Transformersfrontend/src/services/api/transformers.ts响应数据标准化/规范化
Vertexfrontend/src/services/api/vertex.tsVertex 凭据导入
Ampcodefrontend/src/services/api/ampcode.tsAmpcode 相关 API

7. 路由结构 ​

使用 react-router-dom v7 的 HashRouter：

路径页面说明
/loginLoginPage登录页（无需认证）
/ /dashboardDashboardPage仪表盘
/configConfigPage配置管理
/ai-providersProvidersWorkbenchPageAI 提供商管理
/auth-filesAuthFilesPage认证文件管理
/auth-files/oauth-excludedAuthFilesOAuthExcludedEditPageOAuth 排除模型编辑
/auth-files/oauth-model-aliasAuthFilesOAuthModelAliasEditPageOAuth 模型别名编辑
/oauthOAuthPageOAuth 授权管理
/quotaQuotaPage配额管理
/logsLogsPage日志查看
/systemSystemPage系统管理

所有非 /login 路由均受 frontend/src/router/ProtectedRoute.tsx 保护，需要先完成认证。

8. 国际化 ​

支持 4 种语言，通过 frontend/src/i18n/index.ts 配置：

  • 简体中文 (zh-CN) — 默认回退语言
  • 繁体中文 (zh-TW)
  • 英文 (en)
  • 俄语 (ru)

语言文件位于 frontend/src/i18n/locales/ 目录。

9. 样式方案 ​

  • 全局样式：frontend/src/styles/（变量 _variables.scss、主题 _themes.scss、mixins、reset）
  • 组件样式：使用 SCSS Modules（*.module.scss）实现样式隔离
  • 支持亮/暗主题切换

10. 安全设计 ​

  • Management Key 存储在浏览器 localStorage 中，使用轻量混淆格式（enc::v1::...），避免明文存储
  • 凭据存储服务：frontend/src/services/storage/secureStorage.ts
  • 认证通过 Authorization: Bearer <MANAGEMENT_KEY> 请求头传递

11. 构建与发布 ​

bash
bun install --frozen-lockfile   # 安装依赖
bun run dev                     # 开发服务器 (localhost:5173)
bun run build                   # tsc + Vite 构建 → dist/index.html（单文件）
bun run preview                 # 本地预览构建产物
bun run lint                    # ESLint 检查
bun run format                  # Prettier 格式化
bun run type-check              # TypeScript 类型检查
  • 构建输出：dist/index.html（所有资源内联）
  • CI/CD：GitHub Actions（.github/workflows/release.yml），tag vX.Y.Z 触发发布

12. 关键约定 ​

  • 路由使用 Hash 模式（createHashRouter），便于单文件部署
  • API 响应标准化：frontend/src/services/api/transformers.ts 处理后端返回的多种字段命名风格（kebab-case/camelCase/snake_case）
  • 配置分段缓存：useConfigStore 支持按配置段独立缓存和过期控制
  • 组件导出：各模块通常有 index.ts 统一导出