1. 项目背景与整体架构设计思路1.1 医院器械报修业务到底在管什么先说说这类系统的业务本质。很多朋友第一次听“医疗器械医院器材报修管理系统”以为就是个普通的“网上提交维修单”应用这其实低估了它的复杂度。医院器械报修和办公设备报修最大的区别在于设备种类多、分布范围广、责任主体明确、安全要求高而且直接影响临床业务。一个完整的报修流程是这样的临床科室的护士或者医生发现设备故障比如监护仪黑屏、输液泵报警、CT 扫描不出图像通过系统提交报修工单上传设备编号和故障照片设备科的管理员接收到工单后进行分派维修工程师接单后到现场处理记录维修过程和更换配件最后设备科验收并归档。这一整套流程里涉及报修人、分派人、工程师、设备科管理员、院领导审批等多个角色每个角色看到的页面和操作权限完全不一样。这个项目名字里包含“医疗器械”和“医院器材”两个词意味着系统还要承载两类核心数据一类是医疗器械的资产台账设备名称、型号、序列号、所属科室、启用日期、保修期状态另一类是报修工单的流转数据。设备台账要是维护不好报修系统就成了空中楼阁——工程师接到工单后连设备在哪个楼哪个科室都找不到那就谈不上效率了。1.2 为什么选择微服务而不是单体架构这是我在做技术选型时被问得最多的问题。一个医院内部的报修系统并发量可能并不高日常 TPS 可能就几十有必要上微服务吗我的看法是这个项目上微服务不是因为“性能扛不住”而是因为下面四个原因。第一是团队协作边界清晰。这类系统往往不是一个人开发的前端、后端、测试、运维都有分工。拆分成微服务后比如基础数据服务负责设备台账工单服务负责报修流转统计服务负责报表每个团队负责自己的模块代码冲突和发布耦合都大幅减少。第二是业务扩展的需要。医院内部的系统往往不只是报修后面可能还要接设备巡检、耗材管理、供应商售后接口、大屏数据展示等等。单体应用改到后期会变得非常难维护微服务按业务域拆分后新增模块就是在边上再挂一个服务不动老代码。第三是容灾和部署灵活。工单服务临时出问题了不能影响设备台账查询和基础登录。微服务架构下可以把不同的服务部署在不同的节点关键服务多副本部署实现了故障隔离。第四是技术体系的统一演进。团队想引入新的框架或中间件时可以在某个边角服务上先试水稳定后再推广比在单体里做手术要安全得多。当然微服务的代价也很明显部署复杂、链路追踪麻烦、分布式事务处理困难。这也是为什么我在项目中大量使用成熟的 Spring Cloud 组件来解决这些问题而不是自己去造轮子。1.3 整体技术栈与模块化划分这个项目整体采用前后端分离架构前端是 Vue 全家桶Vue 2 Element UI也可以用 Vue 3 Element Plus后面细说后端是 Spring Boot 作为基础框架Spring Cloud 做微服务治理。我最终确定的服务拆分方案是这样的注册与配置中心Nacos同时承担服务注册发现和配置管理两个职责减少运维组件。网关服务Gateway统一入口负责路由转发、统一鉴权、跨域处理。认证服务Auth登录、Token 颁发与刷新、用户信息查询。设备服务Device设备台账管理设备类型维护科室设备绑定。工单服务Order报修工单的创建、流转、处理、验收这是整个系统最核心的服务。通知服务Notify站内信、通知消息推送。统计服务Report设备故障率、工单响应时长、维修费用等维度的报表。前端部分按角色来组织页面比如报修人端提交工单、查看进度、工程师端接单、处理、填写维修记录、管理端分派工单、审批、统计、设备台账管理。前端通过网关统一的接口前缀调用后端服务网关转发到对应的微服务。这个拆分粒度在实际开发中比较舒服每个服务都能独立开发独立部署代码量也不至于太少而导致拆分成本大于收益。2. 微服务核心治理组件的落地细节2.1 Nacos 服务注册发现与配置管理的配置要点Nacos 在这个项目里承担了双重重任。首先是服务注册发现各个微服务启动时把自己注册到 Nacos网关和 Feign 调用方通过服务名来发现目标实例不再写死 IP 和端口。这一点对部署环境的变化非常友好——比如从开发环境切换到测试环境只需要改 bootstrap.yml 里的 Nacos 地址服务之间的调用关系完全不用动。Nacos 做配置中心时我建议把配置文件里容易变化的内容全部抽到 Nacos 配置里比如数据库连接信息、Redis 地址、日志级别、开关类配置。我当时把工单服务的状态机配置、设备类型的默认保修期、通知服务的模板内容都放进了 Nacos 配置这样运营人员调整业务参数时不用重新发版直接在控制台改配置即可生效配合 RefreshScope 注解非常方便。有个容易踩的坑是 Nacos 配置文件与本地配置文件的优先级问题。Spring Cloud 加载配置的顺序是bootstrap.yml 里的 Nacos 配置优于 application.yml所以如果 Nacos 配置中心里配了某项配置本地同名配置不会生效。这个特点用好了是优势用不好就是事故——我曾经有一次把测试环境的数据库地址写到了共享配置里结果本地开发全部连到测试库上去了排查了半小时才发现是配置优先级的问题。2.2 Spring Cloud Gateway 网关的路由与统一鉴权网关是整个微服务架构的守门员所有前端请求统一打到网关由网关转发到后端的各个微服务。我在项目里选择 Spring Cloud Gateway 而不是 Zuul是因为 Gateway 基于 WebFlux 实现性能更好而且与 Spring Cloud 生态融合度高。网关里最核心的两件事路由配置和统一鉴权。路由配置说白了就是做一个映射表前端请求路径以/api/auth/**开头就转发到认证服务以/api/device/**开头就转发到设备服务以/api/order/**开头就转发到工单服务。这里的**是路径通配符把所有子路径都纳入路由。统一鉴权是网关的另外一个核心职责。我的设计思路是用 JWTJSON Web Token作为登录凭证。用户登录认证服务成功后服务端签发一个带过期时间的 JWT 返回给前端前端把 JWT 存在本地存储中每次请求都在 Header 的 Authorization 字段里带上网关在转发请求前拦截校验 JWT 的合法性和过期时间通过后再把用户信息放进请求头转发给下游服务。这个方案的优点是下游服务不再关心用户是谁、权限够不够网关统一处理之后服务层的代码会干净很多。具体的过滤器逻辑可以继承 Gateway 的GlobalFilter接口重写filter方法来实现。白名单问题也要注意登录接口、验证码接口、健康检查接口是不需要鉴权的要把这些路径放进白名单放行其他接口统一走鉴权逻辑。白名单配置放到 Nacos 配置中心方便随时调整。2.3 认证服务与统一权限设计认证服务是独立的微服务它不涉及业务逻辑只负责两件事用户认证和 Token 管理。用户表的设计要比常规系统稍微复杂一点因为医院场景下同一个用户可能有多重身份。比如某个工程师同时也可以是设备管理员某个护士长又可能是院级审批人。我采用了 RBAC 模型基于角色的访问控制用户关联角色角色关联菜单和权限点。这样权限管理逻辑清晰要调整权限只需要改角色配置不需要改代码。认证服务对外提供三个接口登录接口用户名密码校验成功后颁发 Token、Token 刷新接口旧 Token 快过期时申请新的、退出登录接口客户端丢弃 Token服务端维护黑名单。黑名单的存储用的是 Redis把已退出的 Token 放进 Redis 并设置其剩余有效期作为过期时间这样即使 Token 未到过期时间也无法再通过网关校验。2.4 微服务架构下的接口文档聚合Knife4j 集成方案很多团队用 Swagger 给每个微服务生成了文档但开发人员要看接口时得挨个打开不同服务的端口——页面地址记不住而且服务一多管理混乱。后来我把 Knife4j 集成进来把这个问题解决了。Knife4j 是基于 Swagger 的增强 UI 工具对中文支持好、界面舒服。在微服务架构下我采用网关聚合模式来做文档各个微服务仍然暴露自己的接口文档但网关层增加一个/v3/api-docs的聚合路由Knife4j 的 UI 只部署一份在网关侧通过网关去拉取各个微服务的 OpenAPI 信息最终在一个页面上展示所有服务的接口列表。实际操作中需要注意微服务里用 Spring Boot 3.x 时Swagger 依赖要引入 springdoc-openapi-starter-webmvc-ui 这个新版包版本不能配错网关聚合路径要与各服务的 context-path 对齐否则拉取文档会 404。另外生产环境要把 Swagger 文档关掉避免接口信息泄露我一般是通过 Nacos 配置一个swagger.enabled开关来控制生产环境置为 false。3. 核心业务模块设计与实操要点3.1 报修工单状态机的设计工单是这个系统的灵魂工单的每一次状态变化都必须有迹可循。我在设计工单模型时最核心的是定义了一个明确的状态机而不是用简单的字段去存一个手工修改的状态值。工单状态的流转我固定为六个状态待分派报修人提交工单后工单进入待分派状态等待设备科管理员处理待接单管理员分派给指定工程师或维修组后工单转为待接单状态维修中工程师接单并开始处理工单进入维修中待验收工程师提交维修结果后工单进入待验收已完成设备科管理员验收通过工单归档已作废重复提交、信息错误等异常情况的终止状态。状态机的落地我使用了简单的状态模式来实现。在工单服务的内存中维护一张状态流转表定义一个 Map 来存放每个状态允许的下一个状态集合。例如“待分派”只能流转到“待接单”或“已作废”“待接单”只能流转到“维修中”或“待分派”管理员重新分派。每次状态变更前先校验流转是否合法不合法直接抛出业务异常。这套逻辑虽然简单但防止了数据错乱的绝大多数情况。工单的每次状态变更都会写入一张操作日志表记录操作人、操作时间、操作内容、变更前后状态。这是为了应对医院内部审计的要求——设备维修记录需要追溯这个日志表就是追溯的凭证。3.2 设备台账与扫码报修的实现设备台账是工单流转的基础数据。我把设备台账设计成了一张独立的主数据表字段包括设备编号、设备名称、设备型号、生产厂商、所属科室、存放位置、启用日期、保修截止日期、当前状态正常、维修中、报废等。这里有个实操细节值得说床旁设备如何快速定位到具体设备。很多医院的设备编号很长让护士手动录入容易出错我们的解决方案是给每台设备生成一个唯一的二维码贴在设备机身上。护士发现故障后用手机微信扫码自动跳转到报修页面并带上设备编号参数报修人只需要选择故障类型、填写描述、拍照上传即可设备信息自动带出省时又准确。二维码生成用的是 ZXing 库后端为每台设备生成二维码图片管理员打印后贴到设备上。前端扫码进入页面时通过路由参数将设备编码传给后端查询接口工单服务创建工单时会自动关联设备台账数据。3.3 前端 Vue 项目的组织与核心页面拆解前端这块我采用的是按业务模块划分目录的方式而不是单纯按页面类型划分。这样前后端服务划分保持一致开发人员各自负责一个模块时互不干扰。src/ ├── api/ # 接口请求封装按服务模块分文件 │ ├── auth.js │ ├── device.js │ ├── order.js │ └── report.js ├── views/ │ ├── work-bench/ # 工作台与待办 │ ├── report/ # 报修提交 │ ├── order-manage/ # 工单管理工程师端、管理员端 │ ├── device-manage/ # 设备台账管理 │ └── statistics/ # 统计报表 ├── components/ # 通用组件 ├── router/ # 路由配置 └── store/ # 状态管理Vuex/Pinia关键页面方面第一个是报修提交页。这个页面要尽量少让用户做选择。设备信息自动带出故障类型用下拉菜单枚举电源故障、显示屏故障、传感器异常、机械故障、网络连接问题等故障描述用 Textarea 即可再加上图片上传区域。整体表单控制在五个字段以内因为这是使用频率最高的页面使用体验一定要轻。第二个是工单处理页这个页面主要是工程师在用。工程师接单后看到故障描述和设备信息可以填写处理过程、使用配件、处理结果如果需要申请更换整机也可以在这个页面发起。页面右侧最好有设备的历史工单列表工程师可以快速判断这台设备是不是“惯犯”——如果是反复故障处理策略可能就会不同。第三个是管理看板页这是设备科管理员的“驾驶舱”展示今日新增工单数、待分派工单数、维修中工单数、本月完成率、平均响应时长等指标。这块的数据来自统计服务提供的聚合接口前端用 ECharts 图表展示。3.4 文件上传场景的 MinIO 分布式存储报修工单里经常要上传故障照片工程师维修后也要上传完工照片设备台账中还可以维护设备的图片资料。这些图片类型的文件我用的是 MinIO 来做对象存储。MinIO 是一个兼容 S3 协议的对象存储服务支持分布式部署。我选择它而不是直接把图片放在服务器本地目录原因有三个一是应用服务器的磁盘空间有限而且应用重启时本地文件容易丢失二是微服务架构下可能有多个应用实例在跑用户上传的请求打到 A 实例图片却存到了 B 实例的本地磁盘后续访问就会出现 404三是 MinIO 提供了桶Bucket的概念可以很方便地按业务类型隔离文件比如report-images桶放报修图片device-images桶放设备图片。文件上传的链路是这样的前端先把文件传到某个固定服务我放在了工单服务里工单服务把文件流写入 MinIO得到一个文件的元数据包括桶名、对象名、大小、上传时间再把元数据保存到数据库的附件表最后将附件 ID 关联到工单或设备记录上。前端展示图片时通过后端接口签名生成临时访问 URL避免把存储桶设置为公共读导致数据泄露。3.5 分布式事务的取舍与分布式锁的实际应用这里要坦诚说一个经验教训。很多人一听到微服务就想到分布式事务但其实百分之八十的业务场景根本用不着强一致的分布式事务。以创建工单为例表面上看涉及工单服务和通知服务两个服务——工单创建成功后要给报修人推一条站内信。如果为了这两个服务的数据一致性引入 Seata 分布式事务框架成本其实挺高的。我的方案是采取“本地消息表 重试补偿”的方式。具体做法是工单服务在本地数据库的事务里同时写入工单记录和待发送消息记录两个动作在同一条数据库事务中天然保证一致性。然后有一个定时任务扫描待发送消息表把未发送的消息投递到通知服务通知服务处理成功后回调消息服务更新消息状态如果投递失败定时任务下一轮会重新扫描重试。这种方式牺牲了一点实时性但换来了实现简单和数据最终一致对报修通知这种场景完全够用。分布式锁在这个系统里也派上了用场主要解决定时任务重复执行的问题。在微服务架构下如果工单服务部署了两个实例而定时任务没有做处理每个实例都会执行一遍扫描逻辑导致通知消息被重复发送。我用的方案是 Redis 分布式锁代码逻辑很简单任务执行前先去 Redis 设置一个带过期时间的 key只有设置成功的那个实例才能继续执行任务其他实例直接跳出。// 伪代码示意 String lockKey report:notify:send; String requestId UUID.randomUUID().toString(); Boolean locked redisTemplate.opsForValue() .setIfAbsent(lockKey, requestId, Duration.ofSeconds(30)); if (Boolean.TRUE.equals(locked)) { try { // 执行定时任务 sendPendingNotifications(); } finally { // 必须是同一个线程持有锁才能释放防止误删其他线程的锁 String value (String) redisTemplate.opsForValue().get(lockKey); if (requestId.equals(value)) { redisTemplate.delete(lockKey); } } }这里有个细节容易被忽视获取锁时一定要加过期时间不然实例崩溃了锁永远得不到释放任务就彻底锁死了。释放锁之前要先校验 value 是否是自己写入的避免因为任务执行太久超过锁的过期时间锁被其他实例获取后又给误删除。4. 部署架构与高可用实践4.1 开发阶段 IDEA 多实例调试的实践微服务开发阶段最痛苦的事就是本地要把一堆服务都启动起来。一开始我是逐个启动四个服务改一个服务就重启一个服务调试进度非常慢。后来把 IDEA 的 Compound Configuration复合配置用起来了一次点击就能启动所有服务。具体配置方法是在 IDEA 的 Run/Debug Configurations 里新增一个 Compound 类型的配置把认证服务、设备服务、工单服务、通知服务、统计服务各自的 Spring Boot 启动配置都加进去注意给每个服务配置不同的端口并且修改各服务配置文件中 Nacos 的注册地址保持一致。点击调试按钮后IDEA 会并行启动所有服务日志会分 tab 显示哪个服务启动失败直接点进去看日志就行。还有一个经验是前端项目在开发阶段必须配置代理把接口请求转发到网关。Vue 项目的vue.config.js里配置 devServer.proxy将/api前缀的请求都代理到http://localhost:8800网关端口。这样前端开发时不需要关心后端服务的 IP 和端口统一走网关和线上的调用方式保持一致。4.2 基于 K8s 的部署实现与压测验证项目部署到测试环境时我采用的是单节点 Kubernetes 集群把整套微服务环境都跑在 K8s 上。因为把服务都容器化了环境的一致性会很好本地能跑通测试环境和生产环境大概率也能跑通不会出现“在我电脑上明明是好的”这种经典问题。K8s 上的资源编排主要用三种对象Deployment管理服务的副本数、Service提供集群内稳定的访问入口、ConfigMap存放配置文件。每个微服务对应一个 Deployment副本数按服务的重要性来配置——网关和工单服务业务重配置至少 2 个副本通知服务和统计服务 1 个副本就够。负载均衡和入口控制在 K8s 里用 Ingress 来实现。Ingress 将外部的 HTTP 请求按路径分发到网关服务网关再路由到后端微服务。压测时 JMeter 脚本直接打到 Ingress 地址效果比绕过网关直接压测后端服务更真实因为网关层还有鉴权和限流的逻辑这部分也是性能的组成部分。迁移到云上 ECS 的这个场景我实际操作时的顺序是这样的先在云上部署一套与测试环境一致的中间件MySQL、Redis、Nacos、MinIO然后导出测试环境的数据库数据导入云上数据库再去 K8s 集群里修改 ConfigMap 里的连接地址为云上地址最后逐步滚动更新服务实例。等所有服务在云上启动成功后再用 JMeter 脚本做高并发压测观察 CPU 和内存的占用情况来决定后端服务的副本数是否需要调整。4.3 从单机部署到集群部署的演进思考K8s 单节点部署解决的是环境一致性问题但单节点不存在高可用——节点挂了上面的服务全部不可用。如果医院对报修系统的可用性要求高后期可以做下面几个演进数据库用主从模式主库出问题后从库自动提升Redis 做成哨兵模式或集群模式Nacos 部署三个节点形成集群K8s 由单节点扩展为多节点 worker 节点关键服务设置副本反亲和性确保同一服务的不同副本分布在不同的物理节点上。这里想多提醒一句微服务架构的高可用是分层的不要只看应用层的副本数底层的 MySQL、Redis、Nacos 如果挂了应用层副本再多也无济于事。医院业务对可用性要求高的话底层的中间件也要纳入高可用方案。5. 常见问题与排查技巧实录5.1 Spring Boot 版本过高引发的兼容性坑这个项目开发过程中我踩过最深的坑就是 Spring Boot 版本问题。Spring Boot 3.x 发布后很多人直接用最新版本结果发现原来的 Nacos 客户端、Spring Cloud Alibaba 组件全都启动报错。原因是 Spring Boot 3.x 基于 Jakarta EE 9包名从javax.*变更为jakarta.*而且最低要求 JDK 17。很多第三方组件如果没有同步升级到这个规范就会出现类找不到、Bean 注入失败这些诡异问题。我的建议是如果用 Spring Cloud Alibaba 体系Spring Boot 2.7.x 搭配 Spring Cloud 2021.0.x 搭配 Spring Cloud Alibaba 2021.0.5.0 是一套经过大量项目验证的稳定组合如果要上 Spring Boot 3.x先确认你依赖的所有组件都有对应的 Jakarta 兼容版本。报修系统这种业务系统追求稳定优先没有必要追最新版本。5.2 Vue 项目打包后布局异常的问题前端开发中经常出现“本地运行正常npm run build 打包上线后布局全乱了”的情况。这个问题八成与publicPath配置有关。Vue CLI 项目的vue.config.js中publicPath默认是/网站部署在域名根路径时没问题。但如果部署在子路径下比如https://host/hospital-report/静态资源会从根路径去找找不到资源自然布局全乱。解决方案是把publicPath设置为./或相对路径process.env.PUBLIC_URL让资源路径相对当前页面解析。还有一个排查方向是路由模式的问题。如果用了 HTML5 History 路由模式前端部署到 Nginx 后刷新页面会出现 404因为 Nginx 找不到对应的物理文件。解决方案是在 Nginx 配置中加入try_files $uri $uri/ /index.html;让所有未匹配的请求都回退到入口 HTML。5.3 前端播放监控视频的 M3U8 流媒体处理医院设备报修系统有时候要对接设备状态监控视频比如大型设备的运行画面。前端播放视频流时现代浏览器不支持直接播放 M3U8 格式HLS 协议需要借助第三方库。我的方案是用hls.js这个库。它通过 MSEMedia Source Extensions技术将 HLS 流在浏览器端转码播放兼容主流浏览器。接入方式很简单在播放组件中动态引入 hls.js检测到浏览器支持 MSE 后创建 Hls 实例将视频源绑定到 video 元素上。video 标签的 controls 属性开启原生控制条autoplay 属性控制自动播放。如果视频源有防盗链需求在后端生成带签名和过期时间的流地址前端直接用这个地址播放过期后接口再换新的地址。5.4 分布式链路追踪与日志排查经验微服务架构下查问题最痛苦的就是链路太长。用户报一个错根本不知道是网关层的错误、工单服务的错误还是数据库的问题。我后来给项目里接入了简单的链路追踪方案基于 Sleuth 和 Zipkin给每个请求生成一个全局的 TraceId通过网关时生成通过 Feign 调用传递到下一个服务最终把所有服务的日志串联到同一个 TraceId 下。实际使用中并不是日志系统都要上小项目如果没接日志平台也可以自己约定一个规则在日志里打印 TraceId排查问题时用 grep 按 TraceId 过滤所有服务的日志一样能还原调用链。5.5 常见问题速查表现象可能原因解决方案服务启动后无法注册到 NacosNacos 地址配置错误或网络不通检查 bootstrap.yml 中的 server-addr 配置telnet 测试端口连通性跨域请求报错网关未配置跨域过滤器在 Gateway 中配置 GlobalCorsConfigurationToken 过期后接口一律 401JWT 过期时间太短或黑名单误删合理设置 Token 过期时间提供刷新接口定时任务重复执行多实例部署未加分布式锁用 Redis 分布式锁控制任务唯一性上传图片后访问 404MinIO 桶名错误或访问路径不正确检查桶名、对象名拼接逻辑验证临时 URL 签名页面白屏但无报错Vue 路由配置错误或部署路径不对检查路由 base 配置与 publicPath 是否匹配工单验收入库后状态仍是维修中状态变更未走状态机校验检查状态流转配置是否完整统一走状态机方法写在最后的一些实际体会这个项目做完之后我最大的体会是微服务架构本身并不难难的是在拆之前想清楚业务边界、在拆之后管好服务治理。如果业务不复杂、团队也不大老老实实用单体加前后端分离完全没问题但如果你明确知道系统要长期演进、要多团队协作、要对接更多外部系统那花在微服务架构上的投入是值得的。另外有个小建议这类系统在开发时一定要把权限模型设计放在业务开发之前。医院信息系统涉及科室数据隔离比如工程师只能看到自己负责科室的工单这种数据权限如果前期不设计好后期补起来会牵动所有查询接口改造成本极高。我的做法是在设备表上维护科室维度在用户角色上维护数据权限范围所有涉及列表查询的接口统一在 Service 层注入数据权限过滤逻辑这个设计直接省掉了后期大量的返工。最后说一个非常实用的技巧设备台账的导入功能一定要做。医院里存量设备动辄上千台靠管理员手动录入不现实。我们做的是 Excel 模板导入提供了标准的导入模板文件下载、字段校验提示、错误行定位功能。系统上线时设备台账数据的初始化全都靠这个导入功能完成上线当天导入了一千多条设备数据从 Excel 导入到校验通过、落库完成整个过程不到五分钟。希望这篇分享能给正在做类似微服务管理系统的朋友一些参考。如果你也在做医院相关的信息化系统欢迎多交流踩坑经验。