2-系统架构

系统架构用于从研发视角理解智档宝。它回答三个问题：系统由哪些层组成、各层之间怎么协作、出问题时应该先看哪里。

智档宝不是单个 Web 项目。一次完整交付通常包含 Web 前端、后端服务、本地服务、中间件、文件与搜索服务、设备接入程序、现场硬件、固件控制程序和离线安装包。产品视图描述“用户能做什么”，本章描述“这些能力由什么承载”。

阅读目标

• 先建立智档宝的系统地图，知道前端、后端、本地服务、设备和中间件的边界。
• 理解档案管理、数字化、RFID、环境控制、打印等能力在系统里的协作方式。
• 遇到问题时能判断优先排查前端、后端、依赖服务、现场程序还是设备链路。

总体架构

从上往下看，智档宝可以理解为四条主线：

主线	说明	典型问题
业务主线	前端页面调用后端接口，后端维护档案、库房、权限、流程和配置	页面报错、接口失败、数据不一致
文件主线	上传文件进入对象存储或文件目录，再由解析、预览、搜索链路消费	上传失败、预览失败、全文搜不到
设备主线	后端通过设备接入层、MQTT、本地服务或协议程序联动现场设备	RFID 不识别、架体不动、环境控制数据不上报
交付主线	Linux Docker 离线包或 Windows 离线包把上述组件装到现场环境	服务起不来、端口占用、版本对不上

系统分层

层级	主要职责	常见载体
展示层	提供业务入口、状态展示、表单操作、大屏和客户端界面	Web 前端、Electron 客户端、大屏、手持机页面
业务服务层	承载档案规则、权限、流程、接口、设备能力封装	smart-doc-vault 及版本线后端
数据与中间件层	保存业务数据、文件、搜索索引、时序数据、消息和缓存	MySQL、Redis、Minio、Elasticsearch、InfluxDB、EMQX、Tika
本地服务层	处理必须靠现场机器完成的能力	打印服务、文档转换、Windows 监控、客户端本地能力
设备接入层	把现场协议、设备状态和业务系统连接起来	RFID 服务、环境控制网关、架体控制、门口机、调试工具
固件 / 控制层	直接面对硬件输入输出和设备控制	网关、传感器、控制板、移动列、固定列、读写器
部署交付层	把代码和依赖打成可安装、可回滚、可追溯的现场包	Linux Docker 离线包、Windows 离线包、更新服务

这一章只维护稳定边界和关键流向。版本线和仓库演进看 3-开发流程，打包脚本、端口、默认账号和发布目录看 4-打包分发。

展示层

展示层负责用户看到的入口，不负责最终业务一致性。

入口	作用	依赖
Web 前端	档案管理、数字化、库房、权限、配置、设备状态展示	后端接口、静态资源、浏览器缓存
大屏	库房态势、设备状态、统计数据和可视化展示	后端统计接口、设备状态数据
Electron 客户端	桌面场景、客户端分发、本地能力整合	前端构建、后端接口、本地服务
手持机 / 门口机页面	RFID、盘点、现场操作入口	RFID 服务、设备接口、后端业务接口

前端问题先判断三件事：页面版本是否正确、接口是否返回正常、浏览器缓存是否拿到旧资源。版本识别规则看 3-开发流程。

业务服务层

业务服务层是智档宝的核心。它不应该把所有现场差异直接写进业务流程，而是把差异沉淀到配置、设备接入层或项目定制线。

能力	后端职责	典型依赖
档案管理	档案对象、库房位置、借阅归还、盘点、状态流转	MySQL、Redis、设备状态
数字化	文件元数据、上传记录、预览入口、搜索关联	Minio、Tika、DocumentConvert、Elasticsearch
权限认证	用户、角色、库房权限、功能权限、接口鉴权	用户体系、权限表、登录配置
设备联动	把业务动作转换为设备命令或设备状态判断	MQTT、设备接入服务、现场协议
系统配置	现场参数、开关、路径、端口、设备地址	配置文件、数据库配置、部署环境

排查后端问题时，优先确认：接口返回、日志、数据库连接、中间件连接、当前前后端 hash 是否匹配。

数据与中间件层

数据层不是单一数据库。智档宝会按数据类型使用不同组件。

组件	保存什么	常见影响
MySQL	档案、库房、权限、配置、业务流程数据	业务查询、登录、状态流转
Redis	缓存、临时状态、会话或任务状态	登录状态、接口性能、临时任务
Minio / 文件目录	附件、扫描件、图片、预览源文件	上传、下载、预览、电子档案
Elasticsearch	全文索引和检索数据	全文搜索、关键字查询
Tika / DocumentConvert	文档内容解析和格式转换	Office/PDF 预览、内容抽取
InfluxDB	温湿度、设备状态等时序数据	环境控制曲线、历史趋势
EMQX / MQTT	设备事件、设备命令和状态消息	RFID、环境控制、设备联动

如果业务数据能查到，但文件打不开，优先查 Minio / 文件目录和预览链路。如果文件能打开但搜不到，优先查解析和 Elasticsearch。不要把所有问题都归到后端接口。

关键链路

档案业务链路

档案业务链路的关键是“业务状态”和“设备状态”不要混淆。设备动作成功不等于业务一定完成；业务状态更新也需要能追溯对应设备结果。

数字化文件链路

数字化链路常见故障要按阶段拆开看：上传是否成功、元数据是否写入、文件是否存在、解析服务是否可用、索引是否建立、前端预览地址是否正确。

设备接入链路

设备接入层的职责是消化现场差异。协议、串口、网口、网关、设备厂商、项目定制都不应该直接污染核心档案流程。

本地服务和现场程序

本地服务通常运行在 Windows 主机、Linux 服务器、边缘网关或设备控制机上。它们和主系统相比更依赖现场环境。

服务类型	为什么需要本地服务	排查入口
打印服务	浏览器不能直接稳定控制所有打印机和标签机	打印服务进程、打印机驱动、模板、端口
文档转换	Office/PDF 等预览需要额外解析或转换能力	Tika、DocumentConvert、文件路径
Windows 监控	现场 Windows 离线包包含多个服务，需要统一查看状态	serviceMonitor、Windows 服务列表
RFID / 门口机	读写器、门口机和手持设备需要常驻接入程序	RFID 服务日志、MQTT、设备网络
架体 / 环境控制接入	现场协议和硬件状态需要适配	网关、串口/网口、控制程序日志

写本地服务文档时必须说明运行位置、启动方式、监听端口、配置文件、日志位置、主系统调用方式和重启方法。

部署形态

智档宝目前常见两类稳定交付形态。

形态	说明	适合场景
Linux Docker 离线包	后端和依赖服务以容器方式交付，适配 x86_64、arm64、loongarch 等	国产化 Linux、服务器部署、离线环境
Windows 离线包	后端和依赖服务以 Windows 服务或本地目录方式交付	Windows 主机、一体化本地部署、现场工具集成

部署形态不改变系统分层，只改变组件运行位置和守护方式。同一个逻辑组件，在 Linux 可能是 Docker 容器，在 Windows 可能是系统服务或本地进程。

排障入口

遇到问题时，先按现象定位层级。

现象	优先判断	下一步
页面白屏或按钮没反应	前端资源、浏览器缓存、接口地址	看控制台、Network、前端 hash
接口 500 或业务失败	后端日志、数据库、中间件连接	看后端日志和接口返回
登录或权限异常	登录配置、用户信息、角色和库房权限	看认证接口、权限表、当前用户
文件上传失败	后端上传接口、对象存储、磁盘空间	看 Minio / 文件目录和后端日志
文件能上传但不能预览	解析转换服务、文件格式、预览地址	看 Tika / DocumentConvert
全文搜索搜不到	解析结果、索引任务、Elasticsearch	看解析日志和 ES 索引
RFID 不识别	RFID 服务、读写器、MQTT、标签	看 RFID 服务日志和设备连接
环境控制没有数据	网关、传感器、MQTT、InfluxDB	看网关和消息链路
架体不动作	控制程序、串口/网口、固件、供电	先验证设备侧，再看业务命令
Windows 服务启动失败	服务注册、路径、端口占用、权限	看 serviceMonitor、services.msc、事件日志

排障记录至少写清楚：现场版本、前端 hash、后端 hash、部署形态、问题时间、操作路径、接口或服务日志、是否涉及设备。

架构维护原则

• 主线架构只写稳定共识，客户差异放到项目定制或现场记录。
• 架构图优先表达边界和流向，不追求把所有仓库、端口和服务名一次画全。
• 设备差异优先沉淀到设备接入层、协议层或配置层，不直接散落在业务逻辑里。
• 本地服务必须标清运行位置和守护方式，否则后续现场排障会失去入口。
• 版本、打包和发布信息要能追溯到 Git hash，不用“最新版”“现场版”这类无法定位的说法。