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 代理服务。