dsh-sidebar-cdp-browser

使用场景

• 远程 / 无头 Chromium 可视化:浏览器跑在服务器或容器里,你在 DSH 界面里直接看、直接点;
• 在 DSH 会话中观察浏览器自动化:让 agent 操作浏览器的同时,人可以实时盯着画面,随时接管;
• 轻量 VNC 替代:只针对浏览器这一种「远程桌面」,不需要装任何客户端;
• 受控演示 / 排查:把一个测试浏览器投影给同事看,导航、点击都在你的权限模型之内。

使用方法

配置 CDP 地址

CDP 地址在 DSH Web 设置页配置,不需要改 profile 数组:

1. 打开 设置 → 侧边卡片 → 侧边栏内容 → CDP实时视图,点击卡片右下角的齿轮;
2. 在「CDP 地址」输入框填写地址,失焦或按 Enter 保存;
3. 留空 = 默认地址 127.0.0.1:9222;
4. 支持的格式:
   • host:port(自动补 http://)或 http://host:port:Host 从 /json/version 发现 webSocketDebuggerUrl;
   • https:// / wss://:同上,TLS 由部署层保证;
   • ws://.../devtools/browser/...:直接连接 browser WebSocket;
5. 保存后 Host 断开旧连接,已打开的实时视图自动重连到新地址。

地址持久化在 better-sidebar 的 prefs 文档(pluginSettings['dsh-sidebar-cdp-browser:live'].endpoint),Host 通过 DSH settings 服务读取并订阅变更。没有 loopback 限制——远程地址直接可用,请自行确保网络可达与访问控制。

同一设置面板里还有「允许交互」开关:

• 关闭(默认):observe 模式,只能看;
• 打开:interactive 模式,可以点击、输入、导航、新建/关闭标签页。

日常操作

• 标签页(target)切换 / 新建 / 关闭:顶部标签条,需要 interactive 模式;
• 鼠标:点击、拖动、滚轮,坐标按帧画面映射回页面;
• 键盘:先点击画面获得焦点,之后直接输入。中文等 IME 走 composition 合成后一次性提交;粘贴经本机剪贴板转成文本插入;复制(Ctrl+C)暂不支持;
• 导航:工具栏输入 HTTP(S) 地址回车,或使用 back / forward / reload;
• 连接:工具栏可手动重连;断线后客户端自动退避重连。

Loader 运行时调优(可选)

profile 配置里的可选项(均可省略,括号内为默认值与范围):

- insert:
    - id: sidebar-cdp-browser
      name: dsh-sidebar-cdp-browser
      config:
        frameQuality: 60        # JPEG 质量 (20–90)
        frameMaxWidth: 1280     # 帧最大宽 (320–3840)
        frameMaxHeight: 900     # 帧最大高 (240–2160)

字段	默认值	范围
ticketTtlMs	30000	5000–120000,一次性 ticket 有效期
connectTimeoutMs	15000	1000–120000,CDP 连接超时
frameQuality	60	20–90,JPEG 质量
frameMaxWidth	1280	320–3840
frameMaxHeight	900	240–2160
frameEveryNth	1	1–30,每 N 帧取 1 帧
bufferedAmountSoftLimit	524288	64KB–16MB,超过开始丢帧
bufferedAmountHardLimit	4194304	256KB–64MB,超过断开连接

故障排查

被拒绝的 WebSocket 升级返回明确的 HTTP 状态,浏览器控制台显示 Unexpected response code: :

• 401:ticket 无效或已过期(先调 /open 拿新 ticket);
• 403:trust fence 拒绝(Host 头不在信任列表,或带 cross-site 标记);
• 404:路径错误;
• 1006(无状态码):请求在反向代理层就被掐断了。反代必须转发 WebSocket 升级头:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}
location / {
    proxy_pass http://127.0.0.1:3080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
}

CDP 连接失败会在 DSH Host 日志里输出 [dsh-sidebar-cdp-browser] CDP session attach failed: ...,浏览器端只看到断连,排障先看 Host 日志。

配置 CDP 地址

CDP 地址在 DSH Web 设置页配置,不需要改 profile 数组:

1. 打开 设置 → 侧边卡片 → 侧边栏内容 → CDP实时视图,点击卡片右下角的齿轮;
2. 在「CDP 地址」输入框填写地址,失焦或按 Enter 保存;
3. 留空 = 默认地址 127.0.0.1:9222;
4. 支持的格式:
   • host:port(自动补 http://)或 http://host:port:Host 从 /json/version 发现 webSocketDebuggerUrl;
   • https:// / wss://:同上,TLS 由部署层保证;
   • ws://.../devtools/browser/...:直接连接 browser WebSocket;
5. 保存后 Host 断开旧连接,已打开的实时视图自动重连到新地址。

地址持久化在 better-sidebar 的 prefs 文档(pluginSettings['dsh-sidebar-cdp-browser:live'].endpoint),Host 通过 DSH settings 服务读取并订阅变更。没有 loopback 限制——远程地址直接可用,请自行确保网络可达与访问控制。

同一设置面板里还有「允许交互」开关:

• 关闭(默认):observe 模式,只能看;
• 打开:interactive 模式,可以点击、输入、导航、新建/关闭标签页。