214 lines
5.4 KiB
Markdown
214 lines
5.4 KiB
Markdown
# OmniSocket
|
||
|
||
OmniSocket 当前包含 3 个核心程序：
|
||
- `omni_peer`
|
||
- `omni_hub`
|
||
- `omni_bridge`
|
||
|
||
三者统一支持 `tcp | udp | kcp` 三种传输协议。
|
||
|
||
## 构建
|
||
|
||
本地构建：
|
||
|
||
```bash
|
||
make
|
||
```
|
||
|
||
生成文件：
|
||
- `build/omni_peer`
|
||
- `build/omni_hub`
|
||
- `build/omni_bridge`
|
||
|
||
Jetson 场景常用 ARM64 交叉编译：
|
||
|
||
```bash
|
||
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 端监听：
|
||
|
||
```bash
|
||
./build/omni_peer -M direct -p <proto> -L 9001 -i jetson -o /tmp/from_pc.bin
|
||
```
|
||
|
||
A 端连接：
|
||
|
||
```bash
|
||
./build/omni_peer -M direct -p <proto> -H <B_IP> -P 9001 -i pc -b jetson -o /tmp/from_jetson.bin
|
||
```
|
||
|
||
连接建立后，可在 A 端输入：
|
||
|
||
```text
|
||
send start
|
||
put /tmp/input.bin
|
||
```
|
||
|
||
如需反向 `B -> A`，可在 B 端输入：
|
||
|
||
```text
|
||
put /path/to/file.bin
|
||
```
|
||
|
||
## 场景 2：通过 Hub 中转
|
||
|
||
`A <-> C <-> B`
|
||
|
||
C 端启动 Hub：
|
||
- C 维护着一张 `client_id -> session` 映射表，用于记录谁是 `pc`、谁是 `jetson`，并据此转发 `bind / tunnel / status`
|
||
|
||
```bash
|
||
./build/omni_hub -p <proto> -P 9002
|
||
```
|
||
|
||
B 端连接 Hub：
|
||
|
||
```bash
|
||
./build/omni_peer -p <proto> -H <C_IP> -P 9002 -i jetson -o /tmp/from_pc.bin
|
||
```
|
||
|
||
A 端连接 Hub：
|
||
|
||
```bash
|
||
./build/omni_peer -p <proto> -H <C_IP> -P 9002 -i pc -b jetson -o /tmp/from_jetson.bin
|
||
```
|
||
|
||
连接建立后，可在 A 端输入：
|
||
|
||
```text
|
||
send start
|
||
put /tmp/input.bin
|
||
```
|
||
|
||
如需反向 `B -> A`，可在 B 端输入：
|
||
|
||
```text
|
||
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
|
||
|
||
```bash
|
||
./build/omni_hub -p <proto> -P 9003
|
||
```
|
||
|
||
D 端启动 Bridge：
|
||
|
||
```bash
|
||
./build/omni_bridge -p <proto> -H <C_IP> -P 9003 -i jetson -L 9004
|
||
```
|
||
|
||
B 端连接 Bridge：
|
||
|
||
```bash
|
||
./build/omni_peer -p <proto> -H <D_IP> -P 9004 -i jetson -o /tmp/from_pc.bin
|
||
```
|
||
|
||
A 端连接 Hub：
|
||
|
||
```bash
|
||
./build/omni_peer -p <proto> -H <C_IP> -P 9003 -i pc -b jetson -o /tmp/from_jetson.bin
|
||
```
|
||
|
||
连接建立后，可在 A 端输入：
|
||
|
||
```text
|
||
send start
|
||
put /tmp/input.bin
|
||
```
|
||
|
||
如需反向 `B -> A`，可在 B 端输入：
|
||
|
||
```text
|
||
bind pc
|
||
put /path/to/file.bin
|
||
```
|
||
|
||
说明：
|
||
- 该场景已经实现 `A -> C -> D -> B` 与 `B -> D -> C -> A` 的桥接转发
|
||
- 但当前 `bridge` 仍是单下游、单身份模型，不是完整的多节点桥接网络
|
||
|