我记得很清楚这个项目是被一张Excel表格逼出来的。公司IT部门的同事在群里发来一份台账截图三百多台设备IP、位置、负责人、维保日期密密麻麻排了几十列他说每个月都要手动核对一遍设备状态哪台服务器宕机了全靠感觉和同事之间口口相传。当时我就觉得这种重复性操作完全可以用一套小型系统替代——设备台账在线管理、状态自动巡检、异常主动告警人员只需要打开一个网页就能看到整个内网的运行情况。于是就有了这套基于Java SpringBoot Vue3 MyBatis MySQL的企业内部小型网络管理系统。前后端分离部署在公司内网一台普通服务器上不对外网暴露覆盖的设备规模在几百台量级使用人数也就是IT部门加各业务线接口人几十个账号。系统功能包含设备台账管理、IP资源管理、自动巡检与告警中心、用户权限、操作日志等模块。后端SpringBoot提供REST接口和定时任务MyBatis负责持久层MySQL做数据存储前端Vue3配合Element Plus搭建管理界面和监控大屏。这篇文章我不打算写成从零到一的手把手教学而是站在一个已经上线运行、正在持续维护的开发者视角把架构决策、数据库设计、关键模块实现、以及联调部署过程中实打实踩过的坑一次讲清楚。如果你正在规划企业内部的小型管理系统不管方向是网络管理、资产登记还是其他内部工具这套组合和思考路径都可以直接借鉴。1. 从一张Excel台账说起系统到底要做成什么样1.1 需求边界哪些功能真的需要写代码很多内部系统死在第一阶段——需求没边界。我们当时和IT部门聊需求对方一口气提了十多个功能点设备管理、IP管理、固件信息、巡检记录、告警、工单、知识库、报表、大屏……如果全做这套系统就不是小型了而是需要一个专门团队维护三年。我的做法是先问三个问题现在最痛的是什么哪些流程是每周都要重复的哪些数据丢了会出事答案分别是设备状态不透明、每月台账核对费时、设备变更没有记录。基于这三个问题最终把需求收敛成五个模块设备台账管理设备的新增、编辑、删除、导入导出关键字段包括设备名称、类型、IP、MAC、所在位置、负责人、维保日期、备注。IP资源管理统一登记内网IP段、子网掩码、网关、VLAN和使用状态避免这台机器占的IP到底是谁的这种扯皮问题。自动巡检与告警定时探测设备连通性离线或超时自动生成告警记录支持按设备、按类型筛选和人工确认处理。用户与权限账号登录、角色区分管理员、普通用户、只读用户控制谁能改设备信息、谁能处理告警。操作日志记录所有用户的关键操作出问题时能追溯。注意我刻意砍掉了工单系统和知识库模块。不是说这些没用而是内部小系统最怕功能堆砌。工单涉及审批流程和状态流转知识库涉及日常内容维护这两个功能一旦做进去光需求沟通就能耗掉整个项目时间的三分之一。小系统的核心竞争力是快、稳、准不是大而全。1.2 技术选型为什么是SpringBootVue3MyBatis而不是别的技术选型这件事内部工具和商业产品完全是两个逻辑。商业产品要考虑招聘成本、生态适配、长期演进内部工具更看重团队能不能快速上手、部署是否简单、出了问题有没有人接得住。我们当时的选型理由非常直白。SpringBoot不用多说Java后端最主流的框架之一约定优于配置内嵌Tomcat打一个jar包就能跑非常适合内部系统这种扔到一台服务器上就不管的部署模式。版本方面当时选了SpringBoot 2.7.x这个版本生态成熟Spring Cloud、MyBatis各种组件的兼容说明都很齐全。后来我见过一些新项目直接上SpringBoot 3.x结果遇到各种依赖兼容问题虽然都能解决但对内部小工具来说没必要抢这个新稳定排第一。MyBatis vs JPA我们选了MyBatis。理由有三条第一设备巡检、告警统计这类查询有大量动态条件组合MyBatis的动态SQL写起来更直观第二团队里对SQL本身更熟悉维护XML成本低第三内部系统的表结构和查询逻辑相对固定不需要JPA那种自动建表、懒加载等重特性。这里多说一句MyBatis的缓存机制默认情况下是生效的但内部系统数据变更频繁我直接显式关闭了二级缓存只保留一级缓存减少改了数据库前端页面看不到更新的诡异问题。前端选Vue3而不是Vue2一方面Vue3已经是主流组合式API写起来比选项式API清爽太多配合Vite构建速度也快另一方面Element Plus只支持Vue3后台管理界面直接拿它做表格和表单能省大量UI时间。数据库就用MySQL内网规模的数据量MySQL 5.7.44完全够用稳定、资料多、遇到问题搜一下就有答案。整套选型下来没有一个是追新的但每一个都是这个场景下最省心的选项。2. 数据库设计五张核心表撑起整个业务2.1 设备表与IP资源表的设计思路数据库是这类系统的地基。我见过不少项目代码写得花里胡哨结果表结构一塌糊涂查询慢、冗余杂、扩展难。这套系统的核心表一共五张设备信息表、IP资源表、告警记录表、用户表、操作日志表。下面重点说设备表和IP资源表。设备信息表device_info的关键字段字段名类型说明idbigint主键自增device_namevarchar(128)设备名称例如核心交换机-01device_typevarchar(32)设备类型服务器、交换机、路由器、终端、打印机等ip_addressvarchar(64)管理地址支持一个设备多个IP逗号分隔mac_addressvarchar(64)MAC地址locationvarchar(128)所在位置精确到机房/机柜编号responsible_uservarchar(64)负责人姓名maintenance_datedate维保到期日statustinyint在线状态0未知、1在线、2离线last_check_timedatetime最近一次巡检时间remarkvarchar(255)备注create_time / update_timedatetime创建与更新时间IP资源表ip_resource单独建表因为设备与IP不是简单的多对一关系。一台设备可能绑定多个IP管理口、业务口一个IP也可能在规划中从这台设备改绑到另一台设备。单独一张表登记IP段、掩码、网关、VLAN和使用状态查询某个IP现在被谁占用就非常直接不用去设备表里做字符串匹配。这里有个设计细节值得提不要把状态字段存成字符串在线/离线而是用tinyint存数字前端映射显示。原因很简单状态值未来可能扩展比如维护中、已下线数字编码比字符串更灵活也方便写告警规则的逻辑判断。索引方面我对device_type、status、ip_address分别建了普通索引因为设备管理页面的默认查询条件就是这几个字段的组合。这套表结构上线半年没有做过一次结构调整说明当初设计是够用的。2.2 告警记录与操作日志别小看这两张表告警记录表alert_record我一开始想得很简单无非就是巡检发现离线就插一条记录。但真正上线后才发现告警表的设计直接决定了运维人员愿不愿意用这个系统。原因在于告警噪音——如果一台机器离线五分钟就弹一条告警一天下来告警列表能刷几百条没人看系统也就废了。所以告警表加上了几个关键字段alert_type告警类型连通性、超时等、alert_level严重程度提示、警告、严重、status未处理、处理中、已关闭、连续失败次数fail_count。巡检任务发现设备离线时不会立即生成告警而是连续失败三次默认值可配置才生成一条正式告警这样能有效过滤瞬时抖动。人工处理告警时记录处理人和处理备注告警管理才能形成闭环。操作日志表operation_log就更不能省了。内部系统最怕的不是功能少而是出了问题不知道是谁改的、什么时候改的。我在系统中做了一个非常简单的操作日志切面用Spring AOP在增删改接口上统一记录用户、IP、操作类型、目标对象、操作内容、时间。代码量不大但效果显著——有一次一台服务器IP被误改导致业务中断就是靠操作日志查出来是某位同事半小时前做的变更操作一分钟定位问题。这种审计能力平时没人夸真出事的时候能救命。2.3 MyBatis动态SQL处理复杂查询条件的实战写法设备管理页面的查询条件至少有设备名称模糊搜索、设备类型筛选项、IP精确查询、负责人查询、状态筛选、维保日期区间。如果每个组合都写一条SQL那代码能写到天荒地老。MyBatis的动态SQL就是专门解决这个问题的。select idqueryDeviceList resultTypecom.example.entity.DeviceInfo SELECT id, device_name, device_type, ip_address, mac_address, location, responsible_user, maintenance_date, status, last_check_time FROM device_info where if testdeviceName ! null and deviceName ! AND device_name LIKE CONCAT(%, #{deviceName}, %) /if if testdeviceType ! null and deviceType ! AND device_type #{deviceType} /if if testipAddress ! null and ipAddress ! AND FIND_IN_SET(#{ipAddress}, ip_address) /if if teststatus ! null AND status #{status} /if if testmaintenanceStart ! null AND maintenance_date gt; #{maintenanceStart} /if if testmaintenanceEnd ! null AND maintenance_date lt; #{maintenanceEnd} /if /where ORDER BY create_time DESC /select注意两个细节。第一模糊查询用CONCAT包裹参数而不是直接用LIKE #{deviceName}防止用户输入%或_导致查询范围异常扩大第二IP查询用FIND_IN_SET而不是LIKE因为设备表里IP是逗号分隔的多值字段LIKE会把192.168.1.1误匹配成192.168.1.11这种隐蔽BUG排查起来很费劲。分页用的是MyBatis的PageHelper插件在Service层直接PageHelper.startPage(pageNum, pageSize)然后执行查询即可返回的PageInfo里自动带总条数。还有一个日常特别有用的配置是把SQL打印打开在application.yml里设置mybatis: configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpllog-impl输出到控制台联调期看SQL一目了然。虽然生产环境不建议一直打印SQL但内部系统用户量小开着也无妨排查问题效率高很多。map-underscore-to-camel-case这个配置必须开否则数据库的下划线字段映射到Java驼峰属性会全部变成null。3. SpringBoot后端的三个关键实现3.1 JWT登录认证与拦截器的轻量实现内部系统不需要上Spring Security OAuth2那一套重方案JWT 拦截器完全够用。登录接口校验用户名密码后生成一个有效期为8小时的JWT Token返回给前端。前端把Token存到localStorage每次请求在Header里带上Authorization: Bearer 。后端拦截器里校验Token的核心逻辑我放在一个HandlerInterceptor里public class AuthInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { String token request.getHeader(Authorization); if (token ! null token.startsWith(Bearer )) { try { Claims claims JwtUtil.parseToken(token.substring(7)); request.setAttribute(userId, claims.get(userId)); request.setAttribute(userRole, claims.get(role)); return true; } catch (Exception e) { // token无效或过期 } } response.setStatus(401); response.setContentType(application/json;charsetUTF-8); response.getWriter().write({\code\:401,\msg\:\登录已过期请重新登录\}); return false; } }这里有几个细节。JWT的密钥不能写死在代码里放在配置文件中并且定期更换Token里只放userId和role这类非敏感信息绝不能放密码拦截器只拦需要登录的路径登录接口本身、静态资源、健康检查路径要放行。角色权限我这里直接通过注解判断比如RequireRole(admin)在拦截器里根据request.getAttribute(userRole)做校验比引入完整权限框架轻量得多。JWT方案最大的坑是过期这个状态是服务端无法主动控制的——Token一旦签发在过期前都是有效的即使你把用户从系统里删除他手里的Token依然能访问接口。所以对内部系统来说Token有效期不能太长8小时是一个比较平衡的设置真要强制下线可以在用户表加一个token_version字段生成Token时带上拦截器校验版本号不一致就拒绝。这个方案我是在第二版迭代时补上的成本很低但补上了才觉得安心。3.2 设备状态巡检的定时任务与线程池设计巡检功能是这套系统的灵魂。最开始的想法很简单SpringBoot的Scheduled注解定时执行一个方法遍历所有设备调用InetAddress.isReachable(ip)判断在线与否。但实践很快暴露了问题内网设备数量虽然只有几百台但逐台串行检测一台超时算5秒几百台就是几十分钟巡检周期根本压不下去。解决方案是引入线程池并发巡检。用Async配合ThreadPoolTaskExecutor将设备列表分批提交每批并发探测。我这里线程池核心线程数设置为20最大线程数30队列容量500对几百台设备的量级完全够用。ping超时时间设置为3秒通过InetAddress的配置参数控制。spring: task: execution: pool: core-size: 20 max-size: 30 queue-capacity: 500 thread-name-prefix: device-check-巡检逻辑本身有一个容易忽视的点——不是每次ping失败都要立刻更新设备状态。我维护了一个连续失败计数器设备连续N次ping不通才标记为离线并生成告警中间任何一次成功都会把计数器清零。这样临时网络抖动、设备重启等场景不会误报告警列表里不会堆满假故障。巡检任务的定义用cron表达式控制频率比如每5分钟执行一次0 */5 * * * ?。同时要注意定时任务编排和执行任务不要用同一个线程池避免巡检任务堆积时影响其他业务接口的响应。实测下来300台设备并发巡检一轮大约40秒完全满足5分钟一轮的巡检频率。如果你后续想扩展巡检维度比如磁盘空间、CPU负载可以在设备表上加扩展字段再通过SNMP协议去采集逻辑上是能平滑演进的。3.3 统一返回结构与全局异常处理的细节前后端分离项目最怕接口返回结构不统一。有的接口返回 {code: 0, data: {...}}有的直接返回data对象有的错误直接抛个500前端写着写着就心态崩溃。我一开始就定了统一返回结构public class ResultT { private int code; // 0成功非0失败 private String msg; // 提示信息 private T data; // 业务数据 }配合全局异常处理器RestControllerAdvice保证所有异常都被转成这个结构返回。业务异常抛自定义BizException参数校验失败抛MethodArgumentNotValidException兜底异常捕Exception各自映射到不同的错误码和提示文案。这样前端只用处理一种数据结构判断code是否为0即可不需要针对不同接口写不同的错误解析逻辑。全局异常处理里最容易忽略的是404和405的处理。SpringBoot默认对不存在的接口返回Spring默认错误页前端拿到的是HTML而不是JSON页面逻辑直接乱掉。我在异常处理器里单独加了NoHandlerFoundException的兜底并且在application.yml里设置了spring.mvc.throw-exception-if-no-handler-foundtrue、spring.web.resources.add-mappingsfalse确保请求找不到处理器时也会走进全局异常处理器返回JSON。这个小细节能为前后端联调省下一堆摸不着头脑的排查时间。4. Vue3前端的搭建与核心页面实现4.1 用Vite初始化项目并规划目录结构前端部分用Vite来初始化Vue3项目。之所以没用vue-cli是因为Vite的冷启动和热更新在开发阶段太舒服了npm run dev基本秒开这也是Vue3官方主推的方向。npm create vitelatest network-admin -- --template vue项目目录结构我一开始就规划好了后期没有返工src/ ├── api/ # 接口请求封装按模块拆分 ├── components/ # 通用组件 ├── views/ # 页面视图 │ ├── dashboard/ # 监控大屏 │ ├── device/ # 设备管理 │ ├── ipresource/ # IP资源 │ ├── alert/ # 告警中心 │ └── system/ # 用户与日志 ├── router/ # 路由配置 ├── store/ # Pinia状态管理 ├── utils/ # 工具函数含axios封装 └── layout/ # 后台布局框架这套目录结构有个隐形的收益新成员看一眼目录就知道每个功能代码在哪里不需要追着问。Vue3的项目脚手架、官方文档、以及各类后台管理模板现在都很成熟照着官方文档搭建环境、结合一个模板做页面骨架能省很多时间。我当时就是先把Vue3官网的组合式API文档通读了一遍再动手写的前期费点功夫后期写代码非常顺。4.2 Axios封装、Token注入与401统一处理Axios封装是前端最关键的基础设施。我把所有请求收敛到一个utils/http.js里统一做BaseURL设置、Token注入、响应拦截和错误提示。import axios from axios import { ElMessage } from element-plus import router from /router const http axios.create({ baseURL: /api, timeout: 15000 }) // 请求拦截器注入Token http.interceptors.request.use(config { const token localStorage.getItem(token) if (token) { config.headers.Authorization Bearer ${token} } return config }) // 响应拦截器统一处理业务码和HTTP状态码 http.interceptors.response.use( response { const res response.data if (res.code 0) { return res.data } if (res.code 401) { localStorage.removeItem(token) router.push(/login) return Promise.reject(new Error(登录已过期)) } ElMessage.error(res.msg || 请求失败) return Promise.reject(new Error(res.msg || 请求失败)) }, error { if (error.response error.response.status 401) { localStorage.removeItem(token) router.push(/login) } else { ElMessage.error(网络异常请稍后重试) } return Promise.reject(error) } ) export default http401统一处理这里有个常见的坑如果登录页本身也调用了需要认证的接口一旦Token过期被踢到登录页登录页再去请求接口又返回401就会形成循环跳转。我的解决办法是在响应拦截器里判断当前路由是否是登录页是的话就不再执行router.push。这个小判断在联调阶段救了我不少次。4.3 设备监控大屏里的reactive状态设计监控大屏是这套系统的门面也是Vue3组合式API大展身手的地方。我用reactive维护大屏的整体状态包括设备总数、在线率、告警数、各类型设备分布等。import { reactive, ref, onMounted, onUnmounted } from vue const dashboardState reactive({ totalDevices: 0, onlineCount: 0, offlineCount: 0, alertCount: 0, deviceTypeStats: [], recentAlerts: [] }) let pollTimer null async function loadDashboardData() { const data await getDashboardStats() dashboardState.totalDevices data.total dashboardState.onlineCount data.online dashboardState.offlineCount data.offline dashboardState.alertCount data.alert dashboardState.deviceTypeStats data.typeStats dashboardState.recentAlerts data.recentAlerts } onMounted(() { loadDashboardData() pollTimer setInterval(loadDashboardData, 30000) // 30秒轮询一次 }) onUnmounted(() { if (pollTimer) { clearInterval(pollTimer) } })这里最容易被忽略的是定时器的清理。Vue3组件销毁后如果setInterval还在跑回调里调用API会报错造成内存泄漏和资源浪费。onUnmounted里clearInterval是必须的。另外reactive适合放嵌套对象和数组这类需要深层响应式的数据如果只是简单的数字或布尔值用ref更轻量。还有一点30秒轮询对大屏是合理频率但千万别用1秒一次后端压力大页面性能也扛不住。如果内网设备多了建议改成WebSocket推送但当前这个量级轮询完全没问题。5. 联调、部署与维护阶段踩过的坑5.1 跨域与Token过期联调期最磨人的两个问题前后端分离项目跨域是第一个绕不开的坑。开发阶段Vite的proxy配置能解决一大半// vite.config.js server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }这样前端请求/api/xxx会被转发到后端的8080端口浏览器看到的请求是同源的不会有跨域问题。生产环境我直接用Nginx的location转发做同样的事。但这里要注意Nginx的转发和后端的CORS配置只能二选一。如果你Nginx已经代理了后端再配CORS允许跨域两套逻辑叠加有时候反而会出现奇怪的预检请求报错。我的做法是生产环境走Nginx代理代码里不配CORS开发环境走Vite proxy后端也不配CORS统一保持干净。Token过期问题在联调期也折磨了我挺久。场景是这样的用户一直挂着页面Token过期后下一个请求返回401前端跳转到登录页。但跳转之后原来页面上的数据操作已经丢了用户重登之后还得重新点进去体验很割裂。后来我在前端加了一个静默续期机制——Token还有30分钟过期时前端会在页面空闲时调用一个refresh接口换新Token后端签发refreshToken的有效期是24小时。这个机制做进去之后内部同事的反馈好了很多至少不会动不动被踢出去重新登录。5.2 MySQL 5.7安装与中文乱码整改记录数据库这一块踩的坑比想象中多。当时在Windows内网服务器上装MySQL 5.7.44下载解压版之后配置my.ini启动服务基础流程挺顺利。但第一天导入设备数据就发现中文全变成了问号典型的字符集问题。MySQL 5.7的默认字符集是latin1必须显式改成utf8mb4。我的my.ini关键配置如下[mysqld] character-set-serverutf8mb4 collation-serverutf8mb4_general_ci init_connectSET NAMES utf8mb4 [client] default-character-setutf8mb4注意三个层面的字符集必须一致MySQL服务端、数据库表、JDBC连接URL。JDBC连接串一定要加useUnicodetruecharacterEncodingutf8mb4否则Java层和数据库层字符集不一致中文照样出问题spring: datasource: url: jdbc:mysql://localhost:3306/network_admin?useUnicodetruecharacterEncodingutf8mb4useSSLfalseserverTimezoneAsia/Shanghai另外提一个排序的问题。MySQL里中文排序默认按拼音如果你需要按笔画排序要用utf8mb4_bin或者指定其他排序规则。内部系统查询设备列表默认按更新时间倒序就够了这一点比较省心。但如果你想按设备名称做首字母索引那最好在设备名称字段上单独设计一个拼音字段避免数据库层面做复杂的排序计算否则数据量上来之后查询性能会受影响。5.3 部署到内网服务器后的日常运维建议部署阶段我把整个系统做成了两个构建物后端一个jar包前端一堆静态文件再接一个Nginx配置。后端用Maven打包mvn clean package -DskipTests java -jar network-admin.jar --spring.profiles.activeprod前端构建npm run build构建产物放到Nginx的html目录下配置一个location /api反向代理到后端。整个部署过程十分钟内能完成对内部系统的更新频率来说非常够用。如果你用了宝塔面板也可以用它的Docker或Java项目管理器来自动化这个过程但我个人觉得内部小系统直接jar包系统服务的方式反而更直观少一层抽象少一类问题。持续维护方面有几件事我会建议坚持做。第一MySQL每天凌晨做一次mysqldump备份保留最近7天脚本挂到系统计划任务里出意外可以快速恢复。第二后端日志要设置滚动切割logback按天滚动保留30天防止日志文件把磁盘撑爆。第三关键配置一定放到application-prod.yml里和环境无关的配置放公共部分避免改一次环境动一次代码。第四在部署机上放一个health.sh脚本定期curl健康检查接口发现服务挂了就自动拉起jar包进程内部系统没有值班同事这种脚本能省掉很多半夜被叫起来的痛苦。还有一个容易忽略的点是前端构建产物的体积。Element Plus要按需引入可视化图表库如果直接用完整包构建产物会非常大。我当时用了按需加载首屏大小控制在300KB左右内网访问基本秒开。这个细节对内部系统体验提升非常明显。关于MyBatis的缓存再说最后一句如果你关掉了二级缓存一定要在配置里显式标注cache-enabledfalse不要依赖默认行为。因为一旦某个查询被某些操作触发缓存命中会出现数据更新后查出来还是旧值的情况内部系统数据一致性比性能重要得多。系统上线到现在运行了大概半年我最大的感受是企业内部小型系统的成败很多时候不取决于技术有多先进而取决于需求是否收敛、数据结构是否清晰、运维是否省心。SpringBoot Vue3 MyBatis这套组合之所以适合不是因为它新而是因为它把够用、稳定、易维护这三个词占全了。翻一遍这套系统的代码几乎找不到什么炫技的地方但每个功能都在解决实际问题。当然也有遗憾。如果重新做一次我会把设备资产的变更审批流程在一开始就纳入设计范围而不是后期打补丁前端的大屏组件也会在选型阶段就确认好避免中途切换图表库。这些小问题不影响系统正常运行但对后续扩展确实有些影响。最后给一个实用的小技巧内部系统上线后一定要在告警通知里接入企业微信或钉钉的WebHook。设备离线时系统在网页上弹告警没人盯着页面等于白搭但接入聊天工具的消息推送后IT部门的同事手机上就能收到通知这才是主动告警该有的样子。这个功能我是在系统上线第二周加上去的虽然只是多了一个HTTP调用但对实际运维效果的提升是质变级的——毕竟内部系统的最终目的是让每一个异常都能在最短时间内被该知道的人知道。