abfd4b902c
* feat(browser): add CDP remote connection support for server environments This feature enables OpenCLI to connect to a Chrome browser running on a different machine (e.g., your local computer) from a headless server environment via Chrome DevTools Protocol (CDP). Server environments (CI, cloud VMs, headless Linux) cannot run Chrome with a GUI or install the Playwright MCP Bridge extension. This makes it impossible to use OpenCLI commands that require browser authentication. Add support for the `OPENCLI_CDP_ENDPOINT` environment variable, which tells OpenCLI to connect to a remote Chrome instance via CDP instead of using the local extension mode. 1. Start Chrome with remote debugging on local machine: ``` chrome --remote-debugging-port=9222 --user-data-dir="$HOME/chrome-debug" ``` 2. Create SSH tunnel to forward port to server: ``` ssh -R 9222:localhost:9222 your-server ``` 3. Run OpenCLI on server: ``` export OPENCLI_CDP_ENDPOINT="http://localhost:9222" opencli bilibili hot --limit 5 ``` - src/browser.ts: Add CDP endpoint detection in buildMcpArgs() - src/doctor.ts: Show CDP mode status in doctor report - README.md: Add "Remote Chrome (Server/Headless)" section - README.zh-CN.md: Add corresponding Chinese documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: extract CDP connection guide into separate files * docs: clarify CDP vs SSH/Proxy distinction in CDP guides * docs: restructure CDP guides into 3 distinct phases (preparation, tunnel, execution) --------- Co-authored-by: ByteYue <yj976240184@gmail.com> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
104 lines
4.2 KiB
Markdown
104 lines
4.2 KiB
Markdown
# 通过 CDP 远程连接 OpenCLI (服务器/无头环境)
|
|
|
|
如果你无法使用 Playwright MCP Bridge 浏览器扩展（例如：在无界面的远程服务器上运行 OpenCLI 时），OpenCLI 提供了备选方案：通过连接 **CDP (Chrome DevTools Protocol，即 Chrome 开发者工具协议)** 来直接控制本地 Chrome。
|
|
|
|
出于安全考虑，CDP 默认仅绑定在 `localhost` 的本地端口。所以，若是想让**远程服务器**调用本地的 CDP 服务，我们需要依靠一层额外的网络隧道。
|
|
|
|
本指南将整个过程拆分为三个阶段：
|
|
1. **阶段一：准备工作**（在本地启动允许 CDP 调试的 Chrome）。
|
|
2. **阶段二：建立网络隧道**（通过 **SSH反向隧道** 或 **反向代理工具**，将本地的 CDP 端口暴露给服务器）。
|
|
3. **阶段三：执行命令**（在服务器端运行 OpenCLI）。
|
|
|
|
---
|
|
|
|
## 阶段一：准备工作 (本地电脑)
|
|
|
|
首先，你需要在你的本地电脑上，通过命令行参数启动一个开启了远程调试端口的 Chrome 实例。
|
|
|
|
**macOS:**
|
|
```bash
|
|
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
|
|
--remote-debugging-port=9222 \
|
|
--user-data-dir="$HOME/chrome-debug-profile" \
|
|
--remote-allow-origins="*"
|
|
```
|
|
|
|
**Linux:**
|
|
```bash
|
|
google-chrome \
|
|
--remote-debugging-port=9222 \
|
|
--user-data-dir="$HOME/chrome-debug-profile" \
|
|
--remote-allow-origins="*"
|
|
```
|
|
|
|
**Windows:**
|
|
```cmd
|
|
"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
|
|
--remote-debugging-port=9222 ^
|
|
--user-data-dir="%USERPROFILE%\chrome-debug-profile" ^
|
|
--remote-allow-origins="*"
|
|
```
|
|
|
|
> **注意**：此处增加的 `--remote-allow-origins="*"` 参数对于较新版本的 Chrome 来说通常是[必需的]，以允许来自反向代理（如 ngrok）的跨域 WebSocket 连接请求。
|
|
|
|
待这个新的浏览器实例打开后，**手工登录那些你打算使用的网站**（如 bilibili.com、zhihu.com 等），这可以让该浏览器的运行资料（Profile）保留上这些网站登录用的 Cookie。
|
|
|
|
---
|
|
|
|
## 阶段二：建立网络隧道
|
|
|
|
现在你的本地已经有了一个监听在 `9222` 端口的 CDP 服务，接下来，选择以下任意一种方式将其实际暴露给你的远端服务器。
|
|
|
|
### 方法 A：SSH 反向端口转发 (推荐)
|
|
|
|
如果你的本地电脑可以直连远程服务器的 SSH，那么这是最简单且最安全的做法。
|
|
|
|
在你的 **本地电脑** 终端上直接运行这条 ssh 命令，将远程服务器的 `9222` 端口反向映射回本地的 `9222` 端口：
|
|
|
|
```bash
|
|
ssh -R 9222:localhost:9222 your-server-user@your-server-ip
|
|
```
|
|
|
|
保持此 SSH 会话在后台运行即可。
|
|
|
|
### 方法 B：反向代理 / 内网穿透 (ngrok / frp / socat)
|
|
|
|
如果因为 NAT 或防火墙等因素导致无法直连 SSH 服务器，你可以使用 `ngrok` 等内网穿透工具。
|
|
|
|
在 **本地电脑** 运行 ngrok 将本地的 `9222` 端口暴露到公网：
|
|
|
|
```bash
|
|
ngrok http 9222
|
|
```
|
|
|
|
此时终端里会打印出一段专属的转发 URL 地址（如：`https://abcdef.ngrok.app`）。**复制这一段 URL 地址备用**。
|
|
|
|
---
|
|
|
|
## 阶段三：执行命令 (远程服务器)
|
|
|
|
现在，所有的准备工作已结束。请切换到你已安装好 OpenCLI 的 **远程服务器** 终端上。
|
|
|
|
根据你在上方阶段二所选择的隧道方案，在终端中配置对应的 `OPENCLI_CDP_ENDPOINT` 环境变量：
|
|
|
|
### 若使用 方法 A (SSH 反向隧道)：
|
|
|
|
```bash
|
|
export OPENCLI_CDP_ENDPOINT="http://localhost:9222"
|
|
opencli doctor # 查看并验证连接是否通畅
|
|
opencli bilibili hot --limit 5 # 执行目标命令
|
|
```
|
|
|
|
### 若使用 方法 B (Ngrok 等反向代理)：
|
|
|
|
```bash
|
|
# 将刚刚使用 ngrok 得到的地址填入这里
|
|
export OPENCLI_CDP_ENDPOINT="https://abcdef.ngrok.app"
|
|
opencli doctor # 查看并验证连接是否通畅
|
|
opencli bilibili hot --limit 5 # 执行目标命令
|
|
```
|
|
|
|
> *Tip: 如果你填写的是一个普通 HTTP/HTTPS 的 URL 地址，OpenCLI 会自动尝试抓取该地址下的 `/json/version` 节点，来动态解析并连接真正底层依赖的 WebSocket 地址。*
|
|
|
|
如果你想在此服务器上永久启用该配置，可以将对应的 `export` 语句追加进入你的 `~/.bashrc` 或 `~/.zshrc` 配置文件中。
|