1. 项目认知与环境准备1.1 eladmin到底是什么适合谁跑先交代一下背景。eladmin是国内开发者圈子里流传度很高的一套前后端分离后台管理系统脚手架基于Spring Boot 2.x和Vue 2.x这套经典组合。它把权限管理、用户管理、菜单管理、字典管理、操作日志这些后台系统里最磨人的通用功能全部封装好了你拿过来之后主要工作是往里填自己的业务代码而不是从零手搓一套RBAC权限模型。很多朋友拿到这类开源项目之后习惯先看README然后照着文档敲命令结果在环境准备和配置阶段就卡了一周。我不是来念文档的这篇就按我真实跑通的路径把从下载源码到浏览器里出现登录页的全过程拆开揉碎讲清楚。后面每一个步骤、每一处配置我都标了“为什么”很多坑都是文档没写但新手一定会撞上的。先说这个项目适合谁。第一类是想学前后端分离架构的初学者eladmin代码结构清晰、注释齐全拿来当教学范例非常合适第二类是公司要快速交付后台管理系统但不想从零写的开发者eladmin的开箱即用程度在同类项目里算很高的第三类是准备面试、想在自己的简历项目里加一个完整权限系统的同学。如果你是这三类人之一这篇内容正好对路。1.2 跑通之前必须搞懂的三个底层概念动手之前先花三分钟把三件事弄清楚后面能少走很多弯路。第一件是“前后端分离”到底怎么协同。eladmin的后端跑在Spring Boot内置的Tomcat上默认端口8000前端是Vue项目开发模式下跑在Node环境里默认端口9527前端配置里写的devServer端口常见是8000或9527eladmin默认是9527后面会细说。浏览器访问前端页面时Vue开发服务器会代理API请求到后端端口。这里面的核心是Vue CLI提供的proxy代理机制你在前端代码里写/api/login实际请求会被转发到http://localhost:8000/api/login。不懂这一点后面遇到跨域报错会一头雾水。第二件是Redis在eladmin里的角色。很多新手第一次跑这个项目配置了MySQL之后启动后端直接报Redis连接失败。eladmin用Redis做缓存用户的登录Token、验证码验证码的存储、一些配置项的缓存都依赖它。所以你的电脑上必须装一个Redis服务端并且跑起来。这跟某些把缓存逻辑做成“没有Redis也能降级运行”的项目不一样eladmin对Redis是硬依赖不启动Redis后端直接起不来。第三件是数据库初始化逻辑。eladmin的SQL脚本不是自动执行的你需要手动创建一个数据库然后把项目里提供的.sql文件导入进去。关键是这个项目的SQL脚本文件不止一个主库脚本和测试数据脚本是分开的如果你只导了主库脚本登录进去之后很多菜单和权限数据都是空的体验会差很多。把这三件事在脑子里立住后面所有操作都有了解释。1.3 环境版本清单照着配不折腾这可能是全篇最值得“抄作业”的部分。版本不匹配是跑开源项目最大的隐形杀手很多报错看起来稀奇古怪最后发现就是JDK版本不对或者Node版本太新。我实测下来的稳定组合是这样组件推荐版本备注JDK1.88u202及以上不要用JDK 11或17会有兼容问题Maven3.6.x3.8也可以但3.6最稳MySQL5.7或8.0记得用户名密码后面配置要用Redis5.x或6.xWindows下可以用微软维护的移植版Node.js12.22.x不要用14以上node-sass会编译失败npm6.x跟Node 12配套的版本IDEIntelliJ IDEA 2021社区版就能跑不必买旗舰版这里重点说说Node版本这件事。eladmin的前端依赖里包含node-sass这个老牌依赖包它对Node版本非常敏感。Node 14以下用node-sass4.x版本没问题但如果你装了Node 16或更高版本npm install的时候node-sass会尝试从源码编译然后大概率报错错误信息里会出现gyp字样。很多人在这一步心态崩了。解决办法不是硬刚而是老老实实装一个Node 12的版本。我个人一般用版本管理工具来切换Node版本Windows下用nvm-windowsMac下用n这样就省去了卸载重装的麻烦。如果你实在不想折腾多版本管理也可以修改前端项目的package.json把node-sass替换成dart-sasssass但那样改动的面比较大不建议新手在跑通阶段做这种改造。Java侧同样别犯懒。顺手查一下你本机的JDK版本如果在终端里敲java -version显示的是11或者17建议直接去下载JDK 8。不要想当然觉得新版更好Spring Boot 2.x在JDK 8上是最舒服的换到高版本会遇到各种隐形的字节码兼容问题。MySQL我建议直接用8.0但要注意eladmin的驱动配置是兼容MySQL 8的只要在连接串里加上serverTimezoneAsia/Shanghai就好。如果用5.7同样没问题。2. 后端启动完整流程2.1 下载代码与项目结构快速认知代码从哪拉eladmin官方仓库地址在Gitee和GitHub上都有同步国内网络环境建议直接用Gitee上的镜像仓库下载速度要快得多。拉代码用git命令还是直接下载ZIP压缩包都行但如果你后续想跟着社区版本走更新建议用git clone。拉下来之后看一下目录结构这是整个项目认知的关键一步。eladmin是典型的多模块Maven工程根目录下有一个父pom.xml核心子模块有这几个eladmin-common公共工具模块放通用工具类、异常处理、配置类eladmin-system系统核心模块启动类在这个模块里权限、用户、菜单相关的代码也在这里eladmin-logging日志模块操作日志和异常日志eladmin-tools工具模块包括文件存储、邮件发送、在线用户管理等eladmin-system里的SystemApplication是主启动类入口就是它的main方法。首次打开项目时IDEA会提示你是否信任项目并自动导入Maven依赖。这个过程会比较慢因为要下载一大堆jar包。考验耐心的时刻到了。如果下载速度太慢可以检查Maven的镜像配置。打开settings.xml把中央仓库镜像换成国内的仓库地址大概能快好几倍。等待依赖下载的同时顺手把前端的代码也看一下。前端项目在源码目录下通常是单独的文件夹eladmin的前端目录名一般是eladmin-web或者front-end这类名字里面是标准的Vue CLI工程结构有package.json、vue.config.js、src目录这些。2.2 数据库初始化这一步决定你能不能登录数据库准备是一个分步操作我按顺序说明跟着走就不会出错。第一步启动你的MySQL服务。Windows下如果是安装版在服务管理器里确认MySQL服务状态是“正在运行”。Mac下用brew services start mysql。第二步用命令行或者数据库管理工具连接MySQL。命令行方式是这样mysql -u root -p输入密码之后进入MySQL交互环境然后创建数据库CREATE DATABASE eladmin CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;库名你可以自定义但记住了后面改配置的时候要跟这里的名字一致。字符集一定要用utf8mb4因为eladmin的表结构里有些字段存的是emoji或者特殊表情符号utf8mb4才能完整支持。第三步导入SQL脚本。eladmin的SQL文件在源码根目录下通常有一个sql/文件夹里面有类似eladmin.sql这样的主文件还有一个单独的测试数据脚本。我的习惯是先导主脚本再导测试数据脚本。以命令行导入为例mysql -u root -p eladmin /path/to/sql/eladmin.sql mysql -u root -p eladmin /path/to/sql/test_data.sqlWindows的cmd下路径和Linux/Mac的写法略不同注意斜杠方向。这里有个容易被忽略的细节有些版本的eladmin把测试数据脚本跟主脚本合并了或者提供了多个不同后缀的脚本。你导入之前最好用文本编辑器打开看一下文件头部确认里面包含CREATE TABLE语句就对了。如果文件乱码那可能是编码问题SQL文件统一用UTF-8编码别用系统默认的ANSI。导入完成之后验证一下。执行USE eladmin; SHOW TABLES;看到sys_user、sys_menu这一堆以sys_开头的表就说明导入成功了。2.3 修改后端配置四步走一步不能少数据库准备好之后打开eladmin-system模块的资源配置文件。在src/main/resources目录下你会看到一个application.yml这是后端启动时的主配置文件。需要改的地方有四个。第一个是数据源配置。找到spring.datasource这一段把url里面数据库名改成你刚创建的库名username和password改成你自己的数据库账号密码。注意URL末尾要保留?createDatabaseIfNotExisttrueuseUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai这些参数。第一个参数的意思是你即使没手动创建库连接时也会自动建库不过我们前面手动建过了不影响。serverTimezone是必须的不然MySQL 8连接时会报时区错误。第二个是Redis配置。找到spring.redis这一段默认配置通常是host: localhost、port: 6379一般不需要改除非你改了Redis默认端口或者设置了密码。如果你本机的Redis设置了requirepass就得在password那一行填上。第三个是应用端口。在配置里搜port:把8000这个默认值记住后面前端代理配置要用到它。建议不要改这个端口保持默认可以少踩很多坑。第四个是文件上传路径。eladmin有文件上传功能配置里有一个file.path或者files-path之类的属性默认通常是./file/或者/home/eladmin/file/。建议改成你自己的本地目录比如Windows下用D:/eladmin-file/注意目录分隔符用正斜杠。不改的话有些版本会因为默认目录不存在或者无权限报错。改完这四个地方保存。后端配置就算完工了。2.4 启动后端第一次启动的预期与踩坑启动后端的方式有两种一种是直接在IDEA里右键SystemApplication类选择Run另一种是用Maven命令。我建议第一次用IDEA里直接Run因为报错信息在控制台里看更直观。启动过程大约需要十几秒到几十秒看机器性能。正常情况下控制台最后会出现一行类似Started SystemApplication in XX seconds的日志。但第一次启动大概率不会一次成功。我见过的常见启动异常有这几种每种都有对应的解决办法。启动时如果报Unable to connect to Redis说明Redis服务没起来或者端口不通。先确认Redis进程是否存活、端口是否被占用把Redis先启动好再重新启动后端。如果报Access denied for user rootlocalhost那说明数据库密码不对回2.3节确认。如果报类似Unknown database eladmin说明数据库没建成功或者配置里的库名跟你实际建的不一致。如果控制台里有一堆ClassNotFoundException或者BeanCreationException通常是Maven依赖没有全部下载完在IDEA里右键项目选择Maven然后Reload让它重新拉一遍依赖。还有一类不太容易发现的问题启动时端口被占用。Spring Boot默认用的8000端口如果被你本机其他程序占了控制台会直接报端口冲突的错。这时候用命令查一下谁在占用netstat -ano | findstr :8000找到占用进程之后结束它或者改用其他端口。后端启动成功之后你可以在浏览器里直接访问http://localhost:8000这时候浏览器会返回一个空白页或者JSON数据这是正常现象因为后端本身没有页面它只提供API接口。真正的页面要等前端启动。3. 前端启动完整流程3.1 前端依赖安装node-sass这道坎怎么过后端跑通之后切换到前端工程。前端启动的第一步是安装npm依赖。打开命令行进入前端项目根目录就是有package.json的那个目录执行npm install这个命令会把当前项目的所有JS依赖包下载到node_modules目录里。如果网络正常一般两三分钟能跑完。如果你在前面环境准备阶段听了我的劝装了Node 12那npm install的过程会很安静。如果你装了高版本Node大概率会在这里看到红色报错。node-sass编译失败的报错信息长这样终端里出现gyp ERR! build error、gyp ERR! stack Error: not found: make之类的字样。解决办法前面提过了就是把Node版本切到12.x重新跑一遍。装完依赖之后可以在命令行里执行node -v确认当前版本。还有一个网络层面的问题npm默认源是国外地址安装速度感人。建议先把npm源切换到国内镜像npm config set registry https://registry.npmmirror.com/切换之后重新npm install速度提升明显。注意这个命令设置之后以后所有npm安装都走镜像源绝大多数情况下是好事但如果你将来要发布自己的npm包记得切回官方源。依赖装完之后验证一下node_modules目录是否存在且非空。在项目根目录执行ls node_modules在Windows上执行dir node_modules看到一堆文件夹就对了。3.2 前端代理配置解读为什么浏览器没有跨域报错前面反复提到的代理配置现在终于要实操了。打开前端项目的vue.config.js找到devServer和proxy相关配置。这个文件是Vue CLI的配置文件所有开发环境的服务器行为都在这里定义。eladmin的代理配置大概长这样devServer: { port: 9527, proxy: { /api: { target: http://localhost:8000, changeOrigin: true } } }这段配置的意思很直白开发服务器跑在9527端口所有以/api开头的请求都会被转发到http://localhost:8000去。你在浏览器里访问的是http://localhost:9527页面上发登录请求到/api/login时Vue开发服务器会悄悄把请求转发给后端的http://localhost:8000/api/login。这里你只需要看懂一个点前端代码里的请求路径和后端真正的地址之间有一层代理在转接。这也是为什么后端必须跑起来、且端口要跟这里配置一致不然前端页面虽然能打开但登录接口会一直报网络错误。如果后端端口改了这个文件里的target也要跟着改。两边的端口配置要严格对应。3.3 启动前端开发服务器配置确认无误后在项目根目录执行npm run dev第一次启动会比较慢因为Vue CLI要做编译工作。看到控制台里出现Compiled successfully或者类似的提示同时出现一个地址http://localhost:9527就说明启动成功了。如果你在代码里看到的是npm run serve那也可以不同版本的开源项目脚本名可能不同。打开package.json在scripts节点里能看到dev和build等命令dev就是开发模式。前端启动成功之后整体系统的访问路径就是http://localhost:9527。用默认账号admin和默认密码123456这个项目的默认密码一般是123456有少数版本是admin123试一下就知道登录能看到系统的完整界面说明整套系统已经成功跑起来了。但我把话撂在这儿第一次启动前端控制台出现的不一定都是好消息多半伴随着几个warn级别的黄色警告比如ESLint语法检查的不规范提示。这些警告一般不影响运行可以忽略。但如果出现红色的编译错误就要仔细看是哪一行导致的最常见的是有人把某些配置文件的语法写错了。这种问题通常回退代码就能解决。3.4 前端启动的常见报错清单整理一份前端启动报错速查表照着查就行。报错表现根本原因解决办法Module not found: Error: Cant resolve xxx某个依赖包没装上检查node_modules是否存在重新执行npm installNode Sass could not find a bindingnode-sass与Node版本不匹配切换Node版本后重装node_modules或执行npm rebuild node-sassError: listen EADDRINUSE :::95279527端口被占改vue.config.js里的端口或关掉占用端口的进程Failed to load resource: net::ERR_CONNECTION_REFUSED后端没启动回到后端确认8000端口的Spring Boot进程是活的Proxy error: Could not proxy request /api/login后端端口跟代理配置不一致检查后端实际端口调整vue.config.js的target页面能打开但登录报验证码错误后端与Redis有问题确认后端日志没有异常检查Redis连接是否正常第三条那个端口占用问题值得一提。很多人的9527端口被另一个前端项目占着因为Vue CLI的默认端口就是9527两个项目抢同一个端口后启动的那个自然报错。这时候要么把之前那个项目关掉要么改当前项目的端口。4. 登录链路验证与业务代码定位4.1 从登录请求追踪到后端代码第一次读源码的路径系统跑起来了但这不算完。真正有价值的是知道它在各个代码层之间怎么流转的。带着“从浏览器到数据库”这条链路去读一遍代码你对这套项目的理解会直接上一个台阶。以登录为例整个链路大概是这样的。浏览器里输入admin和密码Vue页面捕获点击事件调用src/api/目录下某个登录接口函数。这个函数内部用axios发了一个POST请求路径是/api/auth/login携带参数是用户名和密码。请求到达后端之后Spring Boot的拦截器网络层把请求分发给对应的Controller。eladmin里处理登录的控制器在eladmin-system模块的rest包里类名通常有AuthController或者LoginController字样。控制器的login方法接收用户名密码调用UserService这个服务里会先去Redis里校验验证码再去MySQL里查用户表比对密码。密码比对这一环eladmin用的是BCrypt加密算法数据库里存的密码是一串带随机盐的哈希字符串。所以你永远不会看到明文密码被打印出来。登录成功之后后端生成一个Token这个Token会同时存进Redis并返回给前端。前端拿到Token之后放进每次请求的Header里后面访问其他业务接口时后端通过这个Token识别当前是哪个用户在操作。这条链路走通一遍你对“为什么Redis挂了系统就用不了”“为什么密码不能直接改数据库”这类问题会自发地有答案。4.2 改一个菜单名称前端页面和后端数据的联动演示跑通项目之后的第一个小练习我推荐去“系统管理 - 菜单管理”页面随便改一个菜单名称刷新页面看效果。这个操作背后涉及一个核心设计菜单权限不是写在前端代码里的而是存在数据库的sys_menu表里。前端页面结构会根据当前登录用户的角色动态从后端拉取菜单列表再渲染到侧边栏。这就是RABC模型在真实项目里的落地形态。你改菜单名称的操作后端会执行一条UPDATE语句把sys_menu表里对应条目的name字段改掉。刷新之后前端重新请求菜单接口拿到新名称展示出来。就这么简单但它揭示了一个重要事实eladmin的前端页面是“数据驱动”的页面长什么样、哪些人看到哪些菜单都由后端数据决定。这一点对于理解后台管理系统的架构思维非常关键。4.3 查看日志与调试遇到问题不要瞎猜系统跑起来之后你一定会遇到跟业务有关的问题。这时候别急着乱翻代码先养成看日志的好习惯。后端日志输出在IDEA的控制台里Spring Boot默认的日志级别是INFO能看到请求进出的痕迹。如果你需要用更细的粒度观察SQL执行可以在application.yml里把日志级别调成DEBUG或者在配置里加上一句logging: level: com.eladmin: debug这样控制台会打印更多SQL和业务执行信息。前端调试就简单多了浏览器按F12打开开发者工具切到Network面板所有请求的响应码、响应体、时间消耗都一目了然。前端报错如果指向某个vue文件直接点进去看调用栈。我见过很多新手遇到问题习惯性镜像站搜报错搜出来的答案五花八门结果越改越乱。我的经验是先把报错本身上下左右看一遍找到是哪个请求、哪一步报的错、报什么错再对症下药。多数问题的答案其实就藏在这三步里。5. 二次开发切入点的几条实用建议5.1 新增一张业务表并挂到菜单上完整走一遍CRUD跑通只是第一步大部分同学拿到这个项目是为了做二次开发。我强烈建议你动手做一次“新增业务模块”的全流程练习这是把学习成果变成开发能力的最短路径。流程不长大致是这样首先在MySQL里建一张业务表比如biz_article字段自定。然后在后端写一个对应的实体类、一个Repositoryeladmin用的是Spring Data JPA、一个Service和一个Controller。接着定义一个基础的DTO对象用于接收前端参数。Controller里提供增删改查四个接口注意路径风格跟项目里现有接口保持一致。最后在系统管理页面里通过菜单管理功能把新菜单挂上去配置好前端路由对应的组件路径。这个流程走完你会对eladmin的后端分层、前端路由动态加载机制有一个完整的感知。以后再往里面加业务功能就是肌肉记忆级别的熟练度了。5.2 改前端页面也能练手找对组件和路由如果你暂时不想碰后端改前端页面也是个很好的切入点。eladmin的前端页面在src/views目录下面目录层级跟后端菜单基本一一对应。比如系统管理页面对应在src/views/system这个目录。找到想改的页面文件之后注意它是按什么方式写的。eladmin前端的列表页大多基于el-table组件表单页基于el-form组件。如果你想改表格列就去el-table-column标签里改label和prop属性。如果你想改查询条件找表单区域的el-form-item标签。这些都是Element UI的基础用法改起来没什么心智负担。比较需要小心的是不要在src/utils/request.js这类公共文件里乱动东西那是所有请求的公共出口改了影响全局。5.3 升级依赖之前先跑通再折腾有了一定基础之后你可能会想把项目里的旧依赖升个级比如把Spring Boot升到2.7或者把Vue升级到3。我的忠告是先备份、再升级、升级完立即回归验证。eladmin的社区活跃度挺高但它的核心代码是围绕特定版本设计的直接替换依赖很可能导致一堆莫名其妙的兼容性错误。我见过有人把Spring Boot从2.2升到2.6之后项目的验证码组件行为全变了排查了一下午最后只能回滚。最安全的做法是在本地保留一个跑通的干净副本所有升级尝试都在副本上进行。哪怕试坏了也不影响原本可用的那套。6. 最后讲几句实在话如果你一路读到这里大概率已经在自己的机器上把eladmin成功跑起来了。到了这个节点你会面临一个选择是用它直接做业务还是用它当教材学架构。说实话这两种选择都不冲突但要明确优先级。我的建议是先用它完成一个自己感兴趣的小功能比如做一个个人笔记模块或者一个简单的订单管理页面。功能规模不需要大核心是把“数据库建表 - 后端写接口 - 前端调页面 - 权限挂菜单”这条链路走通。这一步的收获比读十篇架构分析文章都大。在跑通这个项目的过程中你会发现一个现实开源项目的文档写得再详细也总有覆盖不到的地方。很多看似神秘的报错本质都是环境和版本问题跟你本身的编程能力没关系。所以遇到问题不要慌按着日志一层层排查绝大多数情况下都能自己解决。这套项目里的权限设计、日志处理、异常统一封装都值得你把它当成一个“可运行的教科书”反复琢磨。等你能熟练在里面加功能、改页面、调权限的时候恭喜你前后端分离的后台管理系统开发你已经真正入门了。