简体中文 | English

在线预览 | 快速开始 | 官方文档 | 前端仓库 | 部署脚本 | 更新日志 | v2.0.0 升级指南

Sz-Admin 是一套面向企业中后台、管理端系统和二次开发项目的开源脚手架。它由后端 sz-boot-parent、前端 sz-admin 和官方文档共同组成，目标不是堆砌功能，而是提供一套边界清晰、便于升级、适合扩展的基础工程。

• 后端技术栈：Spring Boot 4、JDK 21、Sa-Token、MyBatis-Flex、Liquibase、Redis。
• 前端技术栈：Vue 3、Vite 7、TypeScript、Element Plus、Pinia。
• 内置能力：RBAC 权限、动态菜单、数据权限、代码生成器、字典、Excel、OSS、WebSocket、接口防抖。
• 适用场景：企业后台、SaaS 管理端、二次开发脚手架、代码生成与快速原型、多数据库适配项目。

v2.0.0 是一次面向兼容性和扩展性的结构性重构：后端形成 sz-common、sz-module、sz-service 三层边界，前端引入 src/core、src/editions、src/modules 等模块化入口，让数据库、业务模块、登录适配、页面组合和派生项目接入都具备更清晰的扩展空间。对于二次开发项目来说，推荐把自有业务放进独立模块，从而减少与官方核心代码的耦合，也更利于后续升级。

Sz-Admin 也可以理解为“升职 Admin”，寓意升职加薪、节节高。它希望把常见后台能力整理成一套轻量、直观、可维护的工程底座，让开发者把更多精力放回业务本身。

当前推荐使用 sz-deploy-v3 作为服务器侧部署仓库。它基于 Docker Compose 组织运行环境，负责安装基础环境、创建 Docker 网络、生成服务目录、写入运行 .env，并启动 Redis、MySQL/PostgreSQL、MinIO、后端、WebSocket、前端静态服务和代理服务。

首次部署建议先阅读 部署总览 和 Docker 快速部署。sz-deploy-v3 当前优先适配 RockyLinux 10，其他 Linux 发行版需要按实际环境确认包管理器、防火墙、时区和系统服务差异。

快速部署入口：

wget https://raw.githubusercontent.com/feiyuchuixue/sz-deploy-v3/main/init/install.sh
wget https://raw.githubusercontent.com/feiyuchuixue/sz-deploy-v3/main/init/.env
# 按服务器环境修改 .env 后执行
bash install.sh

初始化后默认会在 /home/docker-compose 下生成 sz-service-admin、sz-service-websocket、sz-admin 等服务目录。普通升级执行服务目录下的 upgrade.sh；启用蓝绿部署时，sz-service-admin 会通过 gen-conf.sh 和 deploy.sh 完成新旧实例切换，并依赖 /api/actuator/health 做健康检查。

GitHub Actions CI/CD 只负责构建并推送后端镜像，然后通过 SSH 触发服务器上 sz-deploy-v3 已生成的 upgrade.sh 或 deploy.sh。接入 CI/CD 前，目标服务器必须先完成 sz-deploy-v3 初始化；数据库密码、Redis 密码、Sa-Token、OSS 等敏感配置应保存在服务器部署目录的 .env 和 config/{profile} 中，而不是写入 workflow。

• 企业后台管理系统：账户、角色、菜单、部门、参数、字典、日志、资源等基础能力可直接使用。
• SaaS 管理端：可基于系统角色、菜单权限、数据权限和模块注册能力继续扩展业务域。
• 二次开发脚手架：官方模块与业务模块边界清晰，适合长期跟随框架升级。
• 代码生成与快速原型：内置代码生成器，可生成常见 CRUD、导入导出、菜单和初始化脚本。
• 数据库适配项目：当前主线对 MySQL 与 PostgreSQL 做了适配优化，部署时二选一启用对应数据库模块。

• 权限体系：内置用户、角色、菜单、按钮权限和动态路由，支持超级管理员兜底策略。
• 数据权限：支持按用户、部门、自定义范围等维度控制数据访问，当前主流程集成在系统角色授权中。
• 数据字典：支持框架内置字典、业务自定义字典、静态字典预热和动态字典按需加载。
• 代码生成器：支持读取表结构、配置字段、预览代码、导出菜单和初始化脚本。
• 数据库迁移：使用 Liquibase 管理框架、生成器、演示业务等模块级 changelog。
• 文件与 OSS：基于资源场景 sceneCode 管理上传路径、访问方式和资源引用。
• Excel 导入导出：封装导入模板、失败记录、字典格式化、导出字段配置等常见能力。
• WebSocket：独立服务承载实时消息，支持多节点转发、心跳、鉴权失效处理。
• 接口防抖：内置重复请求防护能力，可按全局或接口维度配置。

sz-boot-parent/
├── sz-build               # Spring Boot 父版本、第三方依赖版本与 Maven 插件管理
├── sz-common              # 通用能力模块集合，与业务无关
│   ├── sz-common-core
│   ├── sz-common-db-core
│   ├── sz-common-db-mysql
│   ├── sz-common-db-postgresql
│   ├── sz-common-excel
│   ├── sz-common-log
│   ├── sz-common-oss
│   ├── sz-common-resource
│   └── sz-common-security
├── sz-module              # 业务模块集合，不直接启动
│   ├── sz-module-common
│   ├── sz-module-admin
│   └── sz-module-generator
└── sz-service             # 可独立部署的服务
    ├── sz-service-admin
    └── sz-service-websocket

扩展业务时，推荐新增独立 sz-module-* 模块，例如 sz-module-shop、sz-module-crm，再由 sz-service-admin 或新的服务引入。这样可以让官方 RBAC、字典、资源、生成器等模块继续跟随版本升级，自有业务也能独立维护。

sz-admin/
├── src
│   ├── api                # API 请求与接口类型，按业务域组织
│   ├── core               # 登录适配、模块注册、菜单组件解析等底座能力
│   ├── editions           # 产品版本组合入口，决定启用哪些模块能力
│   ├── modules            # 可组合业务模块，如 toolbox / generator
│   ├── views              # 传统页面目录，适合普通 CRUD 和动态路由兜底
│   ├── components         # 全局组件
│   ├── hooks              # 组合式复用逻辑
│   ├── stores             # Pinia 状态
│   ├── router             # 路由与守卫
│   └── config             # 前端常量与配置
├── package.json
└── vite.config.mts

前端 v2.0.0 保留 src/views 的低成本开发路径，普通系统管理页面、简单 CRUD 和一次性业务可以继续放在 src/views；具备独立领域、可选启用、派生项目复用或团队并行开发诉求的业务，建议放入 src/modules/<domain>，再通过 src/core 与 src/editions 进行注册和组合。

动态菜单组件解析会按“模块显式注册 -> src/modules 约定路径 -> src/views 兜底”的顺序匹配。接口调用通过 adminHttp / auditHttp / generatorHttp 区分管理端、审计与生成器接口，并与 VITE_ADMIN_API_BASE、VITE_AUDIT_API_BASE、VITE_GENERATOR_API_BASE 保持一致。

完整步骤请查看 快速开始文档。README 只保留最短启动路径。

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

1. 创建空数据库，例如 sz_admin_preview。
2. 修改 config/local/mysql.yml 或 config/local/postgresql.yml。
3. 默认使用 MySQL；如切换 PostgreSQL，需要同时修改 application.yml 中的 DB_TYPE=postgresql，并在 sz-service/sz-service-admin/pom.xml 中启用 sz-common-db-postgresql、注释 sz-common-db-mysql。
4. 修改 config/local/redis.yml。
5. 启动 sz-service/sz-service-admin 模块中的 com.sz.AdminApplication。
6. 如需 WebSocket 实时消息能力，另行启动 sz-service/sz-service-websocket。

启动后常用地址：

v2.0.0 使用 Liquibase 管理数据库结构和初始化数据，首次启动会自动创建表结构。存量旧库升级不要直接套用快速开始流程，请先阅读 v2.0.0 升级指南。

git clone https://github.com/feiyuchuixue/sz-admin.git
cd sz-admin
corepack enable
corepack prepare pnpm@10.17.1 --activate
pnpm install
pnpm dev

本地开发常用 .env.development.local：

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
VITE_API_PROXY_TARGET=http://127.0.0.1:9991
VITE_APP_CLIENT_ID=195da9fcce574852b850068771cde034
VITE_ADMIN_BYPASS_PERMISSION=true
# VITE_SOCKET_URL=ws://127.0.0.1:9993/socket

前端启动后访问：

http://localhost:9848/

默认账号：

admin / sz123456

部分截图仍沿用旧版页面，用于展示系统基础形态。v2.0.0 新增的字典来源、角色数据权限、脚本预览、模块化代码生成器等页面，后续会继续补充新版截图。

• 快速开始
• 技术选型
• 目录结构
• 配置说明
• 数据库支持
• Liquibase 数据库版本控制
• 部署总览
• Docker 快速部署（sz-deploy-v3）
• GitHub Actions CI/CD
• 数据权限
• 数据字典
• 代码生成器
• v2.0.0 升级指南

Sz-Admin 基于 Apache License 2.0 开源发布。维护项目需要持续投入时间、精力和资源，如果 Sz-Admin 对你的工作或项目有帮助，欢迎通过 Star、Fork、Issue、PR 或捐赠表达支持。

源码遵循 Apache License 2.0。Sz-Admin 名称、Logo、横版品牌图、favicon 等品牌标识与源码授权相互独立；公开使用品牌资产时，请阅读 版权声明与使用说明。

• 微信：xxmmly010（非诚勿扰）
• 邮箱：feiyuchuixue@163.com