简介这是一套基于Spring Boot、MyBatis、Spring MVC、Spring Security与Redis构建的完整网站后台管理系统源码面向具备一定Java Web基础、希望深入理解企业级开发技术栈协同方式的开发者与学习者。项目将持久层、控制层、安全认证与缓存中间件整合在同一工程中可用于课程设计、毕业设计参考或后台管理系统的二次开发。压缩包共326个文件约1.76MB其中95个Java源文件承载核心业务与配置逻辑45个JavaScript、33个HTML与19个CSS文件构成前端交互与页面样式另有12个XML映射与配置文件、1个SQL脚本用于数据库初始化以及gif、png、字体等静态资源。已有958人学习下载。通过研读源码读者可掌握Spring Security的登录认证与权限控制流程、MyBatis的SQL映射写法、Redis缓存集成方式以及前后端资源在Spring Boot工程中的组织与配置思路适合作为技术进阶与项目实战的参考素材。1. 从一台干净服务器开始Spring Boot MyBatis Spring MVC Spring Security Redis 后台管理系统环境搭建很多人第一次拿到这套“Spring Boot MyBatis Spring MVC Spring Security Redis 完整网站后台管理系统”源码时第一反应是直接双击 IDE 的 Run。结果大概率是数据库连不上、Redis 拒绝连接、登录页 302 循环、控制台一片红。这套组合涉及五个核心组件版本错一个后面全是玄学问题。我见过最典型的翻车现场是有人用 Spring Boot 3.x 去跑一份为 2.7.x 写的 Security 配置WebSecurityConfigurerAdapter直接报红整个认证链起不来。所以这篇安装笔记不聊架构设计只解决一件事从零把这套环境装到能登录、能查数据、能跑通后台首页。适合手里已经拿到源码、但卡在环境配置上的开发者也适合想复盘一遍标准后台环境搭建流程的熟手。2. 装前定版本JDK、Maven、MySQL、Redis 四件套怎么选2.1 JDK 版本先看 Spring Boot 父工程再决定装 8 还是 17这套系统能不能跑起来第一道门槛不是代码是 JDK。Spring Boot 2.7.x 官方支持 JDK 8 到 JDK 17但 Spring Security 5.7 之后废弃了WebSecurityConfigurerAdapter很多老教程里的配置类在 JDK 17 下编译没问题运行时会提示找不到适配器。我一般会先打开项目根目录的pom.xml看parent里的spring-boot-starter-parent版本号。如果父工程是 2.x 系列稳妥做法是装 JDK 8 或 JDK 11。JDK 8 兼容性最好但如果你本地还要跑其他新项目JDK 11 是折中选择。JDK 17 不是不能跑而是需要确认 Security 配置已经改成SecurityFilterChainBean 的方式否则启动就报错。安装 JDK 在 Linux 上常见做法是包管理器直接装# Ubuntu/Debian 安装 OpenJDK 11 sudo apt update sudo apt install -y openjdk-11-jdk # 验证版本 java -version javac -versionopenjdk-11-jdk会同时装 JRE 和 JDKjavac能正常输出版本号说明编译环境就绪。如果你用 CentOS把apt换成yum包名换成java-11-openjdk-devel。装完记得检查JAVA_HOME# 查看 Java 安装路径 readlink -f $(which java) # 输出类似 /usr/lib/jvm/java-11-openjdk-amd64/bin/java # 则 JAVA_HOME 应设为 /usr/lib/jvm/java-11-openjdk-amd64JAVA_HOME不配置Maven 在某些系统上会找不到编译器报No compiler is provided in this environment。这个坑我踩过不止一次尤其是在容器里跑构建的时候。2.2 Maven 安装与本地仓库路径调整Maven 本身安装不难难的是依赖下载慢和本地仓库爆盘。先装# Ubuntu/Debian 安装 Maven sudo apt install -y maven # 验证 mvn -vmvn -v会输出 Maven 版本、Java 版本和系统信息。如果 Java 版本显示不对说明JAVA_HOME没生效回头检查上一步。接下来改settings.xml位置在~/.m2/settings.xml没有就新建。我一般会做两件事换国内镜像源、把本地仓库挪到大盘。settings localRepository/data/maven-repo/localRepository mirrors mirror idaliyun/id mirrorOfcentral/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors /settingslocalRepository指向/data/maven-repo避免默认~/.m2/repository把系统盘撑满。mirrorOf写central表示拦截中央仓库请求走阿里云公共仓库。这两个参数改完mvn clean package的速度会有明显差别。2.3 MySQL 8 安装与建库建用户这套后台管理系统通常自带sql脚本里面包含建表语句和初始数据。MySQL 版本建议 8.0因为很多 Spring Boot 2.x 项目默认驱动是mysql-connector-java8.x连 5.7 虽然也能用但时区配置容易出问题。# Ubuntu 安装 MySQL 8 sudo apt install -y mysql-server # 启动并设置开机自启 sudo systemctl start mysql sudo systemctl enable mysql # 安全初始化 sudo mysql_secure_installationmysql_secure_installation会引导你设置 root 密码、移除匿名用户、禁止 root 远程登录。生产环境按提示走本地开发可以跳过部分选项。装完后登录建库-- 创建数据库字符集用 utf8mb4 CREATE DATABASE admin_system DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; -- 创建专用用户避免直接用 root CREATE USER admin_userlocalhost IDENTIFIED BY YourStrongPassword; -- 授权 GRANT ALL PRIVILEGES ON admin_system.* TO admin_userlocalhost; FLUSH PRIVILEGES;字符集必须用utf8mb4否则后台菜单里的中文、emoji 或者特殊符号会变成问号。utf8mb4_general_ci是通用排序规则兼容性比utf8mb4_unicode_ci更稳。建完库再导入项目自带的sql文件mysql -u admin_user -p admin_system /path/to/init.sql导入时如果报Unknown command \多半是sql文件里有反斜杠转义用--default-character-setutf8mb4再试一次。2.4 Redis 安装与密码配置Redis 在这套系统里通常承担验证码存储、登录 Token 缓存、菜单权限缓存。装 Redis 比 MySQL 简单# Ubuntu 安装 Redis sudo apt install -y redis-server # 启动 sudo systemctl start redis-server sudo systemctl enable redis-server # 测试连接 redis-cli ping返回PONG说明服务正常。但默认配置没有密码Spring Boot 连接时会报NOAUTH Authentication required或者直接连上但生产环境不安全。我一般会改/etc/redis/redis.conf# 设置访问密码 requirepass YourRedisPassword # 绑定本地回环禁止外部访问 bind 127.0.0.1 # 保护模式开启 protected-mode yes改完重启sudo systemctl restart redis-server redis-cli -a YourRedisPassword pingrequirepass设置密码后redis-cli需要-a参数才能操作。bind 127.0.0.1确保只有本机能连避免暴露到公网。这两项配完Spring Boot 的application.yml里也要同步改spring: redis: host: 127.0.0.1 port: 6379 password: YourRedisPassword database: 0database: 0是默认库如果项目里用了其他库编号按实际改。密码两边必须一致否则启动时RedisConnectionFailureException直接抛出来。3. 导入项目与配置从 pom.xml 到 application.yml 的逐项核对3.1 用 IDE 导入 Maven 项目并解决依赖冲突源码拿到手第一步是导入 IDE。IntelliJ IDEA 选Open指向项目根目录的pom.xml等 Maven 自动下载依赖。如果右下角弹出Maven projects need to be imported点Import Changes。依赖下载完后常见问题是spring-boot-starter-security和spring-boot-starter-web版本不一致。检查pom.xml里有没有显式指定版本号如果有确认和父工程版本匹配。我一般会跑一遍mvn dependency:tree -Dincludesorg.springframework.security输出里如果出现多个不同版本的spring-security-core说明有传递依赖冲突。解决办法是在pom.xml里用dependencyManagement锁定版本或者直接排除冲突依赖。另一个高频问题是 Lombok 插件没装。项目里大量用Data、Slf4jIDE 不装 Lombok 插件代码全是红。IDEA 在Settings - Plugins搜 Lombok 安装重启后开启Annotation Processors。3.2 application.yml 关键参数逐项说明application.yml是这套系统能不能连上数据库和 Redis 的关键。我一般按下面顺序核对server: port: 8080 servlet: context-path: /admin spring: datasource: url: jdbc:mysql://127.0.0.1:3306/admin_system?useUnicodetruecharacterEncodingutf8mb4serverTimezoneAsia/ShanghaiuseSSLfalse username: admin_user password: YourStrongPassword driver-class-name: com.mysql.cj.jdbc.Driver redis: host: 127.0.0.1 port: 6379 password: YourRedisPassword database: 0 timeout: 5000 mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.admin.entity configuration: map-underscore-to-camel-case: trueserver.servlet.context-path是后台访问前缀如果项目里写的是/admin访问地址就是http://localhost:8080/admin。datasource.url里的serverTimezoneAsia/Shanghai必须加MySQL 8 不加时区会报The server time zone value UTC is unrecognized。useSSLfalse本地开发关掉生产环境按需开启。mybatis.mapper-locations指向 XML 映射文件位置type-aliases-package是实体类包名map-underscore-to-camel-case开启后数据库的user_name会自动映射到 Java 的userName。这三个参数错一个查询结果就是空或者报Invalid bound statement。3.3 Spring Security 配置类适配与放行规则Spring Security 是这套系统里最容易翻车的部分。如果项目用的是 Spring Boot 2.7 以上WebSecurityConfigurerAdapter已经废弃需要改成 Bean 方式Configuration EnableWebSecurity public class SecurityConfig { Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .authorizeRequests() .antMatchers(/login, /css/**, /js/**, /captcha).permitAll() .anyRequest().authenticated() .and() .formLogin() .loginPage(/login) .defaultSuccessUrl(/index) .permitAll() .and() .logout() .logoutUrl(/logout) .logoutSuccessUrl(/login) .and() .csrf().disable(); return http.build(); } }antMatchers里放行登录页、静态资源、验证码接口anyRequest().authenticated()表示其他全部需要认证。formLogin指定自定义登录页和成功跳转地址。csrf().disable()在前后端分离或者纯后台场景下常见做法是关掉否则 POST 请求会被拦截。如果项目里还是旧版WebSecurityConfigurerAdapter而你的 Spring Boot 是 2.7.x启动会报NoClassDefFoundError。解决办法要么降 Spring Boot 版本到 2.6.x要么按上面改成 Bean 方式。我一般选后者因为新版本安全补丁更全。4. 避坑与排查启动失败、登录循环、Redis 超时的常见问题4.1 启动报数据库连接失败先看驱动再看时区现象启动时抛Cannot load driver class: com.mysql.cj.jdbc.Driver或者Communications link failure。原因第一种是pom.xml里没加 MySQL 驱动依赖或者驱动版本和 MySQL 版本不匹配。第二种是 MySQL 没启动或者url里的端口、库名写错。解决先确认pom.xml有mysql-connector-java依赖版本用 8.0.x。然后systemctl status mysql看服务状态mysql -u admin_user -p手动登录测试。如果报时区错误在url末尾加serverTimezoneAsia/Shanghai。4.2 登录页 302 循环Security 放行规则写错现象访问登录页浏览器不断跳转最终提示ERR_TOO_MANY_REDIRECTS。原因antMatchers里没有放行登录页本身或者loginPage路径和实际 Controller 映射不一致。Security 拦截了/login又跳转到/login形成死循环。解决确认antMatchers(/login).permitAll()存在且formLogin().loginPage(/login)的路径和 Controller 里GetMapping(/login)完全一致。如果登录页在templates下还需要模板引擎依赖否则返回 404 也会触发循环。4.3 Redis 连接超时密码、绑定地址、保护模式三查现象启动时报RedisConnectionFailureException: Unable to connect to Redis。原因application.yml里的密码和redis.conf不一致或者 Redis 绑定了127.0.0.1但项目连的是其他 IP或者保护模式开启且没有密码。解决redis-cli -a 密码 ping手动测试。如果手动能通检查application.yml的host、port、password三项。如果手动不通看redis.conf的bind和requirepass改完重启 Redis。4.4 MyBatis 报 Invalid bound statementmapper 路径和包名对不上现象查询时报org.apache.ibatis.binding.BindingException: Invalid bound statement (not found)。原因mapper-locations配置的路径下没有对应的 XML 文件或者 XML 里的namespace和 Mapper 接口全限定名不一致。解决检查target/classes/mapper/目录下有没有 XML 文件。如果没有说明 Maven 没把resources下的 XML 打包进去需要在pom.xml的build里加resources resource directorysrc/main/resources/directory includes include**/*.xml/include /includes /resource /resources然后确认 XML 的namespace写的是 Mapper 接口的完整包名加类名。4.5 静态资源 404Security 拦截了 css/js现象登录页样式全丢控制台报GET /css/login.css 404。原因Security 默认拦截所有请求静态资源没有放行。解决在antMatchers里加/css/**、/js/**、/images/**、/fonts/**。如果用了 WebJars还要加/webjars/**。放行后重启样式就能正常加载。5. 装完怎么验证从登录到数据查询的完整走查环境装完别急着写业务。我一般会按下面顺序走一遍确认每个组件都真正通了。第一步确认端口监听。ss -tlnp | grep -E 8080|3306|6379三个端口都应该有进程监听。8080 是 Spring Boot3306 是 MySQL6379 是 Redis。少一个就回头查对应服务。第二步访问登录页。浏览器打开http://localhost:8080/admin/login如果能看到登录表单说明 Spring MVC 和 Security 的放行规则生效。如果页面样式正常说明静态资源放行也没问题。第三步用初始账号登录。项目sql脚本里通常有一个sys_user表里面存了管理员账号。常见做法是admin/123456但具体看init.sql的插入语句。登录成功后应该跳转到后台首页左侧菜单能正常展开。第四步验证 Redis 缓存。登录后执行redis-cli -a 密码 keys *应该能看到类似login:token:xxx或者captcha:xxx的键。如果没有说明 Redis 配置没生效回头检查application.yml和redis.conf。第五步验证数据库查询。点开用户管理或者菜单管理看列表能不能加载。如果列表为空但数据库里有数据检查 MyBatis 的mapper-locations和map-underscore-to-camel-case。如果报Invalid bound statement按 4.4 排查。第六步验证权限控制。用不同角色的账号登录看菜单和按钮是否按权限显示。Spring Security 的PreAuthorize注解需要开启EnableGlobalMethodSecurity(prePostEnabled true)否则注解不生效。下面这张表是我每次装完都会核对的检查项检查项预期结果失败时看哪里JDK 版本java -version与 pom 匹配JAVA_HOME、pom parentMaven 依赖mvn clean package成功settings.xml、镜像源MySQL 连接mysql -u admin_user -p能登录服务状态、url、时区Redis 连接redis-cli -a 密码 ping返回 PONGrequirepass、bind登录页浏览器能打开且样式正常Security 放行规则登录跳转成功进入后台首页formLogin 配置数据查询列表有数据mapper-locations、namespace权限控制不同角色菜单不同EnableGlobalMethodSecurity最后一步我会把application.yml里的密码换成环境变量避免提交到代码仓库。常见做法是用${DB_PASSWORD}占位启动时通过-DDB_PASSWORDxxx传入。这样本地能跑线上也不会泄露。从那以后我每次装这套环境都会先跑一遍mvn clean package -DskipTests确认编译通过再启动。因为很多配置问题在编译阶段就能暴露等到运行时才查成本高得多。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/23 17:47:55 · 阅读 1.2k Spring Boot + MyBatis + Spring Security + Redis 后台管理系统环境搭建与避坑指南
简介这是一套基于Spring Boot、MyBatis、Spring MVC、Spring Security与Redis构建的完整网站后台管理系统源码面向具备一定Java Web基础、希望深入理解企业级开发技术栈协同方式的开发者与学习者。项目将持久层、控制层、安全认证与缓存中间件整合在同一工程中可用于课程设计、毕业设计参考或后台管理系统的二次开发。压缩包共326个文件约1.76MB其中95个Java源文件承载核心业务与配置逻辑45个JavaScript、33个HTML与19个CSS文件构成前端交互与页面样式另有12个XML映射与配置文件、1个SQL脚本用于数据库初始化以及gif、png、字体等静态资源。已有958人学习下载。通过研读源码读者可掌握Spring Security的登录认证与权限控制流程、MyBatis的SQL映射写法、Redis缓存集成方式以及前后端资源在Spring Boot工程中的组织与配置思路适合作为技术进阶与项目实战的参考素材。1. 从一台干净服务器开始Spring Boot MyBatis Spring MVC Spring Security Redis 后台管理系统环境搭建很多人第一次拿到这套“Spring Boot MyBatis Spring MVC Spring Security Redis 完整网站后台管理系统”源码时第一反应是直接双击 IDE 的 Run。结果大概率是数据库连不上、Redis 拒绝连接、登录页 302 循环、控制台一片红。这套组合涉及五个核心组件版本错一个后面全是玄学问题。我见过最典型的翻车现场是有人用 Spring Boot 3.x 去跑一份为 2.7.x 写的 Security 配置WebSecurityConfigurerAdapter直接报红整个认证链起不来。所以这篇安装笔记不聊架构设计只解决一件事从零把这套环境装到能登录、能查数据、能跑通后台首页。适合手里已经拿到源码、但卡在环境配置上的开发者也适合想复盘一遍标准后台环境搭建流程的熟手。2. 装前定版本JDK、Maven、MySQL、Redis 四件套怎么选2.1 JDK 版本先看 Spring Boot 父工程再决定装 8 还是 17这套系统能不能跑起来第一道门槛不是代码是 JDK。Spring Boot 2.7.x 官方支持 JDK 8 到 JDK 17但 Spring Security 5.7 之后废弃了WebSecurityConfigurerAdapter很多老教程里的配置类在 JDK 17 下编译没问题运行时会提示找不到适配器。我一般会先打开项目根目录的pom.xml看parent里的spring-boot-starter-parent版本号。如果父工程是 2.x 系列稳妥做法是装 JDK 8 或 JDK 11。JDK 8 兼容性最好但如果你本地还要跑其他新项目JDK 11 是折中选择。JDK 17 不是不能跑而是需要确认 Security 配置已经改成SecurityFilterChainBean 的方式否则启动就报错。安装 JDK 在 Linux 上常见做法是包管理器直接装# Ubuntu/Debian 安装 OpenJDK 11 sudo apt update sudo apt install -y openjdk-11-jdk # 验证版本 java -version javac -versionopenjdk-11-jdk会同时装 JRE 和 JDKjavac能正常输出版本号说明编译环境就绪。如果你用 CentOS把apt换成yum包名换成java-11-openjdk-devel。装完记得检查JAVA_HOME# 查看 Java 安装路径 readlink -f $(which java) # 输出类似 /usr/lib/jvm/java-11-openjdk-amd64/bin/java # 则 JAVA_HOME 应设为 /usr/lib/jvm/java-11-openjdk-amd64JAVA_HOME不配置Maven 在某些系统上会找不到编译器报No compiler is provided in this environment。这个坑我踩过不止一次尤其是在容器里跑构建的时候。2.2 Maven 安装与本地仓库路径调整Maven 本身安装不难难的是依赖下载慢和本地仓库爆盘。先装# Ubuntu/Debian 安装 Maven sudo apt install -y maven # 验证 mvn -vmvn -v会输出 Maven 版本、Java 版本和系统信息。如果 Java 版本显示不对说明JAVA_HOME没生效回头检查上一步。接下来改settings.xml位置在~/.m2/settings.xml没有就新建。我一般会做两件事换国内镜像源、把本地仓库挪到大盘。settings localRepository/data/maven-repo/localRepository mirrors mirror idaliyun/id mirrorOfcentral/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors /settingslocalRepository指向/data/maven-repo避免默认~/.m2/repository把系统盘撑满。mirrorOf写central表示拦截中央仓库请求走阿里云公共仓库。这两个参数改完mvn clean package的速度会有明显差别。2.3 MySQL 8 安装与建库建用户这套后台管理系统通常自带sql脚本里面包含建表语句和初始数据。MySQL 版本建议 8.0因为很多 Spring Boot 2.x 项目默认驱动是mysql-connector-java8.x连 5.7 虽然也能用但时区配置容易出问题。# Ubuntu 安装 MySQL 8 sudo apt install -y mysql-server # 启动并设置开机自启 sudo systemctl start mysql sudo systemctl enable mysql # 安全初始化 sudo mysql_secure_installationmysql_secure_installation会引导你设置 root 密码、移除匿名用户、禁止 root 远程登录。生产环境按提示走本地开发可以跳过部分选项。装完后登录建库-- 创建数据库字符集用 utf8mb4 CREATE DATABASE admin_system DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; -- 创建专用用户避免直接用 root CREATE USER admin_userlocalhost IDENTIFIED BY YourStrongPassword; -- 授权 GRANT ALL PRIVILEGES ON admin_system.* TO admin_userlocalhost; FLUSH PRIVILEGES;字符集必须用utf8mb4否则后台菜单里的中文、emoji 或者特殊符号会变成问号。utf8mb4_general_ci是通用排序规则兼容性比utf8mb4_unicode_ci更稳。建完库再导入项目自带的sql文件mysql -u admin_user -p admin_system /path/to/init.sql导入时如果报Unknown command \多半是sql文件里有反斜杠转义用--default-character-setutf8mb4再试一次。2.4 Redis 安装与密码配置Redis 在这套系统里通常承担验证码存储、登录 Token 缓存、菜单权限缓存。装 Redis 比 MySQL 简单# Ubuntu 安装 Redis sudo apt install -y redis-server # 启动 sudo systemctl start redis-server sudo systemctl enable redis-server # 测试连接 redis-cli ping返回PONG说明服务正常。但默认配置没有密码Spring Boot 连接时会报NOAUTH Authentication required或者直接连上但生产环境不安全。我一般会改/etc/redis/redis.conf# 设置访问密码 requirepass YourRedisPassword # 绑定本地回环禁止外部访问 bind 127.0.0.1 # 保护模式开启 protected-mode yes改完重启sudo systemctl restart redis-server redis-cli -a YourRedisPassword pingrequirepass设置密码后redis-cli需要-a参数才能操作。bind 127.0.0.1确保只有本机能连避免暴露到公网。这两项配完Spring Boot 的application.yml里也要同步改spring: redis: host: 127.0.0.1 port: 6379 password: YourRedisPassword database: 0database: 0是默认库如果项目里用了其他库编号按实际改。密码两边必须一致否则启动时RedisConnectionFailureException直接抛出来。3. 导入项目与配置从 pom.xml 到 application.yml 的逐项核对3.1 用 IDE 导入 Maven 项目并解决依赖冲突源码拿到手第一步是导入 IDE。IntelliJ IDEA 选Open指向项目根目录的pom.xml等 Maven 自动下载依赖。如果右下角弹出Maven projects need to be imported点Import Changes。依赖下载完后常见问题是spring-boot-starter-security和spring-boot-starter-web版本不一致。检查pom.xml里有没有显式指定版本号如果有确认和父工程版本匹配。我一般会跑一遍mvn dependency:tree -Dincludesorg.springframework.security输出里如果出现多个不同版本的spring-security-core说明有传递依赖冲突。解决办法是在pom.xml里用dependencyManagement锁定版本或者直接排除冲突依赖。另一个高频问题是 Lombok 插件没装。项目里大量用Data、Slf4jIDE 不装 Lombok 插件代码全是红。IDEA 在Settings - Plugins搜 Lombok 安装重启后开启Annotation Processors。3.2 application.yml 关键参数逐项说明application.yml是这套系统能不能连上数据库和 Redis 的关键。我一般按下面顺序核对server: port: 8080 servlet: context-path: /admin spring: datasource: url: jdbc:mysql://127.0.0.1:3306/admin_system?useUnicodetruecharacterEncodingutf8mb4serverTimezoneAsia/ShanghaiuseSSLfalse username: admin_user password: YourStrongPassword driver-class-name: com.mysql.cj.jdbc.Driver redis: host: 127.0.0.1 port: 6379 password: YourRedisPassword database: 0 timeout: 5000 mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.admin.entity configuration: map-underscore-to-camel-case: trueserver.servlet.context-path是后台访问前缀如果项目里写的是/admin访问地址就是http://localhost:8080/admin。datasource.url里的serverTimezoneAsia/Shanghai必须加MySQL 8 不加时区会报The server time zone value UTC is unrecognized。useSSLfalse本地开发关掉生产环境按需开启。mybatis.mapper-locations指向 XML 映射文件位置type-aliases-package是实体类包名map-underscore-to-camel-case开启后数据库的user_name会自动映射到 Java 的userName。这三个参数错一个查询结果就是空或者报Invalid bound statement。3.3 Spring Security 配置类适配与放行规则Spring Security 是这套系统里最容易翻车的部分。如果项目用的是 Spring Boot 2.7 以上WebSecurityConfigurerAdapter已经废弃需要改成 Bean 方式Configuration EnableWebSecurity public class SecurityConfig { Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .authorizeRequests() .antMatchers(/login, /css/**, /js/**, /captcha).permitAll() .anyRequest().authenticated() .and() .formLogin() .loginPage(/login) .defaultSuccessUrl(/index) .permitAll() .and() .logout() .logoutUrl(/logout) .logoutSuccessUrl(/login) .and() .csrf().disable(); return http.build(); } }antMatchers里放行登录页、静态资源、验证码接口anyRequest().authenticated()表示其他全部需要认证。formLogin指定自定义登录页和成功跳转地址。csrf().disable()在前后端分离或者纯后台场景下常见做法是关掉否则 POST 请求会被拦截。如果项目里还是旧版WebSecurityConfigurerAdapter而你的 Spring Boot 是 2.7.x启动会报NoClassDefFoundError。解决办法要么降 Spring Boot 版本到 2.6.x要么按上面改成 Bean 方式。我一般选后者因为新版本安全补丁更全。4. 避坑与排查启动失败、登录循环、Redis 超时的常见问题4.1 启动报数据库连接失败先看驱动再看时区现象启动时抛Cannot load driver class: com.mysql.cj.jdbc.Driver或者Communications link failure。原因第一种是pom.xml里没加 MySQL 驱动依赖或者驱动版本和 MySQL 版本不匹配。第二种是 MySQL 没启动或者url里的端口、库名写错。解决先确认pom.xml有mysql-connector-java依赖版本用 8.0.x。然后systemctl status mysql看服务状态mysql -u admin_user -p手动登录测试。如果报时区错误在url末尾加serverTimezoneAsia/Shanghai。4.2 登录页 302 循环Security 放行规则写错现象访问登录页浏览器不断跳转最终提示ERR_TOO_MANY_REDIRECTS。原因antMatchers里没有放行登录页本身或者loginPage路径和实际 Controller 映射不一致。Security 拦截了/login又跳转到/login形成死循环。解决确认antMatchers(/login).permitAll()存在且formLogin().loginPage(/login)的路径和 Controller 里GetMapping(/login)完全一致。如果登录页在templates下还需要模板引擎依赖否则返回 404 也会触发循环。4.3 Redis 连接超时密码、绑定地址、保护模式三查现象启动时报RedisConnectionFailureException: Unable to connect to Redis。原因application.yml里的密码和redis.conf不一致或者 Redis 绑定了127.0.0.1但项目连的是其他 IP或者保护模式开启且没有密码。解决redis-cli -a 密码 ping手动测试。如果手动能通检查application.yml的host、port、password三项。如果手动不通看redis.conf的bind和requirepass改完重启 Redis。4.4 MyBatis 报 Invalid bound statementmapper 路径和包名对不上现象查询时报org.apache.ibatis.binding.BindingException: Invalid bound statement (not found)。原因mapper-locations配置的路径下没有对应的 XML 文件或者 XML 里的namespace和 Mapper 接口全限定名不一致。解决检查target/classes/mapper/目录下有没有 XML 文件。如果没有说明 Maven 没把resources下的 XML 打包进去需要在pom.xml的build里加resources resource directorysrc/main/resources/directory includes include**/*.xml/include /includes /resource /resources然后确认 XML 的namespace写的是 Mapper 接口的完整包名加类名。4.5 静态资源 404Security 拦截了 css/js现象登录页样式全丢控制台报GET /css/login.css 404。原因Security 默认拦截所有请求静态资源没有放行。解决在antMatchers里加/css/**、/js/**、/images/**、/fonts/**。如果用了 WebJars还要加/webjars/**。放行后重启样式就能正常加载。5. 装完怎么验证从登录到数据查询的完整走查环境装完别急着写业务。我一般会按下面顺序走一遍确认每个组件都真正通了。第一步确认端口监听。ss -tlnp | grep -E 8080|3306|6379三个端口都应该有进程监听。8080 是 Spring Boot3306 是 MySQL6379 是 Redis。少一个就回头查对应服务。第二步访问登录页。浏览器打开http://localhost:8080/admin/login如果能看到登录表单说明 Spring MVC 和 Security 的放行规则生效。如果页面样式正常说明静态资源放行也没问题。第三步用初始账号登录。项目sql脚本里通常有一个sys_user表里面存了管理员账号。常见做法是admin/123456但具体看init.sql的插入语句。登录成功后应该跳转到后台首页左侧菜单能正常展开。第四步验证 Redis 缓存。登录后执行redis-cli -a 密码 keys *应该能看到类似login:token:xxx或者captcha:xxx的键。如果没有说明 Redis 配置没生效回头检查application.yml和redis.conf。第五步验证数据库查询。点开用户管理或者菜单管理看列表能不能加载。如果列表为空但数据库里有数据检查 MyBatis 的mapper-locations和map-underscore-to-camel-case。如果报Invalid bound statement按 4.4 排查。第六步验证权限控制。用不同角色的账号登录看菜单和按钮是否按权限显示。Spring Security 的PreAuthorize注解需要开启EnableGlobalMethodSecurity(prePostEnabled true)否则注解不生效。下面这张表是我每次装完都会核对的检查项检查项预期结果失败时看哪里JDK 版本java -version与 pom 匹配JAVA_HOME、pom parentMaven 依赖mvn clean package成功settings.xml、镜像源MySQL 连接mysql -u admin_user -p能登录服务状态、url、时区Redis 连接redis-cli -a 密码 ping返回 PONGrequirepass、bind登录页浏览器能打开且样式正常Security 放行规则登录跳转成功进入后台首页formLogin 配置数据查询列表有数据mapper-locations、namespace权限控制不同角色菜单不同EnableGlobalMethodSecurity最后一步我会把application.yml里的密码换成环境变量避免提交到代码仓库。常见做法是用${DB_PASSWORD}占位启动时通过-DDB_PASSWORDxxx传入。这样本地能跑线上也不会泄露。从那以后我每次装这套环境都会先跑一遍mvn clean package -DskipTests确认编译通过再启动。因为很多配置问题在编译阶段就能暴露等到运行时才查成本高得多。希望帮到你。本文还有配套的精品资源点击获取