pb-mapper：P2P 内网穿透隧道工具

项目简介

pb-mapper 用来访问 NAT 后面的私有 TCP 和 UDP 服务。在服务旁边运行 register，在需要访问的地方运行 connect，服务就会出现在一个本地端口上。每条连接先尝试点对点的 QUIC 直连；如果网络不允许，会在发出第一个字节之前回退到中继。路径不需要人工选择，CLI 和 SDK 会按连接自动决定，并在中继重启、中断和网络切换后保持隧道可用。

                 ┌──── direct: UDP hole punching + QUIC ────┐
 your app ─► connect                                         register ─► private service
   :9090         └──── fallback: relay.example.com:7666 ─────┘

主要功能

• SDK 替你处理网络：register 和 connect 就是全部 API，打洞、双向认证的 QUIC、中继回退、重连、DNS 刷新和网络切换后的恢复都在内部完成，TCP 与 UDP 一致。一个进程可以持有任意多条隧道，每条使用自己的凭证。
• 一个 TCP 端口转发所有服务，一个 UDP 端口为所有服务打洞：7666/tcp 承载注册、订阅、状态、管理与各服务的转发字节；7666/udp 为所有服务协调打洞。新增服务不再开新端口。
• 内置密钥、隔离与事件：一个管理员密钥签发可续期、可撤销的 pbmt1_ 凭证，各自限定在自己的命名空间内，租户、设备或 agent 会话只能看到自己的服务。每条隧道都提供状态流和事件历史：直连建立、回退、中继断开、网络变化。
• 两条路径都快：按作者实测，直连会话的交互延迟低于 20 ms；中继回退在延迟与稳定性上与 frp 一端口一映射的方案相当（具体取决于两端网络和中继位置）。
• 多种使用形态：CLI pb-mapper（server、register、connect、status、admin 一个二进制）、Rust 与 TypeScript（Node-API）SDK、Flutter 桌面/移动 GUI（目前走中继路径）、可嵌入自有进程的中继库 pb-mapper-server。

安装与使用

1. 部署中继（任意有公网 IP 的主机），并放通 7666/tcp 与 7666/udp：

cargo install pb-mapper-cli --locked   # 或使用 Releases 中的二进制
pb-mapper server                       # 中继监听 7666/tcp，打洞使用 7666/udp

首次启动时中继会生成随机管理员密钥 admin.key，位于其 auth 状态目录（Linux 服务为 /var/lib/pb-mapper/auth）。

2. 签发凭证：

export MSG_HEADER_KEY="$(sudo cat /var/lib/pb-mapper/auth/admin.key)"
pb-mapper admin --server relay.example.com:7666 key issue --ttl 24h --label laptop

3. 发布服务并访问它，使用上一步打印出的 pbmt1_… 凭证：

# 在服务旁边
MSG_HEADER_KEY='pbmt1_…' pb-mapper register tcp --key web --addr 127.0.0.1:8080 --server relay.example.com:7666
# 在需要访问的地方
MSG_HEADER_KEY='pbmt1_…' pb-mapper connect tcp --key web --addr 127.0.0.1:9090 --server relay.example.com:7666

此后 127.0.0.1:9090 即可访问该服务，pb-mapper status sessions 会显示每条连接走的路径。

Node SDK：npm install pb-mapper，预编译支持 Linux（x64、arm64、glibc）、macOS（x64、arm64）和 Windows x64，要求 Node.js 18+ 或 Bun 1.1+。Rust SDK 依赖 pb-mapper = "0.8"，crates/pb-mapper/examples/ 中每个能力都有可运行示例，可从 cargo run -p pb-mapper --example quickstart 开始（无需自建中继）。

强制走中继：中继侧 pb-mapper server --relay-only；发布侧 pb-mapper register --relay-only …；访问侧 pb-mapper connect --relay-only …。

注意事项

• 直连会话属于两个端点：中继重启或凭证撤销只会阻止新的建立，不会切断已运行的直连会话，停止本地隧道才会；中继连接在撤销时立即关闭。
• 并非所有网络都能打洞，对称 NAT 和被封锁的 UDP 会使用中继，设计说明与验证记录见 issue-13 设计文档。
• 中继只公布 UDP 端口，客户端会与拨出的中继地址配对，1:1 NAT 和端口转发无需额外配置；若 UDP 端口映射到别处，用 --direct-advertise PUBLIC_IP:PORT，用 --direct-listen 绑定不同的本地地址。
• pb-mapper 只负责搬运字节，隧道后的服务仍自行负责认证与授权。

---

本作品整理自 GitHub 开源项目 acking-you/pb-mapper，原作者 @acking-you，许可证 MIT。中文介绍由 AI 根据项目 README 整理，以原仓库为准。