|
1 | | -# Verge - IoT边缘计算网关 |
| 1 | +# Verge - 标准化边缘计算网关解决方案 |
2 | 2 |
|
3 | | -Verge是一个基于[driver-box](https://github.com/ibuilding-x/driver-box)框架的IoT边缘计算网关项目,用于连接物理设备与云端服务,实现设备数据采集、控制命令转发、以及双向通信等功能。 |
| 3 | +[](https://github.com/smartboot/verge/actions/workflows/ci.yml) |
| 4 | +[](https://github.com/smartboot/verge/actions/workflows/docker.yml) |
| 5 | +[](https://go.dev) |
| 6 | +[](LICENSE) |
4 | 7 |
|
5 | | -## 功能特性 |
| 8 | +> **Verge** 是一个轻量级、标准化的边缘计算网关解决方案。它将后台管理功能剥离为独立的云端/桌面服务,网关本身只专注于设备数据采集与治理,将硬件资源需求降至极致。 |
6 | 9 |
|
7 | | -- **双向通信**: 基于Server-Sent Events(SSE)实现云端到边缘的实时指令下发 |
8 | | -- **设备管理**: 支持动态添加、删除、更新设备信息 |
9 | | -- **数据同步**: 自动上报设备状态、设备影子数据到云端 |
10 | | -- **产品模型管理**: 支持物模型的导入和上报 |
11 | | -- **协议适配**: 支持多种物联网通信协议(如MQTT等) |
12 | | -- **设备控制**: 接收云端指令对设备进行远程控制 |
13 | | -- **网络状态监控**: 实时监控网络连接状态并上报 |
| 10 | +## 🎯 设计哲学 |
14 | 11 |
|
15 | | -## 架构设计 |
| 12 | +### 传统网关的困境 |
16 | 13 |
|
17 | | -``` |
18 | | -云端服务 ←→ Verge网关 ←→ 物理设备 |
19 | | - ↑ ↑ |
20 | | - SSE通信 协议适配 |
21 | | - ↓ ↓ |
22 | | -JSON-RPC指令 数据采集 |
23 | | -``` |
| 14 | +传统边缘网关往往集成设备接入、场景联动、规则引擎、用户界面等全量功能。这种"大而全"的设计带来了显著问题: |
24 | 15 |
|
25 | | -### 核心模块 |
| 16 | +- **资源浪费** — 大量功能仅在实施阶段使用,却需长期占用网关资源 |
| 17 | +- **OTA 成本高** — 应用层频繁迭代导致升级包大、耗时长、风险高 |
| 18 | +- **硬件门槛高** — 功能臃肿推高了对 CPU、内存的最低要求 |
26 | 19 |
|
27 | | -- **SSE管理器** (pkg/sse/sse_manager.go): 负责与云端建立长连接,接收下行指令 |
28 | | -- **RPC处理器** (pkg/rpc/): 处理云端下发的各类指令 |
29 | | -- **数据上报器** (pkg/reporter/): 负责向云端上报设备数据 |
30 | | -- **导出器** (export.go): 整合各模块功能,作为driver-box插件入口 |
| 20 | +### Verge 的答案:关注点分离 |
31 | 21 |
|
32 | | -### RPC指令集 |
33 | | - |
34 | | -| 方法 | 描述 | |
35 | | -|------|------| |
36 | | -| `node.networkStatus` | 处理网络状态变化,网络连通时上报设备、模型和驱动 | |
37 | | -| `node.configChanged` | 处理配置变更通知 | |
38 | | -| `node.command` | 执行节点级命令 | |
39 | | -| `device.control` | 控制指定设备 | |
40 | | -| `devices.add` | 添加新设备 | |
41 | | -| `product.import` | 从云端导入产品模型和协议脚本 | |
42 | | -| `products.report` | 上报产品信息 | |
| 22 | +``` |
| 23 | +┌─────────────────────────────────────┐ |
| 24 | +│ 应用层(云端/桌面服务) │ |
| 25 | +│ 设备管理 · 场景联动 · 用户界面 │ |
| 26 | +│ ✓ 快速迭代 ✓ 丰富体验 │ |
| 27 | +└─────────────────┬───────────────────┘ |
| 28 | + │ 标准 API |
| 29 | +┌─────────────────▼───────────────────┐ |
| 30 | +│ 边缘层(Verge 网关) │ |
| 31 | +│ 设备接入 · 数据采集 · 协议转换 │ |
| 32 | +│ ✓ 极致轻量 ✓ 高度稳定 │ |
| 33 | +└─────────────────┬───────────────────┘ |
| 34 | + │ Modbus/MQTT/... |
| 35 | +┌─────────────────▼───────────────────┐ |
| 36 | +│ 物理设备 │ |
| 37 | +└─────────────────────────────────────┘ |
| 38 | +``` |
43 | 39 |
|
44 | | -## 环境要求 |
| 40 | +**核心价值:** |
45 | 41 |
|
46 | | -- Go 1.18+ |
47 | | -- [driver-box](https://github.com/ibuilding-x/driver-box) 框架 |
| 42 | +| 维度 | 传统网关 | Verge 网关 | |
| 43 | +|------|----------|------------| |
| 44 | +| 资源占用 | 高 | 极致低 | |
| 45 | +| OTA 频率 | 高 | 几乎为零 | |
| 46 | +| 硬件要求 | 中高配置 | 任意硬件 | |
| 47 | +| 稳定性 | 受应用迭代影响 | 长期稳定 | |
48 | 48 |
|
49 | | -## 快速开始 |
| 49 | +--- |
50 | 50 |
|
51 | | -### 1. 环境配置 |
| 51 | +## 🚀 快速开始 |
52 | 52 |
|
53 | | -设置云端服务地址: |
54 | | -```bash |
55 | | -export ENV_VERGE_BASE_URL=http://your-cloud-server:8080 |
56 | | -``` |
| 53 | +### 二进制部署(生产推荐) |
57 | 54 |
|
58 | | -### 2. 运行项目 |
| 55 | +从 [Releases](https://github.com/smartboot/verge/releases) 下载对应平台压缩包: |
59 | 56 |
|
60 | 57 | ```bash |
61 | | -# 克隆项目 |
62 | | -git clone https://github.com/smartboot/verge.git |
| 58 | +# 下载并解压 |
| 59 | +tar -xzf verge-linux-arm64-*.tar.gz |
63 | 60 | cd verge |
64 | 61 |
|
65 | | -# 下载依赖 |
66 | | -go mod tidy |
67 | | - |
68 | | -# 运行 |
69 | | -go run cmd/main.go |
70 | | -``` |
71 | | - |
72 | | -### 3. 部署构建 |
73 | | - |
74 | | -使用提供的部署脚本构建多平台二进制文件: |
75 | | -```bash |
76 | | -./deploy.sh |
| 62 | +# 配置并启动 |
| 63 | +export ENV_VERGE_BASE_URL=http://your-server:8080 |
| 64 | +./start.sh |
77 | 65 | ``` |
78 | 66 |
|
79 | | -该脚本会生成适用于不同操作系统的压缩包,包括: |
80 | | -- Linux (arm64, amd64, arm) |
81 | | -- Windows (amd64, arm64) |
82 | | -- macOS (amd64, arm64) |
| 67 | +**为什么推荐二进制部署?** |
| 68 | +- 网关程序稳定后几乎无需更新,一次性部署即可 |
| 69 | +- 直接运行,无容器层开销 |
| 70 | +- 更适合工业现场环境 |
83 | 71 |
|
84 | | -## 使用说明 |
| 72 | +### Docker 部署(家用/开发场景) |
85 | 73 |
|
86 | | -### 设备添加 |
87 | | -通过云端下发`devices.add`指令可动态添加设备,参数包含: |
88 | | -- 插件类型 |
89 | | -- 模型标识符及哈希值验证 |
90 | | -- 连接配置 |
91 | | -- 设备列表 |
| 74 | +适用于家庭实验室、开发测试环境,或设备基于以太网通信的场景: |
92 | 75 |
|
93 | | -### 设备控制 |
94 | | -通过云端下发`device.control`指令控制设备,参数包含: |
95 | | -- 设备ID |
96 | | -- 点位映射(属性名-值对) |
| 76 | +```bash |
| 77 | +docker-compose up -d |
| 78 | +``` |
97 | 79 |
|
98 | | -### 数据上报 |
99 | | -网关定期(默认每10秒)上报设备影子数据,包括设备状态和属性值。 |
| 80 | +> **注意**:如果设备使用串口通信,需确保容器有相应权限访问串口设备。 |
100 | 81 |
|
101 | | -## 配置说明 |
| 82 | +访问 `http://localhost:18080` 查看管理界面。 |
102 | 83 |
|
103 | | -### 环境变量 |
| 84 | +### 源码运行(开发调试) |
104 | 85 |
|
105 | | -- `ENV_VERGE_BASE_URL`: 云端服务基础URL |
106 | | -- `ENV_RESOURCE_PATH`: 资源文件路径(可选,默认为 ./res) |
| 86 | +```bash |
| 87 | +git clone https://github.com/smartboot/verge.git |
| 88 | +cd verge && go mod tidy |
| 89 | +export ENV_VERGE_BASE_URL=http://your-server:8080 |
| 90 | +go run cmd/main.go |
| 91 | +``` |
107 | 92 |
|
108 | | -### 资源目录结构 |
| 93 | +--- |
109 | 94 |
|
110 | | -``` |
111 | | -res/ |
112 | | -├── library/ |
113 | | - ├── model/ # 物模型定义文件 |
114 | | - └── protocol/ # 协议适配脚本 |
115 | | -``` |
| 95 | +## 📦 核心特性 |
116 | 96 |
|
117 | | -## 开发指南 |
| 97 | +- **极致轻量** — 聚焦设备接入核心功能,资源占用最小化 |
| 98 | +- **跨平台** — 支持 Linux/Windows/macOS,兼容 x86_64/ARM 架构 |
| 99 | +- **多协议** — 内置 MQTT、Modbus 等工业协议,支持 Lua 自定义扩展 |
| 100 | +- **云边协同** — SSE 实时通信 + JSON-RPC 标准接口 |
| 101 | +- **容器化** — 提供 Docker 镜像和 compose 配置 |
118 | 102 |
|
119 | | -### 添加新的RPC处理器 |
| 103 | +--- |
120 | 104 |
|
121 | | -1. 在pkg/rpc/目录下创建新的处理器文件 |
122 | | -2. 在handlers.go中注册处理器函数 |
123 | | -3. 实现相应的业务逻辑 |
| 105 | +## 🔧 配置 |
124 | 106 |
|
125 | | -### 添加资源文件 |
| 107 | +### 环境变量 |
126 | 108 |
|
127 | | -物模型文件应放置在res/library/model/目录下,协议脚本应放置在res/library/protocol/目录下。 |
128 | | -此外,驱动脚本应放置在res/library/driver/目录下,这些会在产品导入时自动生成。 |
| 109 | +| 变量 | 说明 | |
| 110 | +|------|------| |
| 111 | +| `ENV_VERGE_BASE_URL` | 管理服务地址(必填)| |
129 | 112 |
|
130 | | -## 目录结构 |
| 113 | +### 目录结构 |
131 | 114 |
|
132 | 115 | ``` |
133 | 116 | verge/ |
134 | | -├── cmd/ # 应用入口 |
135 | | -│ └── main.go |
136 | | -├── pkg/ # 核心功能包 |
137 | | -│ ├── reporter/ # 数据上报模块 |
138 | | -│ ├── rpc/ # RPC处理模块 |
139 | | -│ └── sse/ # SSE通信模块 |
140 | | -├── res/ # 资源文件 |
141 | | -│ └── library/ |
142 | | - ├── model/ # 物模型定义 |
143 | | - └── protocol/ # 协议脚本 |
144 | | -├── Makefile # 构建脚本 |
145 | | -├── deploy.sh # 部署脚本 |
146 | | -├── export.go # 插件导出入口 |
147 | | -├── model.go # 数据模型定义 |
148 | | -└── README.md # 项目文档 |
| 117 | +├── cmd/ # 应用入口 |
| 118 | +├── pkg/ # 核心模块(SSE/RPC/Reporter) |
| 119 | +├── res/ # 资源文件(驱动/模型/协议) |
| 120 | +├── platform/ # 平台启动脚本 |
| 121 | +├── Dockerfile |
| 122 | +└── docker-compose.yml |
149 | 123 | ``` |
150 | 124 |
|
151 | | -## API接口 |
152 | | - |
153 | | -### 登录接口 |
154 | | -- URL: `/api/node/{serial_no}/login` |
155 | | -- 方法: POST |
156 | | -- 用途: 获取访问令牌 |
157 | | - |
158 | | -### SSE接口 |
159 | | -- URL: `/api/node/sse/{token}` |
160 | | -- 方法: GET |
161 | | -- 用途: 建立服务器发送事件连接,接收云端指令 |
162 | | - |
163 | | -## 安全性 |
| 125 | +--- |
164 | 126 |
|
165 | | -- 使用序列号和令牌进行身份验证 |
166 | | -- 模型文件通过MD5哈希验证完整性 |
167 | | -- 支持令牌自动刷新机制 |
| 127 | +## 📡 架构说明 |
168 | 128 |
|
169 | | -## 调试与日志 |
| 129 | +### 数据流 |
170 | 130 |
|
171 | | -系统使用zap日志库记录运行信息,主要包括: |
172 | | -- 网络连接状态 |
173 | | -- RPC调用详情 |
174 | | -- 设备操作记录 |
175 | | -- 错误和警告信息 |
| 131 | +1. **启动** → 登录获取 token → 建立 SSE 连接 |
| 132 | +2. **上报** → 设备列表、产品模型、驱动信息 |
| 133 | +3. **接收** → 云端指令 → 执行设备控制/配置更新 |
| 134 | +4. **采集** → 设备数据 → 协议解析 → 定时上报 |
0 commit comments