FUXA 开发者实践指南：从部署到配置的全方位解析

一、核心组件解析：理解 FUXA 的架构设计

作为一款 Web 基础的过程可视化（SCADA/HMI/仪表盘）软件，FUXA 的目录结构承载了不同层面的功能职责。让我从开发者视角拆解这些核心组件的业务价值：

• app/：前端应用核心模块，包含界面渲染与用户交互逻辑，是操作人员与系统交互的直接入口
• server/：后端服务中枢，处理设备通信、数据存储和业务逻辑，相当于系统的"大脑"
• client/：Angular 前端框架实现，包含组件、服务和模型定义，构建现代化用户界面
• node-red/：Node-RED 集成模块，提供可视化流程编排能力，降低工业自动化场景的集成门槛
• odbc/：数据库连接支持组件，解决工业环境中多样化数据存储的接入需求
• wiki/：项目文档集合，包含从入门到高级配置的完整指南

💡 开发小贴士：server/runtime/devices/ 目录包含各类工业协议的实现代码，是设备驱动开发的关键参考

FUXA 主界面展示了项目管理、设备监控和可视化配置的核心功能入口

二、快速部署方案：选择适合你的启动方式

Docker 容器化部署

Docker 方案适合追求快速启动和环境一致性的场景，尤其推荐在生产环境或多实例部署时使用：

# 拉取最新官方镜像
docker pull frangoteam/fuxa:latest

# 基础运行命令（临时测试用）
docker run -d -p 1881:1881 frangoteam/fuxa:latest

# 生产环境持久化部署
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_images:/usr/src/app/FUXA/server/_images \    # 图像资源存储
    frangoteam/fuxa:latest

NPM 源码部署

源码部署适合需要定制开发或调试的场景，能提供更灵活的配置选项：

# 1. 克隆代码仓库
git clone https://gitcode.com/gh_mirrors/fu/FUXA.git
cd FUXA

# 2. 安装依赖（选择对应目录）
# 基础安装（不含西门子PLC连接）
cd server
npm install

# 如需S7连接支持（西门子PLC通信接口）
npm install --unsafe-perm  # 包含node-snap7原生模块

# 3. 启动服务
npm start

⚠️ 环境要求：Node.js 版本必须为 14、16 或 18，不兼容更高版本的 Node.js

两种部署方案对比

维度	Docker 部署	NPM 源码部署
环境隔离	优秀，不影响主机配置	依赖本地Node环境
启动速度	较快（首次启动需下载镜像）	较慢（需完整安装依赖）
定制能力	有限，需通过挂载实现	强大，可直接修改源码
资源占用	较高（容器化 overhead）	较低，直接运行于系统
升级难度	简单，只需拉取新镜像	需处理代码合并冲突

FUXA 编辑器提供拖拽式界面设计能力，支持快速构建工业可视化界面

三、深度配置指南：解锁系统潜能

配置文件结构与修改方法

FUXA 的核心配置文件位于 server/settings.default.js，主要包含服务器设置、数据库连接和协议配置等关键参数。推荐的修改方法是：

1. 复制默认配置创建自定义配置：cp server/settings.default.js server/settings.js
2. 使用 diff 格式修改关键配置项（仅展示推荐修改部分）：

{
  httpServer: {
-   host: "localhost",
+   host: "0.0.0.0",  // 允许外部访问
    port: 1881,       // 保持默认端口
    timeout: 120000
  },
  database: {
    engine: "sqlite",
-   path: "./_db/data.db",
+   path: "/data/fuxa/_db/data.db",  // 使用绝对路径便于维护
    retention: {
      tags: 365,      // 标签数据保留365天
      alarms: 365     // 告警记录保留365天
    }
  },
  log: {
-   level: "info",
+   level: "debug",   // 开发环境启用调试日志
    maxSize: 10485760
  }
}

配置生效验证方法

修改配置后，需要通过以下步骤验证是否生效：

1. 服务器端口验证：

# 查看端口监听状态
netstat -tulpn | grep 1881
# 预期输出应显示配置的host和port

2. 日志级别验证：

# 查看最新日志
tail -f server/_logs/fuxa.log
# 若配置debug级别，应看到详细的调试信息

3. 数据库路径验证：

# 检查数据库文件是否创建
ls -l /data/fuxa/_db/data.db
# 确认文件存在且有正确的权限

💡 高级技巧：使用 npm run dev 启动开发模式，配置修改后可自动重启服务，加速调试流程

四、设备集成实战：从连接到数据可视化

设备驱动架构

FUXA 支持多种工业协议，驱动实现位于 server/runtime/devices/ 目录，包含：

• modbus/: Modbus 协议实现，支持 RTU 和 TCP 模式
• opcua/: OPC UA 客户端，连接主流工业控制系统
• s7/: Siemens S7 PLC 通信接口
• mqtt/: MQTT 协议支持，用于物联网设备集成

FUXA 设备配置流程展示，支持多种工业协议的参数配置

数据可视化实现

FUXA 提供丰富的可视化组件，通过 client/src/app/gauges/ 目录下的实现可以扩展自定义控件。关键步骤包括：

1. 在编辑器中拖放控件到画布
2. 配置数据源，绑定到设备标签
3. 设置显示样式和动画效果
4. 预览并发布到运行环境

⚠️ 性能注意事项：单个界面建议不超过 50 个动态数据点，过多会导致界面卡顿

五、高级应用场景

Node-RED 集成

通过 node-red/ 目录下的节点，可以将 FUXA 与 Node-RED 工作流引擎无缝集成，实现复杂的自动化逻辑：

# 安装 Node-RED 集成插件
cd node-red/node-red-contrib-fuxa
npm install
# 然后在 Node-RED 中即可看到 FUXA 相关节点

历史数据与报表

FUXA 提供数据归档和报表功能，配置位于 server/runtime/storage/ 目录，支持 SQLite、InfluxDB 等多种存储引擎。通过 server/api/reports/ 接口可以生成自定义报表。

FUXA HMI 运行效果展示，实时数据更新与动画效果

六、常见问题与解决方案

1. 端口冲突：若 1881 端口被占用，修改配置文件中的 httpServer.port 并重启服务
2. 设备连接失败：检查防火墙设置，确保工业设备端口可访问，参考 wiki/HowTo-Devices-and-Tags.md
3. 数据存储增长过快：调整 database.retention 参数，缩短数据保留时间
4. 界面加载缓慢：优化视图复杂度，减少同时加载的控件数量

通过本文的指南，你应该能够顺利部署、配置和扩展 FUXA 系统。建议结合 wiki/ 目录下的详细文档，探索更多高级功能和最佳实践。记住，工业可视化系统的核心价值在于将复杂的数据转化为直观的决策依据，合理配置和优化是发挥其价值的关键。