说起城市轨道交通安全管理系统，很多人第一反应是设备台账、巡检记录、隐患上报这些琐碎功能。但真正动手做过的人都知道，难点从来不在“把数据存进数据库”，而在“安全”这两个字能不能变成一条可落地的流程。去年我用 Spring Boot 完整搭过一套轨道交通综合安全管理系统，从车站设备隐患的发现、流转、整改，到应急事件处置和实时监测告警，前后迭代了三版，今天把核心设计、关键代码和踩过的坑整理出来，给正在做相关毕设或刚入行的朋友当参考。

这套系统面向轨道运营公司、地铁段场和第三方维保单位，核心价值是把“人防”和“技防”的数据捏在一起。比如某站屏蔽门控制系统报警，巡检人员要能快速上报，值班长要能分级审核，维修工单要能自动生成，完成后还要有验收闭环。没有系统支撑，这类信息很难跨部门流转。对开发者来说，这种项目也特别适合做 Spring Boot 练手，因为它把登录权限、定时任务、消息推送、文件上传、报表统计这些常见能力都串起来了，做完能对后端开发形成一个完整的体感。

1. 系统定位与技术方案选型

1.1 这些功能模块先理清楚

安全管理不等于“一个上报按钮”。我最初接到的需求很零散，今天说加个车站大屏，明天说加个整改提醒，如果不先把模块边界划清楚，后面改代码会非常痛苦。我最终把系统按业务域拆成六个模块，每个模块有独立的 Controller 和 Service 边界：

• 基础数据：线路、车站、设备类型、设备台账，是整个系统的主数据源头。
• 隐患排查：巡检计划、隐患登记、整改验收，是业务流的核心。
• 应急指挥：应急事件上报、处置过程记录、资源调度，偏向流程管理。
• 视频联动：摄像头信息、实时视频地址、截图关联，后续可以直接对接流媒体服务。
• 统计分析：按线路、车站、隐患等级、时间周期输出报表，给管理层看。
• 系统管理：用户、角色、菜单、操作日志，属于所有后台系统的标配。

模块划分时我没一上来就拆微服务，而是先用 Spring Boot 单体应用把完整闭环跑通。原因很简单：轨道交通安全管理系统的核心是流程稳定，不是并发规模。一座车站同时在线操作的人员通常只有几十人，整个平台日活量很有限，单体完全够用，部署起来也更省心，一个 jar 包在服务器上跑起来就算上线了。等到真出现单模块性能瓶颈，再按模块拆出去也不迟。

1.2 技术栈不是越新越好

我给这套系统选定的组合是：JDK 17 + Spring Boot 2.7.18 + MyBatis-Plus 3.5.x + MySQL 8 + Redis 6 + WebSocket + 内置定时任务。这套组合的好处是稳定、资料多、团队上手快。当时 Spring Boot 3 已经发布，但 3.x 基于 Spring Framework 6 和 Jakarta EE，很多旧版的项目结构、Filter 配置、第三方库都要跟着调整。除非整个团队都是新项目、没有历史包袱，否则没必要为了“追新”给自己挖坑。热词里经常刷到“springboot 版本太高”，这个坑确实真实存在，后面我会在排查部分单独讲。

ORM 层我选了 MyBatis-Plus 而不是 JPA，原因是安全管理系统查询条件复杂，报表统计要动态拼接 SQL。MyBatis-Plus 提供Wrapper条件构造器，多条件组合查询只需要几行代码，分页插件很稳定，底层还是 MyBatis，团队里只要会写 SQL 的人都能直接上手。JPA 的自动建表、懒加载机制虽然方便，但遇到复杂的多表关联和性能排查时反而容易绕圈子。

1.3 工程结构与配置层设计

工程结构我参考 Maven 多模块的目录思想，但实际落地时用的是单模块加 package 划分。过早拆模块会让 Spring Boot 的组件扫描和配置引用变麻烦，尤其是@MapperScan、@ComponentScan写错路径，启动就会报找不到 Bean。我常用的目录布局是这样的：

src/main/java └─ com/metro/safety ├─ SafetyApplication.java ├─ config // 全局配置：跨域、Redis、线程池、WebSocket ├─ controller // REST 接口层 ├─ service // 业务层，接口 + 实现 ├─ mapper // MyBatis Mapper ├─ entity // 数据库实体 ├─ dto // 请求/响应对象 ├─ task // 定时任务 ├─ utils // 工具类 └─ security // 认证授权相关

config包里我通常放一个MybatisPlusConfig，配置分页插件和乐观锁插件；再放一个JacksonConfig，统一处理 Java 8 日期序列化格式，避免前端展示“2025-03-15T08:30:00”这种带 T 的字符串。时间问题在轨道交通这类跨平台协作项目里特别容易起冲突，后端数据库、前端展示、业务服务器时区、第三方接口时区经常不一致，最好从第一天就把时间格式和时区规范固定下来。

2. 核心业务流程与数据建模

2.1 安全隐患闭环怎么设计

做安全管理系统，真正的核心不是堆功能，而是把“发现 -> 上报 -> 核验 -> 处置 -> 复查 -> 归档”跑通。我拿最常见的“设备故障隐患”举例：巡检班组在地铁站发现屏蔽门控制系统告警，手机端上报一条隐患，附上现场照片和位置；隐患自动进入待核验池，值班长在管理后台分配核验责任人；核验确认为隐患后，生成整改工单，指定维修班组和期望完成时间；维修班组处理完填写结果，上传修复后的照片；值班长复查通过，隐患状态变为“已闭环”，不通过则打回重新整改；整条记录全程留痕，支持追溯。

这套流程引出两个技术需求：一是状态字段不能只存一个字符串，要有状态机和时间节点；二是每个操作都得有操作人、操作时间、操作内容。因此我在设计阶段就增加了一张audit_log表，统一记录接口层面的关键操作，相当于给系统上了操作审计。这个做法很值得，因为安全管理系统在实际使用中会涉及责任认定，比如某个整改超期了，查日志就能立即判断是哪个环节、哪个操作人导致的，而不是靠开发后补。

2.2 核心表与关键字段

核心表大致包括：线路表line、车站表station、设备台账device、巡检任务device_inspection、隐患记录hazard、隐患处置流程序表hazard_process、应急事件emergency_event、用户表sys_user、角色表sys_role和用户角色关联表sys_user_role。我以hazard表为例，列出几个最容易出问题的字段设计：

这里有个容易被忽略的细节：隐患编号不能只靠数据库自增生成，用户和管理员会在台账里直接看到，打印出来还要能追溯到日期。我是用Redis INCR生成当日递增序号，再拼上前缀和日期，这样既避免数据库自增的并发问题，也让编号有业务含义。另外照片字段不要只存一张，前端一次会上传多张，用 JSON 数组存 URL 列表，简单够用，不需要为此单独建一张附件表。

2.3 风险等级与状态机

风险等级我直接在枚举里定成 1 到 3，前端展示时对应绿、橙、红三种颜色。状态机没有引入复杂的阿图状态机框架，而是用小一组 Service 方法实现，每个方法都检查“当前状态允许哪些操作”。比如“核验确认”只允许从“待核验”变到“整改中”；“整改提交”只允许从“整改中”变到“待复查”。这种判断放到 Service 层，可以防止前端绕过按钮直接调用接口乱改状态。虽然实现简单，但避免了很多脏数据，比如把已经闭环的隐患重新改回整改中，就会导致报表统计口径出错。

为了让状态流更直观，我还在管理后台做了一个简单的流转图，用不同颜色标注每个节点，数据来源就是hazard_process表。这张表记录从上报到归档的每一步明细，字段包括操作类型、操作前状态、操作后状态、操作人、操作时间、处理意见。查询时按hazard_id排序返回，前端就能把整条处理链展示出来。做这种追溯功能对安全系统很有价值，运营方经常会问“这个隐患是谁报的”“整改为什么延误了”，有完整的流转记录就是最有力的回答。

3. Spring Boot 关键功能实现

3.1 工程构建：Maven、依赖与自动装配

构建工具我用的 Maven，版本管理是安全系统最容易翻车的地方。POM 里先确定 parent 版本，我锁定的是spring-boot-starter-parent2.7.18，java.version设为 17。关键的依赖如下：

<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-validation</artifactId> </dependency> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-boot-starter</artifactId> <version>3.5.3.2</version> </dependency> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-redis</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-websocket</artifactId> </dependency> </dependencies>

见过不少新同学在 Maven 配置这里被折磨：MySQL 8 数据库要使用com.mysql.cj.jdbc.Driver，很多旧教程写的com.mysql.jdbc.Driver已经废弃了；数据库连接 URL 里还要记得加serverTimezone=Asia/Shanghai，否则时间字段可能差 8 小时。另外，Spring Boot 之所以能省掉大量手动装配，靠的就是自动装配原理：启动时会扫描META-INF/spring.factories里的自动配置类，再根据条件注解按需加载。比如依赖里有数据源连接和 MyBatis-Plus，它就自动装配对应的DataSource、SqlSessionFactory，你只需要在application.yml里配置连接信息即可。

3.2 认证授权：一套轻量可扩展的方案

安全系统的权限要求比普通后台严格，角色至少要分管理员、站区值班员、维保人员、巡查人员。我第一版直接用 Spring Security + JWT，后来发现这个项目有大量自定义登录校验，比如校验账号是否停用、是否绑定车站、是否能处理某个工单，于是改成过滤器链实现 JWT，缩减了两个依赖。核心逻辑不复杂：

• 登录接口校验用户名密码，成功后生成 token 返回；
• 前端把 token 放到请求头Authorization: Bearer xxx；
• 自定义AuthInterceptor拦截所有/api/**，从 Redis 读取用户权限列表写入ThreadLocal；
• Controller 里的关键方法加上自定义注解@RequireRole("admin")做权限判断。

这样做的优点是灵活，缺陷管理完全由自己控制，不用被 Spring Security 一堆配置类绕晕。如果你不想手写，用 Spring Security + JWT 也完全可行，但至少要配置PasswordEncoder，密码不能明文存储。轨道交通系统内部用户很多，如果后期和统一身份认证对接，这套自定义拦截器也容易改造，只要换成从统一认证服务器取 token 状态就行。

3.3 隐患上报与闭环代码实战

我拿隐患上报接口作为示例。Controller 层不写业务逻辑，只负责参数校验和结果包装：

@PostMapping("/hazard") public Result<Long> createHazard(@Valid @RequestBody HazardCreateRequest req) { Long hazardId = hazardService.create(req); return Result.success(hazardId); }

Service 层是闭环核心，我会在方法上使用@Transactional保证主记录和操作日志同时成功或同时失败：

@Transactional(rollbackFor = Exception.class) public Long create(HazardCreateRequest req) { Hazard hazard = new Hazard(); BeanUtils.copyProperties(req, hazard); hazard.setHazardNo(generateHazardNo()); hazard.setStatus(HazardStatus.PENDING_VERIFY.getCode()); hazard.setCreatedBy(UserContext.currentUserId()); hazard.setCreatedTime(LocalDateTime.now()); hazard.setVersion(1); hazardMapper.insert(hazard); auditLogService.log("新增隐患", hazard.getId(), "上报人提交隐患", null, HazardStatus.PENDING_VERIFY.getCode()); return hazard.getId(); }

这里有个新手特别容易踩的坑：如果一个类内部直接调用自己的@Transactional方法，事务会失效，因为 Spring 的事务是基于代理对象的，只有通过注入的 Service 接口调用才会走到代理。所以 Controller 里必须注入 Service 接口，不要用this调用同类的另一个方法。想要保证性能，也尽量别在事务里做太多外部调用，比如把图片上传到 OSS 这种 IO 操作放到事务前后去执行，不然一个慢接口会把数据库连接池拖住。

3.4 定时巡检与实时告警推送

安全管理系统有大量“到期未处理”提醒，我用两个方案覆盖。第一个方案是@Scheduled定时任务，每天凌晨扫描逾期未整改的隐患，生成提醒记录，并通过企业微信机器人推送通知。代码很简单：

@Component public class HazardTimeoutTask { @Scheduled(cron = "0 0 1 * * ?") public void scanTimeoutHazard() { List<Hazard> list = hazardMapper.selectTimeoutHazards(); for (Hazard h : list) { notifyService.push("隐患 " + h.getHazardNo() + " 已超过整改时限，请及时处理"); } } }

定时任务可以配合@EnableScheduling启用。默认是单线程串行执行，如果多个任务同时运行，最好在配置里指定调度线程池大小，或者给每个任务设置错峰执行的 cron，避免互相等待。

第二个方案是实时告警。设备端上报的数据推送到操作台页面，比如某个车站传感器超过阈值，后端通过 WebSocket 推送给关注该车站的用户。我写了一个简单的WebSocketSessionManager维护用户在会话中的连接，推送时根据stationId找到对应 session 发送消息。注意 WebSocket 的 Session 不是线程安全的，高并发推送偶尔会报IllegalStateException，需要做同步处理，或者用 Spring 提供的ConcurrentWebSocketSessionDecorator包装一下，这样推送会更稳。

4. 前端集成与部署上线

4.1 Vue 项目怎么打包进 Spring Boot

这个环节也是反复踩坑的地方。Vue 项目执行npm run build后生成dist目录，很多人以为必须用 Nginx 单独部署一套前端。其实也可以直接把dist/下所有文件复制到工程的src/main/resources/static/目录，重新打包后直接访问http://IP:8080，所有页面都由 Spring Boot 提供。这样部署成本最低，一个服务搞定前后端。

这里的关键点是 Vue 路由如果使用history模式，路径里没有#，刷新页面时 Spring Boot 接收不到/station/detail这类路径，会直接报 404。解决办法是加一个WebMvcConfigurer，把所有非/api的 GET 请求转发到index.html：

@Configuration public class WebConfig implements WebMvcConfigurer { @Override public void addViewControllers(ViewControllerRegistry registry) { registry.addViewController("/{path:[^\\.]*}") .setViewName("forward:/index.html"); registry.addViewController("/{path:^(?!api$).*}/**/{path:[^\\.]*}") .setViewName("forward:/index.html"); } }

另一种更省事的方式是让前端使用hash模式，路径上会多一个#，看起来不如 history 美观，但部署时完全不用额外配置。我的个人建议是：正式交付的项目尽量用 history 模式加转发配置，用户体验更好；如果只是开发自测或者毕设演示，用 hash 模式能省很多麻烦。

4.2 Docker 与宝塔部署配置

部署时我用了宝塔面板的 Docker 管理器，Dockerfile 写得很简单：

FROM openjdk:17-jdk-alpine WORKDIR /app COPY target/safety-manager.jar /app/safety-manager.jar EXPOSE 8080 ENTRYPOINT ["java", "-jar", "safety-manager.jar", "--spring.profiles.active=prod"]

因为前端静态资源和后端 jar 已经打包在一起，容器内不需要再装 Nginx。这是单体方案最舒服的地方：一个容器包含前后端，升级时只要重新构建镜像，替换容器即可。

数据库和缓存我用 docker-compose 一起编排：

version: "3.8" services: app: build: . ports: - "8080:8080" environment: - SPRING_DATASOURCE_URL=jdbc:mysql://mysql:3306/safety_db?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai - SPRING_REDIS_HOST=redis depends_on: - mysql - redis mysql: image: mysql:8.0 environment: - MYSQL_ROOT_PASSWORD=root123 - MYSQL_DATABASE=safety_db redis: image: redis:6-alpine

这里主要用到了 Spring Boot 的外部化配置特性：环境变量以SPRING_为前缀，启动时自动覆盖application.yml里的配置项。所以开发环境和生产环境不需要维护两套代码，只要在容器里分别传入不同的环境变量即可。在宝塔面板中，可以先拉取镜像、创建容器，也可以直接用 Docker-Compose 管理整个服务栈，启动命令无非就是docker-compose up -d，比起手动配置 MySQL 和 Java 环境省心很多。

5. 常见问题与排查实录

5.1 版本坑：Spring Boot 版本太高带来的麻烦

热词里刷到最多的“springboot 版本太高”不是段子，是真坑。Spring Boot 3.x 把javax.*改成了jakarta.*，如果代码里引用了老版本的 Swagger2、springfox之类依赖，启动时就会报符号找不到。我遇到过一位同学项目里用了 Spring Boot 3.2 和 JDK 21，结果第三方 OCR 库报反射访问限制，折腾了一整天才发现要加--add-opens启动参数。我的建议是新手尤其要锁定稳定版本，选 2.7.18 或 3.1.5 都可以，不要盲目使用 latest，也不要随便升级补丁版本后不做回归测试。实际项目管理时，版本升级必须先看发版公告里的 breaking changes，再决定是否升级。

5.2 数据一致性与并发问题

隐患状态变更时，两个值班员同时操作同一条隐患，可能出现状态互相覆盖。我第一版用了悲观锁，后来改成 MyBatis-Plus 乐观锁，其实在低并发场景下更好用。操作逻辑是：更新之前检查实体里的version字段，执行UPDATE hazard SET status=?, version=version+1 WHERE id=? AND version=?，如果影响行数为 0，说明数据已经被别人改过，前端就提示“当前隐患状态已被更新，请刷新后重试”。这种方案不用锁表，对在线人员不多的系统来说够用也稳定。

并发问题还体现在重复提交。用户连续点击两次“提交”按钮，后端会生成两条工单。我在后端接单接口做了幂等处理，用Redis SETNX把请求唯一号放进去，30 秒内再次提交直接拒绝。前端也要做防重复提交状态，比如点击按钮后置灰，但后端兜底是必须的，因为接口可以被绕过前端直接调用。

5.3 MyBatis 与事务失效问题

我遇到最典型的问题是在 Service 里循环调用单条 insert，导入几千条隐患记录能把数据库拖慢。后来改成 MyBatis-Plus 的saveBatch()或自定义批量 insert 的foreach，性能提升非常明显。第二个问题是@Transactional不生效，原因通常是方法被private修饰、或者同类内部调用、或者异常被 catch 住了没有往外抛。排查时先看异常是否在事务边界内抛出，再看代理有没有生效，不要一上来就猜数据库。

还有一个容易被忽略的点：如果把整个导入操作放到一个事务里，几千条数据中间只要错一条，全部回滚，反而会让用户找不到错在哪。我的做法是导入时分批提交，每批 200 条，失败时记录错误行号和原因，这样用户能拿到准确的失败清单，而不是只看到“导入失败”四个字。

5.4 部署后的运维细节

系统上线后最容易被忽略的是日志。Spring Boot 默认只输出控制台，一旦服务重启，问题就无据可查。我给项目加了logback-spring.xml，按天滚动保留 15 天日志，同时在配置里区分dev和prod输出级别，测试环境打 INFO，生产环境打 WARN 以上，减少不必要的日志量。线上排查问题时，通常会开启某个包的 DEBUG 日志，然后用grep过滤关键字，效率很高。

另外，MySQL 和 Redis 一定要设置密码，不要用默认配置直接暴露在公网。轨道交通系统涉及设备状态和应急信息，虽然不算高密级系统，但安全底线还是要守住。运维监控可以接一个简单的健康检查接口，Spring Boot 本身就提供了actuator/health，接入宝塔的监控告警后，服务异常时能第一时间收到通知。

我实际做完这一套之后最大的体会是，这类安全管理系统并不需要太复杂的中间件，最核心的是把业务闭环做严实、把权限审计做清楚、把异常提示做得让人看得懂。如果你未来想扩展，可以从消息队列和时序数据库入手，把设备传感器数据接入进来，在架构里预埋 TDengine 之类的时序库，记录风机、电能表、环境传感器的高频数据，Spring Boot 只需要增加一个接入模块就能和大屏联动。前期流程梳理得越细，后面的代码修改就越少。做这种系统前，一定要先跟使用者聊一遍实际作业流程，再开始写代码，很多返工都源于把状态流转想得太简单了。