OmniSocket/README.md

OmniSocket

OmniSocket 当前包含 3 个核心程序：

• omni_peer
• omni_hub
• omni_bridge

三者统一支持 tcp | udp | kcp 三种传输协议。

构建

本地构建：

make

生成文件：

• build/omni_peer
• build/omni_hub
• build/omni_bridge

Jetson 场景常用 ARM64 交叉编译：

make arm64

生成文件：

• build/arm64/omni_peer
• build/arm64/omni_hub
• build/arm64/omni_bridge

程序说明

omni_peer

omni_peer 支持两种工作模式：

• hub 模式：连接 hub 或 bridge
• direct 模式：peer 之间直接互连

常见用途：

• 发送文本命令
• 发送文件
• 接收文件

omni_hub

omni_hub 是中心注册与转发节点，通常部署在公网服务器或中心网络位置。

主要职责：

• 维护 client_id -> session
• 转发 peer 之间的 bind / tunnel / status

omni_bridge

omni_bridge 是桥接节点，用于将远端 peer 接入上游 hub。

主要职责：

• 上游连接 hub
• 下游监听本地入口供 peer 接入
• 适用于 A <-> C <-> D <-> B 这类桥接链路

当前限制：

• 一个 bridge 仅支持一个下游 peer
• 下游 peer 的 -i 必须与 bridge -i 保持一致
• 上下游必须使用同一种协议，不支持协议转换
• 当前实现更接近“单下游、单身份桥接”，而不是通用多租户中继

角色说明

• A：本地电脑
• B：Jetson
• C：公网 Hub 服务器
• D：公网 Bridge 服务器

下面示例中的 <proto> 可替换为 tcp、udp 或 kcp。

说明：

• 以下 omni_peer 示例统一采用长连接交互模式
• 启动后连接会保持，不再使用“传输一次后自动退出”的一次性写法
• 文本和文件传输通过终端中的交互命令完成
• 若启动命令中使用了 -m 或 -F，程序会执行启动动作模式，而不是进入当前 README 使用的交互模式

常用参数与命令

分类	写法	含义
启动参数	-i <client_id>	当前 peer 的逻辑身份。Hub 会根据这个 ID 记录 client_id -> session 映射，例如 -i pc 表示“我是 pc”，-i jetson 表示“我是 jetson”。
启动参数	-b <peer_id>	启动后默认绑定的目标 peer。例如 -b jetson 表示后续直接输入 send ... 或 put ... 时，默认发给 jetson。
启动参数	-d <peer_id>	启动动作模式下的显式目标。通常与 -m 或 -F 配合使用，表示把启动时的那条消息或那个文件直接发给指定目标。
启动参数	-o <output_file>	本地接收文件时的落盘路径。收到文件后会写入当前机器上的这个路径，例如 -o /tmp/from_pc.bin。
交互命令	bind <peer_id>	将默认目标切换到指定 peer，后续 send 或 put 默认发给它。
交互命令	send <text>	向当前默认目标发送一条文本消息。
交互命令	say <peer_id> <text>	向指定 peer 发送一条文本消息，不修改当前默认目标。
交互命令	put <file>	将当前机器上的文件发送给当前默认目标。
交互命令	push <peer_id> <file>	将当前机器上的文件发送给指定 peer，不修改当前默认目标。
交互命令	show	显示当前本地状态，例如 client_id、当前绑定目标和输出路径。
交互命令	quit	退出当前 omni_peer 进程。

场景 1：点对点直传

A <-> B

B 端监听：

./build/omni_peer -M direct -p <proto> -L 9001 -i jetson -o /tmp/from_pc.bin

A 端连接：

./build/omni_peer -M direct -p <proto> -H <B_IP> -P 9001 -i pc -b jetson -o /tmp/from_jetson.bin

连接建立后，可在 A 端输入：

send start
put /tmp/input.bin

如需反向 B -> A，可在 B 端输入：

put /path/to/file.bin

场景 2：通过 Hub 中转

A <-> C <-> B

C 端启动 Hub：

• C 维护着一张 client_id -> session 映射表，用于记录谁是 pc、谁是 jetson，并据此转发 bind / tunnel / status

./build/omni_hub -p <proto> -P 9002

B 端连接 Hub：

./build/omni_peer -p <proto> -H <C_IP> -P 9002 -i jetson -o /tmp/from_pc.bin

A 端连接 Hub：

./build/omni_peer -p <proto> -H <C_IP> -P 9002 -i pc -b jetson -o /tmp/from_jetson.bin

连接建立后，可在 A 端输入：

send start
put /tmp/input.bin

如需反向 B -> A，可在 B 端输入：

bind pc
put /path/to/file.bin

场景 3：通过 Bridge 桥接

A <-> C <-> D <-> B

C 端启动 Hub：

• C 仍然维护 client_id -> session 映射表；A 以 pc 注册到 C，Bridge 以 jetson 这个逻辑身份注册到 C

./build/omni_hub -p <proto> -P 9003

D 端启动 Bridge：

./build/omni_bridge -p <proto> -H <C_IP> -P 9003 -i jetson -L 9004

B 端连接 Bridge：

./build/omni_peer -p <proto> -H <D_IP> -P 9004 -i jetson -o /tmp/from_pc.bin

A 端连接 Hub：

./build/omni_peer -p <proto> -H <C_IP> -P 9003 -i pc -b jetson -o /tmp/from_jetson.bin

连接建立后，可在 A 端输入：

send start
put /tmp/input.bin

如需反向 B -> A，可在 B 端输入：

bind pc
put /path/to/file.bin

说明：

• 该场景已经实现 A -> C -> D -> B 与 B -> D -> C -> A 的桥接转发
• 但当前 bridge 仍是单下游、单身份模型，不是完整的多节点桥接网络