debug-browser-session

调试 Kernel 浏览器会话

使用 Kernel CLI 诊断异常的 Kernel 云浏览器会话。CLI 可全面访问会话的 VM，包括状态、截图、Playwright 执行、日志文件和 VM 内命令执行；借助这些功能，你可以定位故障原因：机器人检测、Chrome 崩溃、网络/DNS 问题，或实时视图/WebRTC 问题。

输入

调查由两项内容驱动：

1. 会话 ID — 要调试的浏览器会话（例如 abc123example456xyz）。
2. 问题描述 — 出现了什么异常（例如“导航到特定网站时出现 ERR_HTTP2_PROTOCOL_ERROR”“浏览器无响应”“页面无法加载”“实时视图为空白”）。

如果缺少其中任何一项，请先询问，再继续操作。问题描述决定了下方各项检查的优先级。

前置条件

加载 kernel-cli 技能，了解 Kernel CLI 的安装与身份验证。其参考资料涵盖完整的命令集（browser-management、filesystem-ops、process-execution、computer-controls），需要使用下方未列出的选项时可查阅。

核心 CLI 命令

将 <SESSION_ID> 替换为你的会话 ID。

会话状态

kernel browsers get <SESSION_ID> -o json

# If the normal lookup returns not found, recover the soft-deleted record by session ID.
kernel browsers get <SESSION_ID> --include-deleted -o json

已删除的记录会提供静态配置和时间戳等信息，例如 created_at 和 deleted_at；VM、Playwright、截图、curl、日志和实时视图命令仍需会话处于活动状态。

截取当前状态

kernel browsers computer screenshot <SESSION_ID> --to screenshot.png

通过 Playwright 检查页面状态

kernel browsers playwright execute <SESSION_ID> "return { url: page.url(), title: await page.title() }"

查看浏览器服务日志

kernel browsers logs stream <SESSION_ID> --source supervisor --supervisor-process chromium --follow=false
kernel browsers logs stream <SESSION_ID> --source supervisor --supervisor-process neko --follow=false

如需查看其他 VM 日志，可直接列出并读取文件：

kernel browsers fs list-files <SESSION_ID> --path /var/log
kernel browsers fs read-file <SESSION_ID> --path /var/log/supervisord.log

比较 Chrome 与 VM 的网络路径

# Uses Chrome's TLS fingerprint, cookies, headers, and proxy configuration.
kernel browsers curl <SESSION_ID> https://example.com -I -w 'status=%{http_code} total=%{time_total}\n'

# Uses curl inside the VM instead of Chrome's network stack.
kernel browsers process exec <SESSION_ID> -- curl -I https://example.com
kernel browsers process exec <SESSION_ID> -- cat /etc/resolv.conf

通过 Playwright 检查 Cookie

kernel browsers playwright execute <SESSION_ID> "const cookies = await page.context().cookies(); return { count: cookies.length, domains: [...new Set(cookies.map(c => c.domain))] }"

浏览器遥测事件（删除后仍可查看）

只有在故障发生前启用了遥测，遥测才有帮助 — 默认情况下，事件采集处于关闭状态。启用采集后，即使遥测已停用或会话已删除，仍可读取已采集的事件。软删除会话的静态记录也可通过 kernel browsers get <SESSION_ID> --include-deleted 获取；运行时检查仍需要活动会话。

对调试至关重要的类别包括 console（控制台输出和未捕获异常）、network（请求/响应元数据）和 page（导航与生命周期）。高信号事件类型包括：console_error、network_loading_failed、非 2xx 状态的 network_response、system_oom_kill 和 monitor_disconnected（遥测中断 — 后续事件应视为不完整）。完整的类别和事件类型目录请参阅遥测类别文档。

读取事件

kernel browsers telemetry events <SESSION_ID> --since 24h --all
kernel browsers telemetry events <SESSION_ID> --since 24h --categories console,network --all
kernel browsers telemetry events <SESSION_ID> --since 24h --types console_error,network_loading_failed

--since 接受 RFC-3339 时间戳或 5m 这样的时长，默认值为最近 5 分钟。不确定时，请使用较宽的时间范围，例如 --since 24h（如示例所示）；对于已删除的会话，可使用 browsers get --include-deleted 找回其 created_at，并据此精确限定时间范围。--all 会遍历时间范围内的每一页（默认仅显示一页 20 条事件，--limit 最多为 100，可使用 --offset 游标手动翻页）；使用 --types 筛选时会自动遍历整个时间范围。使用 -o json 获取完整事件负载 — 默认表格仅显示序列、时间、类别和类型，因此任何依赖事件内容的信息（例如 network_response 状态码、控制台错误消息或 URL）都需要使用 JSON 输出。相同事件也可通过 API/SDK 获取（GET /browsers/{session_id}/telemetry/events，其 since 默认值同样为 5 分钟）；如果你的 Kernel MCP 服务版本包含此功能，也可通过 manage_browsers 工具的 get_telemetry 操作获取（默认覆盖整个会话时间范围）。对于活动会话，可运行 kernel browsers telemetry stream <SESSION_ID> 实时获取事件。

启用捕获

kernel browsers create --telemetry=console,network,page
kernel browsers update <SESSION_ID> --telemetry=console,network,page

启用后，捕获会立即开始，无法追溯补录。对于预期需要调试的自动化任务，请在创建时启用遥测（包括 console、network、page），确保出错时已有证据；对于正在运行的会话，请启用这些类别，重现问题，然后读取事件。

注意事项：

• 遥测默认不启用。 没有事件可能只是因为从未启用遥测，并不代表什么都没发生。
• 默认数据包不包含调试所必需的类别（console、network、page）。 --telemetry=all 只会捕获控制、连接、系统和验证码事件；需要这些信号时，请像上文所示，明确请求 console、network 和 page。
• monitor_disconnected 表示遥测出现缺口。 采集器已断开；在出现下一个 monitor_reconnected 之前，或在没有该事件时直到事件历史记录结束为止，请将控制台、网络、页面和交互事件的覆盖视为不完整。

常见问题与解决方案

网络错误（ERR_HTTP2_PROTOCOL_ERROR、ERR_CONNECTION_RESET 等）

机器人检测是常见原因。许多网站使用 Cloudflare、Imperva 或 Akamai 等 CDN 来识别浏览器并阻止自动化。

机器人检测的迹象：

• VM 中的 curl 可用，但页面或 kernel browsers curl 失败
• 出现“拒绝访问”、验证码页面或“正在检查您的浏览器……”等消息
• 浏览器配置中的 stealth: false

使用 kernel browsers get <SESSION_ID> -o json 检查 stealth 和显式设置的 proxy_id。如果预期隐身会话使用 Kernel 的默认代理，请先捕获屏幕截图、遥测数据和日志，然后仅隔离该路由：

# This mutates live routing.
kernel browsers update <SESSION_ID> --disable-default-proxy
# Reproduce the failing request once and capture the result.
kernel browsers update <SESSION_ID> --disable-default-proxy=false

仅当会话所有者确认当前应启用默认代理时，才运行此 A/B 测试，因为 browsers get 不会显示先前的 disable_default_proxy 状态。不要用 --clear-proxy 代替；它会移除显式代理。无论结果如何，都要恢复默认代理；如果直连修复了故障，请排查代理路径。

隐身模式在创建时设置，无法在运行中的会话上切换。如果创建隐身替代会话来重现问题，请保留原会话，并在完成后仅删除用于诊断的替代会话：

kernel browsers delete <DIAGNOSTIC_SESSION_ID>

浏览器无响应

原因：Chrome 进程崩溃或挂起。
检查：查看 supervisor 日志中是否有 chromium 重启事件。
解决方案：确认是否已达到超时时间，检查日志中的内存问题，并创建新会话。

页面无法加载

原因：网络、DNS 或代理问题。
检查：比较 kernel browsers curl 与 VM 中的 curl，检查 /etc/resolv.conf，然后检查已配置的代理。仅 Chrome 失败通常指向 Chrome 状态、TLS 指纹、Cookie 或其代理路由；两种路径都失败则表明问题更可能出在 VM 或网络栈的更底层。

实时视图无法使用

原因：Neko/WebRTC 问题。
检查：使用 kernel browsers view <SESSION_ID> 获取实时视图 URL 并打开；使用 browsers logs stream 查看 Neko 日志；在 browsers get 中确认 headless 为 false。
解决方案：检查是否有防火墙阻止 WebRTC，并确认 Playwright 和屏幕截图是否仍可用。如果可用，则浏览器运行正常，故障仅限于实时视图。

预期日志条目（正常运行）

以下日志均属正常，不代表存在问题：

• Failed to call method: org.freedesktop.DBus.Properties.GetAll — DBus 权限问题（在容器中属于预期情况）
• vkCreateInstance: Found no drivers — VM 中没有 GPU（属于预期情况）
• GCM 的 DEPRECATED_ENDPOINT — Google 弃用提示（无害）
• SharedImageManager::ProduceMemory 错误 — 与 GPU 相关（不严重）

调试检查清单

• 已找到活动会话，或使用 --include-deleted 恢复已删除的元数据
• 截图显示了预期内容（或揭示了错误）
• 当前 URL 符合预期
• 监督器日志显示所有服务都在运行
• 已比较 Chrome-stack 和 VM 的 curl 结果
• chromium 日志中没有严重错误
• Cookie／会话状态正确
• 已检查遥测事件中的 console_error / network_loading_failed / system 事件（尤其是在会话已消失时）
• 已还原任何临时默认代理更改；已删除任何诊断替代项

建议顺序

1. 获取浏览器信息；如果浏览器已消失，则使用 --include-deleted 重试。
2. 保存证据：截图、URL／标题、遥测数据，然后查看日志。
3. 对比 Chrome-stack curl 与 VM curl，排查连接故障。
4. 重现一次；仅在相关时才进行临时默认代理 A/B 测试。
5. 还原更改过的路由，并删除任何诊断替代会话。

如果会话已删除，请使用 browsers get --include-deleted 恢复其静态元数据；遥测数据是剩余的运行时信号，而且只有在会话运行期间启用了捕获时才可用。