docs/advanced-configuration.md

# 高级配置指南

本文档介绍项目的高级配置选项和功能。

## 代理配置管理

### 代理配置优先级

项目采用统一的代理配置管理系统，按以下优先级顺序确定代理设置：

1. **`--internal-camoufox-proxy` 命令行参数** (最高优先级)
   - 明确指定代理：`--internal-camoufox-proxy 'http://127.0.0.1:7890'`
   - 明确禁用代理：`--internal-camoufox-proxy ''`
2. **`UNIFIED_PROXY_CONFIG` 环境变量** (推荐，.env 文件配置)
3. **`HTTP_PROXY` 环境变量**
4. **`HTTPS_PROXY` 环境变量**
5. **系统代理设置** (Linux 下的 gsettings，最低优先级)

**推荐配置方式**:
```env
# .env 文件中统一配置代理
UNIFIED_PROXY_CONFIG=http://127.0.0.1:7890
# 或禁用代理
UNIFIED_PROXY_CONFIG=
```

### 统一代理配置

此代理配置会同时应用于 Camoufox 浏览器和流式代理服务的上游连接，确保整个系统的代理行为一致。

## 响应获取模式配置

### 模式1: 优先使用集成的流式代理 (默认推荐)

**推荐使用 .env 配置方式**:
```env
# .env 文件配置
DEFAULT_FASTAPI_PORT=2048
STREAM_PORT=3120
UNIFIED_PROXY_CONFIG=
```

```bash
# 简化启动命令 (推荐)
python launch_camoufox.py --headless

# 传统命令行方式 (仍然支持)
python launch_camoufox.py --headless --server-port 2048 --stream-port 3120 --helper '' --internal-camoufox-proxy ''
```

# 启用统一代理配置（同时应用于浏览器和流式代理）
python launch_camoufox.py --headless --server-port 2048 --stream-port 3120 --helper '' --internal-camoufox-proxy 'http://127.0.0.1:7890'
```

在此模式下，主服务器会优先尝试通过端口 `3120` (或指定的 `--stream-port`) 上的集成流式代理获取响应。如果失败，则回退到 Playwright 页面交互。

### 模式2: 优先使用外部 Helper 服务 (禁用集成流式代理)

```bash
# 基本外部Helper模式，明确禁用代理
python launch_camoufox.py --headless --server-port 2048 --stream-port 0 --helper 'http://your-helper-service.com/api/getStreamResponse' --internal-camoufox-proxy ''

# 外部Helper模式 + 统一代理配置
python launch_camoufox.py --headless --server-port 2048 --stream-port 0 --helper 'http://your-helper-service.com/api/getStreamResponse' --internal-camoufox-proxy 'http://127.0.0.1:7890'
```

在此模式下，主服务器会优先尝试通过 `--helper` 指定的端点获取响应 (需要有效的 `auth_profiles/active/*.json` 以提取 `SAPISID`)。如果失败，则回退到 Playwright 页面交互。

### 模式3: 仅使用 Playwright 页面交互 (禁用所有流式代理和 Helper)

```bash
# 纯Playwright模式，明确禁用代理
python launch_camoufox.py --headless --server-port 2048 --stream-port 0 --helper '' --internal-camoufox-proxy ''

# Playwright模式 + 统一代理配置
python launch_camoufox.py --headless --server-port 2048 --stream-port 0 --helper '' --internal-camoufox-proxy 'http://127.0.0.1:7890'
```

在此模式下，主服务器将仅通过 Playwright 与 AI Studio 页面交互 (模拟点击"编辑"或"复制"按钮) 来获取响应。这是传统的后备方法。

## 虚拟显示模式 (Linux)

### 关于 `--virtual-display`

- **为什么使用**: 与标准的无头模式相比，虚拟显示模式通过创建一个完整的虚拟 X 服务器环境 (Xvfb) 来运行浏览器。这可以模拟一个更真实的桌面环境，从而可能进一步降低被网站检测为自动化脚本或机器人的风险
- **什么时候使用**: 当您在 Linux 环境下运行，并且希望以无头模式操作
- **如何使用**:
  1. 确保您的 Linux 系统已安装 `xvfb`
  2. 在运行时添加 `--virtual-display` 标志：
     ```bash
     python launch_camoufox.py --virtual-display --server-port 2048 --stream-port 3120 --internal-camoufox-proxy ''
     ```

## 流式代理服务配置

### 自签名证书管理

集成的流式代理服务会在 `certs` 文件夹内生成自签名的根证书。

#### 证书删除与重新生成

- 可以删除 `certs` 目录下的根证书 (`ca.crt`, `ca.key`)，代码会在下次启动时重新生成
- **重要**: 删除根证书时，**强烈建议同时删除 `certs` 目录下的所有其他文件**，避免信任链错误

#### 手动生成证书

如果需要重新生成证书，可以使用以下命令：

```bash
openssl genrsa -out certs/ca.key 2048
openssl req -new -x509 -days 3650 -key certs/ca.key -out certs/ca.crt -subj "/C=CN/ST=Shanghai/L=Shanghai/O=AiStudioProxyHelper/OU=CA/CN=AiStudioProxyHelper CA/emailAddress=ca@example.com"
openssl rsa -in certs/ca.key -out certs/ca.key
```

### 工作原理

流式代理服务的特性：

- 创建一个 HTTP 代理服务器（默认端口：3120）
- 拦截针对 Google 域名的 HTTPS 请求
- 使用自签名 CA 证书动态自动生成服务器证书
- 将 AIStudio 响应解析为 OpenAI 兼容格式

## 模型排除配置

### excluded_models.txt

项目根目录下的 `excluded_models.txt` 文件可用于从 `/v1/models` 端点返回的列表中排除特定的模型 ID。

每行一个模型ID，例如：
```
gemini-1.0-pro
gemini-1.0-pro-vision
deprecated-model-id
```

## 脚本注入高级配置 🆕

### 概述

脚本注入功能允许您动态挂载油猴脚本来增强 AI Studio 的模型列表。该功能使用 Playwright 原生网络拦截技术，确保 100% 可靠性。

### 工作原理

1. **双重拦截机制**：
   - **Playwright 路由拦截**：在网络层面直接拦截和修改模型列表响应
   - **JavaScript 脚本注入**：作为备用方案，确保万无一失

2. **自动模型解析**：
   - 从油猴脚本中自动解析 `MODELS_TO_INJECT` 数组
   - 前端和后端使用相同的模型数据源
   - 无需手动维护模型配置文件

### 高级配置选项

#### 自定义脚本路径

```env
# 使用自定义脚本文件
USERSCRIPT_PATH=custom_scripts/my_enhanced_script.js
```

#### 自定义脚本配置

```env
# 使用自定义脚本文件（模型数据直接从脚本解析）
USERSCRIPT_PATH=configs/production_script.js
```

#### 调试模式

```env
# 启用详细的脚本注入日志
DEBUG_LOGS_ENABLED=true
ENABLE_SCRIPT_INJECTION=true
```

### 自定义脚本开发

#### 脚本格式要求

您的自定义脚本必须包含 `MODELS_TO_INJECT` 数组：

```javascript
const MODELS_TO_INJECT = [
    {
        name: 'models/your-custom-model',
        displayName: '🚀 Your Custom Model',
        description: 'Custom model description'
    },
    // 更多模型...
];
```

#### 脚本模型数组格式

```javascript
const MODELS_TO_INJECT = [
    {
        name: 'models/custom-model-1',
        displayName: `🎯 Custom Model 1 (Script ${SCRIPT_VERSION})`,
        description: `First custom model injected by script ${SCRIPT_VERSION}`
    },
    {
        name: 'models/custom-model-2',
        displayName: `⚡ Custom Model 2 (Script ${SCRIPT_VERSION})`,
        description: `Second custom model injected by script ${SCRIPT_VERSION}`
    }
];
```
```

### 网络拦截技术细节

#### Playwright 路由拦截

```javascript
// 系统会自动设置类似以下的路由拦截
await context.route("**/*", async (route) => {
    const request = route.request();
    if (request.url().includes('alkalimakersuite') &&
        request.url().includes('ListModels')) {
        // 拦截并修改模型列表响应
        const response = await route.fetch();
        const modifiedBody = await modifyModelListResponse(response);
        await route.fulfill({ response, body: modifiedBody });
    } else {
        await route.continue_();
    }
});
```

#### 响应修改流程

1. **请求识别**：检测包含 `alkalimakersuite` 和 `ListModels` 的请求
2. **响应获取**：获取原始模型列表响应
3. **数据解析**：解析 JSON 响应并处理反劫持前缀
4. **模型注入**：将自定义模型注入到响应中
5. **响应返回**：返回修改后的响应给浏览器

### 故障排除

#### 脚本注入失败

1. **检查脚本文件**：
   ```bash
   # 验证脚本文件存在且可读
   ls -la browser_utils/more_modles.js
   cat browser_utils/more_modles.js | head -20
   ```

2. **检查日志输出**：
   ```bash
   # 查看脚本注入相关日志
   python launch_camoufox.py --debug | grep -i "script\|inject"
   ```

3. **验证配置**：
   ```bash
   # 检查环境变量配置
   grep SCRIPT .env
   ```

#### 模型未显示

1. **前端检查**：在浏览器开发者工具中查看是否有 JavaScript 错误
2. **后端检查**：查看 API 响应是否包含注入的模型
3. **网络检查**：确认网络拦截是否正常工作

### 性能优化

#### 脚本缓存

系统会自动缓存解析的模型列表，避免重复解析：

```python
# 系统内部缓存机制
if not hasattr(self, '_cached_models'):
    self._cached_models = parse_userscript_models(script_content)
return self._cached_models
```

#### 网络拦截优化

- 只拦截必要的请求，其他请求直接通过
- 使用高效的 JSON 解析和序列化
- 最小化响应修改的开销

### 安全考虑

#### 脚本安全

- 脚本在受控的浏览器环境中执行
- 不会影响主机系统安全
- 建议只使用可信的脚本源

#### 网络安全

- 网络拦截仅限于特定的模型列表请求
- 不会拦截或修改其他敏感请求
- 所有修改都在本地进行，不会发送到外部服务器

## GUI 启动器高级功能

### 本地LLM模拟服务

GUI 集成了启动和管理一个本地LLM模拟服务的功能：

- **功能**: 监听 `11434` 端口，模拟部分 Ollama API 端点和 OpenAI 兼容的 `/v1/chat/completions` 端点
- **启动**: 在 GUI 的"启动选项"区域，点击"启动本地LLM模拟服务"按钮
- **依赖检测**: 启动前会自动检测 `localhost:2048` 端口是否可用
- **用途**: 主要用于测试客户端与 Ollama 或 OpenAI 兼容 API 的对接

### 端口进程管理

GUI 提供端口进程管理功能：

- 查询指定端口上当前正在运行的进程
- 选择并尝试停止在指定端口上找到的进程
- 手动输入 PID 终止进程

## 环境变量配置

### 代理配置

```bash
# 使用环境变量配置代理（不推荐，建议明确指定）
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
python launch_camoufox.py --headless --server-port 2048 --stream-port 3120 --helper ''
```

### 日志控制

详见 [日志控制指南](logging-control.md)。

## 重要提示

### 代理配置建议

**强烈建议在所有 `launch_camoufox.py` 命令中明确指定 `--internal-camoufox-proxy` 参数，即使其值为空字符串 (`''`)，以避免意外使用系统环境变量中的代理设置。**

### 参数控制限制

API 请求中的模型参数（如 `temperature`, `max_output_tokens`, `top_p`, `stop`）**仅在通过 Playwright 页面交互获取响应时生效**。当使用集成的流式代理或外部 Helper 服务时，这些参数的传递和应用方式取决于这些服务自身的实现。

### 首次访问性能

当通过流式代理首次访问一个新的 HTTPS 主机时，服务需要为该主机动态生成并签署一个新的子证书。这个过程可能会比较耗时，导致对该新主机的首次连接请求响应较慢。一旦证书生成并缓存后，后续访问同一主机将会显著加快。

## 下一步

高级配置完成后，请参考：
- [脚本注入指南](script_injection_guide.md) - 详细的脚本注入功能使用说明
- [日志控制指南](logging-control.md)
- [故障排除指南](troubleshooting.md)