Skip to content

Commit 02da77f

Browse files
committed
docs(readme): 更新项目文档以反映标准化边缘计算网关定位
- 将项目标题从"IoT边缘计算网关"更新为"标准化边缘计算网关解决方案" - 添加项目徽章包括CI状态、Docker构建状态、Go版本和许可证信息 - 重写设计哲学部分,强调传统网关困境与Verge解决方案的对比 - 更新架构图,清晰展示应用层、边缘层和物理设备的分层架构 - 优化快速开始部分,区分生产推荐的二进制部署和开发场景的Docker部署 - 简化配置说明和目录结构描述 - 移除过时的技术细节如具体的RPC指令集和API接口说明 - 重新组织核心特性和架构说明内容
1 parent a9c2e85 commit 02da77f

1 file changed

Lines changed: 91 additions & 132 deletions

File tree

README.md

Lines changed: 91 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -1,175 +1,134 @@
1-
# Verge - IoT边缘计算网关
1+
# Verge - 标准化边缘计算网关解决方案
22

3-
Verge是一个基于[driver-box](https://github.com/ibuilding-x/driver-box)框架的IoT边缘计算网关项目,用于连接物理设备与云端服务,实现设备数据采集、控制命令转发、以及双向通信等功能。
3+
[![CI](https://github.com/smartboot/verge/actions/workflows/ci.yml/badge.svg)](https://github.com/smartboot/verge/actions/workflows/ci.yml)
4+
[![Docker](https://github.com/smartboot/verge/actions/workflows/docker.yml/badge.svg)](https://github.com/smartboot/verge/actions/workflows/docker.yml)
5+
[![Go Version](https://img.shields.io/badge/Go-1.23+-00ADD8?logo=go)](https://go.dev)
6+
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
47

5-
## 功能特性
8+
> **Verge** 是一个轻量级、标准化的边缘计算网关解决方案。它将后台管理功能剥离为独立的云端/桌面服务,网关本身只专注于设备数据采集与治理,将硬件资源需求降至极致。
69
7-
- **双向通信**: 基于Server-Sent Events(SSE)实现云端到边缘的实时指令下发
8-
- **设备管理**: 支持动态添加、删除、更新设备信息
9-
- **数据同步**: 自动上报设备状态、设备影子数据到云端
10-
- **产品模型管理**: 支持物模型的导入和上报
11-
- **协议适配**: 支持多种物联网通信协议(如MQTT等)
12-
- **设备控制**: 接收云端指令对设备进行远程控制
13-
- **网络状态监控**: 实时监控网络连接状态并上报
10+
## 🎯 设计哲学
1411

15-
## 架构设计
12+
### 传统网关的困境
1613

17-
```
18-
云端服务 ←→ Verge网关 ←→ 物理设备
19-
↑ ↑
20-
SSE通信 协议适配
21-
↓ ↓
22-
JSON-RPC指令 数据采集
23-
```
14+
传统边缘网关往往集成设备接入、场景联动、规则引擎、用户界面等全量功能。这种"大而全"的设计带来了显著问题:
2415

25-
### 核心模块
16+
- **资源浪费** — 大量功能仅在实施阶段使用,却需长期占用网关资源
17+
- **OTA 成本高** — 应用层频繁迭代导致升级包大、耗时长、风险高
18+
- **硬件门槛高** — 功能臃肿推高了对 CPU、内存的最低要求
2619

27-
- **SSE管理器** (pkg/sse/sse_manager.go): 负责与云端建立长连接,接收下行指令
28-
- **RPC处理器** (pkg/rpc/): 处理云端下发的各类指令
29-
- **数据上报器** (pkg/reporter/): 负责向云端上报设备数据
30-
- **导出器** (export.go): 整合各模块功能,作为driver-box插件入口
20+
### Verge 的答案:关注点分离
3121

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+
```
4339

44-
## 环境要求
40+
**核心价值:**
4541

46-
- Go 1.18+
47-
- [driver-box](https://github.com/ibuilding-x/driver-box) 框架
42+
| 维度 | 传统网关 | Verge 网关 |
43+
|------|----------|------------|
44+
| 资源占用 || 极致低 |
45+
| OTA 频率 || 几乎为零 |
46+
| 硬件要求 | 中高配置 | 任意硬件 |
47+
| 稳定性 | 受应用迭代影响 | 长期稳定 |
4848

49-
## 快速开始
49+
---
5050

51-
### 1. 环境配置
51+
## 🚀 快速开始
5252

53-
设置云端服务地址:
54-
```bash
55-
export ENV_VERGE_BASE_URL=http://your-cloud-server:8080
56-
```
53+
### 二进制部署(生产推荐)
5754

58-
### 2. 运行项目
55+
[Releases](https://github.com/smartboot/verge/releases) 下载对应平台压缩包:
5956

6057
```bash
61-
# 克隆项目
62-
git clone https://github.com/smartboot/verge.git
58+
# 下载并解压
59+
tar -xzf verge-linux-arm64-*.tar.gz
6360
cd verge
6461

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
7765
```
7866

79-
该脚本会生成适用于不同操作系统的压缩包,包括:
80-
- Linux (arm64, amd64, arm)
81-
- Windows (amd64, arm64)
82-
- macOS (amd64, arm64)
67+
**为什么推荐二进制部署?**
68+
- 网关程序稳定后几乎无需更新,一次性部署即可
69+
- 直接运行,无容器层开销
70+
- 更适合工业现场环境
8371

84-
## 使用说明
72+
### Docker 部署(家用/开发场景)
8573

86-
### 设备添加
87-
通过云端下发`devices.add`指令可动态添加设备,参数包含:
88-
- 插件类型
89-
- 模型标识符及哈希值验证
90-
- 连接配置
91-
- 设备列表
74+
适用于家庭实验室、开发测试环境,或设备基于以太网通信的场景:
9275

93-
### 设备控制
94-
通过云端下发`device.control`指令控制设备,参数包含:
95-
- 设备ID
96-
- 点位映射(属性名-值对)
76+
```bash
77+
docker-compose up -d
78+
```
9779

98-
### 数据上报
99-
网关定期(默认每10秒)上报设备影子数据,包括设备状态和属性值。
80+
> **注意**:如果设备使用串口通信,需确保容器有相应权限访问串口设备。
10081
101-
## 配置说明
82+
访问 `http://localhost:18080` 查看管理界面。
10283

103-
### 环境变量
84+
### 源码运行(开发调试)
10485

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+
```
10792

108-
### 资源目录结构
93+
---
10994

110-
```
111-
res/
112-
├── library/
113-
├── model/ # 物模型定义文件
114-
└── protocol/ # 协议适配脚本
115-
```
95+
## 📦 核心特性
11696

117-
## 开发指南
97+
- **极致轻量** — 聚焦设备接入核心功能,资源占用最小化
98+
- **跨平台** — 支持 Linux/Windows/macOS,兼容 x86_64/ARM 架构
99+
- **多协议** — 内置 MQTT、Modbus 等工业协议,支持 Lua 自定义扩展
100+
- **云边协同** — SSE 实时通信 + JSON-RPC 标准接口
101+
- **容器化** — 提供 Docker 镜像和 compose 配置
118102

119-
### 添加新的RPC处理器
103+
---
120104

121-
1. 在pkg/rpc/目录下创建新的处理器文件
122-
2. 在handlers.go中注册处理器函数
123-
3. 实现相应的业务逻辑
105+
## 🔧 配置
124106

125-
### 添加资源文件
107+
### 环境变量
126108

127-
物模型文件应放置在res/library/model/目录下,协议脚本应放置在res/library/protocol/目录下。
128-
此外,驱动脚本应放置在res/library/driver/目录下,这些会在产品导入时自动生成。
109+
| 变量 | 说明 |
110+
|------|------|
111+
| `ENV_VERGE_BASE_URL` | 管理服务地址(必填)|
129112

130-
## 目录结构
113+
### 目录结构
131114

132115
```
133116
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
149123
```
150124

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+
---
164126

165-
- 使用序列号和令牌进行身份验证
166-
- 模型文件通过MD5哈希验证完整性
167-
- 支持令牌自动刷新机制
127+
## 📡 架构说明
168128

169-
## 调试与日志
129+
### 数据流
170130

171-
系统使用zap日志库记录运行信息,主要包括:
172-
- 网络连接状态
173-
- RPC调用详情
174-
- 设备操作记录
175-
- 错误和警告信息
131+
1. **启动** → 登录获取 token → 建立 SSE 连接
132+
2. **上报** → 设备列表、产品模型、驱动信息
133+
3. **接收** → 云端指令 → 执行设备控制/配置更新
134+
4. **采集** → 设备数据 → 协议解析 → 定时上报

0 commit comments

Comments
 (0)