# sim-protocal

**Repository Path**: self-testing-oxchen/sim-protocal

## Basic Information

- **Project Name**: sim-protocal
- **Description**: 万能协议模拟器
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-23
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# sim-protocol

**多协议模拟器** —— 用真实协议接口模拟 MQTT broker、Modbus 从站、
HTTP/WebSocket 服务、MySQL 与 PostgreSQL 数据库，
让你在没有真实设备的情况下开发与验证客户端代码。

[![Go Version](https://img.shields.io/badge/Go-1.25.5+-00ADD8?logo=go)](https://go.dev/)
[![License](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey)]()

---

## 为什么用它

开发客户端时，真实设备往往不在手边 —— 或者太贵、太慢、太难造出异常场景。
sim-protocol 用**真实的协议实现**（不是自造的假接口）模拟这些系统：

- **客户端零改动** —— 用 `mosquitto_pub`、`pymodbus`、`curl` 等标准工具直连
- **切换成本最小** —— 从模拟器切到真实系统，**只改 host 与 port**
- **可造异常场景** —— 未定义地址、只读点、认证失败、端口占用，随时复现
- **绿色免安装** —— 单个可执行文件，删除目录即彻底卸载

---

## 支持的协议

| 协议 | 端口 | 说明 | 手验文档 |
|---|---|---|---|
| **MQTT** | 1883 | 完整 broker：QoS 0/1/2、保留消息、遗嘱、3.1.1 与 5.0、用户名密码认证；`topics[].payload` 支持 `{{点名}}` 模板使数据集 `points` 生效 | [MANUAL](protocols/mqtt/MANUAL.md) |
| **Modbus TCP** | 1502 | 从站模拟：功能码 01/02/03/04/05/06/15/16，Modicon 五位地址；每区默认开放 100 个地址，工具默认参数可直接读取 | [MANUAL](protocols/modbus/MANUAL.md) |
| **HTTP** | 8090 | REST 服务端：端点路径由数据集驱动，自定义方法/状态码/响应体模板，Bearer 认证与只读模式 | [MANUAL](protocols/http/MANUAL.md) |
| **WebSocket** | 8091 | 实时推送：推送组由数据集驱动，各组独立定时，Bearer 认证 | [MANUAL](protocols/ws/MANUAL.md) |
| **MySQL** | 13306 | SQL 服务端：数据集 `tables` 段建表，官方驱动直连执行 SELECT/DML/DDL/事务，原生错误码（1146/1045/1105/1062） | [MANUAL](protocols/mysql/MANUAL.md) |
| **PostgreSQL** | 15432 | SQL 服务端：用**真 PostgreSQL 二进制**（sidecar 子进程），SQL 执行与解析与真库**完全一致**，系统目录与函数由真库自带 | [MANUAL](protocols/postgres/MANUAL.md) |

> 每个协议都配**手验操作文档**，含真实客户端命令、预期现象、
> 保真度验证（错误场景）与切换到真实系统的对照说明。
>
> MySQL 与 PostgreSQL 是**数据库类协议**，数据来自数据集的 `tables` 段，
> 与 MQTT/WS 消费的 `points`/`topics` 段并存于同一份数据集。
>
> **PostgreSQL 需要一份 PG 二进制**（含 `bin/lib/share`），放在程序目录下的
> `runtimes/postgres/<版本>/`。获取与放置步骤见其 MANUAL §1。装了多个版本时
> 用实例配置的 `pgVersion` 选择；控制台的配置页会列出扫描到的可用版本。

### 运行观测与系统配置

- **本地 SQLite 存储** —— 实例日志、控制面事件与连接记录落库，
  可按实例/级别/时间范围/关键词检索；默认保留日志 7 天、事件与连接 30 天。
  数据库文件随程序目录（`data/sim-protocol.db`），删除即彻底卸载
- **日志双写** —— 同时写文件（`data/instances/<id>/logs/<id>.log`，权威记录）
  与 SQLite（可检索层）；数据库不可用时实例照常服务，日志页显示降级原因
- **系统配置页** —— 可热改 `logLevel`（对运行中实例立即生效）与两个保留天数；
  改 `controlPort`/`dataRoot` 会明确提示需重启
- **手验文档内嵌** —— 四份 MANUAL 随二进制分发，只有 exe 的环境也能在
  控制台里直接阅读

### 控制台

控制台是 **Vue 3 单页应用**，导航零整页刷新，共 8 个页面：

| 页面 | 内容 |
|---|---|
| **概览** | 实例统计（总数/运行中/已停止/错误）、最近事件实时流、快捷入口 |
| **实例列表** | 状态胶囊、协议、端口、连接串、连接数，启停/重启/删除 |
| **新建向导** | 协议卡片选择 → 依赖预检 → 配置表单 → 按协议预填可运行样例数据集 |
| **实例详情** | 五个标签页：概览 / 连接地址 / 数据模型 / 配置 / 日志 |
| **协议介绍** | 卡片网格、依赖标签、配置项说明、手验文档入口 |
| **手验文档** | 渲染内嵌的 MANUAL.md，自动生成目录 |
| **日志查询** | 跨实例检索历史日志与控制面事件，按实例/级别/时间/关键词过滤 |
| **系统配置** | 可热改项与需重启项分组，展示运行环境与数据库状态 |

**数据模型页**提供两种编辑方式：`points`/`topics`/`routes`/`pushes`/`tables`/
`redis`/`kafka` 七段全表格化（取值模式按模式显示对应参数、点的地址映射可增删；
`tables` 段的列类型是可编辑下拉，候选由协议自报；`redis` 段按键类型显示不同
内容输入框，`kafka` 段一行一个 topic），
另有原始 JSON 子视图可复制与粘贴（粘贴后手动"应用到表格"）。

前端**不需要 Node/npm**：Vue、Vue Router 与 marked 已手工 vendor 进
`web/static/`（来源与版本见 `web/static/VENDOR.md`），
`go build` 仍是唯一构建步骤，运行时零外部网络依赖。

> **大整数精度**：数据集的 `uint64`/`int64` 大整数（如
> `18446744073709551615`）在浏览器里不会被 `JSON.parse` 静默改值 ——
> 前端在 JSON 文本层做了保护，因此在数据模型页"打开就保存"不会损坏数据。

后续计划：SQL（MySQL/PostgreSQL）、Redis/Kafka、TCP/UDP 基座、
OPC UA/IEC 104、MongoDB/TDengine 等。见 [CHANGELOG](CHANGELOG.md)。

---

## 快速开始

### 1. 构建

```bash
git clone https://gitee.com/self-testing-oxchen/sim-protocal.git
cd sim-protocol
make build
```

需要 Go 1.25.5+。

`make build` 会把**运行所需的文件**（二进制、配置、许可证）一并生成到
`build/` 目录：

```
build/
├── sim-protocol.exe       可执行文件（约 10 MB）
├── sim-protocol.yaml      全局配置
├── README.md
├── LICENSE
└── NOTICE
```

> **为什么要单独一个目录**：程序按"可执行文件所在目录"解析配置与数据，
> 会在自身目录内生成 `data/`。从 `build/` 运行可让运行产物与源码完全隔离，
> 源码目录不会被 `data/` 干扰，也不会误把二进制提交进版本库。

没有 `make` 时手工等价：

```bash
mkdir -p build
go build -trimpath -o build/sim-protocol.exe .
cp sim-protocol.yaml README.md LICENSE NOTICE build/
```

> **不需要 C 工具链，也不需要 cgo**：所有依赖都是纯 Go。
> 因此**可以交叉编译**（`GOOS=linux GOARCH=amd64 make release`），
> 产物只依赖系统 DLL。

### 2. 运行

**务必进入 `build/` 目录再运行**，否则 `data/` 会生成在当前目录：

```bash
cd build

./sim-protocol.exe        # Windows
./sim-protocol            # Linux / macOS
```

或直接用 `make run`（自动构建并进入 `build/` 启动）。

```
控制台已启动 url=http://127.0.0.1:8080 dataRoot=.../build/data
```

### 3. 打开控制台

浏览器访问 **http://127.0.0.1:8080**

「协议介绍」→ 选一个协议 → 「新建实例」→ 填端口与数据集 → 创建 → 启动。

### 4. 用真实客户端连接

以 MQTT 为例（其他协议见各自的 MANUAL）：

```bash
# 订阅
mosquitto_sub -h 127.0.0.1 -p 1883 -t 'factory/line1/temp' -v

# 发布
mosquitto_pub -h 127.0.0.1 -p 1883 -t 'factory/line1/temp' -m '{"t":22.0}'
```

---

## 界面

控制台提供完整的可视化管理：

- **协议介绍页** —— 协议清单、依赖标注、配置说明、手验文档入口
- **新建向导** —— 表单由协议元数据自动生成，创建前自动校验端口与数据集
- **实例列表** —— 状态、端口、连接数、启停按钮、实时事件流
- **实例详情** —— 数据模型在线编辑、实时日志（SSE 推送）
- **系统配置** —— 运行环境、数据库状态与体积、可热改配置项
- **日志查询** —— 历史日志与事件检索（按实例/级别/时间/关键词过滤）

> 控制台**只绑定 `127.0.0.1`**，不对外暴露 —— 它能创建/删除/写入，不应出现在网络上。

操作细节见 [用户手册](docs/project-md/user-manual.md)。

---

## 数据模型

每个实例有一份与协议无关的 JSON 数据集：

```json
{
  "points": [
    {
      "name": "temperature",
      "type": "float32",
      "address": {
        "modbus": "40001",
        "http": "/api/devices/1/temperature"
      },
      "value": {"mode": "sine", "min": 20, "max": 30, "period": "60s"},
      "writable": true
    }
  ],
  "topics": [
    {"name": "factory/line1/temp", "payload": "{\"t\":21.5}", "interval": "5s"}
  ],
  "routes": [
    {"method": "GET", "path": "/api/devices/1",
     "body": "{\"code\":0,\"data\":{\"temp\":{{temperature}}}}"}
  ],
  "pushes": [
    {"path": "/ws/devices", "points": ["temperature"], "interval": "2s"}
  ]
}
```

`routes` 段驱动 HTTP 自定义路由（`{{点名}}` 渲染为该点当前值的 JSON 字面量），
`pushes` 段驱动 WebSocket 推送组（`points` 留空表示全部点）。

**同一份数据可同时被多个协议的实例消费** —— 换协议不用重做数据，只改 `address` 映射。

支持类型：`bool` / `uint16` / `int16` / `uint32` / `int32` / `uint64` / `int64` / `float32` / `float64` / `string`

取值模式：`static` / `sine` / `random` / `enum` / `increment`

详见 [数据架构文档](docs/project-md/data-architecture.md)。

---

## 设计原则

| 原则 | 含义 |
|---|---|
| **协议原生保真** | 对外只暴露协议原生接口，抽象只在内部。客户端用标准库直连，无需专属 SDK |
| **切换成本最小** | 从模拟器切到真实系统只改 host/port。地址表示法、功能码、错误码语义不变 |
| **目录即边界** | 所有数据落在程序目录内。不写注册表、不装系统服务。删目录 = 彻底卸载 |
| **不静默错误** | 未定义地址、只读写入、越界值必须返回协议原生错误，绝不返回零值 |
| **不考虑性能** | 正确性优先于吞吐。这是功能验证工具，不是压测工具 |

---

## 文档

| 文档 | 面向 | 内容 |
|---|---|---|
| [用户手册](docs/project-md/user-manual.md) | 使用者 | 控制台操作、数据模型、故障排查 |
| [部署手册](docs/project-md/deployment.md) | 运维 | 构建、交叉编译、部署、升级、卸载 |
| [架构文档](docs/project-md/architecture.md) | 开发者 | 分层、接缝、生命周期、扩展指引 |
| [数据架构文档](docs/project-md/data-architecture.md) | 开发者 | 数据模型、持久化、数据流 |
| [CODEBUDDY.md](CODEBUDDY.md) | 开发者（AI 协作） | 全局约束与按需加载路由 |
| [CHANGELOG.md](CHANGELOG.md) | 所有人 | 版本变更历史 |
| `protocols/<名>/MANUAL.md` | 使用者 | 该协议的手验操作步骤 |

---

## 开发

```bash
go test ./...           # 全量测试
go test -race ./...     # 竞态检测
go vet ./...            # 静态检查
gofmt -l .              # 格式检查（应无输出）

make build              # 构建到 build/（自包含运行目录）
make run                # 构建并启动
make release            # 交叉编译三平台到 dist/
make clean              # 清理 build/ 与 dist/
```

**源码目录保持干净**：`build/`、`dist/`、`data/` 均已在 `.gitignore` 中，
运行产物不会混进版本库。

### 新增一个协议

只需三步，**不用改任何前端代码**：

1. 新建 `protocols/<name>/`，实现 `core.Adapter` 接口
2. 在 `register.go` 的 `init()` 中 `core.Register(...)`
3. 在 `protocols/all.go` 加一行副作用导入

控制台的协议介绍页、新建向导、配置表单、依赖标注会全部自动生成。

**交付物要求**：`CODEBUDDY.md`（开发者视角）+ `MANUAL.md`（手验文档）+
原生客户端一致性测试（用真实官方客户端库，非自研桩）。

参考实现：`protocols/http/` 与 `protocols/ws/` 是最小完整示例。

---

## 项目结构

```
sim-protocol/
├── main.go                    程序装配
├── internal/
│   ├── core/                  值类型、Adapter 接口、Deps、注册表
│   ├── datasource/            数据源抽象 + StaticDataSource
│   ├── instance/              实例 CRUD、生命周期、磁盘持久化
│   ├── runner/                InProcess（Sidecar 预留）
│   ├── obs/                   事件总线、日志环形缓冲
│   ├── sqlengine/             内存表 + SQL 引擎（MySQL/PG 共用）
│   └── api/                   控制面 HTTP + 控制台
├── protocols/
│   ├── all.go                 协议注册入口
│   ├── mqtt/                  MQTT 适配器
│   ├── modbus/                Modbus TCP 适配器
│   ├── http/                  HTTP REST 适配器
│   ├── ws/                    WebSocket 推送适配器
│   ├── mysql/                 MySQL 适配器
│   └── postgres/              PostgreSQL 适配器（真二进制 sidecar + 多版本管理）
├── web/                       控制台模板与静态资源（embed）
└── docs/project-md/           项目文档
```

---

## 常见问题

**Q：能用于压力测试吗？**
不建议。设计目标是功能验证，明确不考虑性能。

**Q：控制台能远程访问吗？**
不能，只绑定 `127.0.0.1`。这是刻意设计。

**Q：数据会持久化吗？**
实例配置与数据集会。运行时状态（如 `increment` 计数）不持久化。

**Q：怎么卸载？**
删除程序目录即可。程序不写注册表、不装系统服务。

**Q：怎么切到真实设备？**
只改客户端里的 host 与 port。每个协议的 `MANUAL.md` 第 6 节有详细对照。

---

## 许可证

[GNU Affero General Public License v3.0](LICENSE) (AGPL-3.0)

这意味着：你可以自由使用、修改、分发本软件，但**如果你把它作为网络服务提供，
必须向使用者提供源代码**。

第三方依赖的许可证见 [NOTICE](NOTICE) 与
[THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md)。

---

## 贡献

欢迎提交 Issue 与 Pull Request。请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。