# ThingGateway

**Repository Path**: illblood/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**: 2
- **Created**: 2026-07-30
- **Last Updated**: 2026-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ThingGateway 物联网关

# 项目概述

ThingGateway 是基于 Go 的高性能物联网关程序，在同一进程中提供：

- **传输层服务**：MQTT Broker、CoAP Server、LWM2M Server（设备或客户端入站连接）
- **PLC 采集与控制**：Modbus TCP、西门子 S7、三菱 MC、欧姆龙 FINS（出站连接现场设备）
- **应用接口**：HTTP REST API（设备列表、数据查询、命令与 PLC 下行写）

配置文件为 `conf/gateway.conf`（INI 格式）。程序设计、架构约束与领域概念见程序设计文档、`AGENTS.md`、`CONCEPTS.md` 与 `docs/solutions/`。

# 系统要求

## 软件依赖

- **Go**：1.24.7 或更高（与 `go.mod` 一致）
- **操作系统**：Linux、Windows、macOS
- **网络**：TCP/UDP（MQTT、Modbus、HTTP 等）可用

## 硬件依赖

- **推荐**：4 核 CPU、8 GB 内存（满足生产级并发指标）
- **最低**：1 核 CPU、128 MB 内存（功能验证、小规模联调）
- **存储**：至少 50 MB 可用空间（二进制、配置、日志与 MQTT 持久化数据）
- **网络**：网关与 PLC/设备之间 IP 可达

# 软件构建
## 1. 编译
```bash
git clone <repository-url>
cd ThingGateway
go build -o gateway cmd/gateway/main.go    # Linux/macOS
# Windows: go build -o gateway.exe cmd/gateway/main.go
```
## 2. 单元测试
```bash
go test .\tests\...
```

# 部署指南

## 1. 目录准备

确保存在或可自动创建：

- `conf/` — 配置文件
- `logs/` — 日志输出（程序启动时自动创建）

## 2. 必要配置

编辑 `conf/gateway.conf`。以下为最小可运行示例（MQTT + HTTP + 一台 Modbus 设备）：

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

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

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

[plc.modbus.device1]
name = Device1
host = 192.168.1.100
port = 502
slave_id = 1
poll_interval = 10
points = 0-100:uint16

[http]
enabled = true
host = 0.0.0.0
port = 8080
write_token = change-me-in-production

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

### 配置要点

| 节 | 说明 |
|----|------|
| `[gateway]` | `mode`：`foreground`（前台）或 `background`（后台，配合 `-d`） |
| `[mqtt]` | 内置 MQTT Broker；`enabled=false` 可关闭 |
| `[plc.modbus]` / `[plc.s7comm]` / `[plc.mc]` / `[plc.fins]` | 协议全局参数：`timeout`、`retry`；Modbus 另有 `pool_size` |
| `[plc.<协议>.<设备节名>]` | 单台设备：`host`、`port`、`poll_interval`、`points`（**须含类型后缀**，如 `0-100:uint16`）；Modbus 需 `slave_id` |
| `[http]` | REST API；配置 PLC 设备时 **`write_token` 必填**（用于 `/api/write` 鉴权） |
| `[coap]` / `[lwm2m]` | 默认启用；不需要时可设 `enabled = false` |
| `[log]` | `level`：info / debug / warn / error；`file`：日志路径 |

CoAP 默认端口 `5683`，LWM2M 默认端口 `5684`。S7/MC/FINS 设备节格式与 Modbus 类似，端口与地址规则见 `CONCEPTS.md` 与 `docs/solutions/`。

# 基本操作

## 启动

**前台运行**（日志输出到控制台）：

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

**后台运行**：

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

成功启动后输出：`Gateway started successfully`。

## 停止

- **前台**：`Ctrl+C`
- **后台**：使用 `kill`（Linux/macOS）或 `taskkill`（Windows）终止进程

程序会优雅关闭：先停止 PLC 驱动与插件服务，再退出。

## 验证

**1. 进程与端口**

```bash
# Linux/macOS
ps aux | grep gateway
netstat -an | grep -E '1883|8080'

# Windows
tasklist | findstr gateway
netstat -an | findstr "1883 8080"
```

**2. HTTP API**

```bash
curl http://localhost:8080/api/devices
curl "http://localhost:8080/api/data?limit=10"
```

**3. MQTT**（需本机安装客户端工具）

```bash
mosquitto_sub -h localhost -p 1883 -t "device/Device1/#" -v
```

**4. PLC 下行写**（`write_token` 与配置一致）

```bash
curl -X POST http://localhost:8080/api/write \
  -H "Content-Type: application/json" \
  -H "X-Write-Token: change-me-in-production" \
  -d '{"protocol":"modbus","device":"Device1","points":[{"address":"0","type":"uint16","value":100}]}'
```

**5. 日志**

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

**6. 测试套件**（开发/回归）

```bash
go test ./...
```

# 示例

以下演示从配置、启动到采集验证、下行写、停止的完整流程。

## 场景

网关轮询一台 Modbus 温湿度采集设备，数据经 HTTP 查询，并向下行写一个保持寄存器。

## 步骤 1：配置

编辑 `conf/gateway.conf`：

```ini
[plc.modbus]
enabled = true

[plc.modbus.sensor1]
name = TemperatureSensor
host = 192.168.1.100
port = 502
slave_id = 1
poll_interval = 5
points = 0-10:uint16

[http]
enabled = true
port = 8080
write_token = my-write-secret

[mqtt]
enabled = true
port = 1883
```

确认 PLC 设备 `192.168.1.100:502` 网络可达。

## 步骤 2：编译并启动

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

等待控制台出现 `Gateway started successfully`。

## 步骤 3：验证采集

查询已注册设备：

```bash
curl http://localhost:8080/api/devices
```

查询最近采集数据（轮询成功后会有记录）：

```bash
curl "http://localhost:8080/api/data?limit=10"
```

可选：MQTT 订阅设备主题：

```bash
mosquitto_sub -h localhost -p 1883 -t "device/TemperatureSensor/#" -v
```

## 步骤 4：下行写寄存器

将保持寄存器 0 写入值 `100`：

```bash
curl -X POST http://localhost:8080/api/write \
  -H "Content-Type: application/json" \
  -H "X-Write-Token: my-write-secret" \
  -d '{
    "protocol": "modbus",
    "device": "TemperatureSensor",
    "points": [{"address": "0", "type": "uint16", "value": 100}]
  }'
```

`device` 可使用配置节内 `name`（`TemperatureSensor`）或节名（`sensor1`）。

## 步骤 5：停止

在前台运行终端按 `Ctrl+C`。日志中应出现 `Shutting down gateway...` 与 `Gateway stopped`。