docs/troubleshooting.md

# 故障排除指南

本文档提供 AI Studio Proxy API 项目常见问题的解决方案和调试方法，涵盖安装、配置、运行、API 使用等各个方面。

## 快速诊断

在深入具体问题之前，可以先进行快速诊断：

### 1. 检查服务状态

```bash

# 检查服务是否正常运行

curl http://127.0.0.1:2048/health



# 检查API信息

curl http://127.0.0.1:2048/api/info

```

### 2. 检查配置文件

```bash

# 检查 .env 文件是否存在

ls -la .env



# 检查关键配置项

grep -E "(PORT|SCRIPT_INJECTION|LOG_LEVEL)" .env

```

### 3. 查看日志

```bash

# 查看最新日志

tail -f logs/app.log



# 查看错误日志

grep -i error logs/app.log

```

## 安装相关问题

### Python 版本兼容性问题

**Python 版本过低**:

- **最低要求**: Python 3.9+
- **推荐版本**: Python 3.10+ 或 3.11+
- **检查版本**: `python --version`

**常见版本问题**:

```bash

# Python 3.8 或更低版本可能出现的错误

TypeError: 'type' object is not subscriptable

SyntaxError: invalid syntax (类型提示相关)



# 解决方案：升级 Python 版本

# macOS (使用 Homebrew)

brew install python@3.11



# Ubuntu/Debian

sudo apt update && sudo apt install python3.11



# Windows: 从 python.org 下载安装

```

**虚拟环境版本问题**:

```bash

# 检查虚拟环境中的 Python 版本

python -c "import sys; print(sys.version)"



# 使用指定版本创建虚拟环境

python3.11 -m venv venv

source venv/bin/activate  # Linux/macOS

# venv\Scripts\activate  # Windows

```

### `pip install camoufox[geoip]` 失败

- 可能是网络问题或缺少编译环境。尝试不带 `[geoip]` 安装 (`pip install camoufox`)。

### `camoufox fetch` 失败

- 常见原因是网络问题或 SSL 证书验证失败。
- 可以尝试运行 [`python fetch_camoufox_data.py`](../fetch_camoufox_data.py) 脚本，它会尝试禁用 SSL 验证来下载 (有安全风险，仅在确认网络环境可信时使用)。

### `playwright install-deps` 失败

- 通常是 Linux 系统缺少必要的库。仔细阅读错误信息，根据提示安装缺失的系统包 (如 `libgbm-dev`, `libnss3` 等)。

## 启动相关问题

### `launch_camoufox.py` 启动报错



- 检查 Camoufox 是否已通过 `camoufox fetch` 正确下载。

- 查看终端输出，是否有来自 Camoufox 库的具体错误信息。

- 确保没有其他 Camoufox 或 Playwright 进程冲突。



### 端口被占用



如果 [`server.py`](../server.py) 启动时提示端口 (`2048`) 被占用：



- 如果使用 [`gui_launcher.py`](../gui_launcher.py) 启动，它会尝试自动检测并提示终止占用进程。

- 手动查找并结束占用进程：



  ```bash

  # Windows

  netstat -ano | findstr 2048



  # Linux/macOS

  lsof -i :2048

  ```



- 或修改 [`launch_camoufox.py`](../launch_camoufox.py) 的 `--server-port` 参数。



## 认证相关问题



### 认证失败 (特别是无头模式)



**最常见**: `auth_profiles/active/` 下的 `.json` 文件已过期或无效。

**解决方案**:

1. 删除 `active` 下的文件
2. 重新运行 [`python launch_camoufox.py --debug`](../launch_camoufox.py) 生成新的认证文件
3. 将新文件移动到 `active` 目录
4. 确认 `active` 目录下只有一个 `.json` 文件

### 检查认证状态

- 查看 [`server.py`](../server.py) 日志（可通过 Web UI 的日志侧边栏查看，或 `logs/app.log`）
- 看是否明确提到登录重定向

## 流式代理服务问题

### 端口冲突

确保流式代理服务使用的端口 (`3120` 或自定义的 `--stream-port`) 未被其他应用占用。

### 代理配置问题

**推荐使用 .env 配置方式**:

```env

# 统一代理配置

UNIFIED_PROXY_CONFIG=http://127.0.0.1:7890

# 或禁用代理

UNIFIED_PROXY_CONFIG=

```

**常见问题**:

- **代理不生效**: 确保在 `.env` 文件中设置 `UNIFIED_PROXY_CONFIG` 或使用 `--internal-camoufox-proxy` 参数
- **代理冲突**: 使用 `UNIFIED_PROXY_CONFIG=` 或 `--internal-camoufox-proxy ''` 明确禁用代理
- **代理连接失败**: 检查代理服务器是否可用，代理地址格式是否正确

### 三层响应获取机制问题

**流式响应中断**:

- 检查集成流式代理状态 (端口 3120)
- 尝试禁用流式代理测试：在 `.env` 中设置 `STREAM_PORT=0`
- 查看 `/health` 端点了解各层状态

**响应获取失败**:

1. **第一层失败**: 检查流式代理服务是否正常运行
2. **第二层失败**: 验证 Helper 服务配置和认证文件
3. **第三层失败**: 检查 Playwright 浏览器连接状态

详细说明请参见 [流式处理模式详解](streaming-modes.md)。

### 自签名证书管理

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

**证书删除与重新生成**:

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

## API 请求问题

### 5xx / 499 错误

- **503 Service Unavailable**: [`server.py`](../server.py) 未完全就绪
- **504 Gateway Timeout**: AI Studio 响应慢或处理超时
- **502 Bad Gateway**: AI Studio 页面返回错误。检查 `errors_py/` 快照
- **500 Internal Server Error**: [`server.py`](../server.py) 内部错误。检查日志和 `errors_py/` 快照
- **499 Client Closed Request**: 客户端提前断开连接

### 客户端无法连接

- 确认 API 基础 URL 配置正确 (`http://<服务器IP或localhost>:端口/v1`，默认端口 2048)
- 检查 [`server.py`](../server.py) 日志是否有错误

### AI 回复不完整/格式错误

- AI Studio Web UI 输出不稳定。检查 `errors_py/` 快照

## 页面交互问题

### 自动清空上下文失败

- 检查主服务器日志中的警告
- 很可能是 AI Studio 页面更新导致 [`config/selectors.py`](../config/selectors.py) 中的 CSS 选择器失效
- 检查 `errors_py/` 快照，对比实际页面元素更新选择器常量

### AI Studio 页面更新导致功能失效

如果 AI Studio 更新了网页结构或 CSS 类名：

1. 检查主服务器日志中的警告或错误
2. 检查 `errors_py/` 目录下的错误快照
3. 对比实际页面元素，更新 [`config/selectors.py`](../config/selectors.py) 中对应的 CSS 选择器常量

### 模型参数设置未生效

这可能是由于 AI Studio 页面的 `localStorage` 中的 `isAdvancedOpen` 未正确设置为 `true`：

- 代理服务在启动时会尝试自动修正这些设置并重新加载页面
- 如果问题依旧，可以尝试清除浏览器缓存和 `localStorage` 后重启代理服务

## Web UI 问题

### 无法显示日志或服务器信息

- 检查浏览器开发者工具 (F12) 的控制台和网络选项卡是否有错误
- 确认 WebSocket 连接 (`/ws/logs`) 是否成功建立
- 确认 `/health` 和 `/api/info` 端点是否能正常访问

## API 密钥相关问题

### key.txt 文件问题

**文件不存在或为空**:

- 系统会自动创建空的 `auth_profiles/key.txt` 文件
- 空文件意味着不需要 API 密钥验证
- 如需启用验证，手动添加密钥到文件中

**文件权限问题**:

```bash

# 检查文件权限

ls -la key.txt



# 修复权限问题

chmod 644 key.txt

```

**文件格式问题**:

- 确保每行一个密钥，无额外空格
- 支持空行和以 `#` 开头的注释行
- 使用 UTF-8 编码保存文件

### API 认证失败

**401 Unauthorized 错误**:

- 检查请求头是否包含正确的认证信息
- 验证密钥是否在 `key.txt` 文件中
- 确认使用正确的认证头格式：
  ```bash

  Authorization: Bearer your-api-key

  # 或

  X-API-Key: your-api-key

  ```

**密钥验证逻辑**:

- 如果 `key.txt` 为空，所有请求都不需要认证
- 如果 `key.txt` 有内容，所有 `/v1/*` 请求都需要认证
- 除外路径：`/v1/models`, `/health`, `/docs` 等

### Web UI 密钥管理问题

**无法验证密钥**:

- 检查输入的密钥格式，确保至少 8 个字符
- 确认服务器上的 `key.txt` 文件包含该密钥
- 检查网络连接，确认 `/api/keys/test` 端点可访问

**验证成功但无法查看密钥列表**:

- 检查浏览器控制台是否有 JavaScript 错误
- 确认 `/api/keys` 端点返回正确的 JSON 格式数据
- 尝试刷新页面重新验证

**验证状态丢失**:

- 验证状态仅在当前浏览器会话中有效
- 关闭浏览器或标签页会丢失验证状态
- 需要重新验证才能查看密钥列表

**密钥显示异常**:

- 确认服务器返回的密钥数据格式正确
- 检查密钥打码显示功能是否正常工作
- 验证 `maskApiKey` 函数是否正确执行

### 客户端配置问题

**Open WebUI 配置**:

- API 基础 URL：`http://127.0.0.1:2048/v1`
- API 密钥：输入有效的密钥或留空（如果服务器不需要认证）
- 确认端口号与服务器实际监听端口一致

**其他客户端配置**:

- 检查客户端是否支持 `Authorization: Bearer` 认证头
- 确认客户端正确处理 401 认证错误
- 验证客户端的超时设置是否合理

### 密钥管理最佳实践

**安全建议**:

- 定期更换 API 密钥
- 不要在日志或公开场所暴露完整密钥
- 使用足够复杂的密钥（建议 16 个字符以上）
- 限制密钥的使用范围和权限

**备份建议**:

- 定期备份 `key.txt` 文件
- 记录密钥的创建时间和用途
- 建立密钥轮换机制

### 对话功能问题

- **发送消息后收到 401 错误**: API 密钥认证失败，需要重新验证密钥
- **无法发送空消息**: 这是正常的安全机制
- **对话请求失败**: 检查网络连接，确认服务器正常运行

## 脚本注入问题 🆕

### 脚本注入功能未启用

**检查配置**:

```bash

# 检查 .env 文件中的配置

grep SCRIPT_INJECTION .env

grep USERSCRIPT_PATH .env

```

**常见问题**:

- `ENABLE_SCRIPT_INJECTION=false` - 功能被禁用
- 脚本文件路径不正确
- 脚本文件不存在或无法读取

**解决方案**:

```bash

# 启用脚本注入

echo "ENABLE_SCRIPT_INJECTION=true" >> .env



# 检查脚本文件是否存在

ls -la browser_utils/more_modles.js



# 检查文件权限

chmod 644 browser_utils/more_modles.js

```

### 模型未显示在列表中

**前端检查**:

1. 打开浏览器开发者工具 (F12)
2. 查看控制台是否有 JavaScript 错误
3. 检查网络选项卡中的模型列表请求

**后端检查**:

```bash

# 查看脚本注入相关日志

python launch_camoufox.py --debug | grep -i "script\|inject\|model"



# 检查 API 响应

curl http://localhost:2048/v1/models | jq '.data[] | select(.injected == true)'

```

**常见原因**:

- 脚本格式错误，无法解析 `MODELS_TO_INJECT` 数组
- 网络拦截失败，脚本注入未生效
- 模型名称格式不正确

### 脚本解析失败

**检查脚本格式**:

```javascript

// 确保脚本包含正确的模型数组格式

const MODELS_TO_INJECT = [

  {

    name: "models/your-model-name",

    displayName: "Your Model Display Name",

    description: "Model description",

  },

];

```

**调试步骤**:

1. 验证脚本文件的 JavaScript 语法
2. 检查模型数组的格式是否正确
3. 确认模型名称以 `models/` 开头

### 网络拦截失败

**检查 Playwright 状态**:

- 确认浏览器上下文正常创建
- 检查网络路由是否正确设置
- 验证请求 URL 匹配规则

**调试方法**:

```bash

# 启用详细日志查看网络拦截状态

export DEBUG_LOGS_ENABLED=true

python launch_camoufox.py --debug

```

**常见错误**:

- 浏览器上下文创建失败
- 网络路由设置异常
- 请求 URL 不匹配拦截规则

### 模型解析问题

**脚本格式错误**:

```bash

# 检查脚本文件语法

node -c browser_utils/more_modles.js

```

**文件权限问题**:

```bash

# 检查文件权限

ls -la browser_utils/more_modles.js



# 修复权限

chmod 644 browser_utils/more_modles.js

```

**脚本文件不存在**:

- 系统会静默跳过不存在的脚本文件
- 检查 `USERSCRIPT_PATH` 环境变量设置
- 确保脚本文件包含有效的 `MODELS_TO_INJECT` 数组

### 性能问题

**脚本注入延迟**:

- 网络拦截可能增加轻微延迟
- 大量模型注入可能影响页面加载
- 建议限制注入模型数量（< 20 个）

**内存使用**:

- 脚本内容会被缓存在内存中
- 大型脚本文件可能增加内存使用
- 定期重启服务释放内存

### 调试技巧

**启用详细日志**:

```bash

# 在 .env 文件中添加

DEBUG_LOGS_ENABLED=true

TRACE_LOGS_ENABLED=true

SERVER_LOG_LEVEL=DEBUG

```

**检查注入状态**:

```bash

# 查看脚本注入相关的日志输出

tail -f logs/app.log | grep -i "script\|inject"

```

**验证模型注入**:

```bash

# 检查 API 返回的模型列表

curl -s http://localhost:2048/v1/models | jq '.data[] | select(.injected == true) | {id, display_name}'

```

### 禁用脚本注入

如果遇到严重问题，可以临时禁用脚本注入：

```bash

# 方法1：修改 .env 文件

echo "ENABLE_SCRIPT_INJECTION=false" >> .env



# 方法2：使用环境变量

export ENABLE_SCRIPT_INJECTION=false

python launch_camoufox.py --headless



# 方法3：删除脚本文件（临时）

mv browser_utils/more_modles.js browser_utils/more_modles.js.bak

```

## 日志和调试

### 查看详细日志

- `logs/app.log`: FastAPI 服务器详细日志
- `logs/launch_app.log`: 启动器日志
- Web UI 右侧边栏: 实时显示 `INFO` 及以上级别的日志

### 环境变量控制

可以通过环境变量控制日志详细程度：

```bash

# 设置日志级别

export SERVER_LOG_LEVEL=DEBUG



# 启用详细调试日志

export DEBUG_LOGS_ENABLED=true



# 启用跟踪日志（通常不需要）

export TRACE_LOGS_ENABLED=true

```

### 错误快照

出错时会自动在 `errors_py/` 目录保存截图和 HTML，这些文件对调试很有帮助。

## 性能问题

### Asyncio 相关错误

您可能会在日志中看到一些与 `asyncio` 相关的错误信息，特别是在网络连接不稳定时。如果核心代理功能仍然可用，这些错误可能不直接影响主要功能。

### 首次访问新主机的性能问题

当通过流式代理首次访问一个新的 HTTPS 主机时，服务需要动态生成证书，这个过程可能比较耗时。一旦证书生成并缓存后，后续访问会显著加快。

## 获取帮助

如果问题仍未解决：

1. 查看项目的 [GitHub Issues](https://github.com/CJackHwang/AIstudioProxyAPI/issues)
2. 提交新的 Issue 并包含：
   - 详细的错误描述
   - 相关的日志文件内容
   - 系统环境信息
   - 复现步骤

## 下一步

故障排除完成后，请参考：

- [脚本注入指南](script_injection_guide.md) - 脚本注入功能详细说明
- [日志控制指南](logging-control.md)
- [高级配置指南](advanced-configuration.md)