# modbus-forwarder

**Repository Path**: rufeng-2008/modbus-forwarder

## Basic Information

- **Project Name**: modbus-forwarder
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<h1 align="center">Modbus TCP 转发工具</h1>

<p align="center">工业级 Modbus TCP 纯报文透传平台，解决单个从站设备无法同时接受多个主站并发访问的问题</p>

<p align="center">
  <img src="https://img.shields.io/badge/Java-17%20LTS-blue?logo=openjdk" />
  <img src="https://img.shields.io/badge/Netty-4.1.x-brightgreen?logo=apache" />
  <img src="https://img.shields.io/badge/JavaFX-17.0.x-orange?logo=java" />
  <img src="https://img.shields.io/badge/Vue3-3.x-42b883?logo=vue.js" />
  <img src="https://img.shields.io/badge/Maven-3.9.x-red?logo=apachemaven" />
  <img src="https://img.shields.io/badge/SQLite-3.x-003b57?logo=sqlite" />
  <img src="https://img.shields.io/badge/Docker-支持-2496ed?logo=docker" />
  <img src="https://img.shields.io/badge/License-MIT-yellow" />
</p>

<p align="center">
  <a href="./docs/需求文档.md">需求文档</a> ·
  <a href="./docs/架构文档.md">架构文档</a> ·
  <a href="./docs/功能扩展设计文档.md">功能扩展</a>
</p>

---

## 界面预览

| 仪表盘 | 连接管理 |
|--------|---------|
| ![仪表盘](docs/images/仪表盘.png) | ![连接管理](docs/images/连接管理.png) |

| 报文日志 | 异常告警 |
|---------|---------|
| ![报文日志](docs/images/报文日志.png) | ![异常告警](docs/images/异常报警.png) |

| 系统设置-本地服务 | 系统设置-从站连接 |
|----------------|----------------|
| ![本地服务](docs/images/系统设置-本地服务.png) | ![从站连接](docs/images/系统设置-从站连接.png) |

| 系统设置-告警阈值 | 系统设置-日志设置 |
|----------------|----------------|
| ![告警阈值](docs/images/系统设置-告警阈值.png) | ![日志设置](docs/images/系统设置-日志设置.png) |

---

## 项目简介

工业现场中，单个 Modbus TCP 从站设备通常只支持一个主站连接，无法满足多个上位机、SCADA、PLC 同时接入的需求。本工具作为中间代理，对主站伪装为从站、对从站伪装为主站，实现纯字节流双向透传，不解析任何 Modbus 协议内容。

```
上位机 / SCADA（主站 1）
上位机 / SCADA（主站 2）  ──→  本工具（代理）  ──→  现场设备（从站）
上位机 / SCADA（主站 N）
```

## 功能特性

- **零报文解析**：纯字节流透传，不解析任何 Modbus 协议内容，不修改报文数据
- **多主站接入**：支持最多 50 个主站同时连接，FIFO 队列串行调度，避免通讯冲突
- **断线自动重连**：从站断线后自动按策略重连，重连过程实时显示在界面
- **双部署模式**：桌面 GUI 模式（本地单机）+ 无头服务器模式（Docker 部署）
- **远程客户端**：独立 JavaFX 客户端，通过网络连接到服务端进行远程管理
- **Web 管理界面**：浏览器访问，深色工控风格，支持多端访问
- **IP 白名单**：可选开启，限制允许接入的主站 IP
- **配置持久化**：所有配置通过界面操作，自动保存至 `config.toml`
- **告警记录**：异常事件持久化至 SQLite，支持历史查询

## 项目结构

```
modbus-forwarder/
├── modbus-forwarder-common/    公共模型、事件总线、配置类（被其他模块依赖）
├── modbus-forwarder-core/      核心转发引擎 + HTTP/WebSocket API（可独立 Docker 部署）
├── modbus-forwarder-ui/        JavaFX 公共 UI 组件库（desktop 和 client 共用）
├── modbus-forwarder-desktop/   桌面客户端，内嵌 core，适合本地单机使用
├── modbus-forwarder-client/    远程客户端，通过网络连接到 core 服务进行管理
├── modbus-forwarder-server/    服务端启动入口（无头模式，配合 client 使用）
├── modbus-forwarder-web/       Vue 3 Web 前端，构建产物内嵌到 core
├── config.toml                 运行时配置文件（首次启动自动生成）
└── docs/                       设计文档
```

## 技术栈

| 组件 | 版本 | 用途 |
|------|------|------|
| Java | 17 LTS | 开发语言 |
| Netty | 4.1.108 | 异步 TCP 网络框架 |
| Javalin | 6.3.0 | 内嵌 HTTP + WebSocket 服务 |
| JavaFX | 17.0.13 | 桌面 GUI |
| AtlantaFX | 2.0.0 | JavaFX 主题库 |
| Vue 3 | 3.x | Web 前端 |
| Naive UI | 2.x | Web UI 组件库 |
| SQLite + HikariCP | — | 本地数据持久化 |
| Jackson TOML | 2.19.x | 配置文件解析 |
| Maven | 3.9.x | 构建工具 |

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.9+
- Node.js 18+（仅构建 Web 前端时需要）

### 桌面模式（本地单机）

内嵌 core 服务，无需单独启动后端，开箱即用：

```bash
mvn install -pl modbus-forwarder-common,modbus-forwarder-core,modbus-forwarder-ui -am
mvn javafx:run -pl modbus-forwarder-desktop
```

### 服务器 + 远程客户端模式

**启动服务端：**

```bash
mvn package -pl modbus-forwarder-server -am
java -jar modbus-forwarder-server/target/modbus-forwarder-server-1.0.0.jar
```

**启动远程客户端：**

```bash
mvn javafx:run -pl modbus-forwarder-client
# 在连接对话框中输入服务端地址和端口
```

### Docker 部署

```bash
# 构建镜像
docker build -t modbus-forwarder modbus-forwarder-core/

# 运行容器
docker run -d \
  -p 8080:8080 \
  -p 5020:5020 \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/logs:/app/logs \
  --name modbus-forwarder \
  modbus-forwarder

# 访问 Web 管理界面
open http://localhost:8080
```

### Web 前端开发模式

```bash
cd modbus-forwarder-web
npm install
npm run dev
# 访问 http://localhost:3000
```

## 配置文件

首次运行自动生成 `config.toml`，也可手动编辑：

```toml
localPort = 5020           # 本工具监听端口（502 需要 root 权限）⚠ 需重启
slaveHost = "127.0.0.1"   # 从站 IP                              ⚠ 需重启
slavePort = 502            # 从站端口                             ⚠ 需重启
connectTimeoutMs = 5000    # 连接超时（ms）
requestTimeoutMs = 3000    # 请求超时（ms）                       热更新
reconnectIntervalMs = 5000 # 重连间隔（ms）                       热更新
maxReconnectTimes = -1     # 最大重连次数，-1 表示无限            热更新
maxMasterCount = 50        # 最大主站连接数                       热更新
whitelistEnabled = false   # 是否启用 IP 白名单                   热更新
whitelist = []             # 允许接入的主站 IP 列表               热更新
```

## REST API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/config` | 获取当前配置 |
| PUT | `/api/config` | 保存配置（热更新项立即生效） |
| POST | `/api/service/start` | 启动转发服务 |
| POST | `/api/service/stop` | 停止转发服务 |
| GET | `/api/status` | 查询运行状态和统计数据 |
| POST | `/api/slave/reconnect` | 手动触发从站重连 |
| DELETE | `/api/master/{channelId}` | 断开指定主站连接 |
| WS | `/ws/events` | 实时事件推送（WebSocket） |

## 监听低端口（502）

```bash
# Linux 一次性授权（推荐）
sudo setcap 'cap_net_bind_service=+ep' $(which java)
```

## 许可证

[Apache License 2.0](./LICENSE)