# TinyGw

**Repository Path**: illusoryNone/tiny-gw

## Basic Information

- **Project Name**: TinyGw
- **Description**: TinyGW 是一款功能强大的物联网网关系统，专为工业设备数据采集与处理设计。支持多种工业协议，提供设备接入、数据采集、边缘计算、云端通信等功能，为物联网解决方案提供可靠的边缘层支持。
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 102
- **Forks**: 41
- **Created**: 2025-05-01
- **Last Updated**: 2026-09-28

## Categories & Tags

**Categories**: iot

**Tags**: Go语言, 物联网, 645, modbus, Lua

## README

# TinyGW v2 物联网边缘采集网关

[![Go Version](https://img.shields.io/badge/go-1.25+-blue.svg)](https://golang.org/)
[![Vue 3](https://img.shields.io/badge/vue-3.x-green.svg)](https://vuejs.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

TinyGW 是一款面向工业仪表数据采集的边缘网关：**不依赖任何云平台即可独立完成采集、管理、控制全流程**，平台对接是可选增强（插上即用、拔掉无感）。v2 在 v1 基础上整体重构：内置通用协议编解码器、多脚本引擎、点位表配置化、CAT1 离线指令队列、全量 Web 管理界面。

## 功能特性

### 设备接入
- **通用编解码器（零脚本）**：`dlt645-2007` / `dlt645-1997`（电能表）、`cjt188-2004`（水/气/热表）、`modbus-rtu`——点位表配置即接入，厂家微调（DI、小数位、字节序、功能码、±0x33）改配置不改代码
- **脚本插件协议**：CJ/T188 变体、Q/GDW 1376.1、尚永/619 规约等 14+ 现成插件，Web 上传 zip 即装即用，云端亦可远程下发（自动热加载）
- **多链路**：TCP 客户端/服务端（设备拨入）、串口、MQTT、4G CAT1；通道层支持共享 MQTT 连接 / TCP 监听复用
- **通道级纯转发模式（transparent forward）**：DTU/CAT1 透传场景免解析——通道直接透传原始报文，按空闲间隔切帧原样转发云端（raw 信封经 `raw_topic` 发布，nodeKey=通道名），下行经 `RawSend` 命令写回连接（TCP 按 IP、MQTT 按来源 clientId）；同 IP 拨入可配顶替/共存策略（多设备同 NAT 出口选共存），支持 stdout 逐帧报文打印开关现场观察数据流

### 三引擎脚本系统（同一插件契约）
- **Lua**（gopher-lua 内嵌，v1 插件兼容）、**QuickJS**（WASM 沙箱，零外部依赖）、**Node.js**（可选）
- 插件函数契约：`GenerateGetRealVariables`（组帧，支持 64 步连续采集）/ `AnalysisRx`（解析）/ `DeviceCustomCmd`（控制指令）/ `GetSupportedCommands`（指令声明，可带参数）

### 采集与数据
- 周期轮询 + 多步连续采集（如先读电能再读电压）；设备/点位**两级倍率**、**初始值底数**、`_used` 用量累计
- 采集值内存快照（秒级）+ 节流落库，管理界面实时可见；断网本地缓存
- 设备级控制密码，执行指令自动注入（645 拉合闸等免手填）

### 指令与控制
- **内置控制指令**：CJ188 开/关阀、DLT645-2007 跳闸/合闸（自动时间标签+密码域）、Modbus 写线圈/写寄存器
- **CAT1 离线指令队列**：设备不在线时指令自动入队（文件缓存持久化，重启不丢，24h TTL，重试 3 次），设备上线自动补发
- 指令参数表单化（按声明渲染输入，自动拼 JSON），也保留原始 JSON 高级模式；不支持的指令立即明确报错

### 云端协同（可选）
- 上报端点数据库化：HTTP / MQTT 多端点并发推送，CRUD 热生效
- MQTT 下行 RPC：网关/通道/仪表三级命令（配置统一下发、实时抄读、驱动发布 `SetInstrumentDriver`、固件升级 `Upgrade`）
- 网关在线状态与固件版本自动上报；**不配置任何端点时全部静默，本地功能零影响**

### 本地管理（单二进制嵌入 Web）
- 开箱即用：空库首次启动自动建表 + 初始化 `admin / 123456`
- 设备类型编辑器：点位表主从编辑 + 属性预设库（选 `dev_consumption` 自动带 DI `00010000`）；指令页签 + 常用指令预设
- 采集器/通道/设备/任务全 CRUD，任务改完**立即生效**（免重启）；RPC 控制台 + 原始报文调试
- 驱动下拉数据化（`GET /admin/api/drivers`），手滑输错驱动名创建时即拦截

## 技术架构

| 层 | 技术 |
|----|------|
| 后端 | Go 1.25，[go-fast-framework v1.2.0](https://github.com/zhoudm1743/go-fast-framework) + gofast-gorm/gin 驱动插件 |
| 数据库 | SQLite（默认，开箱零依赖；可切 MySQL/PostgreSQL） |
| 脚本引擎 | gopher-lua / fastschema-qjs（WASM+wazero）/ Node.js 子进程 |
| 调度 | robfig/cron（任务运行期热加载） |
| 队列 | 框架 Cache（默认文件存储 `storage/cache`） |
| MQTT | Eclipse Paho |
| 前端 | Vue 3 + Vite + naive-ui，`go:embed` 嵌入后端单二进制 |

## 快速开始

### 方式一：Release 直跑（推荐）

```bash
# 从 Releases 下载 release 包（含前后端、默认配置、预置插件），解压后：
cd release
./tiny-gw            # Linux
# tiny-gw.exe        # Windows

# 浏览器打开
http://<网关IP>:3000
```

> **默认账号：`admin` / `123456`**（首次启动空库自动初始化；首次登录后请立即在右上角「修改密码」处更换，并修改 `config.yaml` 中的 `jwt.secret`）。

### 方式二：源码构建

```bash
git clone https://gitee.com/illusoryNone/tiny-gw.git
cd tiny-gw

# 一键构建（前端 pnpm 构建 → 嵌入后端 → 产出 linux/windows 双端二进制到 release/）
bash scripts/build.sh
# 或
task build
```

### 开发调试

```bash
# 后端（热重载可用 air）
cd backend && go run .

# 前端（代理到本地 3000 后端）
cd frontend && pnpm dev

# 测试
cd backend && go test ./...
```

## 配置说明

主配置文件 `config/config.yaml`（release 包内自带）：

| 配置段 | 说明 |
|--------|------|
| `server` | Web 端口（默认 3000）、运行模式 |
| `database` | 默认 sqlite `database/gofast.db`，可改 mysql/pgsql |
| `jwt` | 登录令牌密钥（生产环境务必修改） |
| `gateway.plugin` | 脚本引擎：`lua`（默认）/ `quickjs` / `nodejs`，插件目录 `plugin` |
| `gateway.collect` | 设备并发数、超时、重连、值刷库间隔（`value_flush_sec` 默认 30） |
| `gateway.cloud` | 上报开关 `event_report_enable`、网关序列号 `client_id`；**端点在 Web「上报端点」页配置（存库）** |
| `cache` | 默认文件缓存（指令队列持久化用），可切 redis |

## 目录结构

```
tiny-gw/
├── backend/            # Go 后端
│   ├── app/            # 控制器 / 模型 / 监听器 / 事件
│   ├── bootstrap/      # 启动装配、自动初始化
│   ├── config/         # 配置结构与默认值
│   ├── services/gateway/
│   │   ├── collect/    # 采集核心（Agent/Supervisor/驱动/指令队列/值快照）
│   │   ├── script/     # 脚本引擎 + 通用编解码器（codec_*.go）
│   │   ├── cloud/      # 上报 Reporter / 下行 RPC / 固件升级
│   │   ├── channel/    # 共享链路（MQTT/TCP server 复用）
│   │   └── schedule/   # 任务调度（热加载）
│   ├── plugin/         # 协议插件（Lua/JS，目录名=驱动名）
│   ├── web/manager/    # 前端构建产物（embed）
│   └── docs/           # 开发文档
├── frontend/           # Vue3 管理端
├── scripts/            # 构建脚本
├── release/            # 发布产物
└── Taskfile.yml
```

## 使用流程

1. **设备类型**：选内置协议（如 `dlt645-2007`）或上传插件 zip；点位从预设库选（自动带出 DI/单位/小数位），控制指令可加预设（开阀/设地址/设密码…）
2. **采集器**：TCP/串口/MQTT 链路参数，启停开关
3. **设备**：地址、型号、倍率/初始值/密码
4. **看数据**：设备列表实时值/展开点位；下发指令即时执行，离线自动排队
5. **接平台**（可选）：「上报端点」加 HTTP/MQTT 端点即开启上行 + 下行 RPC

## 插件开发

插件 = `plugin/<驱动名>/<驱动名>.lua|js`，契约（三引擎一致）：

```lua
function GenerateGetRealVariables(addr, step)  -- 组帧；返回 {Status, Variable}
  -- Status: "0"=最后一步（多步采集前序步传非"0"继续）
end
function AnalysisRx(addr, rxLen)               -- 从全局 rxBuf 解析；{Status="0" 成功, Variable={...}}
function DeviceCustomCmd(addr, cmdName, cmdParam, step)  -- 控制指令（可选）
function GetSupportedCommands()                -- 指令声明 [{name, desc, params}]（可选）
```

详见 [`docs/Plugin 插件编写规范.md`](docs/Plugin%20插件编写规范.md)（插件契约）与 [`backend/docs/point-table-codecs.md`](backend/docs/point-table-codecs.md)（点位表配置 + 厂家微调指南）、v1 插件示例 `backend/plugin/2018F214-33`。

## 文档

- [`docs/HTTP-API接口文档.md`](docs/HTTP-API接口文档.md) — 本地管理 API 全集（60 个接口、认证、错误码、数据模型）
- [`docs/MQTT-RPC 指令集.md`](docs/MQTT-RPC%20指令集.md) — 云端↔网关通信协议（25 条命令、遥测/状态格式）
- [`docs/Plugin 插件编写规范.md`](docs/Plugin%20插件编写规范.md) — 协议插件开发（契约、打包、测试、避坑）
- [`backend/docs/point-table-codecs.md`](backend/docs/point-table-codecs.md) — 通用编解码器点位表配置指南

## v1 → v2 迁移要点

- 插件契约兼容：`Status` 语义（组帧="0" 结束 / 解析="0" 成功）与 v1 一致，旧插件多数可直接使用（`Q3761-1376`、`DTS5886` 等已在 v2 对齐接口）
- 配置从单 yml 迁移到框架 `config.yaml` + 数据库（端点/任务/设备均存库、Web 可管）
- 响应约定：`code = 0` 成功，失败为 HTTP 状态码（如 401/422）

## 常见问题

**设备连不上？** 检查链路参数（IP/端口/波特率/表地址）；`Agent` 状态在日志中可见重连退避；停用采集器不会建立连接。
**CAT1 设备指令发不出去？** 设备离线时指令自动入队（响应 `queued: true`），上线后自动补发；队列在 `storage/cache` 持久化。
**想换 JS 写插件？** 配置 `gateway.plugin.engine: quickjs`（零依赖）或 `nodejs`（需目标机装 Node），契约与 Lua 相同。
**升级固件？** Web「固件升级」或云端 `Upgrade` 命令；替换后由外部守护进程拉起新进程，版本自动上报。

## 许可证

[MIT License](LICENSE)

## 联系方式

如有问题或建议，请提交 Issue 或邮件 804966813@qq.com。微信请备注 TinyGW。

**如果觉得对您有帮助，可以稍微打赏一点吗？** 😊

| <img src="public/image/20250710163746.jpg" alt="我的微信" style="width:35%;">  | <img src="public/image/185671e465f31563f73de5dd2e4083ec.jpg" alt="微信收款码" style="width:35%;">  |
| :-: | :-: |
| 微信交流（请备注 TinyGW） | 微信打赏 |