← 返回首页
叩石寻径问路 · 工业认知与系统架构实录

重构开源EAM：设备管理系统为何需要三层架构？

📅 2026-11-02 🏷️ 工业EAM / 智能制造 / MCP协议 / 架构重构 / InstaBox沙箱 / Go / Vue3 ✍️ 黄峰
重构开源EAM：设备管理系统为何需要三层架构？
图：EAM-Agent 三层解耦架构设计（协议层 MCP + 交互层降噪 + 验证层快照沙箱）
【核心结论先行】
做工业软件或设备管理系统，极容易在两个极端之间摇摆：要么照搬十几年前老旧 ERP、MES 的做法，堆砌出几百张密密麻麻、死板生硬的“网页版 Excel 表格”；要么被这两年大模型概念带偏，试图搞一个聊天框让 AI 直接包揽一切。
1. 协议层解耦（从死板界面到 MCP 生态）： 原生支持 Model Context Protocol（MCP）协议，提供本地 stdio（独立 8.3MB Go 工具）与云端 SSE 双模式，开放 17 个工业级运维工具并施加细粒度 RBAC 权限与频控断路器，让外部 Agent 具备受控的“双手”，而非停留在玩具式聊天。
2. 人机工效与交互降噪（工业 B 端界面的现代工程解法）： 针对工业表格列宽超标导致的“按钮挤压换行、文字被裁切成半个字”顽疾，严格实行“高频操作外露，低频与危险操作折入抽屉”，并在主从配置中采用 38% : 62% 的 Master-Detail 卡片流，让现场操作员与工程师视线不疲劳。
3. 验证与分层部署（纯编译机 vs 业务快照沙箱）： 单测跑通绝不代表生产可用。日常提交使用 4 核空白编译机（35 秒极速完成 Go 单测与 Vite 打包），发版前强制在整机业务快照沙箱中拉起真实数据库、Redis 与工业台账执行全链路探活，彻底杜绝“编译通过但生产白屏”。

一、 协议层解耦：为什么工业系统不该停留在“人点按钮”而要原生支持 MCP？

过去很多团队尝试把大模型引入工厂设备管理，做法通常非常原始：在系统右下角挂一个悬浮聊天弹窗，把设备维保手册当成纯文本塞给模型做 RAG 问答。

这种做法在真实车间里很快就会沦为摆设。一线维修师傅和巡检工程师不需要一个只会复读说明书的聊天机器人，他们需要的是能够真正连接系统数据库、调取实时机台健康度、甚至帮他们草拟工单的生产助手。

如果我们只开放传统 REST API，外部主流的大模型桌面端（如 Claude Desktop）或开发智能体（如 Cursor）根本无法即插即用。为此，我们在本次重构中将系统核心能力全量抽象为 Model Context Protocol（MCP） 原生支持：

🛠️ 双模式灵活接入：本地 stdio 管道与云端原生 SSE

  • 本地 stdio 模式（轻量化独立 Bridge）： 我们单独编译了一个仅 8.3MB 的轻量级 Go 命令行工具 eam-mcp。用户只需在 Claude Desktop 的全局配置文件中填入该命令和本地凭据，启动后即可通过标准输入输出与系统通信，安全隔离度极高。
  • 云端原生 SSE 模式（Server-Sent Events）： 在 Gin 路由底层直接挂载 /api/v1/mcp/sse 与 /api/v1/mcp/message。在 Cursor 或第三方轻量 Agent 中，用户无需下载任何本地二进制程序，只需填写云端 URL 并附带 Bearer Token，即可建立长连接直连。
EAM-Agent MCP 协议接入向导界面
图 1 · 系统内置的 MCP 协议接入向导，动态注入权限密钥并支持一键复制配置

我们在协议层对外暴露了 17 个工业级设备运维工具，涵盖了设备全生命周期：从设备台账与健康度查询（query_equipment_health）、点检异常自动报修（report_repair），到过程排故记录追加（update_repair_progress）与备件库存核销（check_spare_parts）。

工业现场的数据库承载着真实产线数据，绝不能承受 Agent 的失控冲击。我们在架构中为每一个 API Key 显式绑定了 RBAC 作用域（如 read:equipment、write:repair） 与 req/m（每分钟请求频控限制）。一旦外部大模型陷入推理死循环，网关层会在微秒级触发断路器阻断请求，确保工业系统核心业务稳定。

二、 人机工效与视觉重构：工业 B 端界面如何彻底根除“表格挤压与截断”？

工业软件常年给人的刻板印象是：界面充斥着灰暗厚重的铁皮质感、密密麻麻的 2D 齿轮图标，以及动辄几十列宽、横向滑动时按钮挤作一团的表格。这种设计不仅难看，在长时间巡检与数据录入时极易引发视觉疲劳，甚至导致工人按错报废或删除按钮。

EAM-Agent 桌面视窗风格登录页
图 2 · 桌面级原生视窗登录页，采用 3D 等轴测资产立方体 Logo 与夜间漫反射光晕

在本次前端重构中，我们针对工业中后台常见的排版硬伤，落地了两项关键解法：

1. 表格操作列结构收纳：高频外露，低频折入抽屉

在设备台账和任务列表中，往往并存着“查看、编辑、打印二维码、启停变更、报废、删除”等 5 到 6 个操作。如果全部平铺在最后一列，在笔记本或中低分屏上，列宽会被强行挤压变形，经常出现“二维码”被切断成半个字、或者“删除”按钮直接被遮罩截断的灾难现场。

EAM-Agent 设备台账紧凑操作列
图 3 · 设备台账页面，操作列结构化收纳，横向滚动平滑无遮挡

2. 组织架构与模板配置：38% : 62% Master-Detail 卡片流

另一个典型问题发生在层级管理页面。例如原本把“集团基地、制造工厂、作业车间”三张表硬塞在同一行，每张表宽度不足 300px，内部字段被迫恶性折行。

重构后，我们将具有从属关系的实体统一收敛进单个大卡片，通过带计数标记的滑动 Tab（如 集团基地 (1)、制造工厂 (2)）进行维度解耦。而在点检模板页面，左栏采用 38% 宽度的圆角微光卡片流展示模板摘要与当前激活项，右栏占据 62% 舒展展示检查项明细与判定基准，彻底告别了左右悬空的失衡感。

EAM-Agent 点检模板配置页面
图 4 · 点检模板配置界面，左侧卡片流快速切换，右侧沉浸式明细面板

三、 验证与分层部署：跑通单测为什么不等于生产可用？编译机与快照沙箱的分工

在工程协同与 CI/CD 实践中，我们曾遇到过一个深刻的反差：代码在 GitHub 官方提供的 Ubuntu 虚拟机上跑单元测试，全部绿灯通过；但一旦打包镜像部署到服务器上，前端页面却因为缺少响应式依赖瞬间白屏，或者后端因为数据库驱动类型扫描异常而抛出 500。

纯编译机只能验证语法的正确性，无法验证系统的生存能力。

代码提交 / PR 阶段
  │
  ▼
[第一道防线 · 空白编译机] (InstaBox Medium Runner)
  ├─ 4 vCPU / 8GB 纯净空白环境
  ├─ Go 后端单测: 34秒通过 (提速 27%)
  ├─ Vite 生产构建: 35秒完成
  └─ 跑完秒级销毁，不占常驻配额
  │
代码合并主分支 / 发版阶段
  │
  ▼
[第二道防线 · 整机业务快照沙箱] (ems-demo-v2 Snapshot)
  ├─ 1:1 克隆真实车间环境
  ├─ 真实启动 PostgreSQL 数据库、Redis、Nginx 前后端
  ├─ 挂载完整历史设备台账、真实点检记录与账号权限
  ├─ 真实端到端 API 探活与界面渲染检测
  └─ 验收通过后自动回收熔断，杜绝生产白屏

我们在 InstaBox 上最终将这两者做了严格的物理切分：

这两者不是二选一的排他关系，而是分层协同的质量护城河。

四、 为什么我们拒绝推倒重来，坚持小而朴素的闭环？

很多制造业数字化项目之所以最终烂尾，往往是因为一开始就画了过于宏大的蓝图，试图用一套全新的一体化大系统把现有的工作流程全部推倒重来。

在车间里待过的人都知道，推倒重来的代价是极其高昂的。生产不能停，工人的习惯很难一夜改变。

开发这套 EAM-Agent 的初衷，从来不是去打造一个庞大复杂的权威软件，而是探索一种更务实的工程路径：

这是我们在泥土与机台之间找到的一条走得通的路径。

📦 开源仓库与在线演示体验

本系统已完全开源，核心后端采用 Go (Gin) + PostgreSQL + Redis 构建，前端采用 Vue 3 / Vite，欢迎工业开发者与架构同行查阅或自建部署：

GitHub 官方开源地址：
https://github.com/Feng-H/EAM-Agent

💡 关于在线演示体验：
为节约服务器算力资源，我们的 InstaBox 云端演示沙箱平日处于休眠状态。
如果同行或技术朋友想亲自上手体验这套 EAM 系统的调度流转、或者测试 Claude Desktop / Cursor 的 MCP 联动，欢迎在本文底部或公众号后台留言，我们会即时唤醒演示沙箱，并为你分配独立的体验账号。

— 叩石寻径问路 · 工业认知与系统架构实录 —