dumbpipe命令清单:从listen、connect到Unix Socket,6个子命令一次讲透

原创2026-10-29 11:59:281,987 阅读

dumbpipe命令清单:从listen、connect到Unix Socket,6个子命令一次讲透

dumbpipe 是一个跨机器传输数据的 P2P 网络管道工具,可以理解为「自带 NAT 穿透 + TLS 加密的 netcat」。两台机器无论藏在哪层防火墙后,只需一个 ticket 就能连成一根加密管道。本文带你一次讲透 dumbpipe 的 6 个子命令:listen、connect、listen-tcp、connect-tcp、listen-unix、connect-unix,外加一个辅助命令 generate-ticket。

1️⃣ 先认识 dumbpipe:会打洞的"网络管道"

与 netcat 需要用 IP 地址直连不同,dumbpipe 用 256 位 endpoint id 标识机器,位置无关、天然支持跨 NAT,连不上时自动回退到 relay 中转(基于 QUIC 连接)。

快速安装:

# 方式一:Cargo
cargo install dumbpipe

# 方式二:Homebrew
brew install dumbpipe

也可以从源码构建:

git clone https://gitcode.com/gh_mirrors/du/dumbpipe
cd dumbpipe && cargo build --release

2️⃣ 6 个子命令速查表 📋

子命令 本端角色 一句话作用 典型场景
listen 监听端 把 stdin/stdout 接到管道上 终端数据互传、视频流
connect 连接端 凭 ticket 接入,接管 stdin/stdout 同上,主动方
listen-tcp 监听端 把远端流量导入本机 --host 指定的 TCP 服务 转发开发 web 服务器
connect-tcp 连接端 本机起一个 TCP 端口(--addr),流量导去远端 跨机器访问远端服务
listen-unix 监听端 把远端流量导入本机 --socket-path Unix socket 远程接管 Zellij 会话
connect-unix 连接端 本机创建一个 Unix socket,流量导去远端 同上,主动方

💡 记忆口诀:listen-* 是"接收连接、导入本地后端";connect-* 是"建立连接、对外暴露入口"。子命令定义见 src/main.rs#L52-L108。

3️⃣ 基础对:listen 与 connect(标准输入/输出)

listen:监听端,输出连接用的 ticket

dumbpipe listen

运行后输出形如(ticket 打印在 stderr,不污染数据流):

Listening. To connect, use:
dumbpipe connect <ticket>

实现见 src/main.rs#L364-L427。两个新手必须知道的细节:

  • 它只接受第一个成功连接,转发完 stdin/stdout 就退出;
  • 加 --recv-only 可只接收不发送(单向流,比如视频)。

connect:连接端,凭 ticket 接入

dumbpipe connect <ticket>

连接方打开双向流,并先发送一个 hello 握手(定义在 src/lib.rs#L7-L11),随后双向转发 stdin/stdout,直到任一侧 EOF。双向互传效果可参考 tests/cli.rs#L55-L87 的测试用例。

实战:跨机器看摄像头视频流(来自 README.md)

发送端(MacOS,Linux 把采集参数换成 v4l2):

ffmpeg -f avfoundation -r 30 -i "0" -pix_fmt yuv420p -f mpegts - | dumbpipe listen

接收端:

dumbpipe connect <ticket> | ffplay -f mpegts -fflags nobuffer -framedrop -

4️⃣ 端口转发对:listen-tcp 与 connect-tcp

适合"把远端的某个 TCP 服务搬到自己手上",比如分享开发 web 服务器(npm run dev 跑在 3000 端口)。

listen-tcp:远端流量 → 本机 TCP 服务

在跑着服务的机器上执行,--host 指向本地服务:

dumbpipe listen-tcp --host localhost:3000

输出 ticket 后常驻运行,每来一条远端连接,就在本机新开一条到 3000 端口的 TCP 连接转发(src/main.rs#L549-L643)。

connect-tcp:本机 TCP 端口 → 远端

在想访问的机器上执行,--addr 是本机对外端口:

dumbpipe connect-tcp --addr 0.0.0.0:3001 <ticket>

之后直接浏览器打开 http://<你的机器>:3001 即可看到远端网站(src/main.rs#L466-L546)。

5️⃣ Unix Socket 对:listen-unix 与 connect-unix 🐧

(仅 Unix 系统可用)能把远端进程的 Unix socket 拉到本机,杀手级应用是远程接管 Zellij 终端复用器会话:

远端主机(Zellij 正在运行,socket 路径形如 /tmp/zellij-0/0.42.2/remote-task-1234):

dumbpipe listen-unix --socket-path /tmp/zellij-0/0.42.2/remote-task-1234

本机创建对应目录结构并建立转发(实现见 src/main.rs#L780-L879):

mkdir -p /tmp/zj-remote/0.42.1
dumbpipe connect-unix --socket-path /tmp/zj-remote/0.42.1/remote-task-1234 <ticket>

新终端里挂载会话:

ZELLIJ_SOCKET_DIR=/tmp/zj-remote zellij attach remote-task-1234

贴心细节:connect-unix 启动前会自动清理残留的 socket 文件(src/main.rs#L793-L798),退出时也通过 RAII 守卫自动删除(src/main.rs#L762-L776),不用手动收拾。

6️⃣ 辅助命令:generate-ticket

dumbpipe generate-ticket

基于当前密钥直接生成一个短 ticket 打印到 stdout(src/main.rs#L881-L888)。它配合 IROH_SECRET 环境变量使用:先设好固定密钥,提前算出 ticket 分发给对方,之后随时 listen,对方拿旧 ticket 也能连上。

7️⃣ 通用参数速查(所有子命令共享)

参数 作用 备注
--ipv4-addr / --ipv6-addr 指定端点固定监听地址(含端口) 需要配防火墙规则时用,不指定则随机端口
--custom-alpn 自定义 ALPN,接入现有 iroh 协议服务 专家功能;utf8: 前缀表示 UTF-8 字符串,否则按 hex 解析
-v / --verbose 提升日志级别,并额外打印短 ticket 可重复叠加
--recv-only 立即关闭发送端,只接收 仅 listen/connect 可用
IROH_SECRET 环境变量 固定密钥 不设置则随机生成并打印到 stderr

参数定义集中在 src/main.rs#L111-L143。例如给防火墙放行固定端口:

dumbpipe listen --ipv4-addr 0.0.0.0:4242

8️⃣ 新手常见问题 FAQ

Q1:listen 跑完一次连接就退出了,是 bug 吗? 不是。listen 设计上只服务第一个连接(src/main.rs#L422-L423);需要常驻多连接请用 listen-tcp 或 listen-unix。

Q2:出现 Warning: Failed to connect to the home relay 怎么办? 说明 5 秒内没连上默认 relay(src/main.rs#L368-L370),直连打洞仍会尝试,连接大概率可用;若频繁出现请检查本机网络。

Q3:ticket 是什么?会过期吗? ticket 编码了对端 256 位 endpoint id 与 relay 信息,只要对端进程/密钥不变就一直有效,与 IP 无关。

Q4:数据经过 relay 安全吗? 连接全程 TLS 加密,relay 只转发密文,两端直连优先。

9️⃣ 小结

dumbpipe 的 6 个子命令就两对半的组合:listen/connect 管标准输入输出,listen-tcp/connect-tcp 管 TCP 端口,listen-unix/connect-unix 管 Unix socket,generate-ticket 负责提前备好钥匙。记住"listen 端出 ticket、connect 端拿 ticket"这一条主线,配合本文的速查表,跨机器组网、远程接管终端、秒变内网穿透都能一句话搞定。更多用法示例可翻阅 README.md 与依赖清单 Cargo.toml。

登录后查看全文
dumbpipe