简介：Web组态设计器（FUXA）是一套面向工业控制场景的浏览器端应用开发源码，基于Vue.js与Node.js技术栈构建，旨在帮助工程师在无需深入编程的情况下完成设备建模、控制逻辑编排与界面的可视化组态，并支持远程配置、实时监控以及OPC UA、Modbus等多种工业协议对接。压缩包内集成了完整的前端工程与后台服务实现，共计1195个文件，包含四百余个SVG图标、二百七十余个TypeScript源文件、HTML页面、JavaScript脚本、CSS样式及字体资源，另有Docker部署配置和可直接导入体验的示例工程，整体大小约13.92MB，目录结构清晰规范。目前已有两千六百余人学习下载，适合前端开发人员、工业系统集成工程师以及需要快速搭建Web可视化平台的团队。通过分析源代码，可以系统掌握Vue组件化设计、Node.js接口服务、拖拽式绘图、数据绑定与实时刷新等关键技术，并复用现成控件和样式，显著降低自研工业组态系统的门槛与周期。示例工程和源码相互对照，能够帮助读者快速理解组态编辑器的工程组织方式。
1. Web组态设计器FUXA：把工业监控组态搬进浏览器的开源方案
先抛一个反直觉的结论：工业组态软件这个被老牌桌面产品统治了二十多年的赛道，如今用一套 Vue.js + Node.js 的开源方案也能撑起一条产线的实时监控。FUXA 做的就是这件事——它把组态编辑器、画面发布、实时数据展示全部跑在浏览器里，操作员打开网页就能画流程图、拖控件、绑数据源，不再需要每台机器装厚重的客户端。它适合三类人：做工厂数字化的集成商想省掉组态软件的授权费；设备厂商想给自家设备配一个免安装的本地监控界面；还有学习 Web 前端的人想看看工业场景里 Vue 和 Node.js 的真实配合方式。这篇笔记会把架构、跑通方式、核心代码和二次开发改动点一次讲透。
2. 技术选型拆解：Vue.js 与 Node.js 双端架构及目录精读
拿到的第一件事不是急着npm install，而是先把整体架构看清楚。FUXA 不是单页应用硬撑出来的玩具，它从设计初期就分成了 client 和 server 两个独立工程。前端跑在浏览器里负责画布编辑和实时渲染，后端跑在 Node.js 进程里负责协议接入和数据处理。这种拆分方式跟主流 SCADA 系统的 C/S 结构完全对标，只不过把客户端换成了浏览器，把上位机服务换成了 Node.js。
2.1 前端选型：Vue.js 与 SVG 的配合逻辑
FUXA 的前端没有走纯 Canvas 或原生 SVG 手写的路线，而是压在 Vue.js 的组件化体系上做。原因很实际：组态设计器本质上是个复杂可视化编辑器，画布上每个控件都有属性面板、数据绑定、事件配置三套交互，如果用原生 DOM 操作管理，代码量会迅速失控。用 Vue 之后，每个图元（阀门、仪表、管道、报警灯）都是一个独立组件，属性通过 props 传入，全局设备值通过 Vuex 管理，画布刷新只触发生影响的组件重新渲染。
SVG 在这里的角色是画布的底层载体。FUXA 选择 SVG 而不是 Canvas，是因为组态场景里图元数量通常不超过几百个，SVG 的 DOM 节点天然支持事件绑定，双击编辑、拖拽缩放、右键菜单这些交互实现成本远低于 Canvas 命中检测。几何变换直接靠 SVG 的 transform 属性，保存时把图元对象序列化成 JSON，还原时重新生成 SVG 节点即可。对于阀门开度、液位这类图形与数据绑定的场景，SVG 的矢量特性还能保证任意缩放不模糊。
2.2 后端职责：Node.js 的模块化边界
FUXA 的后端没有做成一个厚重的业务服务，而是按协议拆模块。Node.js 的事件驱动模型天然适配 MQTT、Modbus、OPC UA 这类长连接 + 回调的通信方式。后端核心职责有三块：维护设备连接状态、轮询或订阅采集数据、把最新值通过 WebSocket 推给前端。
值得留意的是数据存储层被设计成可插拔的。默认配置下跑 SQLite，文件型数据库零配置文件，下载下来就能跑；部署到生产环境再切 PostgreSQL。我本地跑的时候直接用默认配置，省掉了数据库初始化这一步，对新手非常友好。另一个设计点是设备状态管理：每个设备在后端有一个状态机，连接中、已断开、重试中，这个状态也会同步到前端，画面上的设备图标颜色就是读了这里的状态。
2.3 目录结构：从根目录快速定位关键代码
从仓库克隆下来的目录大致长这样，核心关注两个平级目录：
| 目录/文件 | 职责 | 关键入口 |
|---|---|---|
| server/src | Node.js 服务端，协议接入与数据处理 | app.js / server.ts |
| server/src/engine | 规则引擎与报警判定 | alarm.ts / condition.ts |
| server/src/protocols | MQTT / Modbus / OPC UA 协议驱动 | mqtt.ts / modbus.ts |
| client/src | Vue.js 前端，编辑器与运行时页面 | main.ts / designerApp.ts |
| client/src/components | 可拖拽控件库，按图元类型划分 | meter.vue / valve.vue / tank.vue |
| client/src/store | Vuex 状态管理，设备值和工程配置 | index.ts |
进入 server 入口文件，你会发现启动逻辑依次做了三件事：加载 config 目录下的环境配置、初始化数据库模型、按 config 里 enabled 字段遍历注册协议模块。这种按需加载的方式让新增协议变得干净，不需要改动启动逻辑，只要在 protocols 目录里加一个实现类再配置启用就可以了。
客户端入口相对标准，main.ts 负责创建 Vue 实例并挂载路由。设计器页面和运行时页面是两套独立路由，设计器读工程 JSON 渲染画布并绑控件，运行时就只读发布后的 JSON 做只读展示。两条路径共用同一套控件组件，只是设计器额外挂上了拖拽和属性面板，这个复用思路在二次开发时可以直接沿用。
3. 从零跑通：环境准备、启动命令与第一个监控页面
这章直接照做。跑通 FUXA 不需要先读懂全部源码，只要环境对、命令对，五分钟就能在浏览器里看到组态编辑器界面。
3.1 环境准备：Node.js 版本与依赖安装
FUXA 整个工程依赖 Node.js，推荐装 LTS 版本，v16 或 v18 都行。老项目对 Node 版本比较敏感，如果你用的是 v20 以上，后面 npm install 阶段可能遇到 node-gyp 编译兼容问题，遇到再处理。数据库默认走 SQLite，不需要额外装 MySQL 或 PostgreSQL，零配置启动。
依赖安装建议直接使用 npm，个别情况加--legacy-peer-deps：
git clone <仓库地址> FUXA cd FUXA npm install# 如果因 peerDependencies 冲突失败 npm install --legacy-peer-deps参数说明：--legacy-peer-deps绕过 peerDependencies 严格校验，适用于依赖树有版本冲突的旧工程。安装完成后检查 node_modules 目录是否存在，并确认npm ls --depth=0无大面积 error，再继续启动。
3.2 启动流程：server 与 client 的先后关系
FUXA 支持开发模式和部署模式两种跑法。部署模式先构建再启动：
npm run build:server npm run build:client npm start开发模式则一条命令同时拉起前后端：
npm run dev默认服务端口是 1881，启动后浏览器访问：
http://localhost:1881第一次启动建议留意控制台输出，正常会依次打印数据库初始化、协议注册、HTTP 服务 listening 三条日志。如果只看到提示缺少配置文件，说明路径下没有 .env 文件，复制项目根目录的环境模板文件改名即可，这是很多老工程通用的配置加载约定。
3.3 创建第一个工程：画布、控件与数据绑定
进入编辑器页面后，左侧是控件面板，中间是画布，右侧是属性面板。创建工程时输入项目名，选择宽高分辨率，这一步决定发布后画面的适配基准。随后从左侧拖动一个仪表盘或报警灯到画布上，选中控件，右侧属性面板会出现绑定项，要求输入数据标签（Tag 名称，即设备数据点的标识）。
常见做法是先不绑定具体值，直接把控件摆到画布上，等设备接入后再回来关联标签。FUXA 的绑定逻辑是：后端采集到的数据按标签名分发，前端组件通过全局 store 中的标签值表取值，只要标签名匹配，画面就会自动刷新。
3.4 接入第一个设备：MQTT 模拟数据源
没有真实 PLC 的情况下，可以用 MQTT 模拟设备。先在系统配置里新增设备，通信协议选 MQTT，填 Broker 地址和端口。公共测试 Broker 均可，本地开发更推荐用 EMQX 的 Docker 镜像起一个：
docker run -d --name emqx -p 1883:1883 -p 8083:8083 emqx/emqx:5.0其中1883是 MQTT 标准端口，8083是 WebSocket 端口，FUXA 如果配置走 WebSocket 方式连接 Broker 就用这个。设备添加完成后，在设备详情里配置数据映射规则，告诉 FUXA 哪个主题的数据对应哪个标签。用命令行模拟发送一条数据：
mosquitto_pub -h localhost -t factory/line1/temp -m '{"value": 86.5}'发送完成后回到编辑器画面，如果控件绑定了temp标签，你应该能在实时预览里看到数值变化。到这一步，FUXA 最基础的采集到展示链路已经打通，接下来进入核心代码层面看看这条链路背后到底怎么工作。
4. 核心模块拆解：从设备数据采集到画面刷新的完整链路
组态软件的核心价值不在界面皮肤，而在数据链路。这一章把 FUXA 里一条完整的数据流拆开看：设备产生数据、协议层接收、事件总线分发、WebSocket 推送到前端、Vue 组件响应更新。这条链路上的每个环节都值得细读，二次开发九成需求都是在这个链路上加逻辑。
4.1 MQTT 接入层：订阅与数据解析
MQTT 接入层在 server 端的 protocols 目录下。启动时根据设备配置创建 MQTT Client，连接成功后订阅设备配置的主题，收到消息后按映射规则解析成标签值：
// server/src/protocols/mqtt.js const mqtt = require('mqtt'); function startMqttDevice(deviceConfig, eventBus) { const client = mqtt.connect(deviceConfig.url, { username: deviceConfig.username || '', password: deviceConfig.password || '', clientId: `fuxa-${deviceConfig.id}-${process.pid}`, }); client.on('connect', () => { const topics = deviceConfig.mapping.map(m => m.topic); client.subscribe(topics, { qos: 1 }, err => { if (err) console.error('[MQTT] 订阅失败', err); else console.log('[MQTT] 已订阅:', topics.join(', ')); }); }); client.on('message', (topic, payload) => { // 按 topic 找到对应的映射规则 const rule = deviceConfig.mapping.find(m => m.topic === topic); if (!rule) return; const parsed = JSON.parse(payload.toString()); const value = parseValueByType(parsed[rule.key], rule.type); deviceConfig.mapping.forEach(m => { if (m.expression) { const result = evalExpression(m.expression, parsed); if (result !== undefined) { emitValue(m.tag, result); } } }); eventBus.emit('device:value', { deviceId: deviceConfig.id, tag: rule.tag, value, ts: Date.now(), }); }); return client; } function emitValue(tag, value) { eventBus.emit('tag:value', { tag, value, ts: Date.now() }); }这段代码有几个关键参数：deviceConfig.url是 MQTT Broker 的完整地址；mapping是设备下配置的主题到标签的映射数组，每项包含topic、key、type、tag四个字段；qos: 1表示至少投递一次，适用于大多数工控采集场景。解析时用parsed[rule.key]从 JSON payload 里取值，这意味着上游设备推荐发结构化数据而非裸字符串，纯字符串场景需要改解析逻辑。
4.2 事件总线与 WebSocket 推送
数据不能在协议层直接操作前端，FUXA 在中间加了一个事件总线层，相当于前后端之间的数据总线。协议层只管往总线上丢数据，推送层只管监听总线后转发，互相解耦：
// server/src/eventBus.js const EventEmitter = require('events'); class EventBus extends EventEmitter { constructor() { super(); this.setMaxListeners(100); } emitDeviceValue(deviceId, tag, value) { this.emit('device:value', { deviceId, tag, value, ts: Date.now() }); } emitAlarm(alarm) { this.emit('alarm:active', alarm); } } module.exports = new EventBus();WebSocket 推送层使用 socket.io 实现，服务端在项目级别创建房间，前端连接时带上 projectId，这样不同项目的画面之间数据不会串：
// server/src/ws/socket.js const { Server } = require('socket.io'); function initSocketServer(httpServer, eventBus) { const io = new Server(httpServer, { path: '/fuxa/ws', cors: { origin: '*' }, }); io.on('connection', socket => { const projectId = socket.handshake.query.projectId; socket.join(`project:${projectId}`); socket.on('disconnect', () => { socket.leave(`project:${projectId}`); }); }); eventBus.on('device:value', data => { io.to(`project:${data.projectId}`).emit('tag:update', data); }); return io; }这里的数据分发逻辑是：事件总线收到device:value事件后，根据数据里的 projectId 找到对应房间，只推送该项目的在线客户端。前端收到tag:update后更新 Vuex store 里的标签值表，这个 store 是所有图元组件共享的数据源，组件通过计算属性取store.state.tagValues[tag]，一旦值变化，依赖该标签的组件自动重渲染。这就是实时画面不闪烁的秘密。
4.3 报警模块：阈值判定与事件分发
报警是组态系统里最容易做成黑匣子的模块。FUXA 的方式是把报警规则独立成配置对象，每个标签可以配置高报、低报、回差值。回差的作用是防止数值在临界点抖动导致报警反复触发，这是工业报警设计里最容易忽略的细节：
// server/src/engine/alarm.js class AlarmEngine { constructor(eventBus) { this.rules = new Map(); this.status = new Map(); this.eventBus = eventBus; } registerRule(tagId, rule) { this.rules.set(tagId, rule); this.status.set(tagId, { triggered: false, level: null }); } evaluate(tagId, value) { const rule = this.rules.get(tagId); if (!rule) return; const state = this.status.get(tagId); const { high, low, hysteresis } = rule; if (value > high && !state.triggered) { state.triggered = true; state.level = 'high'; this.eventBus.emitAlarm({ tagId, value, level: 'high', ts: Date.now(), }); } else if (value < low && !state.triggered) { state.triggered = true; state.level = 'low'; this.eventBus.emitAlarm({ tagId, value, level: 'low', ts: Date.now(), }); } else if ( state.triggered && value > high + hysteresis && value < low - hysteresis ) { state.triggered = false; this.eventBus.emitAlarm({ tagId, value, level: 'recovery' }); } } }这段代码的hysteresis参数就是回差宽度。例如某温度标签高报阈值是 90 摄氏度，回差设为 2，那么温度升到 90 触发报警后，要降到 88 以下才会恢复，防止 89 和 91 之间来回跳动。recovery级别的事件用于前端做报警恢复提示。实际部署时需要考虑报警确认流程，常见做法是在 AlarmEngine 里维护一个待确认列表，前端点击确认按钮后调用接口把确认状态写入数据库。
5. 避坑指南：FUXA 二次开发中常见的 5 个坑
跑通只是开始，真正耗时的是改代码时踩坑。这些坑我基本都踩过一遍，写出来给你当参考，每条都是现象、原因、解决三个步骤。
5.1 npm install 报错：peerDependencies 冲突
现象：安装依赖时 npm 直接报 ERESOLVE unable to resolve dependency tree，整个安装流程中断。原因：老版本 Vue 2 工程与新版 npm 的严格依赖校验不兼容。解决：使用npm install --legacy-peer-deps绕过校验。这个参数不影响依赖版本锁定，只会跳过 peerDependencies 的自动安装，工程自带的 dependencies 完全不受影响。
5.2 数据采集正常但画布不刷新
现象：MQTT 终端能看到数据在推送，后端日志也打印了设备值，但前端画面里的控件数值一动不动。原因：八成是标签绑定不一致，后端 mapping 里配置的 tag 名是temp，前端控件属性里填的却是Temp，大小写都对不上。解决：在系统配置的标签管理页面统一查看所有标签名，把控件绑定的值复制过去，不要手打。这种问题没有报错，是最需要细心排查的。
5.3 公共 MQTT Broker 不稳定导致设备状态闪烁
现象：设备列表里连接状态在在线、离线之间来回跳，画面上的设备图标跟着闪。原因：公共 Broker 网络链路不稳定，MQTT 心跳包丢失后客户端自动断开重连。解决：本地开发建议直接用 Docker 起 EMQX，把 Broker 地址指向localhost；如果必须用远程 Broker，调大 keepalive 间隔和 reconnectPeriod 重连周期，减少无效重连。
5.4 修改自定义组件后画面不生效
现象：在 client 源码里加了新组件，日志也打出来了，刷新页面控制面板里还是没有。解决：前端构建产物没有重新生成。开发模式跑npm run dev会热更新，部署模式下必须重新执行npm run build:client。还有一个容易忽略的点，自定义组件注册是在一个独立的注册表文件里完成的，新组件必须手动注册，光写组件文件不够。
5.5 SQLite 数据库文件被锁导致启动失败
现象：服务启动时提示 database is locked，或者偶尔更新设备配置时报 SQLITE_ERROR。原因：SQLite 单文件数据库对并发写有限制，开发模式下前后端同时启动，可能存在多个进程同时访问数据库文件的场景。解决：关闭多余 Node 进程，保留一个服务实例；生产部署建议切换到 PostgreSQL。切换时修改数据库配置文件中的 driver 类型和连接字符串，FUXA 的模型层做了兼容，表结构会自动初始化。
6. 二次开发：从加一个控件到接入私有协议
FUXA 的扩展点非常明确，前端加控件，后端加协议。做明白这两件事，这套系统就能往任何工业场景里塞。
6.1 新增自定义 UI 控件
在client/src/components/extensions目录下新建一个 Vue 文件，例如带历史趋势的仪表盘组件：
<template> <div class="trend-meter" :data-tag="tag"> <div class="current-value">{{ currentValue }}</div> <svg :width="width" :height="height"> <path :d="trendPath" fill="none" stroke="#2a8bf2" stroke-width="2"/> </svg> </div> </template> <script> export default { name: 'trend-meter', props: { tag: { type: String, required: true }, width: { type: Number, default: 200 }, height: { type: Number, default: 80 }, }, computed: { currentValue() { return this.$store.state.tagValues[this.tag] ?? '--'; }, }, data() { return { history: [], alreadyBound: false, }; }, watch: { currentValue(val) { if (val !== '--') this.history.push(val); if (this.history.length > 50) this.history.shift(); }, }, }; </script>组件写好之后，到编辑器控件注册表里登记，控件面板才会出现。注册表通常在client/src/designer/controlRegistry.js，核心配置是指定组件名、缩略图以及默认尺寸。完成后重新构建前端，新控件就能像原生控件一样拖拽到画布上。
6.2 接入私有协议
后端扩展协议几乎不需要改动现有逻辑。在server/src/protocols目录新建驱动文件，实现startCollector(config, eventBus)接口，然后在设备配置里新增协议类型并注册到启动列表。以 UDP 为例，采集器内部实现了解析逻辑：
// server/src/protocols/udp.js const dgram = require('dgram'); function startUdpCollector(deviceConfig, eventBus) { const socket = dgram.createSocket('udp4'); socket.bind(deviceConfig.port, deviceConfig.host); socket.on('message', (msg, rinfo) => { // 按私有协议解析字节：前2字节tagId，后4字节float大端 const tagId = msg.readUInt16BE(0); const value = msg.readFloatBE(2); if (rinfo.address === deviceConfig.peerAddress) { eventBus.emitDeviceValue(deviceConfig.id, deviceConfig.tags[tagId], value); } }); return { close: () => { try { socket.close(); } catch (e) { /* noop */ } }, }; }代码里的eventBus.emitDeviceValue是上一章事件总线的封装，协议层只需要负责拿到数据并丢进总线。做完协议驱动后，在系统配置里新增设备时选择该协议类型，填入端口号、对端地址和标签映射表即可。
6.3 如何验证扩展成果
验证自定义控件和协议驱动，最有效的办法是同时打开浏览器 Developer Tools 和 IDE 调试终端。数据链路侧，在后端打印事件总线日志，确认数据从协议层进入；前端侧，打印控件计算属性的取值变化，确认 store 更新被组件捕获。两端日志同时能看到值，就说明链路是通的。我后来每次给 FUXA 加完新模块，都强制走一遍完整的数据链路验证——不是构建成功就完事，而是从数据源模拟开始，到画布值变化结束，全程打日志。这习惯帮我挡住了很多自以为改好了实际却没走的弯路。希望这次笔记能帮你少踩几个坑，顺利跑起你的第一个组态项目。
本文还有配套的精品资源，点击获取
