★ FEATURED ARTICLE Fuxa 这个工具在工业可视化圈子里被讨论的频率越来越高但真正动手把它跑起来的人第一步往往就卡在安装和部署上。我自己第一次接触 Fuxa 的时候官方文档翻了三遍容器起了删、删了起折腾了大半天才把一套能用的环境稳定下来。这篇文章就把我踩过的坑和最终跑通的方案完整摊开讲一遍从它到底是个什么东西、为什么值得用到环境准备、两种主流部署路径的完整操作、参数怎么调、出问题怎么查全部按实操顺序写清楚。不管你是刚听说 Fuxa 想试水的自动化从业者还是已经在做 SCADA 替代方案选型的技术负责人或者只是想在自己机器上搭个可视化面板玩玩下面这些内容都能直接照着抄。1. Fuxa 到底是什么为什么值得单独部署一套1.1 一句话定位与核心能力边界Fuxa 是一个开源的 Web 端工业可视化SCADA/HMI平台跑在浏览器里用来做设备数据采集、实时画面组态、趋势曲线、报警管理和远程监控。你可以把它理解成一个轻量级的组态软件但它的形态和传统组态软件完全不同——传统组态是装在 Windows 工控机上的桌面程序Fuxa 是一个 Node.js 写的服务端加前端页面部署在服务器或者边缘盒子上任何一台能开浏览器的设备都能访问。它的核心能力可以拆成几块设备连接层支持 Modbus TCP/RTU、MQTT、OPC UA、S7 等常见工业协议能把 PLC、传感器、网关的数据拉进来画面组态层提供拖拽式的编辑器画管道、阀门、仪表、按钮绑定变量后就能实时刷新数据服务层负责历史数据存储、趋势查询和报警判断访问层就是浏览器PC、平板、手机都能看。这个组合意味着你不需要买商业组态授权也不需要给每台操作站装客户端一套服务端部署好整个车间的人开浏览器就能用。需要说清楚它的边界Fuxa 不是那种功能堆到天花板的商业 SCADA它在复杂脚本、冗余架构、大规模点位几万点以上场景下会吃力。但对于几百到几千点位的中小型监控项目、设备厂商自带的本地 HMI 替代、实验室数据看板这类需求它的性价比非常高。我见过不少做非标设备的朋友直接用 Fuxa 给客户做配套的上位机界面省掉了商业授权成本交付也轻便。1.2 为什么部署方式的选择比安装本身更关键很多人把安装 Fuxa理解成跑一条命令把它启动起来这个理解会给你后面埋雷。Fuxa 的部署方式直接决定了它的数据持久化行为、升级路径、多用户访问能力和故障恢复方式。我见过最常见的翻车场景是用临时容器跑起来画面组态做了两天容器一重启所有工程数据全没了——因为没做卷映射数据写在容器内部容器销毁即丢失。所以部署这件事的核心不是能不能启动而是启动之后数据放哪、配置怎么留、以后怎么升级、出问题怎么回滚。这也是为什么我在下面会把 Docker 部署和源码部署两条路径都讲透并且重点讲清楚数据目录、端口、环境变量这几个决定成败的参数。选错部署方式后面每一次改动都是在给自己挖坑选对了升级就是换个镜像标签的事。1.3 适合谁来读这篇内容如果你是刚接触工业可视化的开发者这篇会带你从零把环境跑通并且告诉你每个参数为什么这么设如果你是负责选型和落地的技术负责人里面关于部署架构、数据持久化、反向代理的讨论能帮你判断这套方案能不能进生产如果你是设备厂商的工程师想给设备配一个轻量上位机源码部署和开机自启那部分可以直接拿去用。基础要求不高——会用命令行、知道 Docker 是什么、能看懂 IP 和端口的概念就够了剩下的我在文中都会补。2. 部署前的环境准备与方案选型2.1 硬件与操作系统的实际门槛Fuxa 本身不重官方给的资源需求很宽松但能跑和跑得舒服是两回事。我按实际项目经验给一个参考区间场景CPU内存磁盘说明个人试用/学习2 核2 GB10 GB跑几十个点位、几个画面完全够小型项目几百点位4 核4 GB50 GB历史数据开始累积磁盘要留余量中型项目上千点位4 核以上8 GB100 GB 起建议历史库单独规划磁盘 IO 要跟上操作系统上LinuxUbuntu 22.04、Debian 12 这类主流发行版是最省心的选择Docker 生态成熟出问题资料多。Windows 也能跑Docker Desktop 或者直接装 Node.js 都行适合在工控机上做本地部署但要注意 Windows 下 Docker 的网络和卷映射行为和 Linux 有差异后面会提。树莓派这类 ARM 设备也能跑做边缘小看板很合适但要选对镜像架构。注意磁盘空间这一项最容易被低估。Fuxa 的历史数据如果开了长期存储增长是持续的我见过一个项目磁盘写满导致服务假死排查了半天才发现是日志和历史库把盘吃光了。部署时就把磁盘监控做上别等出事。2.2 Docker 部署与源码部署怎么选这是部署前最重要的一个决策两条路各有适用面Docker 部署的优势是环境隔离、依赖打包好、升级换镜像即可、跨机器迁移方便。缺点是数据持久化必须靠卷映射配置要通过环境变量或挂载文件传入对不熟悉容器的人有一层学习成本。适合绝大多数生产和小型项目场景也是我推荐的首选。源码部署直接装 Node.js 跑的优势是改代码方便、调试直观、能深度定制适合需要二次开发或者研究内部实现的场景。缺点是依赖管理麻烦Node 版本、npm 包、系统库都可能出问题升级要手动拉代码重装依赖。我的建议很直接除非你要改 Fuxa 的源码否则一律用 Docker。源码部署省下的那点直观感在依赖冲突和升级维护上会加倍还回去。下面两条路径我都会完整写但主线是 Docker。2.3 网络与端口的规划Fuxa 默认监听一个 HTTP 端口社区常见配置是 1881具体以你使用的镜像版本为准部署前先确认这个端口在你的环境里没被占用。规划时考虑三件事服务端口给浏览器访问用设备通信端口如果 Fuxa 要主动连 PLC 或网关要保证它能出站访问对应设备的 IP 和端口反向代理端口如果前面要挂 Nginx 做 HTTPS 和域名访问那 Fuxa 本身可以只监听本地回环。一个常见的坑是防火墙只开了服务端口忘了设备通信方向。Fuxa 连不上 PLC 的时候先别怀疑配置先在服务器上用telnet 设备IP 端口或者nc -zv 设备IP 端口测一下通不通这一步能省掉大量无效排查。3. Docker 方式完整部署实操3.1 安装 Docker 环境以 Ubuntu 为例用官方脚本安装最省事# 更新包索引 sudo apt-get update # 安装基础依赖 sudo apt-get install -y ca-certificates curl gnupg # 添加 Docker 官方 GPG 密钥 sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \ sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg # 添加软件源 echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] \ https://download.docker.com/linux/ubuntu $(. /etc/os-release echo $VERSION_CODENAME) stable | \ sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装 Docker 引擎 sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin装完验证一下docker --version docker compose version两个命令都能输出版本号就说明环境 OK。如果提示权限不足把当前用户加进 docker 组sudo usermod -aG docker $USER然后重新登录一次会话生效。这一步很多人漏掉导致后面每条 docker 命令都要加 sudo很别扭。3.2 拉取镜像与目录规划先把数据目录规划好这是整个部署里最关键的一步。我习惯在/opt/fuxa下建结构sudo mkdir -p /opt/fuxa/data sudo mkdir -p /opt/fuxa/logs sudo chown -R $USER:$USER /opt/fuxadata目录用来挂载 Fuxa 的工程数据和历史库logs放日志。为什么要单独建目录而不是让容器自己管因为容器是无状态的删了重建是常态数据必须落在宿主机上才能活下来。这个目录以后就是你的资产目录备份它等于备份了整个工程。拉取镜像docker pull frangoteam/fuxa:latest镜像名和标签以你实际使用的版本为准latest适合试用生产环境建议锁定具体版本号避免某次拉取到新版本引入不兼容变更。我吃过这个亏——某次latest更新后前端行为变了排查半天才发现是镜像悄悄升级了。生产环境请用固定 tag。3.3 用 docker compose 编排服务比起一长串docker run我更推荐用 compose 文件管理配置可读、可版本控制、改参数方便。在/opt/fuxa下建docker-compose.ymlservices: fuxa: image: frangoteam/fuxa:latest container_name: fuxa restart: unless-stopped ports: - 1881:1881 volumes: - ./data:/usr/src/app/Fuxa/server/_appdata - ./logs:/usr/src/app/Fuxa/server/_logs environment: - TZAsia/Shanghai logging: driver: json-file options: max-size: 10m max-file: 3几个参数逐个解释因为每一个都有实际作用restart: unless-stopped服务器重启或容器异常退出时自动拉起生产环境必加。没有它一次意外断电就得人工上去重启。ports的映射格式是宿主机端口:容器端口左边可以改成你想要的端口右边必须和容器内监听端口一致改错了就访问不到。volumes的左边是宿主机路径右边是容器内路径。容器内数据路径必须和镜像实际使用的路径一致不同版本镜像的路径可能有差异部署前用docker inspect 镜像名看一下Volumes或工作目录或者进容器ls确认别想当然。TZ时区不设的话日志时间和报警时间会差 8 小时排查问题时非常误导人。logging限制日志大小防止日志文件无限增长把磁盘写满这是很多教程不写但生产必须加的一项。启动cd /opt/fuxa docker compose up -d-d是后台运行。启动后看状态docker compose ps docker compose logs -f --tail100日志里看到服务监听端口的提示基本就起来了。浏览器访问http://服务器IP:1881能看到登录或主界面就成功了。3.4 首次登录与基础配置首次进入一般需要设置管理员账号密码具体流程以你使用的版本为准。这里给两个实操建议密码别用默认的Fuxa 会暴露在网络上弱口令是最大的风险点部署完立刻确认数据目录里有没有生成文件去/opt/fuxa/data下ls -la看一眼有内容说明卷映射生效了这一步是验证持久化是否成功的最快方法。然后做一次破坏性验证docker compose down再up -d重新登录看工程数据还在不在。在的话说明你的持久化配置是对的可以放心往下做组态了。这个验证我每次部署必做五分钟的事能避免后面几天的数据丢失风险。4. 源码方式部署与开机自启4.1 Node.js 环境与依赖安装源码部署的前提是装好 Node.js。Fuxa 对 Node 版本有要求装之前先看项目package.json里的engines字段选对应的 LTS 版本。用 nvm 管理版本最灵活# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc # 安装并使用 LTS 版本 nvm install --lts nvm use --lts node -v拿到代码后进目录装依赖git clone 项目仓库地址 fuxa cd fuxa/server npm installnpm install这一步在部分网络环境下会慢或者卡在某个包上可以换国内镜像源加速npm config set registry指向可用的镜像。装依赖失败是源码部署最常见的卡点报错通常是某个原生模块编译失败缺python3、make、g这类构建工具按报错补装系统包即可。4.2 启动服务与生产模式运行开发模式用npm start或项目定义的脚本但生产环境不建议直接这么跑因为进程挂了不会自动恢复。更稳的做法是用进程管理工具比如 pm2npm install -g pm2 cd fuxa/server pm2 start main.js --name fuxa pm2 save pm2 startuppm2 save保存当前进程列表pm2 startup生成开机自启脚本按提示执行它输出的那条命令即可。这样服务器重启后 Fuxa 会自动拉起不用人工干预。源码部署的数据目录同样要确认清楚一般在 server 目录下的_appdata备份时把这个目录一起纳入。4.3 反向代理与 HTTPS 接入生产环境不建议直接把 Fuxa 端口暴露到公网标准做法是前面挂 Nginx 做反向代理顺便上 HTTPS。核心配置server { listen 443 ssl; server_name your-domain.example; ssl_certificate /etc/nginx/cert/fullchain.pem; ssl_certificate_key /etc/nginx/cert/privkey.pem; location / { proxy_pass http://127.0.0.1:1881; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_read_timeout 3600s; } }Upgrade和Connection这两行是给 WebSocket 用的Fuxa 的实时数据推送依赖长连接不配这两行会出现页面能开但数据不刷新的诡异现象这是反向代理场景下最高频的坑。proxy_read_timeout调大是为了防止长连接被代理提前掐断。5. 常见问题排查与避坑实录5.1 启动类问题速查现象可能原因排查与解决容器启动后立即退出端口冲突或配置错误docker compose logs看退出原因ss -tlnp查端口占用浏览器打不开页面端口未映射或防火墙拦截确认ports映射正确检查安全组和本机防火墙页面能开但数据不刷新WebSocket 被代理阻断反向代理补Upgrade/Connection头重启后工程数据丢失卷映射路径错误进容器ls确认实际数据路径修正挂载日志时间差 8 小时未设时区加TZAsia/Shanghai环境变量磁盘逐渐写满日志或历史库无限制增长配日志轮转规划历史数据保留策略这张表覆盖了我实际遇到过的绝大多数启动和运行问题。排查顺序建议固定为先看日志再查端口最后查挂载。日志里 90% 的问题都有直接线索很多人一上来就猜反而绕远路。5.2 几个只有踩过才知道的细节镜像 tag 别用 latest 上生产。前面提过一次这里再强调某次自动拉取新版本后接口行为变化前端报错但日志不明显最后靠对比版本才定位。生产环境锁定版本号升级前先在测试环境验证。卷映射路径要按版本核对。不同版本镜像的内部数据目录可能调整照抄网上教程的路径有概率挂到空目录上表现为数据能存但重启就丢。部署后一定做一次重启验证。设备连不上先测网络再查配置。Fuxa 连 PLC 失败八成是网络不通或端口没开不是协议配置错。先用nc -zv测通再回头查 Modbus 从站地址、寄存器地址这些参数能省一半时间。历史数据保留策略要提前定。默认配置下历史数据可能一直累积几百点位跑几个月磁盘就紧张了。部署阶段就把保留天数、采样周期规划好别等磁盘告警了再补。提示每次改动配置端口、挂载、环境变量后用docker compose down docker compose up -d完整重建一次再验证比restart更能暴露配置问题因为 restart 不会重新读取 compose 文件的变更。5.3 升级与备份的稳妥做法升级前先备份数据目录这是铁律cd /opt/fuxa tar -czf fuxa-backup-$(date %Y%m%d).tar.gz data/然后改 compose 文件里的镜像 tagdocker compose pull docker compose up -d。升级后重点验证三件事登录正常、工程画面能打开、历史数据能查到。任何一项异常回滚就是把 tag 改回旧版本再up -d数据目录不动几分钟恢复。这套流程我用了很多次从没因为升级丢过数据。备份策略上我建议数据目录每天定时打包一次保留最近 7 到 14 天异地再存一份。Fuxa 的工程数据是纯文件打包备份成本很低但真出事的时候它就是救命的东西。6. 部署完成后的验证清单环境跑起来不等于部署完成我习惯按一张清单逐项确认全部打勾才算交付服务能通过浏览器正常访问登录成功数据目录已生成文件卷映射生效执行一次downup工程数据仍在时区正确日志时间与实际一致日志轮转已配置磁盘增长可控设备通信方向网络可达如涉及设备接入反向代理和 HTTPS 已配置如对外提供服务备份脚本已就位并测试过一次恢复这张清单看着简单但每一项都对应一个真实踩过的坑。尤其是重启验证和备份恢复测试这两项很多人跳过结果在真正需要的时候才发现配置是错的。我个人在实际操作中的体会是Fuxa 的安装部署本身技术难度不高真正拉开差距的是对数据放哪、怎么活下来、怎么升级回滚这几个问题的处理。把数据目录规划好、把持久化验证做扎实、把版本锁定住后面组态和接设备就是顺水推舟的事。反过来如果部署阶段图省事用临时容器跑后面每一次重启都是一次赌博。这套流程我在不同环境里复现过多次按上面的顺序走基本不会出岔子。
阅读完成 · 觉得有帮助？
