環(huán)境搭建與避坑指南)
簡介這是一套基于Spring Boot、MyBatis、Spring MVC、Spring Security與Redis構建的完整網(wǎng)站后臺管理系統(tǒng)源碼面向具備一定Java Web基礎、希望深入理解企業(yè)級開發(fā)技術棧協(xié)同方式的開發(fā)者與學習者。項目將持久層、控制層、安全認證與緩存中間件整合在同一工程中可用于課程設計、畢業(yè)設計參考或后臺管理系統(tǒng)的二次開發(fā)。壓縮包共326個文件約1.76MB其中95個Java源文件承載核心業(yè)務與配置邏輯45個JavaScript、33個HTML與19個CSS文件構成前端交互與頁面樣式另有12個XML映射與配置文件、1個SQL腳本用于數(shù)據(jù)庫初始化以及gif、png、字體等靜態(tài)資源。已有958人學習下載。通過研讀源碼讀者可掌握Spring Security的登錄認證與權限控制流程、MyBatis的SQL映射寫法、Redis緩存集成方式以及前后端資源在Spring Boot工程中的組織與配置思路適合作為技術進階與項目實戰(zhàn)的參考素材。1. 從一臺干凈服務器開始Spring Boot MyBatis Spring MVC Spring Security Redis 后臺管理系統(tǒng)環(huán)境搭建很多人第一次拿到這套“Spring Boot MyBatis Spring MVC Spring Security Redis 完整網(wǎng)站后臺管理系統(tǒng)”源碼時第一反應是直接雙擊 IDE 的 Run。結果大概率是數(shù)據(jù)庫連不上、Redis 拒絕連接、登錄頁 302 循環(huán)、控制臺一片紅。這套組合涉及五個核心組件版本錯一個后面全是玄學問題。我見過最典型的翻車現(xiàn)場是有人用 Spring Boot 3.x 去跑一份為 2.7.x 寫的 Security 配置WebSecurityConfigurerAdapter直接報紅整個認證鏈起不來。所以這篇安裝筆記不聊架構設計只解決一件事從零把這套環(huán)境裝到能登錄、能查數(shù)據(jù)、能跑通后臺首頁。適合手里已經(jīng)拿到源碼、但卡在環(huán)境配置上的開發(fā)者也適合想復盤一遍標準后臺環(huán)境搭建流程的熟手。2. 裝前定版本JDK、Maven、MySQL、Redis 四件套怎么選2.1 JDK 版本先看 Spring Boot 父工程再決定裝 8 還是 17這套系統(tǒng)能不能跑起來第一道門檻不是代碼是 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 系列穩(wěn)妥做法是裝 JDK 8 或 JDK 11。JDK 8 兼容性最好但如果你本地還要跑其他新項目JDK 11 是折中選擇。JDK 17 不是不能跑而是需要確認 Security 配置已經(jīng)改成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能正常輸出版本號說明編譯環(huán)境就緒。如果你用 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 在某些系統(tǒng)上會找不到編譯器報No compiler is provided in this environment。這個坑我踩過不止一次尤其是在容器里跑構建的時候。2.2 Maven 安裝與本地倉庫路徑調(diào)整Maven 本身安裝不難難的是依賴下載慢和本地倉庫爆盤。先裝# Ubuntu/Debian 安裝 Maven sudo apt install -y maven # 驗證 mvn -vmvn -v會輸出 Maven 版本、Java 版本和系統(tǒng)信息。如果 Java 版本顯示不對說明JAVA_HOME沒生效回頭檢查上一步。接下來改settings.xml位置在~/.m2/settings.xml沒有就新建。我一般會做兩件事?lián)Q國內(nèi)鏡像源、把本地倉庫挪到大盤。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把系統(tǒng)盤撐滿。mirrorOf寫central表示攔截中央倉庫請求走阿里云公共倉庫。這兩個參數(shù)改完mvn clean package的速度會有明顯差別。2.3 MySQL 8 安裝與建庫建用戶這套后臺管理系統(tǒng)通常自帶sql腳本里面包含建表語句和初始數(shù)據(jù)。MySQL 版本建議 8.0因為很多 Spring Boot 2.x 項目默認驅(qū)動是mysql-connector-java8.x連 5.7 雖然也能用但時區(qū)配置容易出問題。# 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 遠程登錄。生產(chǎn)環(huán)境按提示走本地開發(fā)可以跳過部分選項。裝完后登錄建庫-- 創(chuàng)建數(shù)據(jù)庫字符集用 utf8mb4 CREATE DATABASE admin_system DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; -- 創(chuàng)建專用用戶避免直接用 root CREATE USER admin_userlocalhost IDENTIFIED BY YourStrongPassword; -- 授權 GRANT ALL PRIVILEGES ON admin_system.* TO admin_userlocalhost; FLUSH PRIVILEGES;字符集必須用utf8mb4否則后臺菜單里的中文、emoji 或者特殊符號會變成問號。utf8mb4_general_ci是通用排序規(guī)則兼容性比utf8mb4_unicode_ci更穩(wěn)。建完庫再導入項目自帶的sql文件mysql -u admin_user -p admin_system /path/to/init.sql導入時如果報Unknown command \多半是sql文件里有反斜杠轉(zhuǎn)義用--default-character-setutf8mb4再試一次。2.4 Redis 安裝與密碼配置Redis 在這套系統(tǒng)里通常承擔驗證碼存儲、登錄 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或者直接連上但生產(chǎn)環(huán)境不安全。我一般會改/etc/redis/redis.conf# 設置訪問密碼 requirepass YourRedisPassword # 綁定本地回環(huán)禁止外部訪問 bind 127.0.0.1 # 保護模式開啟 protected-mode yes改完重啟sudo systemctl restart redis-server redis-cli -a YourRedisPassword pingrequirepass設置密碼后redis-cli需要-a參數(shù)才能操作。bind 127.0.0.1確保只有本機能連避免暴露到公網(wǎng)。這兩項配完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輸出里如果出現(xiàn)多個不同版本的spring-security-core說明有傳遞依賴沖突。解決辦法是在pom.xml里用dependencyManagement鎖定版本或者直接排除沖突依賴。另一個高頻問題是 Lombok 插件沒裝。項目里大量用Data、Slf4jIDE 不裝 Lombok 插件代碼全是紅。IDEA 在Settings - Plugins搜 Lombok 安裝重啟后開啟Annotation Processors。3.2 application.yml 關鍵參數(shù)逐項說明application.yml是這套系統(tǒng)能不能連上數(shù)據(jù)庫和 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 不加時區(qū)會報The server time zone value UTC is unrecognized。useSSLfalse本地開發(fā)關掉生產(chǎn)環(huán)境按需開啟。mybatis.mapper-locations指向 XML 映射文件位置type-aliases-package是實體類包名map-underscore-to-camel-case開啟后數(shù)據(jù)庫的user_name會自動映射到 Java 的userName。這三個參數(shù)錯一個查詢結果就是空或者報Invalid bound statement。3.3 Spring Security 配置類適配與放行規(guī)則Spring Security 是這套系統(tǒng)里最容易翻車的部分。如果項目用的是 Spring Boot 2.7 以上WebSecurityConfigurerAdapter已經(jīng)廢棄需要改成 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里放行登錄頁、靜態(tài)資源、驗證碼接口anyRequest().authenticated()表示其他全部需要認證。formLogin指定自定義登錄頁和成功跳轉(zhuǎn)地址。csrf().disable()在前后端分離或者純后臺場景下常見做法是關掉否則 POST 請求會被攔截。如果項目里還是舊版WebSecurityConfigurerAdapter而你的 Spring Boot 是 2.7.x啟動會報NoClassDefFoundError。解決辦法要么降 Spring Boot 版本到 2.6.x要么按上面改成 Bean 方式。我一般選后者因為新版本安全補丁更全。4. 避坑與排查啟動失敗、登錄循環(huán)、Redis 超時的常見問題4.1 啟動報數(shù)據(jù)庫連接失敗先看驅(qū)動再看時區(qū)現(xiàn)象啟動時拋Cannot load driver class: com.mysql.cj.jdbc.Driver或者Communications link failure。原因第一種是pom.xml里沒加 MySQL 驅(qū)動依賴或者驅(qū)動版本和 MySQL 版本不匹配。第二種是 MySQL 沒啟動或者url里的端口、庫名寫錯。解決先確認pom.xml有mysql-connector-java依賴版本用 8.0.x。然后systemctl status mysql看服務狀態(tài)mysql -u admin_user -p手動登錄測試。如果報時區(qū)錯誤在url末尾加serverTimezoneAsia/Shanghai。4.2 登錄頁 302 循環(huán)Security 放行規(guī)則寫錯現(xiàn)象訪問登錄頁瀏覽器不斷跳轉(zhuǎn)最終提示ERR_TOO_MANY_REDIRECTS。原因antMatchers里沒有放行登錄頁本身或者loginPage路徑和實際 Controller 映射不一致。Security 攔截了/login又跳轉(zhuǎn)到/login形成死循環(huán)。解決確認antMatchers(/login).permitAll()存在且formLogin().loginPage(/login)的路徑和 Controller 里GetMapping(/login)完全一致。如果登錄頁在templates下還需要模板引擎依賴否則返回 404 也會觸發(fā)循環(huán)。4.3 Redis 連接超時密碼、綁定地址、保護模式三查現(xiàn)象啟動時報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 路徑和包名對不上現(xiàn)象查詢時報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 靜態(tài)資源 404Security 攔截了 css/js現(xiàn)象登錄頁樣式全丟控制臺報GET /css/login.css 404。原因Security 默認攔截所有請求靜態(tài)資源沒有放行。解決在antMatchers里加/css/**、/js/**、/images/**、/fonts/**。如果用了 WebJars還要加/webjars/**。放行后重啟樣式就能正常加載。5. 裝完怎么驗證從登錄到數(shù)據(jù)查詢的完整走查環(huán)境裝完別急著寫業(yè)務。我一般會按下面順序走一遍確認每個組件都真正通了。第一步確認端口監(jiān)聽。ss -tlnp | grep -E 8080|3306|6379三個端口都應該有進程監(jiān)聽。8080 是 Spring Boot3306 是 MySQL6379 是 Redis。少一個就回頭查對應服務。第二步訪問登錄頁。瀏覽器打開http://localhost:8080/admin/login如果能看到登錄表單說明 Spring MVC 和 Security 的放行規(guī)則生效。如果頁面樣式正常說明靜態(tài)資源放行也沒問題。第三步用初始賬號登錄。項目sql腳本里通常有一個sys_user表里面存了管理員賬號。常見做法是admin/123456但具體看init.sql的插入語句。登錄成功后應該跳轉(zhuǎn)到后臺首頁左側菜單能正常展開。第四步驗證 Redis 緩存。登錄后執(zhí)行redis-cli -a 密碼 keys *應該能看到類似login:token:xxx或者captcha:xxx的鍵。如果沒有說明 Redis 配置沒生效回頭檢查application.yml和redis.conf。第五步驗證數(shù)據(jù)庫查詢。點開用戶管理或者菜單管理看列表能不能加載。如果列表為空但數(shù)據(jù)庫里有數(shù)據(jù)檢查 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能登錄服務狀態(tài)、url、時區(qū)Redis 連接redis-cli -a 密碼 ping返回 PONGrequirepass、bind登錄頁瀏覽器能打開且樣式正常Security 放行規(guī)則登錄跳轉(zhuǎn)成功進入后臺首頁formLogin 配置數(shù)據(jù)查詢列表有數(shù)據(jù)mapper-locations、namespace權限控制不同角色菜單不同EnableGlobalMethodSecurity最后一步我會把application.yml里的密碼換成環(huán)境變量避免提交到代碼倉庫。常見做法是用${DB_PASSWORD}占位啟動時通過-DDB_PASSWORDxxx傳入。這樣本地能跑線上也不會泄露。從那以后我每次裝這套環(huán)境都會先跑一遍mvn clean package -DskipTests確認編譯通過再啟動。因為很多配置問題在編譯階段就能暴露等到運行時才查成本高得多。希望幫到你。本文還有配套的精品資源點擊獲取 Spring Boot + MyBatis + Spring Security + Redis 后臺管理系統(tǒng)環(huán)境搭建與避坑指南
簡介這是一套基于Spring Boot、MyBatis、Spring MVC、Spring Security與Redis構建的完整網(wǎng)站后臺管理系統(tǒng)源碼面向具備一定Java Web基礎、希望深入理解企業(yè)級開發(fā)技術棧協(xié)同方式的開發(fā)者與學習者。項目將持久層、控制層、安全認證與緩存中間件整合在同一工程中可用于課程設計、畢業(yè)設計參考或后臺管理系統(tǒng)的二次開發(fā)。壓縮包共326個文件約1.76MB其中95個Java源文件承載核心業(yè)務與配置邏輯45個JavaScript、33個HTML與19個CSS文件構成前端交互與頁面樣式另有12個XML映射與配置文件、1個SQL腳本用于數(shù)據(jù)庫初始化以及gif、png、字體等靜態(tài)資源。已有958人學習下載。通過研讀源碼讀者可掌握Spring Security的登錄認證與權限控制流程、MyBatis的SQL映射寫法、Redis緩存集成方式以及前后端資源在Spring Boot工程中的組織與配置思路適合作為技術進階與項目實戰(zhàn)的參考素材。1. 從一臺干凈服務器開始Spring Boot MyBatis Spring MVC Spring Security Redis 后臺管理系統(tǒng)環(huán)境搭建很多人第一次拿到這套“Spring Boot MyBatis Spring MVC Spring Security Redis 完整網(wǎng)站后臺管理系統(tǒng)”源碼時第一反應是直接雙擊 IDE 的 Run。結果大概率是數(shù)據(jù)庫連不上、Redis 拒絕連接、登錄頁 302 循環(huán)、控制臺一片紅。這套組合涉及五個核心組件版本錯一個后面全是玄學問題。我見過最典型的翻車現(xiàn)場是有人用 Spring Boot 3.x 去跑一份為 2.7.x 寫的 Security 配置WebSecurityConfigurerAdapter直接報紅整個認證鏈起不來。所以這篇安裝筆記不聊架構設計只解決一件事從零把這套環(huán)境裝到能登錄、能查數(shù)據(jù)、能跑通后臺首頁。適合手里已經(jīng)拿到源碼、但卡在環(huán)境配置上的開發(fā)者也適合想復盤一遍標準后臺環(huán)境搭建流程的熟手。2. 裝前定版本JDK、Maven、MySQL、Redis 四件套怎么選2.1 JDK 版本先看 Spring Boot 父工程再決定裝 8 還是 17這套系統(tǒng)能不能跑起來第一道門檻不是代碼是 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 系列穩(wěn)妥做法是裝 JDK 8 或 JDK 11。JDK 8 兼容性最好但如果你本地還要跑其他新項目JDK 11 是折中選擇。JDK 17 不是不能跑而是需要確認 Security 配置已經(jīng)改成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能正常輸出版本號說明編譯環(huán)境就緒。如果你用 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 在某些系統(tǒng)上會找不到編譯器報No compiler is provided in this environment。這個坑我踩過不止一次尤其是在容器里跑構建的時候。2.2 Maven 安裝與本地倉庫路徑調(diào)整Maven 本身安裝不難難的是依賴下載慢和本地倉庫爆盤。先裝# Ubuntu/Debian 安裝 Maven sudo apt install -y maven # 驗證 mvn -vmvn -v會輸出 Maven 版本、Java 版本和系統(tǒng)信息。如果 Java 版本顯示不對說明JAVA_HOME沒生效回頭檢查上一步。接下來改settings.xml位置在~/.m2/settings.xml沒有就新建。我一般會做兩件事?lián)Q國內(nèi)鏡像源、把本地倉庫挪到大盤。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把系統(tǒng)盤撐滿。mirrorOf寫central表示攔截中央倉庫請求走阿里云公共倉庫。這兩個參數(shù)改完mvn clean package的速度會有明顯差別。2.3 MySQL 8 安裝與建庫建用戶這套后臺管理系統(tǒng)通常自帶sql腳本里面包含建表語句和初始數(shù)據(jù)。MySQL 版本建議 8.0因為很多 Spring Boot 2.x 項目默認驅(qū)動是mysql-connector-java8.x連 5.7 雖然也能用但時區(qū)配置容易出問題。# 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 遠程登錄。生產(chǎn)環(huán)境按提示走本地開發(fā)可以跳過部分選項。裝完后登錄建庫-- 創(chuàng)建數(shù)據(jù)庫字符集用 utf8mb4 CREATE DATABASE admin_system DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; -- 創(chuàng)建專用用戶避免直接用 root CREATE USER admin_userlocalhost IDENTIFIED BY YourStrongPassword; -- 授權 GRANT ALL PRIVILEGES ON admin_system.* TO admin_userlocalhost; FLUSH PRIVILEGES;字符集必須用utf8mb4否則后臺菜單里的中文、emoji 或者特殊符號會變成問號。utf8mb4_general_ci是通用排序規(guī)則兼容性比utf8mb4_unicode_ci更穩(wěn)。建完庫再導入項目自帶的sql文件mysql -u admin_user -p admin_system /path/to/init.sql導入時如果報Unknown command \多半是sql文件里有反斜杠轉(zhuǎn)義用--default-character-setutf8mb4再試一次。2.4 Redis 安裝與密碼配置Redis 在這套系統(tǒng)里通常承擔驗證碼存儲、登錄 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或者直接連上但生產(chǎn)環(huán)境不安全。我一般會改/etc/redis/redis.conf# 設置訪問密碼 requirepass YourRedisPassword # 綁定本地回環(huán)禁止外部訪問 bind 127.0.0.1 # 保護模式開啟 protected-mode yes改完重啟sudo systemctl restart redis-server redis-cli -a YourRedisPassword pingrequirepass設置密碼后redis-cli需要-a參數(shù)才能操作。bind 127.0.0.1確保只有本機能連避免暴露到公網(wǎng)。這兩項配完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輸出里如果出現(xiàn)多個不同版本的spring-security-core說明有傳遞依賴沖突。解決辦法是在pom.xml里用dependencyManagement鎖定版本或者直接排除沖突依賴。另一個高頻問題是 Lombok 插件沒裝。項目里大量用Data、Slf4jIDE 不裝 Lombok 插件代碼全是紅。IDEA 在Settings - Plugins搜 Lombok 安裝重啟后開啟Annotation Processors。3.2 application.yml 關鍵參數(shù)逐項說明application.yml是這套系統(tǒng)能不能連上數(shù)據(jù)庫和 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 不加時區(qū)會報The server time zone value UTC is unrecognized。useSSLfalse本地開發(fā)關掉生產(chǎn)環(huán)境按需開啟。mybatis.mapper-locations指向 XML 映射文件位置type-aliases-package是實體類包名map-underscore-to-camel-case開啟后數(shù)據(jù)庫的user_name會自動映射到 Java 的userName。這三個參數(shù)錯一個查詢結果就是空或者報Invalid bound statement。3.3 Spring Security 配置類適配與放行規(guī)則Spring Security 是這套系統(tǒng)里最容易翻車的部分。如果項目用的是 Spring Boot 2.7 以上WebSecurityConfigurerAdapter已經(jīng)廢棄需要改成 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里放行登錄頁、靜態(tài)資源、驗證碼接口anyRequest().authenticated()表示其他全部需要認證。formLogin指定自定義登錄頁和成功跳轉(zhuǎn)地址。csrf().disable()在前后端分離或者純后臺場景下常見做法是關掉否則 POST 請求會被攔截。如果項目里還是舊版WebSecurityConfigurerAdapter而你的 Spring Boot 是 2.7.x啟動會報NoClassDefFoundError。解決辦法要么降 Spring Boot 版本到 2.6.x要么按上面改成 Bean 方式。我一般選后者因為新版本安全補丁更全。4. 避坑與排查啟動失敗、登錄循環(huán)、Redis 超時的常見問題4.1 啟動報數(shù)據(jù)庫連接失敗先看驅(qū)動再看時區(qū)現(xiàn)象啟動時拋Cannot load driver class: com.mysql.cj.jdbc.Driver或者Communications link failure。原因第一種是pom.xml里沒加 MySQL 驅(qū)動依賴或者驅(qū)動版本和 MySQL 版本不匹配。第二種是 MySQL 沒啟動或者url里的端口、庫名寫錯。解決先確認pom.xml有mysql-connector-java依賴版本用 8.0.x。然后systemctl status mysql看服務狀態(tài)mysql -u admin_user -p手動登錄測試。如果報時區(qū)錯誤在url末尾加serverTimezoneAsia/Shanghai。4.2 登錄頁 302 循環(huán)Security 放行規(guī)則寫錯現(xiàn)象訪問登錄頁瀏覽器不斷跳轉(zhuǎn)最終提示ERR_TOO_MANY_REDIRECTS。原因antMatchers里沒有放行登錄頁本身或者loginPage路徑和實際 Controller 映射不一致。Security 攔截了/login又跳轉(zhuǎn)到/login形成死循環(huán)。解決確認antMatchers(/login).permitAll()存在且formLogin().loginPage(/login)的路徑和 Controller 里GetMapping(/login)完全一致。如果登錄頁在templates下還需要模板引擎依賴否則返回 404 也會觸發(fā)循環(huán)。4.3 Redis 連接超時密碼、綁定地址、保護模式三查現(xiàn)象啟動時報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 路徑和包名對不上現(xiàn)象查詢時報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 靜態(tài)資源 404Security 攔截了 css/js現(xiàn)象登錄頁樣式全丟控制臺報GET /css/login.css 404。原因Security 默認攔截所有請求靜態(tài)資源沒有放行。解決在antMatchers里加/css/**、/js/**、/images/**、/fonts/**。如果用了 WebJars還要加/webjars/**。放行后重啟樣式就能正常加載。5. 裝完怎么驗證從登錄到數(shù)據(jù)查詢的完整走查環(huán)境裝完別急著寫業(yè)務。我一般會按下面順序走一遍確認每個組件都真正通了。第一步確認端口監(jiān)聽。ss -tlnp | grep -E 8080|3306|6379三個端口都應該有進程監(jiān)聽。8080 是 Spring Boot3306 是 MySQL6379 是 Redis。少一個就回頭查對應服務。第二步訪問登錄頁。瀏覽器打開http://localhost:8080/admin/login如果能看到登錄表單說明 Spring MVC 和 Security 的放行規(guī)則生效。如果頁面樣式正常說明靜態(tài)資源放行也沒問題。第三步用初始賬號登錄。項目sql腳本里通常有一個sys_user表里面存了管理員賬號。常見做法是admin/123456但具體看init.sql的插入語句。登錄成功后應該跳轉(zhuǎn)到后臺首頁左側菜單能正常展開。第四步驗證 Redis 緩存。登錄后執(zhí)行redis-cli -a 密碼 keys *應該能看到類似login:token:xxx或者captcha:xxx的鍵。如果沒有說明 Redis 配置沒生效回頭檢查application.yml和redis.conf。第五步驗證數(shù)據(jù)庫查詢。點開用戶管理或者菜單管理看列表能不能加載。如果列表為空但數(shù)據(jù)庫里有數(shù)據(jù)檢查 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能登錄服務狀態(tài)、url、時區(qū)Redis 連接redis-cli -a 密碼 ping返回 PONGrequirepass、bind登錄頁瀏覽器能打開且樣式正常Security 放行規(guī)則登錄跳轉(zhuǎn)成功進入后臺首頁formLogin 配置數(shù)據(jù)查詢列表有數(shù)據(jù)mapper-locations、namespace權限控制不同角色菜單不同EnableGlobalMethodSecurity最后一步我會把application.yml里的密碼換成環(huán)境變量避免提交到代碼倉庫。常見做法是用${DB_PASSWORD}占位啟動時通過-DDB_PASSWORDxxx傳入。這樣本地能跑線上也不會泄露。從那以后我每次裝這套環(huán)境都會先跑一遍mvn clean package -DskipTests確認編譯通過再啟動。因為很多配置問題在編譯階段就能暴露等到運行時才查成本高得多。希望幫到你。本文還有配套的精品資源點擊獲取