远程投屏隧道：scrcpy 连接远程 Android 设备的 ADB 隧道实战（基于 doc/tunnels.md）

远程投屏隧道：scrcpy 连接远程 Android 设备的 ADB 隧道实战（基于 doc/tunnels.md）

【免费下载链接】scrcpyDisplay and control your Android device项目地址: https://gitcode.com/GitHub_Trending/sc/scrcpy

Scrcpy 默认面向 USB 直连的本地 Android 设备，而 doc/tunnels.md 解决了另一个高频场景：当 Android 设备连接在远程计算机上时，如何从本机投屏并控制它。本文基于该文档，完整覆盖「远程 ADB server」与「SSH 隧道」两种方案的操作步骤，并结合 app/src/adb/adb_tunnel.c、app/src/server.c 的源码实现，讲清--tunnel-host、--tunnel-port、--force-adb-forward三个参数的底层作用机制，读完后你可以独立完成跨网络的 scrcpy 部署，并理解隧道建立失败时的回退逻辑。

方案总览：为什么隧道能通向远程设备

scrcpy 的通信链路是「客户端进程 → adb → 设备内嵌的 scrcpy server」。当设备挂在远程机器上时，本机 scrcpy 无法直接找到 adb，文档给出的思路是复用 adb 本身的客户端/服务端分离能力：

1. 在远程机器上运行一个监听所有网卡的adb server（adb -a nodaemon server start）；
2. 本机 scrcpy 通过环境变量ADB_SERVER_SOCKET把adb 客户端指向远程的 adb server（adb 协议要求两端版本兼容）；
3. scrcpy 再借助adb forward/adb reverse在设备与本机（或远程机）之间建立视频/音频/控制数据通道。

因此涉及两个独立的「通道」：adb 控制通道（本机 → 远程 5037 端口）和媒体数据隧道（经 adb 转发到设备）。下面按文档的两条路线分别展开。

方案一：远程 ADB server（明文直连）

1. 在远程机器上启动 adb server

adb kill-server adb -a nodaemon server start # keep this open

-a让 server 监听所有网卡（而非仅 localhost），nodaemon使其以前台进程方式运行以便观察日志。文档在此明确警告：客户端与 adb server 之间的所有通信均不加密，因此该方案仅适用于可信内网，跨公网应使用下面的 SSH 隧道。

2. 本机指定远程 adb server

以远程 server 位于192.168.1.2为例，在另一个终端设置ADB_SERVER_SOCKET后运行 scrcpy（三种 shell 写法）：

# in bash export ADB_SERVER_SOCKET=tcp:192.168.1.2:5037 scrcpy --tunnel-host=192.168.1.2

:: in cmd set ADB_SERVER_SOCKET=tcp:192.168.1.2:5037 scrcpy --tunnel-host=192.168.1.2

# in PowerShell $env:ADB_SERVER_SOCKET = 'tcp:192.168.1.2:5037' scrcpy --tunnel-host=192.168.1.2

3. 强制指定隧道端口（可选）

默认情况下 scrcpy 使用建立adb forward隧道时分配到的本地端口（通常是27183，见--port）。当链路中涉及更多重定向（例如中间再套一层 SSH 转发）时，可以强制一个固定端口：

scrcpy --tunnel-port=1234

4. 源码印证：--tunnel-host/--tunnel-port为什么自动开启--force-adb-forward

参数在 app/src/cli.c 中的注册帮助文本就写明：这两个选项会自动启用--force-adb-forward（默认值分别为localhost和0，即「不强制」）。实际的自动开启逻辑在 app/src/cli.c#L3068-L3072：

if ((opts->tunnel_host || opts->tunnel_port) && !opts->force_adb_forward) { LOGI("Tunnel host/port is set, " "--force-adb-forward automatically enabled."); opts->force_adb_forward = true; }

背后的原因在 app/src/adb/adb_tunnel.c 中一目了然。scrcpy 优先尝试adb reverse（设备侧作为发起方回连本机监听端口）：

• enable_tunnel_reverse_any_port()先在--port指定的端口区间（默认27183:27199，由 app/meson.build#L167-L168 配置）内逐端口尝试：调用sc_adb_reverse建立反向映射，同时在本地listen对应端口；源码注释解释了方向选择的巧妙之处——「应用层上设备是服务端，但网络层上客户端监听、服务端连接」，这样客户端可以先监听好再启动 server 应用，无需轮询等待；
• 若端口被占用则移除该映射、端口 +1 重试，超出区间才报错。

而adb reverse在远程场景下行不通：它意味着设备主动回连「配置它的那台计算机」，也就是远程机器，而非跑 scrcpy 的本机。所以在 sc_adb_tunnel_open() 中，当force_adb_forward为真时直接走enable_tunnel_forward_any_port()，即用adb forward让本机主动发起连接。这也是文档中--tunnel-host=192.168.1.2的语义——数据隧道的对端不是 localhost，而是远程机器的 IP。

连接阶段的细节可参考 app/src/server.c#L629-L645：forward 模式下，tunnel_host为 0 时回落到IPV4_LOCALHOST，tunnel_port为 0 时使用tunnel->local_port（即adb forward实际占用的端口）；随后最多 100 次、每次间隔 100ms 的重连循环中，connect_and_read_byte()还会额外读取 1 字节来确认隧道后端的 server 真正在监听——因为「连接成功」与「对端已就绪」是两回事。

方案二：SSH 隧道（加密，推荐跨公网使用）

与远程 adb server 直接通信是不加密的，文档给出的安全做法是：远程机器只跑普通adb start-server，用 SSH 的端口转发同时打通「控制通道」和「媒体隧道」两条路。

1. 准备与建链

# 远程机器上确认 adb server 在运行 adb start-server

# local 5038 --> remote 5037 # local 27183 <-- remote 27183 ssh -CN -L5038:localhost:5037 -R27183:localhost:27183 your_remote_computer # keep this open

两条转发的含义：

• -L5038:localhost:5037：本机 5038 端口 → 远程机器的 5037（adb server），供 adb 客户端通信；
• -R27183:localhost:27183：反向转发——远程机器的 27183 回连到本机的 27183。这正是为adb reverse准备的：设备回连的目标端口落在远程机器上，经由 SSH 转回本机 scrcpy 的监听端口。-C开启压缩、-N不执行远程命令（纯转发）。

2. 本机运行 scrcpy

# in bash export ADB_SERVER_SOCKET=tcp:localhost:5038 scrcpy

:: in cmd set ADB_SERVER_SOCKET=tcp:localhost:5038 scrcpy

# in PowerShell $env:ADB_SERVER_SOCKET = 'tcp:localhost:5038' scrcpy

注意这里不需要--tunnel-host/--force-adb-forward：媒体隧道的入口就在本机（通过-R反向转发可达），adb reverse是首选路径。

3. 变体：只用本地转发，强制adb forward

若不希望开启 SSH 的远程端口转发（-R可能被安全策略限制），文档提供了纯-L的替代方案：

# local 5038 --> remote 5037 # local 27183 --> remote 27183 ssh -CN -L5038:localhost:5037 -L27183:localhost:27183 your_remote_computer # keep this open

此时远程机器的 27183 可经由 SSH 到达，scrcpy 则改用adb forward，让连接从本机主动出发穿过隧道，到达远程机器上的 27183 再进入设备。因此命令需要显式加上--force-adb-forward（否则 scrcpy 会先尝试adb reverse并白白消耗重试时间）：

# in bash export ADB_SERVER_SOCKET=tcp:localhost:5038 scrcpy --force-adb-forward

:: in cmd set ADB_SERVER_SOCKET=tcp:localhost:5038 scrcpy --force-adb-forward

# in PowerShell $env:ADB_SERVER_SOCKET = 'tcp:localhost:5038' scrcpy --force-adb-forward

--force-adb-forward的官方释义见 app/src/cli.c#L430-L434：「不尝试使用adb reverse连接设备」。从源码看，adb reverse失败时本来就会回退到adb forward（adb_tunnel.c#L137-L141 中的"'adb reverse' failed, fallback to 'adb forward'"警告日志），所以显式强制只是跳过注定失败的第一阶段——这一点在旧版 Android 或adb connect（TCP/IP 接入）的设备上尤其典型，adb_tunnel.h 的注释也说明了这一回退的适用场景。

关键参数速查

排障要点

• 「连接成功但 scrcpy 卡住/重连」：connect_and_read_byte() 的存在说明连接建立不等于 server 就绪；远程 server 启动慢、或adb版本在两端不一致时，优先检查ADB_SERVER_SOCKET指向与 adb 版本兼容性（文档强调两端必须使用相同版本的 adb 协议）。
• adb reverse失败回退日志：终端若出现'adb reverse' failed, fallback to 'adb forward'，属于预期的回退行为；在远程拓扑下可提前用--force-adb-forward避免。
• 端口冲突：隧道端口在 27183 起的区间内逐个尝试，日志会打印Could not listen on port N, retrying on N+1；固定端口场景（--tunnel-port）需自行确认端口未被占用。
• 明文警告：方案一中「客户端 ↔ adb server」全程无加密，公网环境请改用 SSH 隧道方案。

小结

• 远程投屏的本质是把adb 客户端/服务端解耦：ADB_SERVER_SOCKET负责把控制面指向远程 adb server，adb forward/adb reverse负责把媒体面穿过网络；
• 可信内网用「远程 adb server +--tunnel-host」最省事，跨公网用 SSH 的-L/-R组合更安全；
• 是否出现--force-adb-forward取决于媒体隧道的发起方向：adb reverse（设备回连，需要-R反向转发）优先，adb forward（本机主动连接，-L即可）作为强制选项或自动回退。

【免费下载链接】scrcpyDisplay and control your Android device项目地址: https://gitcode.com/GitHub_Trending/sc/scrcpy