---
description: 容器/浏览器问题排查指南 — 当用户报告 session 异常时，按此流程读取 CDP 日志定位根因
alwaysApply: true
---

# 容器排查指南

当用户说「session xxx 有问题」或报告浏览器异常行为时，按以下流程排查。

## 容器命名

每个 session 对应一个 Docker 容器，名称为 `bp-{session_id[:12]}`。

## 排查步骤

### 1. 读 CDP 事件日志（最重要）

```bash
docker exec bp-{id前12位} tail -100 /tmp/cdp-events.jsonl
```

每行是一个 JSON 对象，关键字段：
- `ts` — UTC 时间戳
- `type` — 事件类型：`console` | `network` | `navigation` | `error`
- `summary` — 一行人类可读摘要
- `method` — CDP 原始方法名

按类型过滤：
```bash
docker exec bp-xxx tail -200 /tmp/cdp-events.jsonl | python3 -c "
import sys, json
for line in sys.stdin:
    e = json.loads(line)
    if e.get('type') == 'error':
        print(e['ts'], e['summary'])
"
```

### 2. 常见问题模式

| 日志特征 | 可能原因 |
|---------|---------|
| 连续 `Network.responseReceived` 302 | 被反爬重定向，需要手动过验证 |
| `Network.loadingFailed` errorText=net::ERR_* | 网络不通或 DNS 解析失败 |
| `Runtime.exceptionThrown` | 页面 JS 报错 |
| 连续重复的 `Page.frameNavigated` 同一 URL | Agent 在重复导航（检查 prompt 规则） |
| 无任何日志 | CDP logger 可能未启动，见步骤 3 |

### 3. 检查 CDP logger 本身

```bash
docker exec bp-xxx cat /tmp/cdp-logger-supervisor.log
```

### 4. 容器进程状态

```bash
docker exec bp-xxx supervisorctl status
```

正常状态应有：`browser` RUNNING、`cdp-logger` RUNNING、其他 selenium 进程。

### 5. 后端 API

也可通过 HTTP 读取日志（前端面板使用此接口）：
```
GET /api/sessions/{session_id}/logs?tail=100&log_type=network
```

### 6. 内部 Docker / Selenium 请求不能走环境代理

后端访问浏览器容器、Selenium Grid、WebDriver、CDP readiness 等内部地址时，HTTP 客户端必须显式绕过部署机器的 `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` 环境变量，例如 `httpx.AsyncClient(..., trust_env=False)`。

典型症状：
- `GET /api/browser/tabs` 返回 `Expecting value: line 1 column 1 (char 0)`
- WebDriver 响应被代理替换成空 body、HTML 错误页、网关错误页
- 局域网访问 API 本身正常，但浏览器操作接口失败

这类问题不要只从外部 curl 判断“局域网不可用”；要继续确认后端到浏览器容器的内部链路是否被代理或错误 host 劫持。

## JSONL 日志示例

```json
{"ts":"2026-04-05T12:03:01.123Z","type":"navigation","method":"Page.frameNavigated","summary":"navigated -> https://www.zhipin.com/web/user/"}
{"ts":"2026-04-05T12:03:01.456Z","type":"network","method":"Network.responseReceived","summary":"<- GET https://www.zhipin.com/api/user 200 45ms"}
{"ts":"2026-04-05T12:03:02.789Z","type":"error","method":"Runtime.exceptionThrown","summary":"TypeError: Cannot read properties of undefined (reading 'map')"}
```