docs/troubleshooting.md

故障排除指南

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

快速诊断

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

1. 检查服务状态

# 检查服务是否正常运行
curl http://127.0.0.1:2048/health

# 检查API信息
curl http://127.0.0.1:2048/api/info

2. 检查配置文件

# 检查 .env 文件是否存在
ls -la .env

# 检查关键配置项
grep -E "(PORT|SCRIPT_INJECTION|LOG_LEVEL)" .env

3. 查看日志

# 查看最新日志
tail -f logs/app.log

# 查看错误日志
grep -i error logs/app.log

安装相关问题

Python 版本兼容性问题

Python 版本过低:

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

常见版本问题:

# 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 下载安装

虚拟环境版本问题:

# 检查虚拟环境中的 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 脚本，它会尝试禁用 SSL 验证来下载 (有安全风险，仅在确认网络环境可信时使用)。

playwright install-deps 失败

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

启动相关问题

launch_camoufox.py 启动报错

• 检查 Camoufox 是否已通过 camoufox fetch 正确下载。
• 查看终端输出，是否有来自 Camoufox 库的具体错误信息。
• 确保没有其他 Camoufox 或 Playwright 进程冲突。

端口被占用

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

• 如果使用 gui_launcher.py 启动，它会尝试自动检测并提示终止占用进程。

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

  # Windows
  netstat -ano | findstr 2048
  
  # Linux/macOS
  lsof -i :2048
  

• 或修改 launch_camoufox.py 的 --server-port 参数。

认证相关问题

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

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

解决方案:

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

检查认证状态

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

流式代理服务问题

端口冲突

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

代理配置问题

推荐使用 .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 浏览器连接状态

详细说明请参见 流式处理模式详解。

自签名证书管理

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

证书删除与重新生成:

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

API 请求问题

5xx / 499 错误

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

客户端无法连接

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

AI 回复不完整/格式错误

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

页面交互问题

自动清空上下文失败

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

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

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

1. 检查主服务器日志中的警告或错误
2. 检查 errors_py/ 目录下的错误快照
3. 对比实际页面元素，更新 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 密钥验证
• 如需启用验证，手动添加密钥到文件中

文件权限问题:

# 检查文件权限
ls -la key.txt

# 修复权限问题
chmod 644 key.txt

文件格式问题:

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

API 认证失败

401 Unauthorized 错误:

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

  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 密钥认证失败，需要重新验证密钥
• 无法发送空消息: 这是正常的安全机制
• 对话请求失败: 检查网络连接，确认服务器正常运行

脚本注入问题 🆕

脚本注入功能未启用

检查配置:

# 检查 .env 文件中的配置
grep SCRIPT_INJECTION .env
grep USERSCRIPT_PATH .env

常见问题:

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

解决方案:

# 启用脚本注入
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. 检查网络选项卡中的模型列表请求

后端检查:

# 查看脚本注入相关日志
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 数组
• 网络拦截失败，脚本注入未生效
• 模型名称格式不正确

脚本解析失败

检查脚本格式:

// 确保脚本包含正确的模型数组格式
const MODELS_TO_INJECT = [
  {
    name: "models/your-model-name",
    displayName: "Your Model Display Name",
    description: "Model description",
  },
];

调试步骤:

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

网络拦截失败

检查 Playwright 状态:

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

调试方法:

# 启用详细日志查看网络拦截状态
export DEBUG_LOGS_ENABLED=true
python launch_camoufox.py --debug

常见错误:

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

模型解析问题

脚本格式错误:

# 检查脚本文件语法
node -c browser_utils/more_modles.js

文件权限问题:

# 检查文件权限
ls -la browser_utils/more_modles.js

# 修复权限
chmod 644 browser_utils/more_modles.js

脚本文件不存在:

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

性能问题

脚本注入延迟:

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

内存使用:

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

调试技巧

启用详细日志:

# 在 .env 文件中添加
DEBUG_LOGS_ENABLED=true
TRACE_LOGS_ENABLED=true
SERVER_LOG_LEVEL=DEBUG

检查注入状态:

# 查看脚本注入相关的日志输出
tail -f logs/app.log | grep -i "script\|inject"

验证模型注入:

# 检查 API 返回的模型列表
curl -s http://localhost:2048/v1/models | jq '.data[] | select(.injected == true) | {id, display_name}'

禁用脚本注入

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

# 方法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 及以上级别的日志

环境变量控制

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

# 设置日志级别
export SERVER_LOG_LEVEL=DEBUG

# 启用详细调试日志
export DEBUG_LOGS_ENABLED=true

# 启用跟踪日志（通常不需要）
export TRACE_LOGS_ENABLED=true

错误快照

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

性能问题

Asyncio 相关错误

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

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

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

获取帮助

如果问题仍未解决：

1. 查看项目的 GitHub Issues
2. 提交新的 Issue 并包含：
   • 详细的错误描述
   • 相关的日志文件内容
   • 系统环境信息
   • 复现步骤

下一步

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

• 脚本注入指南 - 脚本注入功能详细说明
• 日志控制指南
• 高级配置指南