Cursor rule

1---
2description: 容器/浏览器问题排查指南 — 当用户报告 session 异常时，按此流程读取 CDP 日志定位根因
3alwaysApply: true
4---
5 
6# 容器排查指南
7 
8当用户说「session xxx 有问题」或报告浏览器异常行为时，按以下流程排查。
9 
10## 容器命名
11 
12每个 session 对应一个 Docker 容器，名称为 `bp-{session_id[:12]}`。
13 
14## 排查步骤
15 
16### 1. 读 CDP 事件日志（最重要）
17 
18```bash
19docker exec bp-{id前12位} tail -100 /tmp/cdp-events.jsonl
20```
21 
22每行是一个 JSON 对象，关键字段：
23- `ts` — UTC 时间戳
24- `type` — 事件类型：`console` | `network` | `navigation` | `error`
25- `summary` — 一行人类可读摘要
26- `method` — CDP 原始方法名
27 
28按类型过滤：
29```bash
30docker exec bp-xxx tail -200 /tmp/cdp-events.jsonl | python3 -c "
31import sys, json
32for line in sys.stdin:
33    e = json.loads(line)
34    if e.get('type') == 'error':
35        print(e['ts'], e['summary'])
36"
37```
38 
39### 2. 常见问题模式
40 
41| 日志特征 | 可能原因 |
42|---------|---------|
43| 连续 `Network.responseReceived` 302 | 被反爬重定向，需要手动过验证 |
44| `Network.loadingFailed` errorText=net::ERR_* | 网络不通或 DNS 解析失败 |
45| `Runtime.exceptionThrown` | 页面 JS 报错 |
46| 连续重复的 `Page.frameNavigated` 同一 URL | Agent 在重复导航（检查 prompt 规则） |
47| 无任何日志 | CDP logger 可能未启动，见步骤 3 |
48 
49### 3. 检查 CDP logger 本身
50 
51```bash
52docker exec bp-xxx cat /tmp/cdp-logger-supervisor.log
53```
54 
55### 4. 容器进程状态
56 
57```bash
58docker exec bp-xxx supervisorctl status
59```
60 
61正常状态应有：`browser` RUNNING、`cdp-logger` RUNNING、其他 selenium 进程。
62 
63### 5. 后端 API
64 
65也可通过 HTTP 读取日志（前端面板使用此接口）：
66```
67GET /api/sessions/{session_id}/logs?tail=100&log_type=network
68```
69 
70### 6. 内部 Docker / Selenium 请求不能走环境代理
71 
72后端访问浏览器容器、Selenium Grid、WebDriver、CDP readiness 等内部地址时，HTTP 客户端必须显式绕过部署机器的 `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` 环境变量，例如 `httpx.AsyncClient(..., trust_env=False)`。
73 
74典型症状：
75- `GET /api/browser/tabs` 返回 `Expecting value: line 1 column 1 (char 0)`
76- WebDriver 响应被代理替换成空 body、HTML 错误页、网关错误页
77- 局域网访问 API 本身正常，但浏览器操作接口失败
78 
79这类问题不要只从外部 curl 判断“局域网不可用”；要继续确认后端到浏览器容器的内部链路是否被代理或错误 host 劫持。
80 
81## JSONL 日志示例
82 
83```json
84{"ts":"2026-04-05T12:03:01.123Z","type":"navigation","method":"Page.frameNavigated","summary":"navigated -> https://www.zhipin.com/web/user/"}
85{"ts":"2026-04-05T12:03:01.456Z","type":"network","method":"Network.responseReceived","summary":"<- GET https://www.zhipin.com/api/user 200 45ms"}
86{"ts":"2026-04-05T12:03:02.789Z","type":"error","method":"Runtime.exceptionThrown","summary":"TypeError: Cannot read properties of undefined (reading 'map')"}
87```
88