拓冰网站定制 
看到“企业级健身俱乐部网站管理系统源码SpringBootVueMyBatis架构MySQL数据库【完整版】”这个标题的时候我第一反应是这又是一个典型的“全栈业务系统”项目但真正把它做扎实的人并不多。健身俱乐部这种实体门店业务链条长、角色多、数据敏感会员充值、私教预约、团课排课、收银对账、卡券核销随便拎一个模块出来都够写一堆业务逻辑。标题里这几个关键词——SpringBoot、Vue、MyBatis、MySQL——组合在一起正好覆盖了后端框架、前端渲染、ORM持久层和关系型存储这条最主流的技术路线。这篇博文我就围绕这个系统的完整实现来聊从项目拆解到数据库建模从后端代码到前端集成再到部署上线和踩坑实录把整个项目的设计思路和落地细节一次讲透。这套系统解决的核心问题是一个健身俱乐部从会员办卡、预约上课、到门店收银、经营统计的完整业务闭环。它适合三类人参考一是准备做毕业设计或简历项目的同学二是想学习SpringBootVue前后端分离项目如何整合的开发者三是健身房IT部门或外包团队想快速搭建管理系统的实施人员。我不打算按“功能列表”那样平铺直叙而是按我实际开发这类系统时的思考路径来展开把每一步为什么这么做讲清楚。1. 项目整体设计与技术选型思路很多人拿到项目源码的第一件事就是看目录结构、跑Demo但我觉得先把技术选型和模块边界想明白更重要。技术选型决定了这个项目能走多远模块边界决定了后续加功能会不会把代码改成一团乱麻。1.1 为什么是SpringBootVueMyBatisMySQL这套组合先说结论这套组合不是性能最强的也不是最时髦的但它是“企业级业务系统”里最稳妥、最利于维护的组合之一。SpringBoot负责后端接口服务它的核心价值是“约定大于配置”内置Tomcat自动装配配合Maven或Gradle能快速打出一个可部署的Jar包。我做过几个类似的管理系统SpringBoot的生态成熟度摆在那里无论是做权限Spring Security或Shiro、做缓存Redis、做文件存储MinIO还是做定时任务Quartz都能找到大量现成文档招人也容易。Vue负责前端页面。Vue3的Composition API配合Vite构建开发体验比Vue2提升了不少但市面上大量存量项目还是Vue2Element UI所以看到这个标题源码的时候不用纠结“为什么不用React”Vue在国内企业级的普及率决定了它在管理系统这个领域就是默认选项。MyBatis作为持久层框架和JPA走了完全不同的路线。JPA适合强对象模型、表结构简单的场景而健身俱乐部这种业务SQL里有大量统计查询、多表联查、条件动态拼装MyBatis的XML文件能把每条SQL都清晰管起来。特别是跑报表的时候“本月私教课消课率”、“会员卡即将到期名单”这种SQL自己写SQL比让ORM自动生成靠谱得多。MySQL是数据库的守成者。这套系统数据量不会到千万级单库单表完全能扛住。之所以不选PostgreSQL或Oracle主要是运维成本和人员熟悉度的考量中小企业的服务器上装MySQL是默认操作utf8mb4字符集、事务隔离级别、主从同步这些机制也符合项目当前量级。注意选型这件事没有绝对的对错关键是“团队熟悉什么”和“业务需要什么”。如果团队主攻Node.js那用NestJSTypeORM也完全可以但既然标题定的是SpringBootVue那整套代码的风格、异常处理、分层结构都要向这套生态看齐。1.2 系统模块划分与权限模型我把系统拆成了七个核心模块每个模块对应一个前端菜单组和后端Controller分组模块核心功能对应实体会员管理会员信息、会员卡、余额变动、积分Member, MemberCard, BalanceLog课程管理私教课、团课排期、教练管理Trainer, Course, CourseSchedule预约管理会员约课、取消、排队Appointment, AppointmentLog收银中心商品销售、办卡充值、退款SaleOrder, OrderItem, RechargeRecord营销卡券优惠券发放、核销、过期管理CouponTemplate, UserCoupon统计报表营收趋势、课程消耗、会员增长Dashboard, ReportQuery系统管理账号、角色、菜单、操作日志SysUser, SysRole, SysMenu权限模型用最经典的RBACRole-Based Access Control也就是“用户-角色-权限”三层结构。我见过很多毕业设计把权限直接写在User表里加一个“isAdmin”字段这样做初期很快但一旦出现“前台收银员只能看会员列表但不能看财务报表”这种需求就得改表结构。RBAC把角色和权限解耦新建一个角色、勾选菜单权限即可。后端用JWT做无状态登录认证用户登录成功后返回Token前端把Token存在localStorage或Pinia里每次请求在拦截器中带在Authorization头中。SpringBoot侧用一个拦截器或Spring Security过滤器解析Token解析成功就放行并从Token里取出userId和角色信息。这里我建议不要用Spring Security的重型配置而是用一个自定义的AuthInterceptor配合注解RequirePermission(member:list)代码量小、逻辑直观也方便初学者理解权限控制是怎么一回事。2. 数据库建模与核心业务表设计业务系统最讲究的就是表结构设计。表设计决定了后续写SQL是顺手还是抓狂。健身俱乐部这个项目核心表大约二十张左右我挑几个关键域说清楚。2.1 会员域表结构设计会员表不要只放“姓名手机号”必须把营销属性、物理属性和账户属性分开。我设计的member表核心字段如下member - id BIGINT PK AUTO_INCREMENT - member_no VARCHAR(32) -- 会员编号显示用如 JF20250101001 - name VARCHAR(50) -- 姓名 - phone VARCHAR(20) -- 手机号唯一索引 - gender TINYINT -- 0保密 1男 2女 - birthday DATE - id_card VARCHAR(20) -- 身份证号购卡备案用 - tags VARCHAR(255) -- 标签JSON如 [高价值,减脂] - source VARCHAR(20) -- 来源渠道门店/美团/转介绍 - status TINYINT -- 0禁用 1正常 - created_at DATETIME - updated_at DATETIME设计时要特别注意两个点。第一金额字段一律用DECIMAL(10,2)绝不用DOUBLE因为浮点数的二进制存储会带来0.10.2不等于0.3的精度问题充值和退款时一分钱都不能差。第二phone上建唯一索引同时在后端Service里再校验一次防止并发插入产生重复会员。会员余额不要每次都去消费记录表里SUM单独建一张member_account表存储当前余额每次充值、消费、退款时同步更新。balance_log表记录每一笔变动明细包括变动金额、变动前余额、变动后余额、操作人、关联订单号这样对账的时候有据可查。2.2 预约与排课业务表团课排期是健身房的日常运营核心。course_schedule表表示“某个教练在某时间在某场地开某节课”关键字段包括课程id、教练id、场地id、开始时间、结束时间、总名额、已约名额。这里有一个常用的设计模式——把“每节课的名额”实时体现在表中的booked_count字段上。预约表appointment记录会员和排期课程的关系状态字段用状态机管理appointment.status - 0 待上课 - 1 已取消 - 2 已核销会员扫码或签到 - 3 爽约预约未到且未取消 - 4 已完成课程时间结束自动/后台标记为什么要维护状态机因为约课取消跟会员卡权益直接关联。比如规则是“开课前2小时可免费取消否则扣一次卡次”那后端在cancelAppointment方法里必须判断当前时间和course_schedule.start_time的差值落到不同的业务分支。数据库里还要处理“防止超额预约”的问题。常规思路是先在course_schedule行上加悲观锁SELECT ... FOR UPDATE然后再判断booked_count max_count满足条件才更新booked_count booked_count 1。实测下来这种方式在低并发下够用但一旦预约高峰期并发量上去会锁等待。更好的方案是直接用一条原子更新的SQL来做条件扣减UPDATE course_schedule SET booked_count booked_count 1 WHERE id #{scheduleId} AND booked_count max_count如果影响行数为1说明预约成功如果影响行数为0说明名额已满。这个方案不用显式加锁数据库的原子性保证了不会超卖。2.3 收银与卡券的表关系收银模块我拆成sale_order主表和sale_order_item明细表。为什么拆主从因为一笔订单可能同时包含“私教课一节运动饮料两瓶月卡一张”订单头部存总金额、优惠金额、实付金额、支付方式、收银员明细表存每一项的商品/课程ID、名称、单价、数量、小计。拆分的好处是财务统计时既可以按订单汇总也可以按商品维度分析销量。卡券这块coupon_template是券模板比如“满2000减300周年庆券”user_coupon是发到用户手里的具体券包含模板ID、用户ID、状态未使用/已使用/已过期、领取时间、使用时间、截止时间。发券时候要注意不能直接把模板发出去必须生成具体的一张券这样核销时才能对得上。卡券核销还有一个容易踩坑的点“叠加使用”规则。我的方案是在coupon_template里加一个stackable字段是否可叠加和use_scenario适用场景充值/购卡/商品/全部核销时由后端校验而不是前端控制防止有人绕过前端限制直接调接口。3. 后端实现细节与踩坑记录后端是整个系统的地基我挑四个我认为“最值得写进简历和博客”的点来讲MyBatis整合与配置、TypeHandler处理复杂字段、MinIO文件存储接入、事务与并发控制。3.1 SpringBoot整合MyBatis的配置与分层在application.yml里配置MyBatis需要注意几个关键项。数据源我用Druid连接池不是因为它比HikariCP快而是因为它自带监控页面便于排查慢SQL。spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/fitness_club?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai username: root password: xxx druid: initial-size: 5 min-idle: 5 max-active: 20 mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.fitness.entity configuration: map-underscore-to-camel-case: true cache-enabled: falsemap-underscore-to-camel-case这个配置特别重要它能自动把数据库的created_at字段映射到实体的createdAt属性省去大量resultMap手写映射。cache-enabled这里我建议设置成false也就是关闭MyBatis的二级缓存原因稍后细说。分层结构上我遵循标准的Controller-Service-Mapper三层实体Entity和DTO分开Controller里不允许直接出现SqlSession这类持久层对象。事务边界放在Service方法上用Transactional(rollbackFor Exception.class)这样保证了例如“创建订单扣减库存记录流水”三个操作要么全成功要么全回滚。3.2 MyBatis缓存与TypeHandler的实战用法先说缓存。MyBatis有一级缓存和二级缓存。一级缓存是SqlSession级别的默认开启同一个SqlSession内重复查询同一SQL会命中缓存但在Spring管理的场景下每次Mapper调用都是新开的SqlSession一级缓存的意义不大二级缓存是Mapper级别的默认关闭开启后多个SqlSession可以共享查询结果。听起来很好实际运行中我踩过一个大坑当会员余额更新后另一个查询会员信息的Mapper因为命中了二级缓存返回的还是旧余额造成了非常难排查的数据不一致。解决方案就是干脆关掉二级缓存引入Redis做业务级缓存由Service层手动控制哪些数据需要缓存、何时失效。对于这种强一致性要求的业务系统缓存控制权必须掌握在业务代码手里。TypeHandler是MyBatis里一个容易被忽视但非常实用的扩展点。member表里有个tags字段存的是JSON字符串如果每次查询出来都手动JSON.parse一遍代码会非常啰嗦。我自定义了一个JsonStringTypeHandlerMappedTypes(List.class) public class JsonStringTypeHandler extends BaseTypeHandlerListString { private final ObjectMapper objectMapper new ObjectMapper(); Override public void setNonNullParameter(PreparedStatement ps, int i, ListString parameter, JdbcType jdbcType) throws SQLException { try { ps.setString(i, objectMapper.writeValueAsString(parameter)); } catch (JsonProcessingException e) { throw new SQLException(Cannot convert List to JSON string, e); } } Override public ListString getNullableResult(ResultSet rs, String columnName) throws SQLException { String value rs.getString(columnName); if (value null) { return null; } try { return objectMapper.readValue(value, new TypeReferenceListString() {}); } catch (JsonProcessingException e) { throw new SQLException(Cannot convert JSON string to List, e); } } // 其余两个重载方法类似实现略 }然后在Mapper XML或实体字段注解上指定handler查询和插入时就能自动完成JSON与List的互转。这个技巧在处理“会员标签”、“图片URL数组”、“扩展属性”时非常通用能省掉大量重复的序列化代码。3.3 文件上传MinIO对象存储接入健身房的系统会涉及会员头像、课程封面、私教简介图片、训练视频等文件存储。如果只把文件传到服务器本地磁盘后患无穷磁盘故障、日志膨胀、多机部署时文件不同步、备份困难。接入对象存储是更合理的选择。MinIO是自建对象存储方案兼容Amazon S3接口部署成本低。为什么不直接用云OSS因为很多健身房管理系统是私有化部署在门店内网服务器上的外网访问带宽有限MinIO这种可以自托管、内网访问不限速的方案更贴合场景。SpringBoot整合MinIO的步骤不复杂核心代码是用MinioClient做两件事上传文件和生成预签名URL。Service public class MinioService { private final MinioClient minioClient; public MinioService(MinioProperties props) { this.minioClient MinioClient.builder() .endpoint(props.getEndpoint()) .credentials(props.getAccessKey(), props.getSecretKey()) .build(); } public String upload(MultipartFile file, String bucketName) { String objectName UUID.randomUUID().toString().replace(-, ) _ file.getOriginalFilename(); try { boolean exists minioClient.bucketExists(BucketExistsArgs.builder() .bucket(bucketName).build()); if (!exists) { minioClient.makeBucket(MakeBucketArgs.builder() .bucket(bucketName).build()); } minioClient.putObject(PutObjectArgs.builder() .bucket(bucketName) .object(objectName) .stream(file.getInputStream(), file.getSize(), -1) .contentType(file.getContentType()) .build()); return objectName; } catch (Exception e) { throw new BusinessException(文件上传失败 e.getMessage()); } } public String getPreviewUrl(String bucketName, String objectName) { try { return minioClient.getPresignedObjectUrl(GetPresignedObjectUrlArgs.builder() .method(Method.GET) .bucket(bucketName) .object(objectName) .expiry(60 * 60) .build()); } catch (Exception e) { throw new BusinessException(文件预览地址生成失败); } } }上传成功后数据库里保存的是objectName而不是完整的URL。因为MinIO的endpoint可能是内网IP也可能未来换域名存完整URL容易失效存objectName展示时动态生成预签名URL或通过网关拼接灵活得多。注意MinIO上传默认有大小限制SpringBoot的spring.servlet.multipart.max-file-size要同步调大。另外如果MinIO和SpringBoot之间经过Nginx反向代理需要把Nginx的client_max_body_size也调大否则大文件上传时会在代理层直接被截断前端报“413 Request Entity Too Large”。3.4 事务与并发控制的落地写法除了之前提到的“预约防超卖”还有两个地方对事务一致性要求很高。第一个是“办卡充值”。用户提交一笔充值和办卡订单后端要同时完成三件事生成sale_order订单记录、更新member_account余额、新增一条balance_log流水。这三件事必须放在一个事务里Transactional(rollbackFor Exception.class) public RechargeResult recharge(Long memberId, BigDecimal amount, Long operatorId) { // 1. 创建订单状态为已支付 SaleOrder order createOrder(memberId, amount, operatorId); // 2. 乐观锁更新余额 MemberAccount account accountMapper.selectByMemberIdForUpdate(memberId); account.setBalance(account.getBalance().add(amount)); accountMapper.updateById(account); // 3. 记录资金流水 saveBalanceLog(memberId, amount, account.getBalance(), order.getId()); return RechargeResult.success(order.getId()); }注意selectByMemberIdForUpdate这个操作它会对member_account表对应行加锁防止两个请求同时把余额从100改成110最后丢失一次更新。也可以在account表加version字段做乐观锁但充值场景下系统的写冲突并不高悲观锁的编码成本更低实测稳定。第二个是“库存扣减”。前台卖运动补剂、私教课次包时库存表或卡次包的剩余次数不能减成负数。和预约同理用WHERE remaining_count 0做条件更新。4. Vue前端实现与集成经验前端不是我吹这部分往往决定了系统给人的第一印象。健身房前台用的PC收银机、iPad预约端、管理者的手机报表页都靠前端来呈现。我用Vue3ViteElement Plus来搭建重点讲三个关键点路由与权限、axios封装、拖拽上传。4.1 工程结构与动态路由权限控制工程结构采用标准的Vue3项目按模块划分views目录src/ - api/ // 每个模块的请求方法 - assets/ // 静态资源 - components/ // 通用组件如上传、富文本、表单弹窗 - layout/ // 主框架布局侧边栏头部内容区 - router/ // 路由配置 - store/ // Pinia状态管理 - utils/ // axios封装、工具函数 - views/ - member/ // 会员管理 - course/ // 课程管理 - order/ // 收银中心 - report/ // 统计报表 - system/ // 系统管理动态路由是这类管理系统的刚需因为不同角色的账号登录后左侧菜单和可访问页面必须不同。我的做法是登录接口返回用户信息时同时返回该用户的菜单树由后端根据RBAC权限生成前端拿到菜单树后用router.addRoute()动态注册路由而不是在前端代码里硬编码“哪种角色能看哪个页面”。路由守卫里做三件事检查本地有没有Token、没有就跳到登录页每次路由跳转前校验当前用户是否拥有该路由的权限404页面兜底。router.beforeEach((to, from, next) { const token localStorage.getItem(token) if (!token) { if (to.path /login) { next() } else { next(/login) } return } if (to.path /login) { next(/) return } // 动态路由权限判断 if (to.meta.roles !to.meta.roles.includes(userStore.role)) { next(/403) return } next() })4.2 axios封装与统一错误处理管理系统百分之八十的接口都在做CRUDaxios封装的目的是把“重复代码”降到最低。我在utils/request.js里统一处理三件事请求头注入Token、响应拦截器统一拆包、HTTP错误码统一弹提示。const service axios.create({ baseURL: /api, timeout: 15000 }) service.interceptors.request.use(config { const token localStorage.getItem(token) if (token) { config.headers.Authorization Bearer ${token} } return config }) service.interceptors.response.use( resp { const res resp.data if (res.code ! 200) { ElMessage.error(res.message || 请求失败) return Promise.reject(new Error(res.message)) } return res.data // 直接返回业务数据页面里不用再包一层 }, err { if (err.response?.status 401) { localStorage.removeItem(token) router.push(/login) } ElMessage.error(err.response?.data?.message || 网络异常) return Promise.reject(err) } )这样每个API模块只需写请求配置不用写错误处理页面调用时拿到的就是后端返回的业务数据非常清爽。4.3 m3u8播放与视频水印方案会员端或管理端会涉及教学视频、训练课程回放经常遇到 m3u8 格式的流媒体视频。浏览器原生video标签不支持直接播放m3u8过去还要装Flash播放器体验很差。现在推荐用hls.js来实现免安装播放它通过Media Source ExtensionsMSE在浏览器里解析并播放HLS流不需要任何插件。import Hls from hls.js function playM3u8(videoElement, src) { if (Hls.isSupported()) { const hls new Hls() hls.loadSource(src) hls.attachMedia(videoElement) hls.on(Hls.Events.MANIFEST_PARSED, () { videoElement.play() }) } else if (videoElement.canPlayType(application/vnd.apple.mpegurl)) { // Safari原生支持 videoElement.src src } }这段代码我在项目里实测过Chrome、Edge、Firefox都能稳定播放iOS Safari走原生支持分支。要注意的是m3u8的分片地址如果是相对路径hls.js会以m3u8文件自身的URL为基准解析所以如果视频文件和分片不在同一目录层级可能会出现404需要在服务端返回的m3u8里写绝对路径或完整前缀。4.4 前端构建产物放进SpringBoot标题里的“完整版”意味着前后端要能一键运行。我推荐的做法是前端构建后把dist目录下的文件复制到SpringBoot的src/main/resources/static目录下最后打成一个Jar包统一用8080端口对外提供访问。这样部署时只有一个进程不需要额外部署Nginx也省去跨域配置的麻烦。需要注意一个大坑Vue Router如果使用history模式用户刷新/member/list这类地址时SpringBoot的DispatcherServlet找不到对应的Controller就会返回404。解决办法是写一个Controller把非API路径都重定向到index.htmlController public class PageForwardController { RequestMapping(value {/, /{path:[^\\.]*}, /{path:[^\\.]*}/{sub:[^\\.]*}}) public String forward() { return forward:/index.html; } }这个正则的意思是路径中不带点号的请求都转发到index.html而静态资源如/static/js/app.js、/api/**不会命中这个规则。如果前端路由层级更深调整PathVariable的数量即可。这是整合部署时最容易遇到的问题我几乎每次做前后端打包都会被人问一次。如果不想合并部署也可以把前端跑在Vite的dev server上通过server.proxy把/api代理到SpringBoot的8080端口这样开发时改前端热更新非常爽。上线时再合并打包。5. 部署上线与常见问题排查这部分我把项目从“能跑”到“能上线”之间会遇到的实际问题拉出来挨个说都是我在真实部署环境里踩过的坑。5.1 Linux环境初始化与MySQL安装生产环境建议用Linux服务器我习惯用CentOS 7或Ubuntu 20.04。MySQL的安装方式很多最省事的是用包管理器安装。这里以yum源安装MySQL 8为例# 先卸载系统自带的mariadb rpm -qa | grep mariadb | xargs rpm -e --nodeps # 下载并安装MySQL官方yum源 wget https://repo.mysql.com/mysql80-community-release-el7-3.noarch.rpm rpm -ivh mysql80-community-release-el7-3.noarch.rpm yum install mysql-community-server -y # 启动并设置开机自启 systemctl start mysqld systemctl enable mysqld # 查看临时密码MySQL 8首次启动会生成 grep temporary password /var/log/mysqld.log拿到临时密码后执行mysql -uroot -p进入然后立刻修改密码并创建业务库ALTER USER rootlocalhost IDENTIFIED BY 你的新密码; CREATE DATABASE fitness_club DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; USE fitness_club; SOURCE /opt/fitness_club.sql;字符集必须用utf8mb4不要用utf8因为utf8mb4能存emoji表情和生僻字健身房的会员备注里什么奇奇怪怪的字符都可能有。导入SQL时如果表里已经有DEFAULT CHARSETutf8mb4一般不用额外指定但如果导入过程中出现中文乱码排查顺序是SQL文件本身的编码、MySQL客户端的连接字符集、表字段的字符集。set names utf8mb4;能解决大部分导入乱码问题。5.2 前端部署与启动参数调优打包前在vite.config.js里设置base: /如果部署在子路径下则改为/fitness/。执行npm run build后把dist目录拷贝到SpringBoot的resources/static下重新执行mvn clean package -DskipTests。启动Jar包时我习惯用nohup配合资源限制参数而不是java -jar裸跑nohup java -Xms512m -Xmx1024m -XX:UseG1GC -jar fitness-club.jar \ --spring.profiles.activeprod /opt/fitness/logs/app.log 21 -Xms和-Xmx的配置要看服务器内存如果是2G内存的阿里云/腾讯云轻量服务器堆内存设到512M-1024M比较稳妥再高会跟MySQL抢内存导致OOM。--spring.profiles.activeprod意味着读取application-prod.yml部署环境的数据库地址、MinIO地址、日志路径都放在这个文件里绝不写死在代码中。MySQL连接池参数也要跟着调Druid默认的max-active: 20对多数门店并发够用但如果前端页面频繁轮询接口、或报表页同时开多标签页连接不够时会报Connection is not available, request timed out。这时把max-active调到50同时检查MySQL侧max_connections是否够。5.3 线上环境必调的参数除了连接池有三个参数是线上运行一段时间后必调的提前说清楚省得半夜被叫起来修。一是spring.jackson的时间格式。前后端时间传递很容易出问题统一在application.yml里配置spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT8二是MyBatis的日志级别。开发环境需要打印SQL方便调试可以配置logging.level.com.fitness.mapperdebug线上环境一定要调成info或warn不然每个接口请求都会打印一堆SQL日志磁盘很快会被撑爆而且日志I/O也会拖慢响应。三是MySQL的max_allowed_packet。上传课程视频或大图时如果报Packet for query is too large执行SET GLOBAL max_allowed_packet 64 * 1024 * 1024;同时写入my.cnf保证重启后永久生效。这个错误在对接MinIO、上传base64图片时非常常见。5.4 常见问题速查表把部署和开发中常见问题整理成一张表方便你排查时直接对号入座问题现象根本原因解决方式接口报404前端history路由刷新丢失配置PageForwardController转发跨域报错前端dev server与后端端口不一致Vite配置proxy代理或后端配置CorsFilter中文乱码MySQL连接参数缺characterEncodingURL加useUnicodetruecharacterEncodingutf8SQL连接失败Public Key Retrieval is not allowedMySQL 8默认认证插件问题URL加allowPublicKeyRetrievaltrue大文件上传413Nginx或SpringBoot上传限制两端都调大client_max_body_size和max-file-size接口响应慢报表SQL全表扫描用EXPLAIN看执行计划建联合索引数据重复提交用户双击提交按钮前端按钮loading禁用后端防重token缓存后数据不同步MyBatis二级缓存关闭二级缓存用Redis手动控制缓存JSP或静态资源404资源路径映射错误确认SpringBoot的spring.web.resources.static-locations5.5 上线前的安全检查清单我最后一份清单是上线前的自查表适合直接打印出来照着过强制要求修改root账号密码并创建独立业务账号应用代码里不能用root连接数据库JWT密钥不要硬编码在代码里放到环境变量或配置中心生产环境删除Swagger或Knife4j的公开访问配置或者加访问密码涉及金额的接口必须校验幂等性用订单号或Token防止重复提交日志中不得打印会员完整身份证号和支付信息属于敏感数据定时备份数据库建议每天凌晨全量备份binlog开启管理员账号启用双因素认证或至少强密码策略这个不复杂但非常有效6. 总结与后续扩展方向项目做到这个程度已经是一个结构完整、可以从代码层面跑通业务闭环的企业级管理系统了。但这套系统的价值绝不止于“能跑通”更在于整个过程中对业务规则的建模和对技术栈的融会贯通。比如从会员办卡到约课消课再到收银对账每一步都有明确的状态和操作记录从数据库表结构到后端事务再到前端权限控制每一环都考虑到了真实场景的并发和数据一致性问题。我个人在实际操作中最大的体会是这类系统最容易出问题的地方往往不是某个高大上的算法而是业务规则的一致性。比如会员退款时卡券要不要作废私教课取消后教练的排班要不要释放团课临时加位后已预约的用户要不要通知这些都是代码之外的业务判断但最终都体现在数据库的事务和接口的幂等设计里。后续如果要扩展我个人觉得比较有价值的方向有三个一是接入微信小程序端让会员在手机上完成自助约课、签到和查看卡包后端接口大部分可以复用二是引入消息推送课程开课前用短信或微信模板消息提醒会员能明显降低爽约率三是把报表模块做深入一点加入会员流失预警、教练效能分析让管理者从“看流水”升级到“看经营”。如果准备拿这个项目去面试或做毕业设计能把中间任何一个扩展点讲清楚都足以证明你不是只会照着模版敲代码。最后再分享一个我实际项目里常用的技巧像“会员余额变动日志”这类天天都在写、而且不允许丢的数据除了后端代码里同步写我还会额外加一个定时任务在每天凌晨做一次“余额抽样校验”——把当天的balance_log流水重新SUM一遍跟member_account表当前余额对账发现不一致立刻告警。这种双写校验的习惯能帮你提前发现很多上线初期不易察觉的逻辑漏洞尤其是退款、废单、系统异常回滚这些容易漏记的场景。 企业级健身俱乐部管理系统实战：SpringBoot+Vue+MyBatis+MySQL全栈架构解析
看到“企业级健身俱乐部网站管理系统源码SpringBootVueMyBatis架构MySQL数据库【完整版】”这个标题的时候我第一反应是这又是一个典型的“全栈业务系统”项目但真正把它做扎实的人并不多。健身俱乐部这种实体门店业务链条长、角色多、数据敏感会员充值、私教预约、团课排课、收银对账、卡券核销随便拎一个模块出来都够写一堆业务逻辑。标题里这几个关键词——SpringBoot、Vue、MyBatis、MySQL——组合在一起正好覆盖了后端框架、前端渲染、ORM持久层和关系型存储这条最主流的技术路线。这篇博文我就围绕这个系统的完整实现来聊从项目拆解到数据库建模从后端代码到前端集成再到部署上线和踩坑实录把整个项目的设计思路和落地细节一次讲透。这套系统解决的核心问题是一个健身俱乐部从会员办卡、预约上课、到门店收银、经营统计的完整业务闭环。它适合三类人参考一是准备做毕业设计或简历项目的同学二是想学习SpringBootVue前后端分离项目如何整合的开发者三是健身房IT部门或外包团队想快速搭建管理系统的实施人员。我不打算按“功能列表”那样平铺直叙而是按我实际开发这类系统时的思考路径来展开把每一步为什么这么做讲清楚。1. 项目整体设计与技术选型思路很多人拿到项目源码的第一件事就是看目录结构、跑Demo但我觉得先把技术选型和模块边界想明白更重要。技术选型决定了这个项目能走多远模块边界决定了后续加功能会不会把代码改成一团乱麻。1.1 为什么是SpringBootVueMyBatisMySQL这套组合先说结论这套组合不是性能最强的也不是最时髦的但它是“企业级业务系统”里最稳妥、最利于维护的组合之一。SpringBoot负责后端接口服务它的核心价值是“约定大于配置”内置Tomcat自动装配配合Maven或Gradle能快速打出一个可部署的Jar包。我做过几个类似的管理系统SpringBoot的生态成熟度摆在那里无论是做权限Spring Security或Shiro、做缓存Redis、做文件存储MinIO还是做定时任务Quartz都能找到大量现成文档招人也容易。Vue负责前端页面。Vue3的Composition API配合Vite构建开发体验比Vue2提升了不少但市面上大量存量项目还是Vue2Element UI所以看到这个标题源码的时候不用纠结“为什么不用React”Vue在国内企业级的普及率决定了它在管理系统这个领域就是默认选项。MyBatis作为持久层框架和JPA走了完全不同的路线。JPA适合强对象模型、表结构简单的场景而健身俱乐部这种业务SQL里有大量统计查询、多表联查、条件动态拼装MyBatis的XML文件能把每条SQL都清晰管起来。特别是跑报表的时候“本月私教课消课率”、“会员卡即将到期名单”这种SQL自己写SQL比让ORM自动生成靠谱得多。MySQL是数据库的守成者。这套系统数据量不会到千万级单库单表完全能扛住。之所以不选PostgreSQL或Oracle主要是运维成本和人员熟悉度的考量中小企业的服务器上装MySQL是默认操作utf8mb4字符集、事务隔离级别、主从同步这些机制也符合项目当前量级。注意选型这件事没有绝对的对错关键是“团队熟悉什么”和“业务需要什么”。如果团队主攻Node.js那用NestJSTypeORM也完全可以但既然标题定的是SpringBootVue那整套代码的风格、异常处理、分层结构都要向这套生态看齐。1.2 系统模块划分与权限模型我把系统拆成了七个核心模块每个模块对应一个前端菜单组和后端Controller分组模块核心功能对应实体会员管理会员信息、会员卡、余额变动、积分Member, MemberCard, BalanceLog课程管理私教课、团课排期、教练管理Trainer, Course, CourseSchedule预约管理会员约课、取消、排队Appointment, AppointmentLog收银中心商品销售、办卡充值、退款SaleOrder, OrderItem, RechargeRecord营销卡券优惠券发放、核销、过期管理CouponTemplate, UserCoupon统计报表营收趋势、课程消耗、会员增长Dashboard, ReportQuery系统管理账号、角色、菜单、操作日志SysUser, SysRole, SysMenu权限模型用最经典的RBACRole-Based Access Control也就是“用户-角色-权限”三层结构。我见过很多毕业设计把权限直接写在User表里加一个“isAdmin”字段这样做初期很快但一旦出现“前台收银员只能看会员列表但不能看财务报表”这种需求就得改表结构。RBAC把角色和权限解耦新建一个角色、勾选菜单权限即可。后端用JWT做无状态登录认证用户登录成功后返回Token前端把Token存在localStorage或Pinia里每次请求在拦截器中带在Authorization头中。SpringBoot侧用一个拦截器或Spring Security过滤器解析Token解析成功就放行并从Token里取出userId和角色信息。这里我建议不要用Spring Security的重型配置而是用一个自定义的AuthInterceptor配合注解RequirePermission(member:list)代码量小、逻辑直观也方便初学者理解权限控制是怎么一回事。2. 数据库建模与核心业务表设计业务系统最讲究的就是表结构设计。表设计决定了后续写SQL是顺手还是抓狂。健身俱乐部这个项目核心表大约二十张左右我挑几个关键域说清楚。2.1 会员域表结构设计会员表不要只放“姓名手机号”必须把营销属性、物理属性和账户属性分开。我设计的member表核心字段如下member - id BIGINT PK AUTO_INCREMENT - member_no VARCHAR(32) -- 会员编号显示用如 JF20250101001 - name VARCHAR(50) -- 姓名 - phone VARCHAR(20) -- 手机号唯一索引 - gender TINYINT -- 0保密 1男 2女 - birthday DATE - id_card VARCHAR(20) -- 身份证号购卡备案用 - tags VARCHAR(255) -- 标签JSON如 [高价值,减脂] - source VARCHAR(20) -- 来源渠道门店/美团/转介绍 - status TINYINT -- 0禁用 1正常 - created_at DATETIME - updated_at DATETIME设计时要特别注意两个点。第一金额字段一律用DECIMAL(10,2)绝不用DOUBLE因为浮点数的二进制存储会带来0.10.2不等于0.3的精度问题充值和退款时一分钱都不能差。第二phone上建唯一索引同时在后端Service里再校验一次防止并发插入产生重复会员。会员余额不要每次都去消费记录表里SUM单独建一张member_account表存储当前余额每次充值、消费、退款时同步更新。balance_log表记录每一笔变动明细包括变动金额、变动前余额、变动后余额、操作人、关联订单号这样对账的时候有据可查。2.2 预约与排课业务表团课排期是健身房的日常运营核心。course_schedule表表示“某个教练在某时间在某场地开某节课”关键字段包括课程id、教练id、场地id、开始时间、结束时间、总名额、已约名额。这里有一个常用的设计模式——把“每节课的名额”实时体现在表中的booked_count字段上。预约表appointment记录会员和排期课程的关系状态字段用状态机管理appointment.status - 0 待上课 - 1 已取消 - 2 已核销会员扫码或签到 - 3 爽约预约未到且未取消 - 4 已完成课程时间结束自动/后台标记为什么要维护状态机因为约课取消跟会员卡权益直接关联。比如规则是“开课前2小时可免费取消否则扣一次卡次”那后端在cancelAppointment方法里必须判断当前时间和course_schedule.start_time的差值落到不同的业务分支。数据库里还要处理“防止超额预约”的问题。常规思路是先在course_schedule行上加悲观锁SELECT ... FOR UPDATE然后再判断booked_count max_count满足条件才更新booked_count booked_count 1。实测下来这种方式在低并发下够用但一旦预约高峰期并发量上去会锁等待。更好的方案是直接用一条原子更新的SQL来做条件扣减UPDATE course_schedule SET booked_count booked_count 1 WHERE id #{scheduleId} AND booked_count max_count如果影响行数为1说明预约成功如果影响行数为0说明名额已满。这个方案不用显式加锁数据库的原子性保证了不会超卖。2.3 收银与卡券的表关系收银模块我拆成sale_order主表和sale_order_item明细表。为什么拆主从因为一笔订单可能同时包含“私教课一节运动饮料两瓶月卡一张”订单头部存总金额、优惠金额、实付金额、支付方式、收银员明细表存每一项的商品/课程ID、名称、单价、数量、小计。拆分的好处是财务统计时既可以按订单汇总也可以按商品维度分析销量。卡券这块coupon_template是券模板比如“满2000减300周年庆券”user_coupon是发到用户手里的具体券包含模板ID、用户ID、状态未使用/已使用/已过期、领取时间、使用时间、截止时间。发券时候要注意不能直接把模板发出去必须生成具体的一张券这样核销时才能对得上。卡券核销还有一个容易踩坑的点“叠加使用”规则。我的方案是在coupon_template里加一个stackable字段是否可叠加和use_scenario适用场景充值/购卡/商品/全部核销时由后端校验而不是前端控制防止有人绕过前端限制直接调接口。3. 后端实现细节与踩坑记录后端是整个系统的地基我挑四个我认为“最值得写进简历和博客”的点来讲MyBatis整合与配置、TypeHandler处理复杂字段、MinIO文件存储接入、事务与并发控制。3.1 SpringBoot整合MyBatis的配置与分层在application.yml里配置MyBatis需要注意几个关键项。数据源我用Druid连接池不是因为它比HikariCP快而是因为它自带监控页面便于排查慢SQL。spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/fitness_club?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai username: root password: xxx druid: initial-size: 5 min-idle: 5 max-active: 20 mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.fitness.entity configuration: map-underscore-to-camel-case: true cache-enabled: falsemap-underscore-to-camel-case这个配置特别重要它能自动把数据库的created_at字段映射到实体的createdAt属性省去大量resultMap手写映射。cache-enabled这里我建议设置成false也就是关闭MyBatis的二级缓存原因稍后细说。分层结构上我遵循标准的Controller-Service-Mapper三层实体Entity和DTO分开Controller里不允许直接出现SqlSession这类持久层对象。事务边界放在Service方法上用Transactional(rollbackFor Exception.class)这样保证了例如“创建订单扣减库存记录流水”三个操作要么全成功要么全回滚。3.2 MyBatis缓存与TypeHandler的实战用法先说缓存。MyBatis有一级缓存和二级缓存。一级缓存是SqlSession级别的默认开启同一个SqlSession内重复查询同一SQL会命中缓存但在Spring管理的场景下每次Mapper调用都是新开的SqlSession一级缓存的意义不大二级缓存是Mapper级别的默认关闭开启后多个SqlSession可以共享查询结果。听起来很好实际运行中我踩过一个大坑当会员余额更新后另一个查询会员信息的Mapper因为命中了二级缓存返回的还是旧余额造成了非常难排查的数据不一致。解决方案就是干脆关掉二级缓存引入Redis做业务级缓存由Service层手动控制哪些数据需要缓存、何时失效。对于这种强一致性要求的业务系统缓存控制权必须掌握在业务代码手里。TypeHandler是MyBatis里一个容易被忽视但非常实用的扩展点。member表里有个tags字段存的是JSON字符串如果每次查询出来都手动JSON.parse一遍代码会非常啰嗦。我自定义了一个JsonStringTypeHandlerMappedTypes(List.class) public class JsonStringTypeHandler extends BaseTypeHandlerListString { private final ObjectMapper objectMapper new ObjectMapper(); Override public void setNonNullParameter(PreparedStatement ps, int i, ListString parameter, JdbcType jdbcType) throws SQLException { try { ps.setString(i, objectMapper.writeValueAsString(parameter)); } catch (JsonProcessingException e) { throw new SQLException(Cannot convert List to JSON string, e); } } Override public ListString getNullableResult(ResultSet rs, String columnName) throws SQLException { String value rs.getString(columnName); if (value null) { return null; } try { return objectMapper.readValue(value, new TypeReferenceListString() {}); } catch (JsonProcessingException e) { throw new SQLException(Cannot convert JSON string to List, e); } } // 其余两个重载方法类似实现略 }然后在Mapper XML或实体字段注解上指定handler查询和插入时就能自动完成JSON与List的互转。这个技巧在处理“会员标签”、“图片URL数组”、“扩展属性”时非常通用能省掉大量重复的序列化代码。3.3 文件上传MinIO对象存储接入健身房的系统会涉及会员头像、课程封面、私教简介图片、训练视频等文件存储。如果只把文件传到服务器本地磁盘后患无穷磁盘故障、日志膨胀、多机部署时文件不同步、备份困难。接入对象存储是更合理的选择。MinIO是自建对象存储方案兼容Amazon S3接口部署成本低。为什么不直接用云OSS因为很多健身房管理系统是私有化部署在门店内网服务器上的外网访问带宽有限MinIO这种可以自托管、内网访问不限速的方案更贴合场景。SpringBoot整合MinIO的步骤不复杂核心代码是用MinioClient做两件事上传文件和生成预签名URL。Service public class MinioService { private final MinioClient minioClient; public MinioService(MinioProperties props) { this.minioClient MinioClient.builder() .endpoint(props.getEndpoint()) .credentials(props.getAccessKey(), props.getSecretKey()) .build(); } public String upload(MultipartFile file, String bucketName) { String objectName UUID.randomUUID().toString().replace(-, ) _ file.getOriginalFilename(); try { boolean exists minioClient.bucketExists(BucketExistsArgs.builder() .bucket(bucketName).build()); if (!exists) { minioClient.makeBucket(MakeBucketArgs.builder() .bucket(bucketName).build()); } minioClient.putObject(PutObjectArgs.builder() .bucket(bucketName) .object(objectName) .stream(file.getInputStream(), file.getSize(), -1) .contentType(file.getContentType()) .build()); return objectName; } catch (Exception e) { throw new BusinessException(文件上传失败 e.getMessage()); } } public String getPreviewUrl(String bucketName, String objectName) { try { return minioClient.getPresignedObjectUrl(GetPresignedObjectUrlArgs.builder() .method(Method.GET) .bucket(bucketName) .object(objectName) .expiry(60 * 60) .build()); } catch (Exception e) { throw new BusinessException(文件预览地址生成失败); } } }上传成功后数据库里保存的是objectName而不是完整的URL。因为MinIO的endpoint可能是内网IP也可能未来换域名存完整URL容易失效存objectName展示时动态生成预签名URL或通过网关拼接灵活得多。注意MinIO上传默认有大小限制SpringBoot的spring.servlet.multipart.max-file-size要同步调大。另外如果MinIO和SpringBoot之间经过Nginx反向代理需要把Nginx的client_max_body_size也调大否则大文件上传时会在代理层直接被截断前端报“413 Request Entity Too Large”。3.4 事务与并发控制的落地写法除了之前提到的“预约防超卖”还有两个地方对事务一致性要求很高。第一个是“办卡充值”。用户提交一笔充值和办卡订单后端要同时完成三件事生成sale_order订单记录、更新member_account余额、新增一条balance_log流水。这三件事必须放在一个事务里Transactional(rollbackFor Exception.class) public RechargeResult recharge(Long memberId, BigDecimal amount, Long operatorId) { // 1. 创建订单状态为已支付 SaleOrder order createOrder(memberId, amount, operatorId); // 2. 乐观锁更新余额 MemberAccount account accountMapper.selectByMemberIdForUpdate(memberId); account.setBalance(account.getBalance().add(amount)); accountMapper.updateById(account); // 3. 记录资金流水 saveBalanceLog(memberId, amount, account.getBalance(), order.getId()); return RechargeResult.success(order.getId()); }注意selectByMemberIdForUpdate这个操作它会对member_account表对应行加锁防止两个请求同时把余额从100改成110最后丢失一次更新。也可以在account表加version字段做乐观锁但充值场景下系统的写冲突并不高悲观锁的编码成本更低实测稳定。第二个是“库存扣减”。前台卖运动补剂、私教课次包时库存表或卡次包的剩余次数不能减成负数。和预约同理用WHERE remaining_count 0做条件更新。4. Vue前端实现与集成经验前端不是我吹这部分往往决定了系统给人的第一印象。健身房前台用的PC收银机、iPad预约端、管理者的手机报表页都靠前端来呈现。我用Vue3ViteElement Plus来搭建重点讲三个关键点路由与权限、axios封装、拖拽上传。4.1 工程结构与动态路由权限控制工程结构采用标准的Vue3项目按模块划分views目录src/ - api/ // 每个模块的请求方法 - assets/ // 静态资源 - components/ // 通用组件如上传、富文本、表单弹窗 - layout/ // 主框架布局侧边栏头部内容区 - router/ // 路由配置 - store/ // Pinia状态管理 - utils/ // axios封装、工具函数 - views/ - member/ // 会员管理 - course/ // 课程管理 - order/ // 收银中心 - report/ // 统计报表 - system/ // 系统管理动态路由是这类管理系统的刚需因为不同角色的账号登录后左侧菜单和可访问页面必须不同。我的做法是登录接口返回用户信息时同时返回该用户的菜单树由后端根据RBAC权限生成前端拿到菜单树后用router.addRoute()动态注册路由而不是在前端代码里硬编码“哪种角色能看哪个页面”。路由守卫里做三件事检查本地有没有Token、没有就跳到登录页每次路由跳转前校验当前用户是否拥有该路由的权限404页面兜底。router.beforeEach((to, from, next) { const token localStorage.getItem(token) if (!token) { if (to.path /login) { next() } else { next(/login) } return } if (to.path /login) { next(/) return } // 动态路由权限判断 if (to.meta.roles !to.meta.roles.includes(userStore.role)) { next(/403) return } next() })4.2 axios封装与统一错误处理管理系统百分之八十的接口都在做CRUDaxios封装的目的是把“重复代码”降到最低。我在utils/request.js里统一处理三件事请求头注入Token、响应拦截器统一拆包、HTTP错误码统一弹提示。const service axios.create({ baseURL: /api, timeout: 15000 }) service.interceptors.request.use(config { const token localStorage.getItem(token) if (token) { config.headers.Authorization Bearer ${token} } return config }) service.interceptors.response.use( resp { const res resp.data if (res.code ! 200) { ElMessage.error(res.message || 请求失败) return Promise.reject(new Error(res.message)) } return res.data // 直接返回业务数据页面里不用再包一层 }, err { if (err.response?.status 401) { localStorage.removeItem(token) router.push(/login) } ElMessage.error(err.response?.data?.message || 网络异常) return Promise.reject(err) } )这样每个API模块只需写请求配置不用写错误处理页面调用时拿到的就是后端返回的业务数据非常清爽。4.3 m3u8播放与视频水印方案会员端或管理端会涉及教学视频、训练课程回放经常遇到 m3u8 格式的流媒体视频。浏览器原生video标签不支持直接播放m3u8过去还要装Flash播放器体验很差。现在推荐用hls.js来实现免安装播放它通过Media Source ExtensionsMSE在浏览器里解析并播放HLS流不需要任何插件。import Hls from hls.js function playM3u8(videoElement, src) { if (Hls.isSupported()) { const hls new Hls() hls.loadSource(src) hls.attachMedia(videoElement) hls.on(Hls.Events.MANIFEST_PARSED, () { videoElement.play() }) } else if (videoElement.canPlayType(application/vnd.apple.mpegurl)) { // Safari原生支持 videoElement.src src } }这段代码我在项目里实测过Chrome、Edge、Firefox都能稳定播放iOS Safari走原生支持分支。要注意的是m3u8的分片地址如果是相对路径hls.js会以m3u8文件自身的URL为基准解析所以如果视频文件和分片不在同一目录层级可能会出现404需要在服务端返回的m3u8里写绝对路径或完整前缀。4.4 前端构建产物放进SpringBoot标题里的“完整版”意味着前后端要能一键运行。我推荐的做法是前端构建后把dist目录下的文件复制到SpringBoot的src/main/resources/static目录下最后打成一个Jar包统一用8080端口对外提供访问。这样部署时只有一个进程不需要额外部署Nginx也省去跨域配置的麻烦。需要注意一个大坑Vue Router如果使用history模式用户刷新/member/list这类地址时SpringBoot的DispatcherServlet找不到对应的Controller就会返回404。解决办法是写一个Controller把非API路径都重定向到index.htmlController public class PageForwardController { RequestMapping(value {/, /{path:[^\\.]*}, /{path:[^\\.]*}/{sub:[^\\.]*}}) public String forward() { return forward:/index.html; } }这个正则的意思是路径中不带点号的请求都转发到index.html而静态资源如/static/js/app.js、/api/**不会命中这个规则。如果前端路由层级更深调整PathVariable的数量即可。这是整合部署时最容易遇到的问题我几乎每次做前后端打包都会被人问一次。如果不想合并部署也可以把前端跑在Vite的dev server上通过server.proxy把/api代理到SpringBoot的8080端口这样开发时改前端热更新非常爽。上线时再合并打包。5. 部署上线与常见问题排查这部分我把项目从“能跑”到“能上线”之间会遇到的实际问题拉出来挨个说都是我在真实部署环境里踩过的坑。5.1 Linux环境初始化与MySQL安装生产环境建议用Linux服务器我习惯用CentOS 7或Ubuntu 20.04。MySQL的安装方式很多最省事的是用包管理器安装。这里以yum源安装MySQL 8为例# 先卸载系统自带的mariadb rpm -qa | grep mariadb | xargs rpm -e --nodeps # 下载并安装MySQL官方yum源 wget https://repo.mysql.com/mysql80-community-release-el7-3.noarch.rpm rpm -ivh mysql80-community-release-el7-3.noarch.rpm yum install mysql-community-server -y # 启动并设置开机自启 systemctl start mysqld systemctl enable mysqld # 查看临时密码MySQL 8首次启动会生成 grep temporary password /var/log/mysqld.log拿到临时密码后执行mysql -uroot -p进入然后立刻修改密码并创建业务库ALTER USER rootlocalhost IDENTIFIED BY 你的新密码; CREATE DATABASE fitness_club DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; USE fitness_club; SOURCE /opt/fitness_club.sql;字符集必须用utf8mb4不要用utf8因为utf8mb4能存emoji表情和生僻字健身房的会员备注里什么奇奇怪怪的字符都可能有。导入SQL时如果表里已经有DEFAULT CHARSETutf8mb4一般不用额外指定但如果导入过程中出现中文乱码排查顺序是SQL文件本身的编码、MySQL客户端的连接字符集、表字段的字符集。set names utf8mb4;能解决大部分导入乱码问题。5.2 前端部署与启动参数调优打包前在vite.config.js里设置base: /如果部署在子路径下则改为/fitness/。执行npm run build后把dist目录拷贝到SpringBoot的resources/static下重新执行mvn clean package -DskipTests。启动Jar包时我习惯用nohup配合资源限制参数而不是java -jar裸跑nohup java -Xms512m -Xmx1024m -XX:UseG1GC -jar fitness-club.jar \ --spring.profiles.activeprod /opt/fitness/logs/app.log 21 -Xms和-Xmx的配置要看服务器内存如果是2G内存的阿里云/腾讯云轻量服务器堆内存设到512M-1024M比较稳妥再高会跟MySQL抢内存导致OOM。--spring.profiles.activeprod意味着读取application-prod.yml部署环境的数据库地址、MinIO地址、日志路径都放在这个文件里绝不写死在代码中。MySQL连接池参数也要跟着调Druid默认的max-active: 20对多数门店并发够用但如果前端页面频繁轮询接口、或报表页同时开多标签页连接不够时会报Connection is not available, request timed out。这时把max-active调到50同时检查MySQL侧max_connections是否够。5.3 线上环境必调的参数除了连接池有三个参数是线上运行一段时间后必调的提前说清楚省得半夜被叫起来修。一是spring.jackson的时间格式。前后端时间传递很容易出问题统一在application.yml里配置spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT8二是MyBatis的日志级别。开发环境需要打印SQL方便调试可以配置logging.level.com.fitness.mapperdebug线上环境一定要调成info或warn不然每个接口请求都会打印一堆SQL日志磁盘很快会被撑爆而且日志I/O也会拖慢响应。三是MySQL的max_allowed_packet。上传课程视频或大图时如果报Packet for query is too large执行SET GLOBAL max_allowed_packet 64 * 1024 * 1024;同时写入my.cnf保证重启后永久生效。这个错误在对接MinIO、上传base64图片时非常常见。5.4 常见问题速查表把部署和开发中常见问题整理成一张表方便你排查时直接对号入座问题现象根本原因解决方式接口报404前端history路由刷新丢失配置PageForwardController转发跨域报错前端dev server与后端端口不一致Vite配置proxy代理或后端配置CorsFilter中文乱码MySQL连接参数缺characterEncodingURL加useUnicodetruecharacterEncodingutf8SQL连接失败Public Key Retrieval is not allowedMySQL 8默认认证插件问题URL加allowPublicKeyRetrievaltrue大文件上传413Nginx或SpringBoot上传限制两端都调大client_max_body_size和max-file-size接口响应慢报表SQL全表扫描用EXPLAIN看执行计划建联合索引数据重复提交用户双击提交按钮前端按钮loading禁用后端防重token缓存后数据不同步MyBatis二级缓存关闭二级缓存用Redis手动控制缓存JSP或静态资源404资源路径映射错误确认SpringBoot的spring.web.resources.static-locations5.5 上线前的安全检查清单我最后一份清单是上线前的自查表适合直接打印出来照着过强制要求修改root账号密码并创建独立业务账号应用代码里不能用root连接数据库JWT密钥不要硬编码在代码里放到环境变量或配置中心生产环境删除Swagger或Knife4j的公开访问配置或者加访问密码涉及金额的接口必须校验幂等性用订单号或Token防止重复提交日志中不得打印会员完整身份证号和支付信息属于敏感数据定时备份数据库建议每天凌晨全量备份binlog开启管理员账号启用双因素认证或至少强密码策略这个不复杂但非常有效6. 总结与后续扩展方向项目做到这个程度已经是一个结构完整、可以从代码层面跑通业务闭环的企业级管理系统了。但这套系统的价值绝不止于“能跑通”更在于整个过程中对业务规则的建模和对技术栈的融会贯通。比如从会员办卡到约课消课再到收银对账每一步都有明确的状态和操作记录从数据库表结构到后端事务再到前端权限控制每一环都考虑到了真实场景的并发和数据一致性问题。我个人在实际操作中最大的体会是这类系统最容易出问题的地方往往不是某个高大上的算法而是业务规则的一致性。比如会员退款时卡券要不要作废私教课取消后教练的排班要不要释放团课临时加位后已预约的用户要不要通知这些都是代码之外的业务判断但最终都体现在数据库的事务和接口的幂等设计里。后续如果要扩展我个人觉得比较有价值的方向有三个一是接入微信小程序端让会员在手机上完成自助约课、签到和查看卡包后端接口大部分可以复用二是引入消息推送课程开课前用短信或微信模板消息提醒会员能明显降低爽约率三是把报表模块做深入一点加入会员流失预警、教练效能分析让管理者从“看流水”升级到“看经营”。如果准备拿这个项目去面试或做毕业设计能把中间任何一个扩展点讲清楚都足以证明你不是只会照着模版敲代码。最后再分享一个我实际项目里常用的技巧像“会员余额变动日志”这类天天都在写、而且不允许丢的数据除了后端代码里同步写我还会额外加一个定时任务在每天凌晨做一次“余额抽样校验”——把当天的balance_log流水重新SUM一遍跟member_account表当前余额对账发现不一致立刻告警。这种双写校验的习惯能帮你提前发现很多上线初期不易察觉的逻辑漏洞尤其是退款、废单、系统异常回滚这些容易漏记的场景。