Bright Data — 浏览器会话调试器

使用 Browser Sessions API 诊断 Bright Data 抓取浏览器（Scraping Browser）会话。获取实时会话数据并执行智能分诊：错误诊断、带宽分析、验证码上报，以及在近期会话中检测异常模式。

配置

设置您的 API 密钥：

export BRIGHTDATA_API_KEY="your-api-key"

密钥可从 Bright Data 控制台 → API Tokens 页面获取。

无需配置 zone — zone 将作为会话数据中的一个字段返回。

使用方法

列出并分诊近期会话

不带任何参数调用 /brd-browser-debug 即可启动该功能。

API 参考： GET /browser_sessions

获取会话数据

建议首先发起一次请求，使用最大限制 limit=100，并按时间倒序排列（最新优先）：

GET https://api.brightdata.com/browser_sessions?limit=100&sort=timestamp&order=desc
Authorization: Bearer $BRIGHTDATA_API_KEY

分页机制： 响应中包含 total、has_more 和 next_offset 字段。若 has_more 为 true，且当前分析需要更多数据（例如：带宽离群值检测需更大样本量），则使用 offset= 获取下一页数据。持续翻页，直至满足数据需求或 has_more 变为 false。

可用过滤器 —— 当用户指定了作用范围时应用以下过滤条件：

• status=failed|finished|running —— 限定为特定会话状态
• api_name= —— 限定为特定 Bright Data zone
• target_url= —— 按目标域名过滤（例如：ksp.co.il）
• start_date / end_date —— ISO 8601 格式的时间范围
• sort=timestamp|duration|bandwidth 配合 order=asc|desc

若用户询问了特定 zone、日期范围或域名，请直接在 API 请求中应用对应过滤器，而非拉取全部会话后在客户端进行过滤。

分诊步骤

1. 呈现一份健康概览：响应中的 total 总数，以及 finished / failed / running 各状态的计数。
2. 最近一次会话 —— 无论其状态如何，始终高亮展示（细节深度与单一会话模式一致）。
3. 失败会话 —— 对每个失败会话，列出其 session ID、时间戳、持续时间、带宽，并结合下方“失败会话诊断”部分所述信号，推断失败原因。
4. 模式检测 —— 若有 3 个及以上会话共享相同的 error.code，则判定为系统性问题：

   “3 个会话因 custom_headers 失败 —— 您覆盖了 Bright Data 禁止使用的请求头。请从代码中移除 page.setExtraHTTPHeaders()。”

5. 带宽离群值 —— 按 target_url 所属域名对会话分组。对每个拥有 ≥3 个会话的域名，计算其带宽中位数；若某会话带宽超过该域名中位数的 2 倍，则标记为离群值，并注明该会话是否为失败会话、且在终止前消耗了异常高的带宽。
6. 验证码活动 —— 统计命中验证码的会话数量，并说明其中成功解决的比例。
7. 以一句结论性判断收尾：指出最重要的发现，以及最具影响的修复建议。

检查单个会话

通过 /brd-browser-debug 调用。

API 参考： GET /browser_sessions/{session_id}

1. 发起请求：

   GET https://api.brightdata.com/browser_sessions/
   Authorization: Bearer $BRIGHTDATA_API_KEY
   

   若返回 404（会话 ID 未找到），请明确告知用户并中止后续流程。

2. 基于响应字段进行深度剖析：

   • 状态（status）：running / finished / failed
   • zone（api_name）：处理该会话的 Bright Data zone
   • 时间戳（timestamp）：ISO 8601 格式 —— 展示为本地友好的时间格式
   • 持续时间（duration）：单位为秒（可为空）—— 若失败且持续时间 < 2 秒，需特别标注（会话几乎未启动）
   • 带宽（bandwidth）：将字节数转换为 MB 显示
   • 导航次数（navigations）：若为 0，需标注（页面未加载任何内容）
   • 验证码（captcha）：取值为 solved / none / detected / failed —— detected 表示出现验证码挑战但未解决；failed 表示尝试解决但失败
   • 路由路径：从 target_url 到 end_url —— 若发生显著跳转（跨域、登录页、错误页等），需特别注明
   • 错误信息（error.code + error.message）：结合下方“失败会话诊断”部分的信号综合分析失败原因

3. 以一句结论性判断收尾。

从对话上下文中自动识别

当对话中出现 Bright Data 浏览器相关问题时 —— 包括 Puppeteer 堆栈跟踪、错误码、提及 brd.superproxy.io、用户描述会话失败，或爬虫产出空结果/非预期结果（例如：“找到 0 个分类”、“获取到 0 个商品”、结果数量明显少于预期）：

• 若输出中可见 session ID → 对其执行单一会话深度剖析。
• 若未见 session ID → 执行列表与分诊，并按相关目标域名进行过滤。将最近一次会话高亮为最可能的问题根源。
• 将对话中观察到的错误或异常行为，与 API 返回的数据交叉比对。例如：某会话显示为 successful 结束、带宽正常，但爬虫却返回 0 条结果，则问题大概率出在客户端的选择器或提取逻辑上，而非代理服务本身。

特性

• 智能分诊：自动按失败模式对会话聚类，而非简单罗列
• 动态带宽离群值检测：按域名分组计算中位数，标记超过该域名中位数 2 倍的会话
• 验证码上报：展示验证码命中率与解决率
• 错误归因分析：综合解读所有会话信号，推断根本原因
• 零配置：从环境变量读取 API 密钥，无需手动配置 zone

失败会话诊断

切勿仅依赖 error.code 判断问题。请交叉比对所有可用的会话信号，全面分析失败原因：

• 持续时间 + 导航次数：若会话在 < 2 秒内失败且导航次数为 0，说明尚未进入连接阶段 —— 很可能是配置或认证问题；若会话运行数分钟后才失败，则更可能是运行时问题（如中途被屏蔽、空闲超时、网络中断）。
• 带宽相对于其他会话的表现：失败会话若消耗带宽与成功会话相近，说明很可能已抵达目标页面，但在数据提取阶段出错；若失败会话带宽接近零，则表明页面根本未加载。
• 验证码字段：若 captcha 值为 detected 但非 solved，说明会话因未解决的验证码挑战而中止 —— 建议在对应 zone 中启用验证码自动解决功能。
• target_url 与 end_url 的差异：若存在显著跳转（跨域、跳转至登录页或错误页），说明会话被重定向离开了原定目标。
• error.message：直接采用原始消息文本描述发生了什么 —— 不得主观猜测或添加原文未明确表达的含义。若原因仍不清晰，请引导用户联系 Bright Data 官方支持。