docs/architecture-guide.md

项目架构指南

本文档详细介绍 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 代理服务。