docs/troubleshooting.md

排障指南

1. 启动阶段失败

现象 A：浏览器相关初始化失败

优先检查：

1. CAMOUFOX_WS_ENDPOINT 是否被 launcher 正确注入（或你是否手动提供了有效地址）
2. 网络与代理配置（UNIFIED_PROXY_CONFIG）
3. 是否已有可用认证文件（auth_profiles/active/*.json）

现象 B：/health 一直是 503

查看响应中的 details：

• is_playwright_ready
• is_browser_connected
• is_page_ready
• workerRunning

如果 launchMode=direct_debug_no_browser，browser/page 不是硬依赖。

---

2. 聊天接口超时或挂起

排查步骤

1. 检查请求是否持续积压：GET /v1/queue
2. 查看日志中的 timeout/silence 关键字
3. 调整超时参数：
   • RESPONSE_COMPLETION_TIMEOUT
   • SILENCE_TIMEOUT_MS
   • WAIT_FOR_ELEMENT_TIMEOUT_MS
4. 在 debug 模式观察 AI Studio 页面是否卡住

---

3. Function Calling 异常

建议顺序：

1. FUNCTION_CALLING_MODE=auto
2. 开启 FUNCTION_CALLING_DEBUG=true
3. 仅打开必要 FC_DEBUG_* 模块（先 ORCHESTRATOR/UI/WIRE）
4. 观察 logs/fc_debug/ 具体报错

如是 UI 结构变化导致，可核查 config/selectors.py 相关选择器。

---

4. 认证轮转不生效 / 频繁触发

检查：

• AUTO_ROTATE_AUTH_PROFILE
• AUTO_AUTH_ROTATION_ON_STARTUP
• QUOTA_SOFT_LIMIT / QUOTA_HARD_LIMIT
• saved/ 或 emergency/ 是否有可用 profile

如果“轮转后仍很快触发”，优先确认账号是否都已接近配额。

---

5. Docker 常见问题

认证文件问题

容器无头运行时不能完成交互登录。必须先在宿主机生成认证文件，再挂载 auth_profiles/。

健康检查失败

docker compose logs -f
docker compose exec ai-studio-proxy /bin/bash
curl -v http://127.0.0.1:2048/health

日志/权限问题

如果你挂载了 ../logs:/app/logs，需保证目录可写。