企业官网建设流程全解析

• 后端
• 前端
• 物联网
• 工业制造
• 数据可视化
• 时序数据库

FUXA 是一款基于 Web 的工业过程可视化软件，用于快速构建与部署可扩展的 SCADA、HMI、Dashboard 和 IIoT 系统。本指南以官方文档 docs/index.md 为主线，结合仓库中的服务端源码与配置文件，系统讲解 FUXA 的软件模型、功能特性、全部安装方式、服务端配置要点，以及从"连接设备→配置 Tag→创建可视化视图→设置报警"的完整项目构建流程。读完本文，你将能够独立完成 FUXA 的部署，并掌握在编辑器中搭建一套实时数据可视化 HMI 页面的实战方法。

一、FUXA 是什么：核心定位与软件模型

FUXA（Fast Universal eXecution Architecture）是一个功能强大的Web 化软件平台，可用于快速构建和部署可扩展的 SCADA、HMI、Dashboard 或 IIoT 系统。借助 FUXA，你可以为机器设备创建具有个性化设计的现代化过程可视化界面，实现实时数据显示，并对自动化工业装置进行控制操作。

其软件模型非常简洁清晰：

• 服务端：基于Node.js 运行时（后端），负责设备通信、数据处理、报警、历史存储（DAQ）与 API 服务；
• 前端：你只需在 Web 浏览器中访问服务端地址，即可打开编辑器来创建你的 SCADA/HMI/Dashboard 应用；同时浏览器也作为客户端运行可视化页面。

这与传统桌面版组态软件有明显区别——工程设计与运行环境全部在浏览器中完成，天然支持跨平台。

FUXA 支持常用的工业通信标准，例如Siemens S7 协议和OPC UA（可连接第三方 OPC 服务器），并且支持的通信标准列表可以通过**开发额外的驱动（Driver）**进行扩展。这一点在服务端源码中有直接体现：设备驱动按协议类型存放在 server/runtime/devices 目录下（adsclient、bacnet、ethernetip、modbus、mqtt、opcua、s7 等），而 设备管理器 在创建设备时会动态加载对应驱动，若插件缺失会给出 "plugin is missing!" 的告警。

用户界面：两种视图

FUXA 由两个不同的视图组成：

前端的路由定义可在 client/src/app/app.routing.ts 中查看：home、editor、lab、device、alarms、scripts、recipes、reports、logs等页面均有对应的 Angular 组件，其中编辑器等管理页面通过AuthGuard保护（启用安全模式后需要登录）。

二、功能特性

免运行时授权

FUXA不需要任何运行时许可证（runtime licenses）。你可以任意数量、任意规模地构建 HMI 项目，而无需担心运行时环境的额外授权费用。这对于中小型自动化项目、系统集成商和教育科研场景非常友好。

支持的通信协议

FUXA 平台内置了与 Siemens PLC 和 OPC UA 数据源直接通信的连接器，并支持多种工业协议：

• OPC UA 客户端：连接 OPC UA 数据源（含第三方 OPC 服务器）；
• S7 协议：通过以太网与 Siemens CPU 200、300、400、1200 和 1500 通信；
• Modbus RTU/TCP、BACnet IP、MQTT、Ethernet/IP（Allen Bradley）、WebAPI。

此外，从仓库内容看，README.md 中还列出了 ODBC、ADSclient、GPIO（Raspberry）、WebCam、MELSEC、Redis 等连接方式，服务端对应驱动位于 server/runtime/devices 各子目录。

跨平台全栈架构

系统设计为可在多种操作系统上运行，且安装简单：

• 后端：Node.js 开发；
• 前端：可扩展的 HTML5 Web 前端，使用 Web 技术（HTML5、CSS、JavaScript、Angular、SVG）开发，兼容所有现代浏览器。

该架构使得 FUXA 可以在 Linux、Windows、macOS、Docker、Raspberry Pi 等环境中运行，前后端职责分离清晰。

三、安装与运行

本节综合 安装与运行指南 与 README.md 中的全部安装途径，逐一说明。安装完成后，默认通过浏览器访问http://localhost:1881（或宿主机 IP:1881）。

方式一：Electron 预构建桌面应用

FUXA 提供 Electron 打包的桌面应用（需要登录 GitHub 后在 Actions 构建产物中下载对应系统的安装包）。这种方式适合不希望依赖浏览器、需要独立桌面窗口的部署场景。

方式二：Headless 便携二进制（嵌入式设备）

针对无 GUI 的嵌入式设备、服务器或自动化系统，FUXA 提供自包含的便携二进制文件，将整个应用（服务端 + 客户端）打包为单个可执行文件，无需安装任何外部依赖。平台对应的文件名如下：

Linux/macOS 下的运行方式：

chmod +x fuxa-headless-linux-x64 ./fuxa-headless-linux-x64 # 浏览器访问 http://localhost:1881

Windows 下直接双击.exe文件即可。Headless 版本的关键特性：

• 自包含：无外部依赖或额外安装；
• 数据持久化：用户数据存储在宿主机的~/.fuxa-headless-data目录；
• 跨平台：支持 Windows、macOS、Linux（含 ARM 架构）；
• 完整工业协议：支持 Modbus、OPC-UA、MQTT、Siemens S7 等；
• Web 界面：通过任意浏览器访问完整的 FUXA 编辑器与仪表盘。

故障排查：确保 1881 端口未被占用且未被防火墙拦截；嵌入式设备需关注内存与 CPU 资源（FUXA 使用 Node.js 运行时）；日志位于~/.fuxa-headless-data/logs。

方式三：Docker Compose

仓库根目录提供了现成的 compose.yml（桥接网络模式）。官方文档中的 host 网络模式示例：

version: '3.5' services: fuxa: image: frangoteam/fuxa:latest network_mode: "host" volumes: - ./fuxa_appdata:/usr/src/app/FUXA/server/_appdata - ./fuxa_db:/usr/src/app/FUXA/server/_db - ./fuxa_logs:/usr/src/app/FUXA/server/_logs environment: - TZ=America/New_York restart: always

启动命令：

sudo docker compose up -d

说明：host 网络模式让容器与宿主机处于同一网络，便于直连 PLC/数据库，但仅适用于 Linux 系统；Windows 上需改用network_mode: "bridge"桥接模式。

方式四：Docker 单容器运行

docker pull frangoteam/fuxa:latest docker run -d -p 1881:1881 frangoteam/fuxa:latest

如需持久化应用数据（项目）、DAQ（Tag 历史）、日志与资源图片，可挂载以下数据卷：

docker run -d -p 1881:1881 \ -v fuxa_appdata:/usr/src/app/FUXA/server/_appdata \ -v fuxa_db:/usr/src/app/FUXA/server/_db \ -v fuxa_logs:/usr/src/app/FUXA/server/_logs \ -v fuxa_shapes:/usr/src/app/FUXA/client/assets/lib/svgeditor/shapes \ -v fuxa_images:/usr/src/app/FUXA/server/_images \ frangoteam/fuxa:latest

各卷对应服务端运行时目录（这些目录在 server/main.js 中由_appdata、_db、_logs、_images等配置派生）。

方式五：从源码构建自定义 Docker 镜像

仓库根目录的 Dockerfile 采用三段式构建（Angular 客户端构建 → 服务端及原生依赖构建 → 精简运行镜像），支持两个构建参数：

• NODE_SNAP（默认false）：是否安装 node-snap7（Siemens S7 通信）；
• INSTALL_ODBC（默认true）：是否安装 ODBC 驱动（unixodbc、MySQL/MSSQL 驱动等）。

构建并运行自定义镜像：

wget https://raw.githubusercontent.com/frangoteam/FUXA/master/Dockerfile sudo docker build -t fuxa-custom-image-name --no-cache .

随后可在 compose 文件中使用image: fuxa-custom-image-name替换官方镜像。

方式六：NPM 全局安装

需要先安装Node.js 18（FUXA 1.2.7 起不再支持 Node.js 14 及更早版本）：

npm install -g --unsafe-perm @frangoteam/fuxa fuxa

Linux 提示：在 Linux 上使用 Node.js 18 安装可能遇到原生依赖编译问题；如果不需要通过 S7 与 Siemens PLC 通信，可以安装精简版@frangoteam/fuxa-min（不含 node-snap7）。

方式七：源码发行包安装

下载最新发行包并解压后：

cd ./server npm install npm start

同样地，若不需要 S7，可先从server/package.json中移除node-snap7；不需要外部数据库连接时还可移除odbc依赖，以减少 Linux/Raspberry Pi 上的编译负担。

服务端命令行参数

直接运行服务端可执行文件时，支持以下命令行选项（定义于 server/main.js）：

node main.js --port 3000 --userDir /path/to/fuxa-data

端口与用户目录也可以在_appdata/settings.js中配置（详见下文第四节）。服务端默认监听0.0.0.0:1881。

将 FUXA 设置为 HMI 终端（Linux）

如需用 Electron 替代浏览器作为 HMI 前端（更轻量、更适合触摸屏，可禁用右键菜单等），可参考以下流程（安装与运行指南 中给出，仅 Linux 环境验证过）：

1. 安装 Node.js 18 与 Electron；
2. 创建 Electron 项目，main.js指向已运行的 FUXA Web 服务器：

const { app, BrowserWindow } = require('electron'); function createWindow() { const win = new BrowserWindow({ fullscreen: true, // 全屏模式 webPreferences: { nodeIntegration: false, contextIsolation: true, } }); win.loadURL('http://localhost:1881'); // 指向 FUXA Web 服务器 } app.whenReady().then(createWindow);

3. 通过 systemd 用户服务实现开机自启（ExecStart=/opt/fuxa-electron-startup.sh指向启动脚本），并用systemctl enable --user fuxa-electron-startup.service启用。

反向代理部署（BASE_PATH）

当 FUXA 部署在反向代理之后时，可通过环境变量BASE_PATH指定带尾斜杠的自定义路径，例如要在foo.bar/fuxa下提供服务，设置BASE_PATH=/fuxa。服务端在 server/main.js 中会在内存中改写index.html的<base href>与静态资源引用路径，无需修改源码即可工作。

四、服务端配置详解

配置文件位置与加载机制

FUXA 的服务端配置位于server/_appdata/settings.js（Windows 下为server\_appdata\settings.js）。从 server/main.js 的启动逻辑可以看到：首次启动时，若_appdata/settings.js不存在，服务端会把代码内置的默认配置 server/settings.default.js 复制过去；若已有配置文件但版本落后，会从默认配置深度合并缺失字段并给出告警。修改配置后必须重启服务端才能生效。

关键配置参数

以下参数均以 server/settings.default.js 为准：

认证与安全配置

在 server/settings.default.js 中，安全相关的参数（均为注释状态，按需启用）：

secureEnabled: true, // 启用/禁用安全认证 secretCode: '<strong-random-secret>', // 用于编码 Token 的密钥 tokenExpiresIn: '1h', // Token 过期时间，'1h'=1小时, 60=60秒, '1d'=1天 // enableRefreshCookieAuth: false, // 为 true 时使用 HttpOnly Cookie 刷新令牌流程 // refreshTokenExpiresIn: '7d' // 刷新令牌过期时间

启用安全模式后，默认用户admin的初始密码为123456，可在用户管理中修改。从 server/main.js 的源码可以看到：若启用secureEnabled却未设置secretCode，服务端会在内存中生成随机 JWT 密钥并告警提示应将其持久化到配置中，以保证重启后会话稳定。

五、从零构建你的第一个 HMI 项目

本节以 快速入门教程 为主线，目标是演示 FUXA 最常用功能的完整流程：连接设备 → 数据推送 → 构建实时 GUI SCADA/HMI/Dashboard → 定义阈值并触发报警。

前置条件：FUXA 服务端已按上文第三节完成安装并运行，通过http://localhost:1881可访问；同时具备设备凭据（如 Modbus 从站地址、OPC UA 端点等）。

Step 1：连接设备并配置 Tag

在编辑器左侧菜单进入Connections（连接），即可添加设备（详见 设备与 Tags 配置指南）。

• OPC UA 设备：添加并连接 OPC UA 设备后，即可在其地址空间下浏览并订阅 Tag；只有设备处于已连接状态才能添加 Tag；
• Modbus 设备：需要先在Plugins（插件）中安装 Modbus 驱动，再进行连接配置；
• MQTT 设备：添加 MQTT 连接后配置主题（Topic）订阅，即可接收订阅主题发布的数据；
• WebAPI 设备：添加 WebAPI 连接后，可把 HTTP JSON 响应中的字段映射为 Tag。

从服务端源码看，设备一旦配置为启用状态，设备管理器 会在服务启动时加载并启动所有活动设备，设备内部通过bindSaveDaqValue把实时值写入 DAQ 存储，同时通过bindGetProperty供报警、脚本等模块查询 Tag 属性。

Tag Options：数据类型与 Scale 脚本

对于没有预定义数据类型的 Tag（例如 TIME 类型，其基础数据类型通常是 int64/uint64，单位为毫秒），可以在Tag Options（Tag 选项）中设置数据类型。

还可以使用Scale 脚本完成任意数据类型转换。例如，当数据源返回的 TIME 是高低位组成的数组时，可以编写一个脚本取出数组元素并作为数值返回；写操作时再返回真实的 Tag 值。需要注意两点：

• 脚本参数必须命名为value——系统会以此过滤并显示相关脚本供选择；
• 脚本中不要使用注释，因为注释不受支持。

脚本的读写转换机制与 FUXA 脚本引擎相关，脚本列表与权限配置可参考 scripts 模块 相关组件。

Step 2：创建可视化视图

Step 2.1 创建空白视图：进入编辑器，点击左上角"+"图标，选择"Canvas/SVG"新建视图（详见 创建 View 指南）。随后点击Property（属性），定义视图的尺寸与背景。视图属性配置组件为 view-property，编辑器主逻辑见 editor.component.ts。

Step 2.2 绑定控件：将控件（按钮、指示灯、数值、滑块、开关等）拖入视图并绑定到已配置的 Tag，实现实时数据显示与交互控制，参考 绑定控件指南。

Step 2.3 绑定形状：SVG 形状（管道、阀门、泵等）可与 Tag 绑定实现动态状态显示与动画，参考 绑定形状指南。

Step 2.4 绑定图表控件：将历史/实时数据以图表形式呈现，参考 图表控件指南。

Step 3：配置 UI 布局

为最终用户界面配置导航、页眉等布局，参考 UI 布局指南。

Step 4：配置报警（Alarms）

定义 Tag 的阈值条件并触发报警，报警发生后可在报警视图（/alarms）中确认，参考 报警配置指南。

Step 5：创建客户用户

在用户管理中创建客户账号，结合第四节中的认证配置，为最终用户提供受限的访问权限。

六、运行时架构纵深：设备管理与数据流

为了让读者对"设备 → 数据 → 可视化"的链路有源码级认识，这里补充设备管理器 server/runtime/devices/index.js 的核心设计：

• 设备生命周期：load()从项目配置读取全部设备，按enabled状态决定是否创建实例；start()/stop()/update()/removeDevice()分别对应启动、停止、更新与移除，其中 ModbusRTU 设备还会按串口地址分组共享通信资源（sharedDevices）；
• 插件缺失处理：当某设备类型对应的驱动插件未安装时，设备被记入failedDevices，连接状态上报为connect-failed，前端插件页面会显示相应告警；
• Tag 读写 API：getTagValue/setTagValue/getTagId/getDevice等函数供报警引擎与脚本引擎调用，getHistoricalTags从 DAQ 存储按时间区间查询历史数据；
• DAQ 绑定：在daqEnabled开启时，每个活动设备绑定 DAQ 节点，实时值自动写入历史存储（默认 SQLite，也支持 InfluxDB、QuestDB、TDengine 等，见 server/runtime/storage）。

配合前端的 Angular 路由（app.routing.ts），/home用于最终用户查看可视化页面，/editor用于工程设计与编辑，两者共享同一套服务端 API，这正是 FUXA"一个运行时、两种视图"架构的具体体现。

结语

FUXA 通过 Node.js 运行时与 Angular/HTML5/SVG 前端组合，将 SCADA/HMI 工程的编辑、运行与设备接入统一到了 Web 环境中。从本文可以看到：其免授权特性降低了 HMI 项目成本，内置的 OPC UA、S7、Modbus、MQTT 等多协议驱动覆盖了主流工业数据源，Docker、Headless 二进制、NPM 等多种部署方式适配了从云服务器到嵌入式设备的各类场景。接下来，建议你结合 官方文档目录 中列出的其余指南（Getting-Started.md、Settings.md 及各 HowTo 文档），在真实设备或仓库自带的 project.demo.fuxap 示例项目上动手实践，逐步掌握 FUXA 的完整工程能力。

• 后端
• 前端
• 物联网
• 工业制造
• 数据可视化
• 时序数据库