企业官网建设流程全解析

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/**开头就转发到工单服务。这里的**是路径通配符，把所有子路径都纳入路由。

统一鉴权是网关的另外一个核心职责。我的设计思路是用 JWT（JSON 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 报修工单状态机的设计

工单是这个系统的灵魂，工单的每一次状态变化都必须有迹可循。我在设计工单模型时，最核心的是定义了一个明确的状态机，而不是用简单的字段去存一个手工修改的状态值。

工单状态的流转我固定为六个状态：

1. 待分派：报修人提交工单后，工单进入待分派状态，等待设备科管理员处理；
2. 待接单：管理员分派给指定工程师或维修组后，工单转为待接单状态；
3. 维修中：工程师接单并开始处理，工单进入维修中；
4. 待验收：工程师提交维修结果后，工单进入待验收；
5. 已完成：设备科管理员验收通过，工单归档；
6. 已作废：重复提交、信息错误等异常情况的终止状态。

状态机的落地我使用了简单的状态模式来实现。在工单服务的内存中维护一张状态流转表，定义一个 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这个库。它通过 MSE（Media Source Extensions）技术将 HLS 流在浏览器端转码播放，兼容主流浏览器。接入方式很简单：在播放组件中动态引入 hls.js，检测到浏览器支持 MSE 后创建 Hls 实例，将视频源绑定到 video 元素上。video 标签的 controls 属性开启原生控制条，autoplay 属性控制自动播放。如果视频源有防盗链需求，在后端生成带签名和过期时间的流地址，前端直接用这个地址播放，过期后接口再换新的地址。

5.4 分布式链路追踪与日志排查经验

微服务架构下查问题最痛苦的就是链路太长。用户报一个错，根本不知道是网关层的错误、工单服务的错误还是数据库的问题。我后来给项目里接入了简单的链路追踪方案：基于 Sleuth 和 Zipkin，给每个请求生成一个全局的 TraceId，通过网关时生成，通过 Feign 调用传递到下一个服务，最终把所有服务的日志串联到同一个 TraceId 下。

实际使用中并不是日志系统都要上，小项目如果没接日志平台，也可以自己约定一个规则：在日志里打印 TraceId，排查问题时用 grep 按 TraceId 过滤所有服务的日志，一样能还原调用链。

5.5 常见问题速查表

写在最后的一些实际体会

这个项目做完之后我最大的体会是：微服务架构本身并不难，难的是在拆之前想清楚业务边界、在拆之后管好服务治理。如果业务不复杂、团队也不大，老老实实用单体加前后端分离完全没问题；但如果你明确知道系统要长期演进、要多团队协作、要对接更多外部系统，那花在微服务架构上的投入是值得的。

另外有个小建议：这类系统在开发时一定要把权限模型设计放在业务开发之前。医院信息系统涉及科室数据隔离，比如工程师只能看到自己负责科室的工单，这种数据权限如果前期不设计好，后期补起来会牵动所有查询接口，改造成本极高。我的做法是在设备表上维护科室维度，在用户角色上维护数据权限范围，所有涉及列表查询的接口统一在 Service 层注入数据权限过滤逻辑，这个设计直接省掉了后期大量的返工。

最后说一个非常实用的技巧：设备台账的导入功能一定要做。医院里存量设备动辄上千台，靠管理员手动录入不现实。我们做的是 Excel 模板导入，提供了标准的导入模板文件下载、字段校验提示、错误行定位功能。系统上线时设备台账数据的初始化全都靠这个导入功能完成，上线当天导入了一千多条设备数据，从 Excel 导入到校验通过、落库完成，整个过程不到五分钟。

希望这篇分享能给正在做类似微服务管理系统的朋友一些参考。如果你也在做医院相关的信息化系统，欢迎多交流踩坑经验。