文档/后端/项目体验

快速上手

从零开始，跑通 EasyBuild Admin 全流程阅读时间 ~15 min

本指南将带你从零开始，完成环境搭建、数据库准备、后端接口启动、前端项目运行的全流程，最终跑通一套完整的中后台管理系统。

1. 环境准备

✨

请确保本机已安装以下软件：

软件	版本要求	用途
JDK	≥ 21	后端运行环境
Maven	最新稳定版	后端构建工具
Node.js	≥ 18.17.0	前端运行环境
MySQL 或 PostgreSQL	MySQL 5.7+ / PG 12+	业务数据库
Redis	最新稳定版	缓存服务

TIP

JDK、Maven、Node.js 的安装与环境变量配置请参考网上资料或借助 AI 完成，建议使用 nvm 管理 Node 版本。

2. 配置 Maven 私服

✨

EasyBuild 的依赖包托管在私有 Maven 仓库，需要在 Maven 的 settings.xml 中添加仓库配置。

找到你的 Maven 配置文件（通常在 ~/.m2/settings.xml），将以下内容合并进去：

仓库凭证

获取仓库配置

扫码关注 EasyBuild 公众号，回复关键词获取 Maven / Gradle 仓库配置信息（仓库地址、用户名、密码）

点击二维码可放大查看

xml

<settings>
  <mirrors>
    <mirror>
      <id>aliyun</id>
      <mirrorOf>central,jcenter,!jackorg-easybuild-profile</mirrorOf>
      <name>mirror</name>
      <url>https://maven.aliyun.com/nexus/content/groups/public</url>
    </mirror>
  </mirrors>

  <servers>
    <server>
      <id>jackorg-easybuild</id>
      <username>【关注公众号获取】</username>
      <password>【关注公众号获取】</password>
    </server>
  </servers>

  <profiles>
    <profile>
      <id>jackorg-easybuild-profile</id>
      <repositories>
        <repository>
          <id>jackorg-easybuild</id>
          <url>【关注公众号获取仓库地址】</url>
        </repository>
      </repositories>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
    </profile>
  </profiles>
</settings>

注意

mirrors 中的 mirrorOf 必须包含 !jackorg-easybuild-profile 排除项，否则阿里云镜像会拦截私服请求，导致依赖下载失败。

3. 准备数据库

✨

3.1 创建数据库

MySQL 用户：创建一个名为 eb_demo 的数据库（字符集 UTF-8）。

sql

CREATE DATABASE eb_demo DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

PostgreSQL 用户：创建一个名为 eb_demo 的数据库。

sql

CREATE DATABASE eb_demo;

3.2 执行初始化脚本

克隆后端项目后（见第四步），在项目的 doc/sql/ 目录下有初始化脚本：

MySQL → 执行 mysql_260322.sql
PostgreSQL → 执行 postgresql_260322.sql

脚本已包含全部表结构和初始数据（管理员账号、权限资源等），执行完毕即可直接使用。

3.3 启动 Redis

确保 Redis 服务已启动，默认连接 127.0.0.1:6379，无需额外配置。

4. 启动后端项目（demo-bms）

✨

4.1 克隆项目

bash

# GitHub
git clone https://github.com/jackliuyijun/demo-bms.git

cd demo-bms

4.2 修改数据库连接

MySQL 用户 — 编辑 config/application-dev.yml：

yaml

spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/eb_demo?characterEncoding=UTF-8&useSSL=false&useInformationSchema=true&remarks=true&useUnicode=true&allowPublicKeyRetrieval=true
    username: root
    password: YOUR_PASSWORD    # 改为你的数据库密码

PostgreSQL 用户 — 编辑 config/application-pgDev.yml：

yaml

spring:
  datasource:
    url: jdbc:postgresql://127.0.0.1:5432/eb_demo
    username: postgres
    password: YOUR_PASSWORD    # 改为你的数据库密码

同时修改 config/application.yml 中的配置文件引用：

yaml

spring:
  config:
    import:
      # MySQL 用（默认）
      - "file:config/application-dev.yml"
      # PostgreSQL 用（二选一，注释掉上面那行，打开下面这行）
      # - "file:config/application-pgDev.yml"

TIP

PostgreSQL 用户还需修改 pom.xml：注释掉 db-mysql 依赖，打开 db-postgresql 依赖。

4.3 修改 Redis 连接（如非默认配置）

在 config/application-dev.yml（或 application-pgDev.yml）中：

yaml

spring:
  redis:
    database: 11
    host: 127.0.0.1
    port: 6379

4.4 执行数据库脚本

用数据库客户端工具执行 doc/sql/ 目录下对应的 SQL 脚本（参见第三步 3.2）。

4.5 编译并启动

方式一：IDE 启动（推荐开发时使用）

用 IntelliJ IDEA 打开 demo-bms 项目
等待 Maven 依赖下载完成
运行启动类 com.easybuild.admin.bms.ServerApp

方式二：命令行启动

bash

mvn clean package -DskipTests
java -jar target/demo-bms-server.jar

4.6 验证后端启动

看到控制台输出 Spring Boot 启动成功日志后，打开浏览器访问接口文档：

text

http://localhost:5001/doc.html

能看到 Knife4j 接口文档页面，说明后端已启动成功。

5. 启动前端项目（easybuild-admin）

✨

5.1 创建前端项目

方式一：使用 CLI 命令创建（推荐）

bash

npx easybuild-admin my-admin

按照提示输入项目描述、选择包管理器（推荐 yarn）即可，CLI 会自动完成模板下载、依赖安装和 Git 初始化。

方式二：手动克隆

bash

# GitHub
git clone https://github.com/jackliuyijun/easybuild-admin.git my-admin

cd my-admin
yarn install

5.2 配置后端接口地址

编辑 .env.development 文件，将 API 地址指向刚才启动的后端服务：

env

NEXT_PUBLIC_API_URL=http://localhost:5001

5.3 启动前端

bash

yarn dev

启动成功后，打开浏览器访问：

text

http://localhost:4000

5.4 登录系统

使用初始化脚本中预置的管理员账号登录（默认账号密码请查看 SQL 脚本中的初始数据），登录后即可看到完整的中后台管理界面。

TIP

以上流程是 EasyBuild 最基础的示例，更多强大的功能请继续阅读官网其他模块文档。在实际开发过程中，EasyBuild 为你提供了强大的代码生成工具，可以极大提升开发效率。

6. 常见问题

✨

Q: Maven 依赖下载失败？

检查 settings.xml 中 mirrors 的 mirrorOf 是否包含了 !jackorg-easybuild-profile 排除项。如果缺少这个排除项，阿里云镜像会代理所有请求，导致私服依赖拉取不到。

Q: 后端启动报数据库连接失败？

确认数据库服务已启动
确认 eb_demo 数据库已创建
确认 application-dev.yml（或 application-pgDev.yml）中的用户名和密码正确
PostgreSQL 用户需确认 pom.xml 中已切换为 db-postgresql 依赖

Q: 后端启动报 Redis 连接失败？

确认 Redis 服务已启动，且配置文件中的 host、port 与实际一致。

Q: 前端页面空白或接口 404？

确认 .env.development 中的 NEXT_PUBLIC_API_URL 地址正确
确认后端服务已正常运行在 5001 端口
重启前端开发服务器使环境变量生效

Q: 前端登录后页面没有菜单？

菜单由后端动态下发。确认数据库初始化脚本已执行完毕，脚本中包含了完整的菜单资源数据。

完成！

✨

到这里，你已经跑通了 EasyBuild Admin 的完整流程：

text

MySQL/PostgreSQL + Redis  →  demo-bms（后端 :5001）  →  easybuild-admin（前端 :4000）

你可以：

在 http://localhost:5001/doc.html 查看和测试所有后端接口
在 http://localhost:4000 体验完整的中后台管理功能
基于 demo-bms 和 easybuild-admin 模板，开始开发自己的业务模块

— END —