第一次拿到 eladmin 的源码，很多人都是同一个结局：README 写得清清楚楚，代码也顺着克隆下来了，结果后端一启动就是满屏红色报错，前端 npm install 卡到怀疑人生，最后连登录页的影子都没见到。
这不是你菜。eladmin 虽然是被大量开发者拿去二开的经典后台管理脚手架，但它的启动过程里藏着不少"版本依赖 + 默认配置"的坑，文档没提、社区里也散落得到处都是。我自己把这套项目在本地反复跑过很多次，还给不止一个人远程看过启动问题，所以这篇就把从零跑通 eladmin 的完整链路、每一步为什么要这么配、以及高频报错的排查思路一次性讲透。适合第一次接触 Spring Boot + Vue 全家桶项目、想拿真实开源项目练手、或者准备基于它快速搭企业后台的同学看。
1. 先搞懂 eladmin 是什么，以及它为什么值得亲手跑一遍
1.1 它到底解决了什么问题
eladmin 是一套完整的企业级后台管理系统框架。后端基于 Spring Boot，接入了 Spring Security 做认证授权、JWT 做登录态、MyBatis-Plus 操作数据库、Redis 管缓存；前端基于 Vue，用的是 Element UI 这套组件库，配合 Vuex 管状态、Axios 发请求、Vue Router 管路由。
听起来好像很多名词，但你不用慌。本质上是把企业后台里最常做的一堆事——用户管理、角色权限、菜单路由、操作日志、定时任务、代码生成——全都提前做好了。你在自己的业务里需要做的，只是在这个框架上往里面加表和页面。这也是它被大量拿来当"脚手架"的原因：不用从零搭权限系统，直接站在一个成熟底座上做业务。
1.2 "两个端一条链路"的前置认知
跑这个项目之前，最应该先建立的认知是：它有两个进程，前端 dev server 和后端 Spring Boot，中间靠接口通信。浏览器先访问前端页面，页面里的 Axios 把请求发给 dev server，dev server 再按代理规则把请求转发到后端端口，后端再去查 MySQL、读 Redis。
你后面遇到的所有启动问题，基本都能在这条链路的某一环找到答案。如果你之前只写过单体小项目，这种"两段式"联调方式需要先接受——因为很多报错根本不是代码问题，而是链路断了。比如前端页面能打开但接口全部 404，十有八九就是代理转发没对上端口。这个认知一旦建立，后面排查问题会快很多。
2. 环境准备：版本匹配是能不能一次跑通的第一道坎
2.1 一套经过验证的版本组合
我在本地测试过很多分支，最后稳定可用的搭配大致是这样：
| 组件 | 推荐版本 | 说明 |
|---|---|---|
| JDK | 1.8 | 后端基于 Spring Boot 2.x，JDK 8 最稳，8u201 以上即可 |
| Maven | 3.6.3 左右 | 3.8 以上也能用，但注意镜像源配置 |
| MySQL | 5.7 或 8.0 | 两个版本都行，但连接 URL 有差异，见第 5 章 |
| Redis | 5.0 以上 | 用于验证码、在线用户、缓存，必须启动 |
| Node | 12.x 或 14.x | 前端是 Vue 2 + Webpack 4，Node 太高会踩 OpenSSL 坑 |
| npm | 6.x | 配合 Node 12/14 使用最省心 |
很多人上来就装最新版 JDK、最新版 Node，结果项目反而跑不起来。原因很简单：eladmin 前端依赖了 node-sass 这类原生编译模块，对 Node 版本非常敏感；后端 Spring Boot 2.x 和 JDK 8 是配套的，用 JDK 11 通常没事，但没必要给自己增加变量。跑老项目的时候，版本保守才是最快的路。
2.2 MySQL 建库和 Redis 准备
MySQL 这边建议手动建一个库，再导入项目根目录下的 eladmin.sql 文件。建库语句顺手指定 utf8mb4 字符集：
CREATE DATABASE eladmin DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;导入方式可以直接用客户端工具执行 SQL 文件，也可以在命令行里source /你的路径/eladmin.sql。用 utf8mb4 的原因很实在：它支持 emoji 和生僻字，中文不会乱码，这是企业环境里的基本要求。
Redis 更简单，本地测试的话密码留空，保证服务真的起来了就行。验证方式很直接：
redis-cli ping返回 PONG 说明正常。这里有个重要背景：eladmin 登录页的验证码是后端生成后放到 Redis 里的，前端提交登录请求时带上验证码和对应的 key，后端从 Redis 取出来比对。所以 Redis 没启动，你连登录页都进不去——这是跑这个项目最经典的"看起来是前端问题、实际是后端缓存问题"的案例。
3. 后端启动全流程：从代码到手到接口正常响应的每一环
3.1 代码获取与版本选择
仓库在开源平台上有，国内也有同步地址。我的建议是：第一次跑不要直接拉最新 master，选一个带稳定 tag 的分支或 release 版本。原因很简单，最新分支可能正在改版，配置文件的位置和参数命名都会变，而大多数你搜到的教程、社区问答都是针对某个稳定版本的，版本对不上，教程里的路径就对不上，很容易越改越乱。
克隆下来之后先看目录结构。常见的有几个模块：common（公共工具）、logging（日志记录）、system（系统管理核心）、tools（工具模块，含代码生成）等。入口主类一般放在 system 模块下，比如 AppRun 之类的类名，你看到带@SpringBootApplication注解的主类就是它。
3.2 改配置：三处必改，一处建议改
打开后端配置文件，通常主配置是 application.yml，有些版本还按环境拆分了 dev、prod 文件。你需要先确认当前激活的是哪个环境配置，别改了 dev 文件，程序跑的是 prod，白忙活。
第一处必改：数据源。把 datasource 的 url、username、password 改成你本机的。MySQL 8 的 url 一般要带上时区参数，不然会报时间相关的错，比如：
url: jdbc:mysql://localhost:3306/eladmin?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true第二处必改：Redis。把 host、port、password、database 改成你本机的。注意 database 这个下标，很多项目默认不是 0，而是用了 1、2 这种编号，你本机 Redis 如果没配置那么多库，或者里面本来有其他数据，建议统一到你自己习惯的下标上。
第三处必改：日志路径和文件上传路径。老版本里经常写死成类似/home/eladmin/这种 Linux 路径，在 Windows 上跑会因为没权限或路径不存在直接报错。把它们改成你本机的目录，能省掉一堆莫名其妙的启动失败。
3.3 Maven 依赖与启动入口
用 IDEA 打开项目根目录的 pom.xml，让它自动下载依赖。这一步在国内网络环境下经常很慢，处理办法是在 Maven 的 settings.xml 里配置国内镜像源。具体地址网上搜"Maven 公共镜像"第一条就有，配置好之后下载速度能快上好几倍。
依赖下载完，建议先把所有模块装到本地仓库，再启动项目：
mvn clean install -DskipTests然后再运行 system 模块下的主类。启动日志刷完，看到类似Tomcat started on port(s): 8000以及项目自己打印的 banner，说明后端进程已经起来了。不同版本默认端口可能不同，以你本地配置文件里的server.port为准。
3.4 验证后端是不是真的活着
后端起来不等于能登录。最直接的验证方式：浏览器访问后端的验证码接口，路径一般是/auth/code（以你版本的 controller 为准）。如果返回一段 JSON 数据，里面含验证码图片的 base64 和 uuid，说明接口链路通了。
进一步可以打开 Redis 命令行，调用完验证码接口后看一下有没有生成相应的 key。如果 Redis 里有，说明后端写缓存的链路也是通的。到这一步，后端基本就绪，可以安心去搞前端了。
4. 前端工程启动：依赖安装、代理转发与登录页出现
4.1 npm install 的三个高频坑
前端目录通常是独立的工程，进入目录后第一件事就是装依赖。这里有三个坑基本人人都踩过。
第一个坑是依赖源太慢。默认 npm 源在国外，一个 node-sass 就能卡你半小时。解决办法是把 npm 源切到国内公共镜像，具体命令一条：
npm config set registry https://registry.npmmirror.com第二个坑是 node-sass 编译失败。如果你用的 Node 版本太新，node-sass 会直接编译不过，日志里一堆 gyp 报错。最快的解是切换到 Node 12/14。如果你的环境确实不方便切版本，也可以设置SASS_BINARY_SITE环境变量，让 node-sass 从国内二进制镜像下载预编译文件，但说实话，切 Node 版本最省心。
第三个坑是 Node 17 以上跑 Webpack 4 时会报ERR_OSSL_EVP_UNSUPPORTED。这是 OpenSSL 版本变化导致的，解决办法要么降 Node，要么启动时加一个环境变量：
NODE_OPTIONS=--openssl-legacy-provider我强烈建议直接用 Node 12/14，别跟工具链较劲。
4.2 dev server 启动与代理检查
依赖装完，执行npm run dev，正常情况下前端会在 8088 之类的端口启动（具体看 package.json 里的 scripts 和 vue.config.js 的配置）。浏览器打开对应地址，如果看到登录页，说明前端进程起来了。
但这时候离"跑通"还差一步：检查代理配置。打开前端工程的 vue.config.js，看 devServer 的 proxy 部分，确认它把请求转发到了后端正确的端口。比如后端是 8000，代理配置里 target 也应该是 8000，路径前缀带/api之类的规则要和后端接口对得上。
这一步被很多人忽略。前端页面能开，但点登录按钮后请求全部失败，十有八九就是代理转发的目标端口和后端实际端口不一致。改完配置，重启前端 dev server 就生效。
4.3 用默认账号完成第一次登录
后端就绪、前端就绪、代理对上调到这一步，在登录页输入默认账号和密码——通常是 admin / admin123，再填上验证码，点击登录。能进到首页，并且左侧菜单、用户列表这些数据都能正常加载，整条链路才算真正打通。
如果验证码图片一直加载不出来，别在前端代码里找原因，回到第 2 章检查 Redis；如果验证码能出来但登录提示验证码错误，多半是 Redis 里存验证码的 key 和校验时的 key 对不上，或者你前后端连的不是同一个 Redis。
5. 我帮别人处理过的三个高频启动问题：完整排查链路
5.1 Redis 连不上导致的"登录即失败"
现象：后端启动正常，前端页面也正常，但一登录就报错，控制台里能搜到redis或者Unable to connect一类的日志。
排查链路：
- 先看后端日志的最后 50 行，找有没有 Redis 连接异常的关键词。
- 命令行执行
redis-cli ping，确认本机 Redis 是否返回 PONG。如果 Redis 压根没启动，直接启动它。 - 检查 application.yml 里 Redis 的 password 和 database 是否和你本机一致。密码不对是小事，但 database 下标选错了，验证码可能写进了别的库，前端校验时依然读不到。
- 如果你用的是远程 Redis 或容器里的 Redis，还要确认 bind 配置允许外部访问，不能只绑定 127.0.0.1。
这个问题的根因就是验证码依赖 Redis，Redis 链路一断，登录必然失败。理解了这一点，排查方向就永远不会跑偏。
5.2 前端页面正常但接口全部 401/404
现象：登录页能打开，验证码也能显示，但点击登录后请求报 401，或者登录进去了，列表页的接口全是 404。
这两种状态码要分开看。401 是认证失败，说明请求确实到达了后端，但登录态没通过校验。常见原因有三个：账号密码不对、验证码不匹配、JWT 解析异常。按顺序检查 Redis 里的验证码、数据库里的用户、配置里的 JWT 密钥就行。注意别把密码搞复杂，先确认默认账号能登录，再谈别的。
404 的情况多半不是后端没有这个接口，而是前端代理转发错了地方。打开浏览器 F12，看 Network 面板里那个失败请求的完整 URL：如果前缀是http://localhost:8000/api/xxx但后端实际监听 8013，那必然 404。回去改 vue.config.js 的 target，重跑前端。记住一个原则：遇到接口问题，先在 Network 面板确认请求到底发给了谁，再决定去前端还是后端找原因。
5.3 MySQL 8 连接报错与字符集问题
MySQL 8 和 5.7 在默认认证插件上有区别。你可能会看到这几种报错：
| 报错信息 | 原因 | 解决方式 |
|---|---|---|
| Public Key Retrieval is not allowed | MySQL 8 认证插件需要显式允许 | JDBC URL 加allowPublicKeyRetrieval=true |
| Could not create connection | 连接参数不对 | 核对用户名、密码、端口、库名 |
| 中文乱码 | 库或连接字符集不对 | 建库用 utf8mb4，URL 加characterEncoding=utf8 |
还有一类很隐蔽的问题是集群环境里 MySQL 已经有人用过，库结构和你导入的 eladmin.sql 不完全一致，导致启动时某张表不存在。处理方式很简单：找到项目文档要求的 SQL 文件，在干净的数据库里重新导入一遍，别在旧数据基础上硬跑。
6. 跑通之后怎么用：权限模型、代码生成与二次开发方向
6.1 顺着菜单位把 RBAC 权限模型读一遍
eladmin 登录进去之后，先别急着改代码，花半小时把它的权限模型捋一遍，这比单纯会启动值钱得多。
核心表就那么几张：sys_user、sys_role、sys_menu，再加上关联表 sys_users_roles、sys_roles_menus，以及部门表 sys_dept。用户挂在角色下，角色关联菜单，菜单里不仅有页面菜单，还存了按钮级权限标记。换句话说，你给一个角色勾选了哪些菜单，用户登录后前端就只渲染哪些菜单和按钮，后端接口也会校验对应的权限标识。
我建议你在系统管理里新建一个测试用户，配一个只有部分菜单权限的角色，再登录试试。你会直观看到：同一个系统，不同账号看到的东西完全不一样。这个体验比读十篇权限文章都管用。
6.2 用代码生成器快速产出第一个业务模块
跑通之后最有成就感的事情，是用它的代码生成器生成一个完整的业务模块。流程大致是：
- 在数据库里建一张你自己的业务表，比如产品表、订单表，规范起见字段注释写清楚。
- 在系统菜单里找到代码生成入口（不同版本菜单位置可能不一样，有的在工具模块下，有的在系统管理下，以你本地菜单为准）。
- 选择刚建的表，配置字段的展示方式：哪些字段作为查询条件、哪些作为表格列、哪些是富文本或下拉字典。
- 点击生成，前端代码和后端代码分别拿到，贴在对应模块目录里。
- 重启后端，重新跑前端，把生成的菜单挂到角色上，就能看到页面了。
生成的代码能覆盖 80% 的增删改查需求，但复杂的校验、级联逻辑还是得手写。另外记得检查字典配置，前端下拉组件和后端字典类型如果没对齐，页面不出数据。
6.3 一个适合新手的扩展方向
如果你暂时没有明确业务，我推荐从"给用户表加一个字段"开始练手。流程很完整：改表、调整前端表格列、加字典项、再走一遍代码生成。这一圈走下来，你会把 eladmin 的数据库设计、前后端接口约定、菜单权限挂载方式全串起来，比单纯跑通项目理解深得多。
之后想部署到服务器，就按官方文档里的部署说明，把后端打成 jar 包、前端打包成静态文件，再处理跨域和静态资源路径。经历过一次本地到服务器的完整部署，你对这个项目的掌控才算真正到位。
最后分享几个我的实操习惯
跑这种多依赖的开源项目，我的习惯是先核对三组端口：后端端口、前端 dev 端口、Redis 端口，全部记在纸上再动手。改配置时一次只改一处，重启验证完再继续下一步，别一口气改五个地方，出了问题根本不知道是哪处引起的。遇到报错直接看日志最后 50 行，别从头翻——前面都是框架启动过程，最后才是真正的异常。启动后端时如果连不上，先看 Redis 和数据库这两个外部依赖，它们比代码本身更容易出问题。
还有一个省时间的小技巧：前端依赖一旦装成功，就把 node_modules 目录留着，别动不动删了重装。很多二开项目的卡顿根本不是代码问题，而是依赖反复重新安装时踩了版本坑。记住了这些，你跑通 eladmin 只是开始，真正的收获是它背后那套企业级后台的开发思路。
