快速开始

本文用于从零启动 Sz-Admin 2.0 主线项目。当前项目由后端 sz-boot-parent 和前端 sz-admin 两个仓库组成：后端提供管理端、生成器、权限、字典、数据权限、资源和 OpenAPI；前端提供登录、动态路由、系统管理页面和代码生成器页面。

准备环境

环境	推荐版本	说明
JDK	21	示例使用 Azul Zulu
Maven	3.8+	推荐 3.9.x
数据库	MySQL 8.0.17+ 或 PostgreSQL 16+	默认使用 MySQL
Redis	7.x	用于登录态、缓存和同步能力
Node.js	>= 20.19.0，推荐 20.19.5	Vite 7 与当前 `package.json` 的运行要求
pnpm	10.17.1	前端包管理工具，建议与 `packageManager` 保持一致

IMPORTANT

PostgreSQL 支持不是只改连接串。若从默认 MySQL 切换为 PostgreSQL，需要同时修改 DB_TYPE=postgresql，并在 sz-service-admin/pom.xml 中启用 sz-common-db-postgresql、注释 sz-common-db-mysql。

分支说明

main：主分支，用于发布稳定版本。
dev：开发分支，用于持续集成和测试。
{other}：其他分支，用于特定功能或修复的临时开发。

启动顺序

准备 MySQL/PostgreSQL 和 Redis。
启动后端 sz-service-admin，由 Liquibase 自动初始化数据库结构和基础数据。
启动前端 sz-admin，通过 Vite 代理访问后端 /api/admin/** 和 /api/generator/**。

默认访问关系如下：

能力	地址
后端服务	`http://127.0.0.1:9991/api`
管理端 API	`http://127.0.0.1:9991/api/admin/**`
审计 API	`http://127.0.0.1:9991/api/audit/**`
生成器 API	`http://127.0.0.1:9991/api/generator/**`
Swagger UI	`http://127.0.0.1:9991/api/swagger-ui.html`
前端页面	`http://localhost:9848/`

后端运行

后端仓库采用 sz-common、sz-module、sz-service 三层结构。日常本地启动时只需要运行 sz-service-admin，它会装配后台管理模块、代码生成器模块、数据库实现、Redis、OpenAPI 和 Liquibase。

第一步：源码下载

GithubGitee

shell

git clone https://github.com/feiyuchuixue/sz-boot-parent.git

shell

git clone https://gitee.com/feiyuchuixue/sz-boot-parent.git

第二步：导入项目

这里使用的是idea

sz-admin 使用 IDEA 导入后端项目截图

第三步：依赖安装

导入 Maven 依赖。为了加快下载速度，项目可按需配置 Maven 镜像；如果你的网络环境已经可以稳定访问中央仓库，也可以使用默认 Maven 配置。

xml

    <repositories>
        <repository>
            <id>public</id>
            <url>https://maven.aliyun.com/repository/public</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </repository>

        <!-- 配置官方Maven中央仓库 -->
        <repository>
            <id>central</id>
            <url>https://repo1.maven.org/maven2</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled> <!-- 通常中央仓库不包含snapshots -->
            </snapshots>
        </repository>

    </repositories>

第四步：修改配置文件

重要提示！

后端配置不放在 resources/config 下，而是在仓库根目录的 config 目录按环境拆分。application.yml 会根据 spring.profiles.active 和 DB_TYPE 自动导入对应配置。

name	描述
dev	开发环境
local	本地环境
preview	预览/测试环境
prod	正式环境

详见配置说明。

打开项目根目录下的 config/local 目录。
默认 DB_TYPE=mysql，打开 mysql.yml 和 redis.yml 修改配置。
如使用 PostgreSQL，请将 application.yml 中的 DB_TYPE 改为 postgresql，打开 postgresql.yml 修改连接信息，并在 sz-service-admin/pom.xml 中启用 PostgreSQL 数据库模块。

sz-admin 修改 mysql.yml 和 redis.yml 数据库连接配置截图

IMPORTANT

这里需要先创建空数据库，例如 sz_admin_preview 或 sz_admin_preview_test。后续不需要手动导入 SQL，当前版本使用 Liquibase 管理数据库结构和初始化数据，项目启动时会自动检查数据库状态并创建相应表结构。

MySQL 推荐使用 utf8mb4 字符集。存量旧库升级不要直接套用快速开始流程，请先阅读 v2.0.0 升级指南。

修改mysql连接信息：

yaml

## mysql.yml
spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://127.0.0.1:3306/sz_admin_preview?useUnicode=true&characterEncoding=UTF-8&serverTimezone=GMT%2B8&useSSL=false&allowPublicKeyRetrieval=true // [!code highlight]   // [!code focus] // [!code warning]
    username: root // [!code highlight]   // [!code focus] // [!code warning]
    password: Yanfa2023@ // [!code highlight]   // [!code focus] // [!code warning]
    hikari:
      #连接池名
      pool-name: HikariCP
      #最小空闲连接数
      minimum-idle: 5
      # 空闲连接存活最大时间，默认10分钟
      idle-timeout: 600000
      # 连接池最大连接数，默认是10
      maximum-pool-size: 10
      # 此属性控制从池返回的连接的默认自动提交行为,默认值：true
      auto-commit: true
      # 此属性控制池中连接的最长生命周期，值0表示无限生命周期，默认30分钟
      max-lifetime: 1800000
      # 数据库连接超时时间,默认30秒
      connection-timeout: 30000
      # 连接测试query
      connection-test-query: SELECT 1

切换 PostgreSQL 时需要同步调整依赖：

xml

<!-- Mysql 数据库：使用 PostgreSQL 时请注释 -->
<!--
<dependency>
    <groupId>com.sz</groupId>
    <artifactId>sz-common-db-mysql</artifactId>
</dependency>
-->

<!-- PostgreSQL 数据库：使用 PostgreSQL 时请启用 -->
<dependency>
    <groupId>com.sz</groupId>
    <artifactId>sz-common-db-postgresql</artifactId>
</dependency>

WARNING

MySQL 和 PostgreSQL 数据库方言模块不要同时启用，否则数据权限方言、类型处理器和元数据读取可能出现冲突。

修改redis连接信息：

yaml

## redis.yml
spring:
  data:
    redis:
      #单机配置
      host: 127.0.0.1 // [!code highlight]   // [!code focus] // [!code warning]
      port: 6379 // [!code highlight]   // [!code focus] // [!code warning]
      # 数据索引
      database: 0
      # 连接超时时间（毫秒）
      timeout: 50000
      ###连接池配置###
      jedis:
        pool:
          # 连接池最大连接数（使用负值表示没有限制）
          max-active: 100
          # 连接池最大阻塞等待时间（使用负值表示没有限制）
          max-wait: -1
          # 连接池中的最大空闲连接
          max-idle: 30
          # 连接池中的最小空闲连接
          min-idle: 10
      password: 123456 // [!code highlight]   // [!code focus] // [!code warning]

# 开启redis监听
redis:
  listener:
    enable: true

至此，后端本地启动前的基础配置已经完成。

第五步：启动!

运行 sz-service/sz-service-admin 模块中的 com.sz.AdminApplication.java 启动文件。

启动成功信息如下：

shell

2024-05-14 19:42:10.871  INFO 31360 ---  [admin-service] [           main] c.sz.platform.listener.AppStartListener  :  ===================== app is running finish ... =====================
                                   __                _
                                  |  ]              (_)
 .--.   ____  ______  ,--.    .--.| |  _ .--..--.   __   _ .--.
( (`\] [_   ]|______|`'_\ : / /'`\' | [ `.-. .-. | [  | [ `.-. |
 `'.'.  .' /_        // | |,| \__/  |  | | | | | |  | |  | | | |
[\__) )[_____]       \'-;__/ '.__.;__][___||__||__][___][___||__]
------------------https://szadmin.cn  (v2.0.0)-------------------

验证

访问 http://127.0.0.1:9991/api/swagger-ui.html，能打开 Springdoc 提供的 Swagger UI，即表示接口文档能力可用。也可以访问 http://127.0.0.1:9991/api/actuator/health 检查健康状态。

常用接口前缀：

类型	前缀	示例
管理端接口	`/api/admin`	`/api/admin/auth/login`、`/api/admin/sys-user/page`
审计接口	`/api/audit`	`/api/audit/sys-operation-log/page`
生成器接口	`/api/generator`	`/api/generator/generator-table/page`

IMPORTANT

v2.0.0 基于 Spring Boot 4.x，Knife4j UI 暂未作为当前主线适配，实际接口文档请使用 Springdoc OpenAPI / Swagger UI。历史 doc.html 访问方式已暂停作为官网推荐入口。

注：格式化

框架引入了spotless-maven-plugin作为格式化方案，提交代码前可手动运行 spotless:apply插件。

java-format

前端运行

前端仓库默认使用 Vite 7、Vue 3、TypeScript 和 Element Plus。v2.0.0 起接口调用拆分为管理端、审计和生成器三个 HTTP 实例；v2.0.1 起自定义业务模块可通过 VITE_API_CONTEXT_PATH + 模块前缀动态创建 HTTP client。因此本地环境需要同时配置 VITE_ADMIN_API_BASE、VITE_AUDIT_API_BASE、VITE_GENERATOR_API_BASE、VITE_API_CONTEXT_PATH 和 VITE_API_PROXY_TARGET。

第一步：源码下载

GithubGitee

shell

git clone https://github.com/feiyuchuixue/sz-admin.git

shell

git clone https://gitee.com/feiyuchuixue/sz-admin.git

第二步：导入项目

同上

第三步：依赖安装

shell

# 使用 package.json 中锁定的 pnpm 版本
corepack enable
corepack prepare pnpm@10.17.1 --activate

# 如本机未使用 Corepack，也可以全局安装指定版本
npm install -g pnpm@10.17.1

# 进入项目根目录，安装依赖
pnpm install

第四步：创建local环境

仓库中已经提供 .env.development，如果只是本地修改后端地址、WebSocket 地址或 clientId，建议在项目根目录创建 .env.development.local，避免覆盖团队共享配置。

properties

# 本地环境
VITE_USER_NODE_ENV=development

# 公共基础路径
VITE_PUBLIC_PATH=/

# 管理端、审计和生成器接口前缀
VITE_ADMIN_API_BASE=/api/admin
VITE_AUDIT_API_BASE=/api/audit
VITE_GENERATOR_API_BASE=/api/generator
# 自定义模块动态 API 前缀的公共 context-path
VITE_API_CONTEXT_PATH=/api
VITE_API_PROXY_TARGET=http://127.0.0.1:9991

# 授权的 clientId，需要与后端【客户端管理】中的可用客户端一致
VITE_APP_CLIENT_ID=195da9fcce574852b850068771cde034

# 是否对 admin（超管）用户放行前端按钮权限验证，默认放行
VITE_ADMIN_BYPASS_PERMISSION=true

## 启用 WebSocket 连接
## 若需启用 WebSocket，请设置 VITE_SOCKET_URL 为有效的 WebSocket 地址
## 若不设置或留空，WebSocket 功能将不会启用。例：
# VITE_SOCKET_URL=ws://127.0.0.1:9993/socket

TIP

本地开发时，Vite 会将 VITE_API_CONTEXT_PATH 下的请求代理到 VITE_API_PROXY_TARGET。因此前端代码里 adminHttp.get('/sys-user/page') 实际会请求后端 /api/admin/sys-user/page；自定义模块通过 createModuleHttp('crm', '/crm') 发起的请求会落到 /api/crm/**。

第五步：启动！

打开命令行，执行 pnpm dev，项目很快启动，并弹出窗口！！你没看错，它只用了574ms！！！这就是vite！！

shell

  VITE v7.3.3  ready in 574 ms

  ➜  Local:   http://localhost:9848/
  ➜  Network: http://192.168.124.7:9848/
  ➜  Network: http://192.168.56.1:9848/
  ➜  press h + enter to show help

sz-admin 登录页面截图

输入账号密码admin/sz123456，进入home页。

sz-admin 首页（home 页面）截图

注：常用命令

shell

# 运行dev环境
pnpm dev

# 打包
pnpm build

# ts类型检查
pnpm type-check

# es-lint 检查
pnpm lint

# 格式化
pnpm format

快速开始 ​

准备环境 ​

分支说明 ​

启动顺序 ​

后端运行 ​

第一步：源码下载 ​

第二步：导入项目 ​

第三步：依赖安装 ​

第四步：修改配置文件 ​

第五步：启动! ​

前端运行 ​

第一步：源码下载 ​

第二步：导入项目 ​

第三步：依赖安装 ​

第四步：创建local环境 ​

第五步：启动！ ​

相关文档 ​

快速开始

准备环境

分支说明

启动顺序

后端运行

第一步：源码下载

第二步：导入项目

第三步：依赖安装

第四步：修改配置文件

第五步：启动!

前端运行

第一步：源码下载

第二步：导入项目

第三步：依赖安装

第四步：创建local环境

第五步：启动！

相关文档