当您需要在本地使用 ADB 调试云手机实例时，云手机平台提供了一种基于 SSH 隧道的安全接入方式。您在本地执行 ADB 连接后，请求会通过一条加密隧道转发到目标云手机实例的 ADB 服务，不需要为实例开放公网 ADB 端口。调试凭证由 OpenAPI 一次性签发，具备明确的有效期，用完即失效，适用于应用安装、日志抓取、shell 调试和自动化测试等日常场景。本文介绍如何调用 [GetEdgeTunnelConnectionInfo](https://docs.volcengine.com/docs/6394/2612190) 接口获取隧道信息，并在本地建立 SSH 隧道后使用 ADB 连接云手机实例。 ## 使用场景 * 需要通过 ADB 对云手机实例做应用安装、日志抓取、shell 调试、自动化测试等操作。 * 本地或办公网络访问 ADB 公网端口不便，或希望使用统一的鉴权凭证进行访问控制。 * 希望通过一次性签发的连接凭证来限制调试通道的作用范围与有效期。 ## 前提条件请提前在本地机器上准备以下工具。 1. **OpenSSH 客户端**：用于执行 `ssh -L` 建立本地端口转发操作。 * 执行如下命令，返回 OpenSSH 客户端的版本号，即表示客户端已安装并且可以正常使用。 ```Plain Text ssh -V ``` 2. **ADB 客户端**：是 Android 官方提供的调试命令行工具，用于连接本地转发端口，[下载地址](https://developer.android.com/tools/releases/platform-tools?hl=zh-cn)。 * 执行如下命令，返回本地 ADB 的版本信息，即表示工具已安装并且可以正常使用。 ```Plain Text adb version ``` 3. 选择并安装如下工具：两种工具都是作为 OpenSSH 的 `ProxyCommand`，把 SSH 字节流通过 WebSocket 转发到隧道服务，任选其一安装即可。 * **ws\-tunnel 命令工具（推荐）** ：火山引擎云手机官方提供的 OpenSSH `ProxyCommand` 辅助工具，专为本方案的隧道服务适配，开箱即用。 * 如何安装：下载压缩包并解压至本地进行安装。 ws-tunnel-dist.tar.gz * 执行如下命令，返回 `ws-tunnel v2.51.0-7-g167ae0f-20260731` 版本信息，即表示工具已安装并且可以正常使用。 ```Plain Text ws-tunnel --version ``` * 支持使用以下文件验证工具完整性。 SHA256SUMS * **websocat 开源工具**：开源的通用 WebSocket 字节流转发工具，可作为 ws\-tunnel 的替代方案，[下载地址](https://github.com/vi/websocat)。 ## 步骤一、调用 OpenAPI 获取隧道（Tunnel）连接信息调用 [GetEdgeTunnelConnectionInfo](https://docs.volcengine.com/docs/6394/2612190) 接口，为目标实例签发一次性调试凭证。凭证是一段包含鉴权信息，有明确有效期的连接地址，一次调试对应一份凭证，过期或调试结束后即失效。接口会直接返回可复制执行的 SSH 建连命令与 ADB 连接命令模板，避免手工拼接隧道地址时遗漏 URL 中的鉴权参数（即 `?` 之后由 `&` 连接的 Query 参数，例如签名、会话 ID、有效期等），或在命令行中因特殊字符（如 `&`）未做转义而导致连接失败。 ## 步骤二、建立 SSH 隧道推荐直接从响应的 `ConnectionInfo.Note` 字段复制生成的 SSH 命令执行，示例代码如下。 ```Bash ssh \ -o "ProxyCommand=ws-tunnel --url ''" \ -o HostKeyAlias= \ -o ControlMaster=yes \ -o ControlPath=/tmp/edge-tunnel-.sock \ -o ExitOnForwardFailure=yes \ -o ServerAliveInterval=30 \ -o ServerAliveCountMax=6 \ -L 5555::5555 \ -Nf \ adb@ ``` ### SSH 参数说明 |参数 |说明 | |---|---| |ProxyCommand=ws\-tunnel \-\-url '' |设置 SSH 不使用默认的直连方式，而是先通过 ws\-tunnel 工具将连接送入火山引擎的隧道服务，再抵达目标云手机实例。默认使用 `ws-tunnel --url ''`。若使用 websocat 替代，则替换为 `websocat - --binary ''`。

如需手动拼接 URL，请将其中的 `%` 字符进行转义，即将 `%` 替换为 `%%`，避免因字符解析问题导致连接失败。 | |HostKeyAlias= |为本条隧道连接设置一个“名称”用于身份校验。SSH 首次连接时会把对方的“名称”记录至本地 `~/.ssh/known_hosts`，下次再连同一别名时用它验证对方是否被替换。请直接使用接口返回的 `HostKeyAlias`，避免与本地已有 SSH 主机记录产生冲突。 | |ControlMaster / ControlPath |开启 SSH 的“连接复用”，后续对同一隧道的操作复用第一次的连接，避免重复握手。`ControlPath` 是这条连接在本地留下的“控制文件”路径，建议用接口返回的 `ConnectionId` 拼接以区分不同调试会话；关闭时使用 `ssh -O exit` 退出，不用强杀进程。 | |ExitOnForwardFailure=yes |若本地端口转发失败，SSH 立即退出，而不是继续保持一个“空隧道”误以为连接成功。当出现端口占用、参数错误等问题时，帮助排查及时发现问题。 | |ServerAliveInterval / ServerAliveCountMax |让 SSH 定期发出“心跳包”以确认连接存活。建议保留默认值，避免长时间无 ADB 交互时隧道被中间网络设备当作“闲置连接”提前断开。 | |\-L 5555::5555 |把本地 5555 端口“接管”下来，之后 ADB 访问 `127.0.0.1:5555` 的流量都会被转发到目标云手机实例的 ADB 端口。若本地 5555 已被占用，可换成 `-L 15555::5555`，相应地 adb connect 也要改成对应端口。 | |\-Nf |让 SSH 只负责“打通隧道”，从而不打开远程 shell，并放到后台运行。排查问题时可以替换为 \-N 或 \-vvv 打印详细日志定位具体步骤。 | ### 确认隧道已建立执行以下命令确认本地端口已经在监听。 ```Bash lsof -iTCP:5555 -sTCP:LISTEN ``` 若返回中出现由 SSH 进程持有的 5555 端口 `LISTEN` 记录，即代表本地端口已经在监听，隧道建立成功。 ```Plain Text COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME ssh 12345 user 5u IPv6 0x123456789 0t0 TCP localhost:5555 (LISTEN) ssh 12345 user 6u IPv4 0x987654321 0t0 TCP localhost:5555 (LISTEN) ``` ## 步骤三、使用 ADB 连接云手机实例 1. SSH 隧道建立成功后，在本地执行以下命令即可通过 ADB 连接目标实例。 ```Bash adb connect 127.0.0.1:5555 ``` 2. 执行如下命令，查看设备列表。 ```Bash adb devices ``` 当返回结果中设备状态为 device 时，表示连接成功，如下所示。 ```Bash List of devices attached 127.0.0.1:5555 device ``` 此时可使用 ADB 命令连接云手机，[了解更多](https://docs.volcengine.com/docs/6394/1126585)。 ```Bash # 指定要操作的目标设备 adb -s 127.0.0.1:5555 shell # 把当前目录下的 app.apk 安装包安装到指定的云手机实例上 adb -s 127.0.0.1:5555 install app.apk # 实时打印该云手机实例的系统日志 adb -s 127.0.0.1:5555 logcat ``` ## 步骤四、结束调试并清理连接调试完成后，请主动断开 ADB 连接并关闭 SSH 隧道，避免残留监听进程和端口占用。 1. 执行如下命令，断开 ADB 连接。 ```Bash adb disconnect 127.0.0.1:5555 ``` 2. 若使用了 [步骤二](https://docs.volcengine.com/docs/6394/2609473#uWRaf1Lo) 中的 `ControlPath`，可以执行如下命令关闭 SSH 隧道。

说明

-S 后的路径需与步骤二中 ControlPath 的路径保持一致。

adb@ 需与步骤二中 SSH 命令末尾的目标一致。

```Bash ssh -O exit \ -S /tmp/edge-tunnel-sess_0380BB16CB10CF6B2DF0319EEA20078E.sock \ adb@7644710100737809196.1806209850762334208 ```