gateway-rs

OpenIoTHub 网关的 Rust 版本，是 gateway-go 的完整重写，与 Go 版本保持线协议兼容。

功能特性

JWT Token 登录 OpenIoTHub 服务器
首次运行自动获取 Token 并展示二维码供手机扫码绑定
多协议端口转发：TCP / TLS / UDP / WebSocket / WSS / SSH / 串口
TUN/TAP 虚拟网络接口（跨平台）
mDNS 服务发现与网关注册
TCP 端口扫描
组播 UDP 监听转发
系统状态信息采集（CPU、内存、磁盘、网络）
IPv6 P2P 直连
HTTP 管理界面与二维码展示
gRPC 管理服务（登录状态查询 / Token 登录 / Reflection）
Docker 容器服务发现
yamux 多路复用（与 Go 版本 wire-compatible）

环境要求

Rust >= 1.75（2021 edition）
protoc（Protocol Buffers 编译器，编译时需要）
TUN/TAP 功能需要管理员/root 权限

快速开始

从 crates.io 安装

cargo install gateway-rs
gateway-rs

从源码编译

cd gateway_rs
cargo build --release

编译产物位于 target/release/gateway-rs。

运行

# 默认启动（使用配置文件，首次运行自动创建并自动登录）
./target/release/gateway-rs

# 使用 Token 登录
./target/release/gateway-rs -t <your-gateway-token>

# 指定配置文件路径
./target/release/gateway-rs -c /path/to/gateway-go.yaml

# 初始化配置文件（不启动服务）
./target/release/gateway-rs init

# 初始化到指定路径
./target/release/gateway-rs init -c /etc/gateway-go/gateway-go.yaml

# 测试命令是否可用
./target/release/gateway-rs test

启动后，网关会在终端打印 OpenIoTHub Logo 和版本号。如果没有已保存的 Token，会自动向云端申请并展示二维码，用云亿连 App 扫码即可绑定。

命令行参数

Usage: gateway-rs [OPTIONS] [COMMAND]

OpenIoTHub Gateway - Rust implementation

Commands:
  init  Initialize config file
  test  Test command

Options:
  -c, --config <CONFIG>  Config file path [env: GatewayConfigFilePath]
  -t, --token <TOKEN>    Login server by gateway token [env: GatewayLoginToken]
  -h, --help             Print help
  -V, --version          Print version

配置文件

默认配置文件名为 gateway-go.yaml（与 Go 版共用同一格式），首次运行时自动创建。

gatewayuuid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
logconfig:
  enablestdout: true
  logfilepath: ""
http_service_port: 34323
loginwithtokenmap: {}

配置说明

字段	类型	默认值	说明
`gatewayuuid`	string	自动生成	网关 UUID，长度不足 35 位时会重新生成
`logconfig.enablestdout`	bool	`true`	是否将日志输出到终端
`logconfig.logfilepath`	string	`""`	日志文件路径，为空则不写文件
`http_service_port`	number	`34323`	HTTP 管理界面端口
`loginwithtokenmap`	map	`{}`	已登录服务器的 Token 映射（RunId -> JWT Token）

配置文件路径查找顺序

-c / --config 命令行参数
GatewayConfigFilePath 环境变量
$SNAP_USER_DATA/gateway-go.yaml（Snap 环境）
./gateway-go.yaml（当前目录）

环境变量

变量名	说明
`GatewayLoginToken`	直接指定登录 Token（优先级高于配置文件）
`GatewayConfigFilePath`	指定配置文件路径
`SNAP_USER_DATA`	Snap 应用数据目录（自动拼接配置文件路径）
`RUST_LOG`	日志级别，如 `info`、`debug`、`gateway_rs=debug`

示例：

# 通过环境变量启动
GatewayLoginToken=eyJhbGci... ./target/release/gateway-rs

# 指定配置文件
GatewayConfigFilePath=/etc/gateway-go/gateway-go.yaml ./target/release/gateway-rs

# 开启 debug 日志
RUST_LOG=debug ./target/release/gateway-rs

Docker 部署

构建镜像

docker build -t gateway-rs .

运行容器

# 基本运行（自动登录模式）
docker run -d \
  --name gateway-rs \
  -p 34323:34323 \
  -p 55443:55443 \
  gateway-rs

# 使用 Token 登录
docker run -d \
  --name gateway-rs \
  -e GatewayLoginToken=eyJhbGci... \
  -p 34323:34323 \
  -p 55443:55443 \
  gateway-rs

# 挂载配置文件持久化
docker run -d \
  --name gateway-rs \
  -p 34323:34323 \
  -p 55443:55443 \
  -v /path/to/gateway-go.yaml:/root/gateway-go.yaml \
  gateway-rs -c /root/gateway-go.yaml

# 启用 Docker 容器服务发现（需要挂载 docker.sock）
docker run -d \
  --name gateway-rs \
  -p 34323:34323 \
  -p 55443:55443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gateway-rs

端口说明

端口	协议	说明
`34323`	HTTP	管理界面与二维码展示
`55443`	gRPC	网关管理服务（登录状态查询 / Token 登录）

systemd 部署

将二进制文件复制到系统路径，并安装 service 文件：

# 安装二进制
sudo cp target/release/gateway-rs /usr/local/bin/

# 创建配置目录并初始化
sudo mkdir -p /etc/gateway-go
sudo gateway-rs init -c /etc/gateway-go/gateway-go.yaml

# 安装 systemd service
sudo cp systemd/gateway-rs.service /etc/systemd/system/

# 启动并设为开机自启
sudo systemctl daemon-reload
sudo systemctl enable --now gateway-rs

# 查看运行状态
sudo systemctl status gateway-rs

# 查看日志
sudo journalctl -u gateway-rs -f

如需使用 Token 登录，可在 service 文件中添加环境变量：

[Service]
Environment="GatewayLoginToken=eyJhbGci..."

Feature 开关

Feature	默认	说明	依赖 crate
`docker`	是	Docker 容器服务发现	`bollard`
`ssh`	是	SSH PTY 转发	`russh`
`tuntap`	是	TUN/TAP 虚拟网络接口	`tun-rs`
`serial`	否	串口转发	`tokio-serial`

# 编译所有功能
cargo build --release --all-features

# 仅核心功能（无 Docker / SSH / TUN）
cargo build --release --no-default-features

# 选择性启用
cargo build --release --no-default-features --features "docker,ssh"

# 启用串口支持
cargo build --release --features serial

服务接口

HTTP 接口

路径	方法	说明
`/`	GET	管理首页（显示登录状态与 QR 码链接）
`/DisplayQrHandler`	GET	返回二维码图片（PNG），供手机扫码绑定网关

浏览器访问 http://<网关IP>:34323/ 可查看网关状态。

gRPC 接口

服务定义见 proto/gateway.proto：

方法	说明
`CheckGatewayLoginStatus`	查询网关登录状态
`LoginServerByToken`	通过 Token 登录服务器

支持 gRPC Reflection，可使用 grpcurl 等工具直接探索接口：

# 查看可用服务
grpcurl -plaintext localhost:55443 list

# 查询登录状态
grpcurl -plaintext localhost:55443 pb.GatewayLoginManager/CheckGatewayLoginStatus

# 通过 Token 登录
grpcurl -plaintext -d '{"value":"eyJhbGci..."}' \
  localhost:55443 pb.GatewayLoginManager/LoginServerByToken

协议兼容性

Rust 版与 Go 版使用完全相同的线上协议，可以直接替换部署：

协议层	说明
yamux	流多路复用，与 `libp2p/go-yamux` wire-compatible
msgio	消息帧格式：4 字节大端长度前缀 + 载荷
消息格式	两帧组成：`[len][type_string]` + `[len][json_body]`
类型标识	Go 反射类型字符串，如 `models.ConnectTCP`
配置文件	使用相同的 `gateway-go.yaml` 格式，无缝切换

作为库使用

gateway-rs 支持以库的形式嵌入其他 Rust 项目：

# Cargo.toml
[dependencies]
gateway-rs = "0.1"
tokio = { version = "1", features = ["full"] }

use gateway_rs::services::gateway_manager::get_gateway_manager;

#[tokio::main]
async fn main() {
    // 添加服务器
    get_gateway_manager()
        .add_server("your-jwt-token")
        .await
        .unwrap();

    // 启动后台服务（HTTP, gRPC, IPv6 任务）
    gateway_rs::run().await;
}

项目结构

gateway_rs/
├── Cargo.toml                  # 包管理与依赖配置
├── build.rs                    # Proto 编译 + Git 信息注入
├── Dockerfile                  # 多阶段 Docker 构建
├── README.md
├── proto/                      # gRPC Proto 文件
│   ├── gateway.proto
│   └── public_api.proto
├── systemd/                    # systemd 服务文件
│   └── gateway-rs.service
├── docs/                       # 详细文档
│   ├── unimplemented-features.md   # 未实现功能清单
│   ├── optimization-suggestions.md # 优化建议
│   └── go-rs-comparison.md         # Go/Rust 功能对照表
└── src/
    ├── main.rs                 # CLI 入口
    ├── lib.rs                  # 库入口
    ├── config.rs               # 配置管理（读写 + 全局状态）
    ├── models.rs               # 协议消息定义
    ├── protocol.rs             # 消息帧编解码
    ├── io_util.rs              # 双向流复制
    ├── chans.rs                # 异步通道（IPv6 任务）
    ├── info.rs                 # 版本与构建信息
    ├── register.rs             # 本地服务注册
    ├── tasks.rs                # 后台任务（IPv6 P2P）
    ├── services/               # 业务层
    │   ├── gateway_manager.rs  # 多会话管理
    │   ├── server_session.rs   # 单会话（心跳重连）
    │   ├── startup.rs          # 启动流程
    │   ├── autosetup.rs        # 自动登录
    │   └── http_handler.rs     # HTTP 页面与二维码
    ├── netservice/             # 网络服务层
    │   ├── handle.rs           # 消息分发
    │   ├── login.rs            # 服务器登录
    │   ├── conn.rs             # 连接转发（TCP/UDP/WS/SSH/串口）
    │   └── service.rs          # 服务处理（mDNS/扫描/系统状态/TUN）
    ├── client/                 # 客户端服务
    │   ├── http_server.rs      # HTTP 服务器（Axum）
    │   ├── grpc_server.rs      # gRPC 服务器（Tonic + Reflection）
    │   └── mdns_register.rs    # mDNS 网关注册
    └── utils/                  # 工具层
        ├── qr.rs               # 二维码生成
        └── docker.rs           # Docker 容器发现

详细的功能对比与优化建议见 docs/ 目录。

从 Go 版本迁移

如果你正在使用 gateway-go，迁移到 Rust 版非常简单：

编译或安装 gateway-rs
直接使用原有的 gateway-go.yaml 配置文件
用相同参数启动：gateway-rs -c /path/to/gateway-go.yaml

两个版本使用相同的配置格式和线上协议，可以无缝切换。

License

MIT

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

gateway-rs

功能特性

环境要求

快速开始

从 crates.io 安装

从源码编译

运行

命令行参数

配置文件

配置说明

配置文件路径查找顺序

环境变量

Docker 部署

构建镜像

运行容器

端口说明

systemd 部署

Feature 开关

服务接口

HTTP 接口

gRPC 接口

协议兼容性

作为库使用

项目结构

从 Go 版本迁移

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github/workflows		.github/workflows
docs		docs
proto		proto
src		src
systemd		systemd
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Dockerfile		Dockerfile
README.md		README.md
build.rs		build.rs
gateway-go.yaml		gateway-go.yaml

Folders and files

Latest commit

History

Repository files navigation

gateway-rs

功能特性

环境要求

快速开始

从 crates.io 安装

从源码编译

运行

命令行参数

配置文件

配置说明

配置文件路径查找顺序

环境变量

Docker 部署

构建镜像

运行容器

端口说明

systemd 部署

Feature 开关

服务接口

HTTP 接口

gRPC 接口

协议兼容性

作为库使用

项目结构

从 Go 版本迁移

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages