acking-you/pb-mapper
acking-you/pb-mapper has 78 GitHub stars and 6 forks. GitHot measured 0 stars in 24 hours and +1 in 7 days. Last checked 2026-11-15 17:50 UTC. Last push 2026-11-02.
实测星标增长
- 24小时
- 0
- 7天
- +1
- 15天
- 更新延迟
- 1个月
- 更新延迟
各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。
关于
P2P-first tunnels to private TCP/UDP services: direct QUIC with automatic relay fallback, one TCP + one UDP port for every service, built-in scoped keys and event listeners. Rust CLI plus Rust and Node SDKs, made for agent-harness remote control.
自托管README.zh-CN.md
原文pb-mapper 用来访问 NAT 后面的私有 TCP / UDP 服务。在服务旁边运行 register,在需要用它的地方运行 connect,服务就出现在本地端口上。每条连接都先尝试 P2P QUIC 直连;网络打不通时,在发送任何业务字节之前自动回退到中继。路径不需要手动选:CLI 和 SDK 按连接自动决定,并在中继重启、断网和网络切换时自动维持隧道。
┌──── 直连:UDP 打洞 + QUIC ────────────────┐
你的应用 ─► connect register ─► 私有服务
:9090 └──── 回退:relay.example.com:7666 ──────────┘
为什么选 pb-mapper
🧩 SDK 把网络问题全包了。 register 和 connect 就是全部 API。打洞、双向认证 QUIC、中继回退、断线重连、DNS 刷新、网络切换后的恢复都在里面自动完成,TCP 和 UDP 一视同仁。一个进程可以同时维护任意多条隧道,每个 Client 各用各的凭据。
🔌 一个 TCP 端口承载全部中继,一个 UDP 端口让所有服务自由打洞。 7666/tcp 承载所有服务的注册、订阅、状态查询、管理和中继数据;7666/udp 为所有服务协调打洞。新增服务不用再开任何端口。
🔑 自带密钥管理、隔离和事件监听。 一把管理员密钥签发可续期、可吊销的 pbmt1_ 临时凭据,每把凭据拥有独立命名空间,租户、设备或 agent 会话只能看到自己的服务。每条隧道都提供状态流和事件历史(直连建立、回退中继、中继断开、网络切换),接入任何 App 都很直接,agent harness 的 remote control 正是它的主场景。
⚡ 两条路都快。 作者实测:P2P 直连可以把交互延迟压到 20 ms 以内;回退到中继时,延迟和稳定性与 frp「一个端口对应一段映射」的模式持平。实际表现取决于两端网络和中继所在位置。
快速开始
1. 在有公网 IP 的机器上运行 relay:
cargo install pb-mapper-cli --locked # 或从 Releases 下载二进制
pb-mapper server # 7666/tcp 中继,7666/udp 打洞
在防火墙和云安全组放行 7666/tcp 和 7666/udp。首次启动时 relay 会在认证状态目录生成随机管理员密钥 admin.key(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 可以查看每条连接走的是哪条路径。
连接如何选择路径
以下条件全部满足时走直连,前三条都是默认值:
- relay 提供打洞服务(默认开启,使用与 TCP 相同的端口号);
- 提供端允许直连(
register默认允许); - 消费端请求直连(
connect默认--path auto); - 两端网络确实能打通。
任一条件不满足就走中继。切换发生在提供端打开本地服务之前、任何业务字节发送之前,因此不会重放任何数据,后端也只会被拨号一次。回退之后,这条隧道接下来的连接会直接走中继一段时间(10 秒起,翻倍增长到 5 分钟;直连成功或网络切换时清零),所以打不通的网络只付出一次尝试的代价,而不是每条连接都等一次。
需要时可以在任意一侧关闭直连:
| 位置 | 参数 | 效果 |
|---|---|---|
| Relay | pb-mapper server --relay-only |
不开 UDP 端口,所有连接走中继 |
| 提供端 | pb-mapper register --relay-only … |
这项服务只能经中继访问 |
| 消费端 | pb-mapper connect --relay-only … |
这条隧道始终走中继 |
relay 只公布 UDP 端口号,客户端把它和自己拨通 relay 时用的地址配对,所以 1:1 NAT、端口转发都不用额外配置。如果 UDP 端口被映射到别处,用 --direct-advertise 公网IP:端口 指定;用 --direct-listen 绑定其他本地地址。
需要了解的边界:
- 直连会话归两端所有。 relay 重启或凭据吊销只阻止新的建连,不会切断已建立的直连;停止本地隧道才会关闭它。中继连接则在吊销时立即关闭。
- 并非所有网络都能打通。 对称 NAT、UDP 被封锁等情况走中继。已测试的场景见设计说明与验收记录。
- pb-mapper 只负责传输字节。 隧道后面的服务仍然负责自己的认证与授权。
SDK
Rust
[dependencies]
pb-mapper = "0.8"
tokio = { version = "1", features = ["full"] }
use pb_mapper::{Client, ClientConfig, ConnectRequest, RegisterRequest, Transport};
let client = Client::new(ClientConfig {
server: "relay.example.com:7666".into(),
credential: std::env::var("MSG_HEADER_KEY")?,
keep_alive: true,
namespace: None,
})?;
// 设备端:发布本地服务
let registration = client.register(RegisterRequest {
key: "web".into(),
local_addr: "127.0.0.1:8080".into(),
transport: Transport::Tcp,
codec: false,
force_namespace: false,
}).await?;
registration.wait_ready().await?;
// 任意位置:在本地端口访问它,直连优先
let connection = client.connect(ConnectRequest {
key: "web".into(),
local_addr: "127.0.0.1:9090".into(),
transport: Transport::Tcp,
}).await?;
connection.wait_ready().await?;
// 监听状态变化:Starting → Connected → Retrying → …
let mut status = connection.subscribe();
while status.changed().await.is_ok() {
println!("{:?}", *status.borrow());
}
每项能力都有可运行的示例,见 crates/pb-mapper/examples/。建议从 cargo run -p pb-mapper --example quickstart 开始,它不需要你自己的 relay:
| 示例 | 内容 |
|---|---|
quickstart |
内嵌 relay、发布 echo 服务、直连往返,并打印实际路径 |
register_tcp / connect_tcp |
TCP 隧道两端,实时显示直连与中继的连接数 |
udp |
UDP 隧道两端,例如游戏服务器 |
path_options |
allow_direct: false、PathPolicy::RelayOnly、空闲超时 |
watch_events |
状态流、事件历史、直连实时阶段、JSON 诊断 |
status |
命名空间内的服务、控制连接与会话 |
admin_credentials |
签发、查看、显示密钥、续期、列出、吊销、回收凭据 |
admin_inventory |
所有租户的服务与连接、清理卡住的连接、轮换根密钥 |
remote_control |
agent harness 模式:每个会话一把凭据、相互隔离、结束时吊销 |
关闭 p2p feature(default-features = false)可得到不含 QUIC 的纯中继客户端。
TypeScript(Node-API)
npm install pb-mapper
import { Client } from "pb-mapper";
const client = new Client({
server: "relay.example.com:7666",
credential: process.env.MSG_HEADER_KEY!,
});
const conn = await client.connect({
key: "web", localAddr: "127.0.0.1:9090", transport: "tcp",
});
await conn.waitReady();
// 事件监听:每次变化 resolve 一次,隧道终止后循环结束
for (let s = conn.status(); s !== "stopped" && !s.startsWith("failed");) {
s = await conn.nextStatus();
console.log(s, conn.diagnostics().events.at(-1));
}
预编译覆盖 Linux(x64、arm64,glibc)、macOS(x64、arm64)与 Windows x64,支持 Node.js 18+ 与 Bun 1.1+。完整 API 见 js/README.md。
其他接入面
| 接入面 | 能力 |
|---|---|
CLI pb-mapper |
一个二进制包含 server、register、connect、status、admin |
| Agent Skill | 端到端安装并验收 relay、register 与 connect(见下文) |
| Flutter UI | 基于 C ABI 的桌面与移动端 GUI,目前走中继路径 |
| Relay 库 | pb-mapper-server,可把 relay 内嵌进自己的进程 |
凭据与安全
| 凭据 | 持有者 | 权限 |
|---|---|---|
| 管理员密钥(32 字节) | Relay 运维者或可信的凭据分发自动化 | 签发、查看、续期、吊销、轮换;检查所有命名空间 |
临时 pbmt1_ 凭据 |
单个租户、设备、harness 或会话 | 只能在自己的命名空间内注册、连接和查询 |
- 临时凭据由管理员密钥、持久化的 relay 实例 ID 和 key ID 派生,relay 只保存生命周期元数据,不保存密钥本身。过期、吊销与根密钥轮换会立即作用于现有中继连接。
- V2 协议在加密的首个请求内完成认证,不额外增加往返。直连会话运行在 QUIC 上,双方证书互相固定并绑定到会话授权。
register --codec为中继数据增加 AES-256-GCM 加密。 - 凭据是预共享的,不是公钥身份体系。如需证书身份或对流量分析的防护,请在其上叠加 TLS 或其他应用协议。详见认证设计与数据加密兼容性。
部署
- Agent Skill:直接告诉你的编码 agent
Fetch and follow instructions from https://raw.githubusercontent.com/acking-you/pb-mapper/master/skills/pb-mapper-suite/INSTALL.md, 它会安装 CLI、部署 relay、配置 register/connect 并完成验收。 - Docker:
docker compose -f docker/docker-compose.yml up -d同时发布7666/tcp与7666/udp,见DOCKER_README.md。 - systemd:relay、register、connect 的 unit 文件在
services/。 - 预编译二进制:Linux、macOS、Windows 的 CLI 与 UI 见 Releases。
从 0.7 升级
现在所有位置的默认值都是「直连优先、中继兜底」。原有命令继续可用:--enable-direct、--allow-direct、--path auto 仍然被接受,连接旧版 relay 的客户端会直接走中继。想保持 0.7 的行为,就给 server、register 或 connect 加上 --relay-only。SDK 中,Node 设 allowDirect: false / path: "relay-only",Rust 用 RegisterOptions { allow_direct: false, .. } / PathPolicy::RelayOnly。0.7 客户端不会把公布的端口号与 relay 地址配对,因此即使开启了直连,连接默认配置的 0.8 relay 也会回退中继;升级客户端,或用 --direct-advertise 公网IP:7666 启动 relay 即可。
文档
- 可选 QUIC 中继:默认 TCP、CLI 开关、Rust/Node SDK、可观测接口与性能实测
- 使用手册:所有命令与参数
- 弱网恢复:超时、资源边界与故障测试
- 认证与 V2 协议
- 直连设计说明
- 更新日志
仓库结构:crates/ 是 Rust workspace(core、auth、protocol、server、client、pb-mapper SDK 门面、Node-API 绑定、CLI 与 testkit);js/ 是 npm 包;ui/ 是 Flutter 应用及其 C ABI;skills/ 是 agent 工作流;docker/、services/、scripts/ 是打包与运维工具。
make build-pb-mapper
cargo test --workspace --all-features
