快速开始

本文面向 v2.1.0 当前主线的全新本地开发环境。完成后，你将能启动后端和前端，用初始管理员登录并查看系统管理菜单。默认路线使用 MySQL；PostgreSQL 用户按文中的数据库切换分支操作。

已有项目先走升级路线

已有业务数据的数据库不要直接用于本教程。请先阅读升级指南，根据当前版本完成备份、迁移和兼容检查。空库初始化不替代存量升级。

准备环境

环境	推荐版本	说明
Java	25 LTS	示例使用 Azul Zulu；当前统一产出 Java 25 字节码
Maven	3.9.x	使用 `mvn -v` 确认 Java 也是 25
数据库	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` 保持一致

TIP

自 v2.1.0 起，Java 25 是本地构建和运行的最低基线，根 POM 通过 --release 25 产出 Java 25 字节码。Java 21 仅适用于 v2.0.2 及更早历史版本。

IMPORTANT

PostgreSQL 支持不是只改连接串。若从默认 MySQL 切换为 PostgreSQL，需要同时设置 DB_TYPE=postgresql，并选择 Maven 的 postgresql profile；不要再通过注释、取消注释依赖来切换数据库模块。

开始前运行 java -version、mvn -v、node -v 和 pnpm -v 检查版本。Java 不一致时，先统一终端 JAVA_HOME、PATH 和 IDEA 的 Project SDK / Maven Runner JRE。

分支说明

首次体验从前后端仓库的 main 获取源码；复现某次发布时，选择对应版本。dev 用于开发迭代，不要混用不同版本的前后端与初始化数据。

启动顺序

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

本教程只启动主后台服务，独立 WebSocket 服务可在登录跑通后再接入。

默认访问关系如下：

能力	地址
后端服务	`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

下载完成后，确认目录内包含 pom.xml、sz-build、sz-common、sz-module、sz-service 和 config。下载失败先检查 Git、网络和仓库地址。

第二步：导入项目

在 IDEA 打开 sz-boot-parent 根目录或根 pom.xml，以 Maven 工程导入。不要只打开 sz-service-admin 子目录。将 Project SDK、Maven 导入和运行使用的 JDK 统一为 25。

完成标志： IDEA 能识别各 Maven 模块；依赖仍标红时继续下一步查看构建错误。

第三步：依赖安装

在后端根目录运行：

shell

mvn -v
mvn -pl sz-service/sz-service-admin -am compile -Pmysql -DskipTests

PostgreSQL 用户将 -Pmysql 改为 -Ppostgresql。-am 一起编译依赖模块，无需逐个安装模块。

完成标志： 输出 BUILD SUCCESS。提示 release version 25 not supported 时检查 mvn -v 的 Java 版本；依赖下载失败时先处理 Maven 网络或镜像设置。编译成功仅验证构建，连接配置将在服务启动时验证。

第四步：修改配置文件

当前 sz-service/sz-service-admin/src/main/resources/application.yml 默认设置 DB_TYPE: mysql 和 spring.profiles.active: local，从进程工作目录导入 config/local/*.yml。保留仓库提供的整套配置，下面只调整连接文件；完整加载关系见配置说明。

先用数据库客户端创建空开发库 sz_admin_local，MySQL 字符集选择 utf8mb4。应用账号需要对该开发库有建表和读写权限。首次启动时 Liquibase 自动创建表和初始化数据，无需手动导入旧 SQL。

配置 config/local/mysql.yml：

以下是可用于本地开发的最小配置，将地址、库名、用户名与密码换成自己的值。在原文件上编辑时，可保留 Hikari 连接池参数，但不要删除 spring.liquibase。

yaml

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: "jdbc:mysql://127.0.0.1:3306/sz_admin_local?useUnicode=true&characterEncoding=UTF-8&serverTimezone=GMT%2B8&useSSL=false&allowPublicKeyRetrieval=true"
    username: "your-mysql-user"
    password: "your-mysql-password"
  liquibase:
    enabled: true
    change-log: classpath:db/changelog/changelog-master.xml
    database-change-log-lock-table: databasechangeloglock
    database-change-log-table: databasechangelog

PostgreSQL 分支： 先创建空开发库 sz_admin_local，确认应用账号有目标 schema 的建表和读写权限。在 config/local/postgresql.yml 填写：

yaml

spring:
  datasource:
    driver-class-name: org.postgresql.Driver
    url: "jdbc:postgresql://127.0.0.1:5432/sz_admin_local"
    username: "your-postgresql-user"
    password: "your-postgresql-password"
  liquibase:
    enabled: true
    change-log: classpath:db/changelog/changelog-master.xml
    database-change-log-lock-table: databasechangeloglock
    database-change-log-table: databasechangelog

将 application.yml 中的 DB_TYPE 改为 postgresql，同时在 IDEA Maven Profiles 中只选择 postgresql，重新加载项目。终端构建使用 -Ppostgresql。前者选择运行配置，后者选择数据库模块，两者必须一致，不能同时启用两种数据库 profile。切换前编译过 MySQL 时，执行：

shell

mvn -pl sz-service/sz-service-admin -am clean compile -Ppostgresql -DskipTests

配置 config/local/redis.yml：

yaml

spring:
  data:
    redis:
      host: 127.0.0.1
      port: 6379
      database: 0
      password: "your-redis-password"
      timeout: 50000
redis:
  listener:
    enable: true

无密码 Redis 使用 password: ""。密码保留引号，端口和数据库索引保持数字。团队共用 Redis 时，使用独立开发实例或约定的数据库索引。

完成标志： 数据库客户端能连接开发库，Redis 地址与密码已确认。连接失败先核对服务进程、地址、端口、账号权限和库名，再继续启动后端。

第五步：启动!

在 IDEA 为 com.sz.AdminApplication 创建运行配置：

运行项	设置
Main class	`com.sz.AdminApplication`
Module classpath	`sz-service-admin`
JRE	JDK 25
Working directory	本机 `sz-boot-parent` 根目录，该目录下必须能看到 `config`
Program arguments	`--spring.profiles.active=local --DB_TYPE=mysql`；PostgreSQL 改为 `--DB_TYPE=postgresql`

IDEA Maven Profiles 选择与 DB_TYPE 一致的数据库 profile，重新加载后运行。工作目录不能设为 sz-service/sz-service-admin，否则 file:config/local/... 会找不到文件。

也可以打包后用命令行启动

在后端根目录执行：

shell

mvn -pl sz-service/sz-service-admin -am package -Pmysql -DskipTests
java -jar sz-service/sz-service-admin/target/sz-service-admin-2.1.0-SNAPSHOT.jar --spring.profiles.active=local --DB_TYPE=mysql

PostgreSQL 将两条命令中的 mysql 换成 postgresql。其他版本按 target 中实际生成的 jar 文件名调整。保持当前工作目录为后端根目录，不要进入 target 后启动。

完成标志： 日志确认使用 local，Liquibase 初始化没有失败，出现 Started AdminApplication 且进程持续运行。然后访问本地 Swagger UI，确认接口文档加载成功。当前使用 Springdoc，历史 doc.html 不作为本教程入口。

启动失败时保留第一个异常日志，对照启动失败定位。不要反复重启或直接删除迁移记录。

前端运行

前端通过 Vite 代理连接刚才启动的后端。新开终端，在后端项目同级目录下载前端，后续命令均在 sz-admin 根目录执行。

第一步：源码下载

GithubGitee

shell

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

shell

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

下载完成后，确认 sz-admin 目录内有 package.json、src 和 vite.config.mts。

第二步：导入项目

用编辑器打开 sz-admin，终端进入该目录。保持后端服务运行。

第三步：依赖安装

shell

# 尚未安装 pnpm 时执行；已有正确版本则跳过第一条
npm install -g pnpm@10.17.1
pnpm -v
pnpm install

完成标志： 安装正常结束，没有未解决错误。Node 引擎不兼容时先检查版本；依赖下载失败时检查网络设置。不要混用 npm / yarn 安装项目依赖或删除锁文件来规避错误。

第四步：创建local环境

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

properties

VITE_USER_NODE_ENV=development
VITE_PUBLIC_PATH=/
VITE_PORT=9848
VITE_ADMIN_API_BASE=/api/admin
VITE_AUDIT_API_BASE=/api/audit
VITE_GENERATOR_API_BASE=/api/generator
VITE_API_CONTEXT_PATH=/api
VITE_API_PROXY_TARGET=http://127.0.0.1:9991
VITE_APP_CLIENT_ID=195da9fcce574852b850068771cde034
# 本教程只启动主后台，显式覆盖共享配置中的 WebSocket 地址
VITE_SOCKET_URL=

该 clientId 对应全新库初始化的管理端客户端。已有库若修改过客户端，请使用【客户端管理】中的可用 clientId，不要把 client secret 放入前端环境变量。

完成标志： 代理目标只写后端主机和端口，前缀与后端一致。.env.development.local 会覆盖共享配置中的同名变量；修改后必须重新启动 Vite。

TIP

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

第五步：启动！

shell

pnpm dev

打开终端输出的 Local 地址，默认是 http://localhost:9848/。端口被占用时以终端实际地址为准。

完成标志： 浏览器显示登录页，后端仍在运行。页面打不开时检查 Vite 是否启动；页面打开但请求失败时，查看浏览器 Network 的请求路径和响应，再对照下面的定位表。

登录并确认结果

全新开发库使用账号 admin、密码 sz123456 登录；页面要求验证码时完成验证再提交。已有数据库请使用实际账号，不要假设初始密码仍有效。

登录后进入首页，左侧菜单正常加载。
打开系统管理中的用户、角色页面，列表可以返回。
刷新后仍能进入已授权页面，没有立即返回登录页。

以上均通过，才算本地登录主线跑通。首次登录后修改初始管理员密码。以下为已有登录页示意，实际界面以当前版本为准：

Sz-Admin 登录页示意，沿用已有截图

准备开发业务时，继续阅读代码生成器，先确认导入表、生成目标、预览、磁盘检查和数据库脚本边界。

启动失败定位

现象	首先检查	后续入口
编译不支持 release 25	`mvn -v` 和 IDEA Maven Runner 是否使用 JDK 25	技术选型
找不到 `config/local/*.yml`	工作目录是否为后端根目录、profile 是否为 local	配置说明
数据库拒绝连接或认证失败	地址、端口、库名、账号密码和权限	数据库支持
驱动缺失或方言不匹配	`DB_TYPE` 与 Maven profile 是否一致，是否重新构建	数据库支持
Liquibase 失败或等待锁	第一个失败 changeSet、是否误用旧库、是否有另一实例正在迁移	Liquibase
Redis 连接或认证失败	主机、数字端口、密码；无密码时配置空字符串	配置说明
页面打开但 API 404 或代理失败	后端 9991、环境文件是否生效、API 前缀是否匹配	常见问题
登录提示客户端或账号错误	clientId 是否可用、账号是否已修改密码	常见问题
登录后立即失效或 C105	实际响应、后端日志、Redis 连接、旧登录态及前后端版本	常见问题

快速开始 ​

准备环境 ​

分支说明 ​

启动顺序 ​

后端运行 ​

第一步：源码下载 ​

第二步：导入项目 ​

第三步：依赖安装 ​

第四步：修改配置文件 ​

第五步：启动! ​

前端运行 ​

第一步：源码下载 ​

第二步：导入项目 ​

第三步：依赖安装 ​

第四步：创建local环境 ​

第五步：启动！ ​

登录并确认结果 ​

启动失败定位 ​

相关文档 ​

快速开始

准备环境

分支说明

启动顺序

后端运行

第一步：源码下载

第二步：导入项目

第三步：依赖安装

第四步：修改配置文件

第五步：启动!

前端运行

第一步：源码下载

第二步：导入项目

第三步：依赖安装

第四步：创建local环境

第五步：启动！

登录并确认结果

启动失败定位

相关文档