Spaces:
Runtime error
Runtime error
| # 项目架构指南 | |
| 本文档详细介绍 AI Studio Proxy API 项目的模块化架构设计、组件职责和交互关系。 | |
| ## 🏗️ 整体架构概览 | |
| 项目采用现代化的模块化架构设计，遵循单一职责原则，确保代码的可维护性和可扩展性。 | |
| ### 核心设计原则 | |
| - **模块化分离**: 按功能领域划分模块，避免循环依赖 | |
| - **单一职责**: 每个模块专注于特定的功能领域 | |
| - **配置统一**: 使用 `.env` 文件和 `config/` 模块统一管理配置 | |
| - **依赖注入**: 通过 `dependencies.py` 管理组件依赖关系 | |
| - **异步优先**: 全面采用异步编程模式，提升性能 | |
| ## 📁 模块结构详解 | |
| ``` | |
| AIstudioProxyAPI/ | |
| ├── api_utils/ # FastAPI 应用核心模块 | |
| │ ├── app.py # FastAPI 应用入口和生命周期管理 | |
| │ ├── routes.py # API 路由定义和端点实现 | |
| │ ├── request_processor.py # 请求处理核心逻辑 | |
| │ ├── queue_worker.py # 异步队列工作器 | |
| │ ├── auth_utils.py # API 密钥认证管理 | |
| │ └── dependencies.py # FastAPI 依赖注入 | |
| ├── browser_utils/ # 浏览器自动化模块 | |
| │ ├── page_controller.py # 页面控制器和生命周期管理 | |
| │ ├── model_management.py # AI Studio 模型管理 | |
| │ ├── script_manager.py # 脚本注入管理 (v3.0) | |
| │ ├── operations.py # 浏览器操作封装 | |
| │ └── initialization.py # 浏览器初始化逻辑 | |
| ├── config/ # 配置管理模块 | |
| │ ├── settings.py # 主要设置和环境变量 | |
| │ ├── constants.py # 系统常量定义 | |
| │ ├── timeouts.py # 超时配置管理 | |
| │ └── selectors.py # CSS 选择器定义 | |
| ├── models/ # 数据模型定义 | |
| │ ├── chat.py # 聊天相关数据模型 | |
| │ ├── exceptions.py # 自定义异常类 | |
| │ └── logging.py # 日志相关模型 | |
| ├── stream/ # 流式代理服务模块 | |
| │ ├── main.py # 流式代理服务入口 | |
| │ ├── proxy_server.py # 代理服务器实现 | |
| │ ├── interceptors.py # 请求拦截器 | |
| │ └── utils.py # 流式处理工具 | |
| ├── logging_utils/ # 日志管理模块 | |
| │ └── setup.py # 日志系统配置 | |
| └── node_stream/ # Node流式处理模块 | |
| ``` | |
| ## 🔧 核心模块详解 | |
| ### 1. api_utils/ - FastAPI 应用核心 | |
| **职责**: FastAPI 应用的核心逻辑，包括路由、认证、请求处理等。 | |
| #### app.py - 应用入口 | |
| - FastAPI 应用创建和配置 | |
| - 生命周期管理 (startup/shutdown) | |
| - 中间件配置 (API 密钥认证) | |
| - 全局状态初始化 | |
| #### routes.py - API 路由 | |
| - `/v1/chat/completions` - 聊天完成端点 | |
| - `/v1/models` - 模型列表端点 | |
| - `/api/keys/*` - API 密钥管理端点 | |
| - `/health` - 健康检查端点 | |
| - WebSocket 日志端点 | |
| #### request_processor.py - 请求处理核心 | |
| - 三层响应获取机制实现 | |
| - 流式和非流式响应处理 | |
| - 客户端断开检测 | |
| - 错误处理和重试逻辑 | |
| #### queue_worker.py - 队列工作器 | |
| - 异步请求队列处理 | |
| - 并发控制和资源管理 | |
| - 请求优先级处理 | |
| ### 2. browser_utils/ - 浏览器自动化 | |
| **职责**: 浏览器自动化、页面控制、脚本注入等功能。 | |
| #### page_controller.py - 页面控制器 | |
| - Camoufox 浏览器生命周期管理 | |
| - 页面导航和状态监控 | |
| - 认证文件管理 | |
| #### script_manager.py - 脚本注入管理 (v3.0) | |
| - Playwright 原生网络拦截 | |
| - 油猴脚本解析和注入 | |
| - 模型数据同步 | |
| #### model_management.py - 模型管理 | |
| - AI Studio 模型列表获取 | |
| - 模型切换和验证 | |
| - 排除模型处理 | |
| ### 3. config/ - 配置管理 | |
| **职责**: 统一的配置管理，包括环境变量、常量、超时等。 | |
| #### settings.py - 主要设置 | |
| - `.env` 文件加载 | |
| - 环境变量解析 | |
| - 配置验证和默认值 | |
| #### constants.py - 系统常量 | |
| - API 端点常量 | |
| - 错误代码定义 | |
| - 系统标识符 | |
| ### 4. stream/ - 流式代理服务 | |
| **职责**: 独立的流式代理服务，提供高性能的请求转发。 | |
| #### proxy_server.py - 代理服务器 | |
| - HTTP/HTTPS 代理实现 | |
| - 请求拦截和修改 | |
| - 上游代理支持 | |
| #### interceptors.py - 请求拦截器 | |
| - AI Studio 请求拦截 | |
| - 响应数据解析 | |
| - 流式数据处理 | |
| ## 🔄 三层响应获取机制 | |
| 项目实现了三层响应获取机制，确保高可用性和最佳性能： | |
| ### 第一层: 集成流式代理 (Stream Proxy) | |
| - **位置**: `stream/` 模块 | |
| - **端口**: 3120 (可配置) | |
| - **优势**: 最佳性能，直接处理请求 | |
| - **适用**: 日常使用，生产环境 | |
| ### 第二层: 外部 Helper 服务 | |
| - **配置**: 通过 `--helper` 参数或环境变量 | |
| - **依赖**: 需要有效的认证文件 | |
| - **适用**: 备用方案，特殊环境 | |
| ### 第三层: Playwright 页面交互 | |
| - **位置**: `browser_utils/` 模块 | |
| - **方式**: 浏览器自动化操作 | |
| - **优势**: 完整参数支持，最终后备 | |
| - **适用**: 调试模式，参数精确控制 | |
| ## 🔐 认证系统架构 | |
| ### API 密钥管理 | |
| - **存储**: `auth_profiles/key.txt` 文件 | |
| - **格式**: 每行一个密钥 | |
| - **验证**: Bearer Token 和 X-API-Key 双重支持 | |
| - **管理**: Web UI 分级权限查看 | |
| ### 浏览器认证 | |
| - **文件**: `auth_profiles/active/*.json` | |
| - **内容**: 浏览器会话和 Cookie | |
| - **更新**: 通过调试模式重新获取 | |
| ## 📊 配置管理架构 | |
| ### 配置优先级 | |
| 1. **命令行参数** (最高优先级) | |
| 2. **环境变量** (`.env` 文件) | |
| 3. **默认值** (代码中定义) | |
| ### 配置分类 | |
| - **服务配置**: 端口、代理、日志等 | |
| - **功能配置**: 脚本注入、认证、超时等 | |
| - **API 配置**: 默认参数、模型设置等 | |
| ## 🚀 脚本注入架构 v3.0 | |
| ### 工作机制 | |
| 1. **脚本解析**: 从油猴脚本解析 `MODELS_TO_INJECT` 数组 | |
| 2. **网络拦截**: Playwright 拦截 `/api/models` 请求 | |
| 3. **数据合并**: 将注入模型与原始模型合并 | |
| 4. **响应修改**: 返回包含注入模型的完整列表 | |
| 5. **前端注入**: 同时注入脚本确保显示一致 | |
| ### 技术优势 | |
| - **100% 可靠**: Playwright 原生拦截，无时序问题 | |
| - **零维护**: 脚本更新自动生效 | |
| - **完全同步**: 前后端使用相同数据源 | |
| ## 🔧 开发和部署 | |
| ### 开发环境 | |
| - **依赖管理**: Poetry | |
| - **类型检查**: Pyright | |
| - **代码格式**: Black + isort | |
| - **测试框架**: pytest | |
| ### 部署方式 | |
| - **本地部署**: Poetry 虚拟环境 | |
| - **Docker 部署**: 多阶段构建，支持多架构 | |
| - **配置管理**: 统一的 `.env` 文件 | |
| ## 📈 性能优化 | |
| ### 异步处理 | |
| - 全面采用 `async/await` | |
| - 异步队列处理请求 | |
| - 并发控制和资源管理 | |
| ### 缓存机制 | |
| - 模型列表缓存 | |
| - 认证状态缓存 | |
| - 配置热重载 | |
| ### 资源管理 | |
| - 浏览器实例复用 | |
| - 连接池管理 | |
| - 内存优化 | |
| ## 🔍 监控和调试 | |
| ### 日志系统 | |
| - 分级日志记录 | |
| - WebSocket 实时日志 | |
| - 错误追踪和报告 | |
| ### 健康检查 | |
| - 组件状态监控 | |
| - 队列长度监控 | |
| - 性能指标收集 | |
| 这种模块化架构确保了项目的可维护性、可扩展性和高性能，为用户提供稳定可靠的 AI Studio 代理服务。 | |