dumbpipe命令清单:从listen、connect到Unix Socket,6个子命令一次讲透
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。