# ThingGateway

**Repository Path**: mes-system-lin/thing-gateway

## Basic Information

- **Project Name**: ThingGateway
- **Description**: ThingGateway 是一个基于 Go 语言开发的高性能、插件化物联网关。它原生支持 MQTT、Modbus TCP、CoAP 和 LWM2M 等多种协议，具备十万级设备并发接入能力，并提供高效的数据路由与协议转换功能。

项目采用三层插件化架构，协议、编解码与应用接口均可灵活扩展，便于二次开发。适用于工业物联网、智能设备监控、边缘计算等场景，帮助开发者快速构建稳定可靠的设备接入与数据汇聚层。
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-07
- **Last Updated**: 2026-01-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ThingGateway 物联网关

## 项目概述

ThingGateway 是一个基于 Go 语言开发的高性能物联网关程序，采用插件化架构设计，支持多种协议和数据格式的灵活扩展。

### 核心特性

- **协议支持**
  - MQTT 服务器（网关作为服务器，无需外部 broker）
    - 支持 10 万并发连接
    - 支持 20 万订阅
    - 消息吞吐量 40,000 次/秒
    - Topic Tree 路由算法，O(L) 复杂度
    - 支持 QoS 0/1/2，带重传机制（指数退避）
    - 支持遗嘱消息
    - 会话持久化（文件存储，支持恢复）
    - QoS 消息持久化（QoS 1/2 消息持久化到磁盘）
    - RFC 合规的 KeepAlive 机制（1.5x KeepAlive 间隔检查）
    - $SYS 系统主题发布（连接数、消息统计等）
    - 认证支持（可配置认证处理器）
    - 限流支持（Token Bucket 算法）
  - Modbus TCP 客户端（支持设备轮询）
    - 支持 3000 设备并发
    - 连接池管理，支持连接复用
    - 5000 协程并发处理
    - 点位采集频率 50,000 点/秒
    - 支持批量读写操作
    - 异常响应处理（检查功能码 >= 0x80，防止误读）
    - TCP 帧完整性保证（使用 MBAP Header Length 字段）
    - 明确的错误消息（异常码到错误消息映射）
  - CoAP 服务器和客户端（基于UDP）
    - 支持 10 万并发设备
    - 新建连接速率 500 连接/秒
    - 消息处理能力 20,000 消息/秒
    - 消息延迟小于 50ms
    - 支持资源发现（.well-known/core）
    - 支持观察者模式（Observe），带 ACK 跟踪和重传
    - Block-wise Transfer 支持（RFC 7959，支持大文件传输）
    - 前缀树路由，O(path_length)复杂度
    - 分片map优化，减少锁竞争
    - DTLS 框架（预留接口，Go 标准库不支持 DTLS）
  - LWM2M 服务器和客户端（基于CoAP）
    - 支持 10 万并发设备
    - 消息处理能力 6,000 消息/秒
    - 消息延迟小于 50ms
    - 支持标准对象：Security、Server、Device、Firmware Update、Location
    - 支持客户端注册、更新、注销
    - **完整的Bootstrap流程**：主动向设备推送配置（DELETE / 和 WRITE /0/...、/1/...）
    - 支持Read、Write、Execute、Create、Delete操作
    - 支持Observe和Notify机制（带ACK跟踪）
    - TLV编解码，符合OMA规范
    - **Mandatory Resources校验**：注册时验证设备是否包含必需资源
    - 分片map优化，减少锁竞争

- **数据编解码**
  - JSON 编解码
  - TLV 编解码
  - 预留扩展接口：XML 等

- **应用接口**
  - HTTP RESTful API
  - 支持连接数限制和超时控制
  - 预留扩展接口：HTTPS、WebSocket、SSE

- **架构特点**
  - 插件化设计，协议层、编解码层、应用层均可扩展
  - 高性能并发处理，支持大规模设备接入
  - 跨平台支持（Linux、Windows、macOS）
  - 使用 Go 标准库，无第三方依赖

## 系统要求

### 软件依赖

- **Go 版本**：1.21 或更高版本
- **操作系统**：Linux、Windows、macOS
- **网络**：TCP/IP 网络支持

### 硬件要求

- **推荐配置**：4 核 CPU，8GB 内存（满足性能要求）
- **最低配置**：1 核心，128MB RAM
- **存储**：至少 50MB 可用空间
- **网络**：支持 TCP/IP 连接

### 性能指标（4C8G 服务器，CPU 负荷 70%）

- **MQTT**
  - 最大连接数：10 万
  - 最大订阅数：20 万
  - 消息吞吐量：40,000 次/秒
  - 消息延迟：< 50ms

- **Modbus TCP**
  - 并发扫描节点数：3,000 个设备
  - 点位采集频率：50,000 点/秒
  - 并发任务数：5,000 个协程
  - 响应超时处理：< 1000ms

- **CoAP**
  - 设备连接数：10 万并发设备
  - 新建连接速率：500 连接/秒
  - 消息处理能力：20,000 消息/秒
  - 消息延迟：< 50ms

- **LWM2M**
  - 设备连接数：10 万并发设备
  - 消息处理能力：6,000 消息/秒
  - 消息延迟：< 50ms

### 开发环境（可选）

- **IDE**：GoLand（推荐）或 VS Code
- **编译工具**：Go 编译器（go build）

## 部署指南

### 1. 获取代码

```bash
git clone <repository-url>
cd ThingGateway
```

### 2. 编译程序

```bash
go build -o gateway cmd/gateway/main.go
```

编译成功后，会在当前目录生成可执行文件：
- Linux/macOS: `gateway`
- Windows: `gateway.exe`

### 3. 配置文件

配置文件位于 `conf/gateway.conf`，使用 INI 格式，支持分节配置。

#### 配置文件结构

```ini
[gateway]
name = ThingGateway
version = 1.0.0
mode = foreground

[mqtt]
enabled = true
host = 0.0.0.0
port = 1883
keepalive = 60
max_connections = 100000

[modbus]
enabled = true
timeout = 5
retry = 3
pool_size = 50

[http]
enabled = true
host = 0.0.0.0
port = 8080
max_connections = 10000

[modbus.device1]
name = Device1
host = 192.168.1.100
port = 502
slave_id = 1
poll_interval = 10
registers = 0-100

[coap]
enabled = true
host = 0.0.0.0
port = 5683
max_connections = 100000
timeout = 5
retry = 3

[lwm2m]
enabled = true
host = 0.0.0.0
port = 5684
max_connections = 100000
timeout = 5
retry = 3

[log]
level = info
file = logs/gateway.log
```

#### 配置说明

- **gateway**: 网关基本信息
  - `name`: 网关名称
  - `version`: 版本号
  - `mode`: 运行模式（foreground/background）

- **mqtt**: MQTT 服务器配置
  - `enabled`: 是否启用（true/false）
  - `host`: 监听地址（0.0.0.0 表示所有接口）
  - `port`: 监听端口（默认 1883）
  - `keepalive`: 保活时间（秒）
  - `max_connections`: 最大连接数（默认 100,000）

- **modbus**: Modbus TCP 客户端全局配置
  - `enabled`: 是否启用
  - `timeout`: 连接超时时间（秒）
  - `retry`: 重试次数
  - `pool_size`: 每个设备的连接池大小（默认 50）

- **http**: HTTP 应用服务器配置
  - `enabled`: 是否启用
  - `host`: 监听地址
  - `port`: 监听端口（默认 8080）
  - `max_connections`: 最大连接数（默认 10,000）

- **modbus.deviceX**: Modbus 设备配置（X 为设备名称）
  - `name`: 设备名称
  - `host`: 设备 IP 地址
  - `port`: 设备端口（默认 502）
  - `slave_id`: 从站 ID
  - `poll_interval`: 轮询间隔（秒）
  - `registers`: 寄存器范围（如 "0-100" 或 "0-50,100-200"）

- **coap**: CoAP 服务器配置
  - `enabled`: 是否启用（默认 true）
  - `host`: 监听地址（默认 0.0.0.0）
  - `port`: 监听端口（默认 5683）
  - `max_connections`: 最大连接数（默认 100,000）
  - `timeout`: 超时时间（秒，默认 5）
  - `retry`: 重试次数（默认 3）

- **lwm2m**: LWM2M 服务器配置
  - `enabled`: 是否启用（默认 true）
  - `host`: 监听地址（默认 0.0.0.0）
  - `port`: 监听端口（默认 5684）
  - `max_connections`: 最大连接数（默认 100,000）
  - `timeout`: 超时时间（秒，默认 5）
  - `retry`: 重试次数（默认 3）

- **log**: 日志配置
  - `level`: 日志级别（info/debug/warn/error）
  - `file`: 日志文件路径

### 4. 目录结构

确保以下目录存在：
- `conf/`: 配置文件目录
- `logs/`: 日志文件目录（程序会自动创建）

## 基本操作

### 启动程序

#### 前台运行

```bash
# Linux/macOS
./gateway -c conf/gateway.conf

# Windows
gateway.exe -c conf/gateway.conf

# 或使用 go run
go run cmd/gateway/main.go -c conf/gateway.conf
```

#### 后台运行

```bash
# Linux/macOS
./gateway -c conf/gateway.conf -d

# Windows
gateway.exe -c conf/gateway.conf -d

# 或使用 go run
go run cmd/gateway/main.go -c conf/gateway.conf -d
```

### 停止程序

- **前台运行**：按 `Ctrl+C` 发送中断信号
- **后台运行**：使用系统进程管理工具（如 `kill`、`taskkill`）终止进程

程序支持优雅关闭，会先停止所有服务再退出。

### 验证运行状态

#### 1. 检查进程

```bash
# Linux/macOS
ps aux | grep gateway

# Windows
tasklist | findstr gateway
```

#### 2. 检查端口监听

```bash
# Linux/macOS
netstat -an | grep 1883
netstat -an | grep 8080

# Windows
netstat -an | findstr 1883
netstat -an | findstr 8080
netstat -an | findstr 5683
```

#### 3. 测试 MQTT 服务

使用 MQTT 客户端工具连接：
- 地址：`localhost:1883`
- 协议：MQTT 3.1.1

#### 4. 测试 CoAP 服务

使用 CoAP 客户端工具连接：
- 地址：`localhost:5683`
- 协议：CoAP（UDP）

```bash
# 使用 coap-client 测试资源发现
coap-client -m get coap://localhost:5683/.well-known/core

# 使用 coap-client 测试GET请求
coap-client -m get coap://localhost:5683/resource/path
```

#### 5. 测试 LWM2M 服务

使用 LWM2M 客户端工具连接：
- 地址：`localhost:5684`
- 协议：LWM2M（基于CoAP/UDP）

```bash
# 使用 coap-client 测试LWM2M客户端注册
coap-client -m post coap://localhost:5684/rd?ep=test-device&lt=86400

# 使用 coap-client 测试LWM2M资源读取
coap-client -m get coap://localhost:5684/3/0
```

#### 6. 测试 HTTP API

```bash
# 查询设备列表
curl http://localhost:8080/api/devices

# 查询数据（最近100条）
curl http://localhost:8080/api/data?limit=100

# 发送命令
curl -X POST http://localhost:8080/api/command \
  -H "Content-Type: application/json" \
  -d '{"action":"test","params":{}}'
```

#### 7. 查看日志

```bash
# Linux/macOS
tail -f logs/gateway.log

# Windows
type logs\gateway.log
```

## 示例

### 完整操作流程示例

#### 场景：通过网关采集 Modbus 设备数据，并通过 MQTT 和 HTTP 接口提供访问

#### 步骤 1：配置设备

编辑 `conf/gateway.conf`，配置 Modbus 设备：

```ini
[modbus.device1]
name = TemperatureSensor
host = 192.168.1.100
port = 502
slave_id = 1
poll_interval = 5
registers = 0-10
```

#### 步骤 2：启动网关

```bash
./gateway -c conf/gateway.conf
```

启动成功后，会看到类似输出：
```
Gateway started successfully
```

#### 步骤 3：验证服务

**验证 MQTT 服务**：
```bash
# 使用 mosquitto_sub 订阅主题
mosquitto_sub -h localhost -p 1883 -t "device/TemperatureSensor/registers/0-10"
```

**验证 HTTP API**：
```bash
# 查询设备列表
curl http://localhost:8080/api/devices

# 返回示例
{
  "TemperatureSensor": {
    "protocol": "modbus",
    "codec": "json"
  }
}

# 查询采集的数据
curl http://localhost:8080/api/data?limit=10

# 返回示例
[
  {
    "protocol": "modbus",
    "codec": "json",
    "topic": "device/TemperatureSensor/registers/0-10",
    "payload": "[1234,5678,9012]",
    "clientID": "TemperatureSensor"
  }
]
```

#### 步骤 4：通过 MQTT 发布数据

使用 MQTT 客户端发布数据到网关：

```bash
# 使用 mosquitto_pub 发布消息
mosquitto_pub -h localhost -p 1883 -t "sensor/data" -m '{"temperature":25.5,"humidity":60}'
```

网关会接收消息并路由到订阅该主题的客户端。

#### 步骤 5：通过 HTTP API 发送命令

```bash
curl -X POST http://localhost:8080/api/command \
  -H "Content-Type: application/json" \
  -d '{
    "device": "TemperatureSensor",
    "action": "read",
    "registers": [0, 1, 2]
  }'
```

#### 步骤 6：停止网关

按 `Ctrl+C` 停止程序，网关会优雅关闭所有服务。

### GoLand 调试配置

1. 打开 GoLand，导入项目
2. 创建运行配置：
   - **运行类型**：Go Build
   - **运行种类**：Package
   - **包路径**：`ThingGateway/cmd/gateway`
   - **程序参数**：`-c conf/gateway.conf`
   - **工作目录**：`$PROJECT_DIR$`（项目根目录）
   - **输出目录**：`$PROJECT_DIR$/bin`（可选，避免使用 C 盘临时目录）
3. 点击运行或调试按钮

**注意**：如果遇到路径过长或权限问题，可以在运行配置中设置：
- **输出目录**：设置为项目目录下的 `bin/` 文件夹（如 `$PROJECT_DIR$/bin`）
- 或者在项目根目录创建 `bin/` 文件夹，GoLand 会自动使用

### 常见问题

**Q: 端口被占用怎么办？**
A: 修改配置文件中的端口号，或停止占用端口的程序。

**Q: Modbus 设备连接失败？**
A: 检查设备 IP 地址、端口、从站 ID 是否正确，确保网络连通。

**Q: 日志文件未生成？**
A: 检查 `logs/` 目录权限，确保程序有写入权限。

**Q: 后台运行后如何查看输出？**
A: 查看日志文件 `logs/gateway.log`，或使用系统日志工具。

## 技术架构

### 插件系统

程序采用三层插件架构：
- **协议层**：实现设备通信协议（MQTT、Modbus 等）
- **编解码层**：实现数据格式转换（JSON、TLV 等）
- **应用层**：实现应用接口（HTTP、WebSocket 等）

### 数据流

```
设备 -> 协议层 -> 编解码层 -> 应用层 -> 外部系统
```

### 性能优化

#### MQTT 路由优化
- **Topic Tree 算法**：使用前缀树（Trie）实现主题路由
- **复杂度**：从 O(N×M) 优化到 O(L)，L 为主题层级数（通常 3-5）
- **异步处理**：消息发布采用异步处理，支持高吞吐量
- **连接管理**：支持 10 万并发连接
- **持久化**：会话、订阅、QoS 消息持久化到磁盘，支持恢复
- **重传机制**：QoS > 0 消息使用指数退避策略重传
- **KeepAlive**：RFC 合规的 KeepAlive 检查（1.5x 间隔）
- **系统监控**：$SYS 主题发布服务器统计信息
- **安全**：支持认证和限流（Token Bucket）

#### Modbus 并发优化
- **连接池**：每个设备维护连接池，支持连接复用
- **并发处理**：每个寄存器范围使用独立协程处理
- **信号量控制**：使用信号量控制并发数，避免资源耗尽
- **自动重连**：连接断开时自动从池中获取新连接
- **异常处理**：检查异常响应（功能码 >= 0x80），防止误读
- **TCP 帧完整性**：使用 MBAP Header Length 字段确保完整读取响应帧
- **错误消息**：明确的异常码到错误消息映射

#### CoAP 性能优化
- **分片map**：客户端状态和消息ID使用分片map管理，减少锁竞争
- **对象池**：使用sync.Pool复用Message和Option结构体，减少GC压力
- **前缀树路由**：资源路由使用前缀树，O(path_length)复杂度
- **Goroutine池**：固定大小的goroutine池处理UDP数据包，避免goroutine爆炸
- **批量通知**：观察者通知批量发送，减少系统调用
- **原子操作**：消息ID生成使用原子操作，避免锁
- **Block-wise Transfer**：支持RFC 7959 Block-wise Transfer，处理大文件传输
- **Observe ACK跟踪**：跟踪Observe通知的ACK/RST，支持重传

#### LWM2M 性能优化
- **分片map**：对象注册表和客户端状态使用分片map管理，减少锁竞争
- **Worker Pool**：固定大小的goroutine池处理请求，避免goroutine爆炸
- **TLV编码优化**：预分配缓冲区，减少内存分配
- **对象复用**：使用sync.Pool复用Message对象，减少GC压力
- **路径解析缓存**：缓存常用路径解析结果，提高查找效率
- **Bootstrap完整实现**：主动向设备推送配置（DELETE / 和 WRITE），支持设备引导
- **Mandatory Resources校验**：注册时验证设备是否包含必需资源，确保合规性

### 扩展开发

要添加新的协议、编解码器或应用接口，只需：
1. 实现对应的接口（Protocol、Codec 或 App）
2. 在程序启动时注册到插件管理器
3. 配置文件中启用相应功能

## 许可证

[根据实际情况填写]

## 联系方式

[根据实际情况填写]