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 -version

openjdk-11-jdk会同时装 JRE 和 JDK，javac能正常输出版本号，说明编译环境就绪。如果你用 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-amd64

JAVA_HOME不配置，Maven 在某些系统上会找不到编译器，报No compiler is provided in this environment。这个坑我踩过不止一次，尤其是在容器里跑构建的时候。

2.2 Maven 安装与本地仓库路径调整

Maven 本身安装不难，难的是依赖下载慢和本地仓库爆盘。先装：

# Ubuntu/Debian 安装 Maven sudo apt install -y maven # 验证 mvn -v

mvn -v会输出 Maven 版本、Java 版本和系统信息。如果 Java 版本显示不对，说明JAVA_HOME没生效，回头检查上一步。

接下来改settings.xml，位置在~/.m2/settings.xml，没有就新建。我一般会做两件事：换国内镜像源、把本地仓库挪到大盘。

<settings> <localRepository>/data/maven-repo</localRepository> <mirrors> <mirror> <id>aliyun</id> <mirrorOf>central</mirrorOf> <url>https://maven.aliyun.com/repository/public</url> </mirror> </mirrors> </settings>

localRepository指向/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_installation

mysql_secure_installation会引导你设置 root 密码、移除匿名用户、禁止 root 远程登录。生产环境按提示走，本地开发可以跳过部分选项。

装完后登录建库：

-- 创建数据库，字符集用 utf8mb4 CREATE DATABASE admin_system DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; -- 创建专用用户，避免直接用 root CREATE USER 'admin_user'@'localhost' IDENTIFIED BY 'YourStrongPassword'; -- 授权 GRANT ALL PRIVILEGES ON admin_system.* TO 'admin_user'@'localhost'; 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-set=utf8mb4再试一次。

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 ping

requirepass设置密码后，redis-cli需要-a参数才能操作。bind 127.0.0.1确保只有本机能连，避免暴露到公网。这两项配完，Spring Boot 的application.yml里也要同步改：

spring: redis: host: 127.0.0.1 port: 6379 password: YourRedisPassword database: 0

database: 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 -Dincludes=org.springframework.security

输出里如果出现多个不同版本的spring-security-core，说明有传递依赖冲突。解决办法是在pom.xml里用<dependencyManagement>锁定版本，或者直接排除冲突依赖。

另一个高频问题是 Lombok 插件没装。项目里大量用@Data、@Slf4j，IDE 不装 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?useUnicode=true&characterEncoding=utf8mb4&serverTimezone=Asia/Shanghai&useSSL=false 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: true

server.servlet.context-path是后台访问前缀，如果项目里写的是/admin，访问地址就是http://localhost:8080/admin。datasource.url里的serverTimezone=Asia/Shanghai必须加，MySQL 8 不加时区会报The server time zone value 'UTC' is unrecognized。useSSL=false本地开发关掉，生产环境按需开启。

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末尾加serverTimezone=Asia/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 statement：mapper 路径和包名对不上

现象：查询时报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> <directory>src/main/resources</directory> <includes> <include>**/*.xml</include> </includes> </resource> </resources>

然后确认 XML 的namespace写的是 Mapper 接口的完整包名加类名。

4.5 静态资源 404：Security 拦截了 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 Boot，3306 是 MySQL，6379 是 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)，否则注解不生效。

下面这张表是我每次装完都会核对的检查项：

最后一步，我会把application.yml里的密码换成环境变量，避免提交到代码仓库。常见做法是用${DB_PASSWORD}占位，启动时通过-DDB_PASSWORD=xxx传入。这样本地能跑，线上也不会泄露。

从那以后我每次装这套环境，都会先跑一遍mvn clean package -DskipTests，确认编译通过再启动。因为很多配置问题在编译阶段就能暴露，等到运行时才查，成本高得多。希望帮到你。

本文还有配套的精品资源，点击获取