文档导航

这篇文档用于帮助你按当前任务选择阅读顺序。你不需要从头到尾读完整站文档，先完成当前任务，再补齐相关知识即可。

当前任务	推荐起点	完成信号
先体验产品	在线体验 -> 介绍	看过真实界面，确认技术栈和能力边界符合项目要求
在本地跑起来	快速开始	后端和前端可以访问，并能完成登录
开发业务功能	代码生成器 -> 开发规范	明确生成范围、代码落点、迁移方式和权限边界
部署或升级	部署总览 / 升级指南	选定部署路线，或完成存量升级前的影响盘点

我想先判断是否适合使用

适合：正在评估后台管理脚手架、RBAC 权限体系、前后端分离框架，或想了解 Sz-Admin 的技术选型和能力边界。

建议阅读顺序：

1. 在线体验：先查看真实管理端界面和主要交互。
2. 介绍：了解项目定位、仓库地址和主要功能。
3. 技术栈：确认后端、前端、数据库、缓存等基础技术是否符合团队现状。
4. 目录结构：快速判断模块边界、扩展方式和二开隔离方式。
5. 序言与版权声明：开始使用前确认开源协议和品牌使用边界。

我想先把项目跑起来

适合：第一次下载项目、准备本地启动后端和前端，或想快速验证预览环境效果。

建议阅读顺序：

1. 快速开始：完成后端、前端的本地启动和登录。
2. 配置：理解 profile、数据库、Redis、客户端 ID、API 前缀等运行配置。
3. 数据库支持：确认 MySQL 或 PostgreSQL 的选择方式和注意事项。
4. Liquibase 版本控制：理解数据库结构和初始化数据如何自动创建。
5. 常见问题：启动失败、依赖下载、编码、合并冲突等问题优先在这里排查。

我准备做业务开发

适合：已经能运行项目，准备新增页面、接口、菜单、权限、表结构，或判断某个业务是否需要拆成独立模块。

建议阅读顺序：

1. 代码生成器：了解导入表、字段配置、预览、磁盘检查和生成结果。
2. 规范与约定：校正生成后的命名、分层、接口、菜单和权限实现。
3. 目录结构：确认小型 CRUD 与独立业务域各自的落点。
4. 业务模块接入：业务具备独立边界时，再了解后端 module、API 前缀、Liquibase、前端 module 和 edition 注册。
5. Liquibase 版本控制：新增表结构和初始化数据前必须阅读。

普通系统管理页面或很小的 CRUD，可以继续放在 sz-module-admin 既有能力范围；按当前代码生成器默认布局，前端放在 src/modules/admin。已有的 src/views 页面可以继续兼容运行；代码生成器、审计、SSO、商城、CRM 等边界更清晰的业务域，建议新建独立 sz-module-* 和前端 src/modules/<domain>，这样后续同步官方版本时更容易降低冲突。

我需要使用核心扩展能力

适合：已经有明确功能目标，需要接入字典、审计日志、数据权限、Excel、OSS、WebSocket 或接口防抖。

按能力阅读：

目标	优先阅读
管理下拉选项、状态枚举、导入导出值转换	数据字典
查看谁做了什么、哪些接口慢、哪些接口异常	审计日志
按部门、人员或权限范围限制数据可见性	数据权限
做 Excel 导入、导出、模板下载和失败记录	Excel 导入导出
接入上传、下载、对象存储和资源访问地址填充	OSS 文件存储
推送通知、在线状态、实时消息	WebSocket
防止接口短时间重复提交	接口防抖

阅读这些专题前，建议先补一遍 约定，避免权限码、字典类型、资源场景码、审计注解、前后端字段命名不一致。审计日志默认复用 @Tag 和 @Operation，如果只是查看操作审计、性能日志、异常日志，直接阅读 审计日志 即可。

我准备部署到服务器

适合：本地已经验证通过，准备部署测试、预览或生产环境。

建议阅读顺序：

1. 部署总览：先理解 jar、外置配置、资源和日志目录，再选择部署方式。
2. Docker 快速部署：全新环境优先阅读。
3. GitHub CI/CD：需要自动构建、自动发布时阅读。
4. 旧版 Shell 部署：需要理解历史 shell 部署方式时阅读。
5. 配置与常见问题：部署前复核运行参数，遇到失败时按症状排查。

生产部署前务必替换默认账号、默认密钥、数据库密码、Redis 密码、OSS 配置等敏感信息，并确认 Nginx 代理和 API/WebSocket 前缀一致。

我准备从旧版本升级

适合：已有存量项目、已经二开、准备合并新版框架或迁移到当前版本。

建议阅读顺序：

1. 更新日志：先看版本变化、兼容影响和不兼容调整。
2. 升级指南：按迁移、兼容、新功能、行为变化逐项处理。
3. 业务模块接入：理解 v2.0.0 后端 module、前端 module 和 edition 注册方式，避免把客户业务混入官方核心模块。
4. Liquibase 版本控制：确认数据库变更如何叠加到存量库。
5. 审计日志：如果启用审计模块，提前确认 audit-log.yml、日志写入策略和关闭方式。
6. 常见问题：升级中的冲突、脚本、配置、构建问题优先排查。

存量升级不要直接覆盖现有代码和数据库。建议先备份仓库与数据库，在影子库或测试环境完成验证，再合并到生产分支。

我遇到问题不知道从哪看

可以按问题类型定位：

问题类型	优先阅读
启动失败、依赖下载、端口、环境变量	快速开始、常见问题
数据库初始化、表结构、迁移脚本	Liquibase 版本控制、数据库支持
接口返回、权限注解、菜单按钮权限	约定、规范
前端接口、路由、页面解析、模块注册	业务模块接入、目录结构
操作审计、性能日志、异常日志、traceId	审计日志、配置
版本差异、历史变更、升级风险	更新日志、升级指南
非标准能力设计，例如多数据源	多数据源的实现

我想交流或支持项目

适合：需要加入社区讨论、反馈问题、关注项目动态，或希望通过 Star、分享、打赏等方式支持 Sz-Admin 开源维护。

建议入口：

1. 加入讨论群：查看微信群入口，适合交流使用经验、反馈问题、了解项目动态。
2. 捐赠与支持：查看微信、支付宝打赏入口，也可以通过 Star、Fork、Watch、分享项目等方式支持开源维护。

提问前建议先阅读 常见问题，并尽量附上版本号、运行环境、报错截图或关键日志。这样社区成员更容易快速判断问题。

我需要增值服务

适合：问题已经超出社区互助范围，需要明确响应、定制开发、远程排查、部署协助、升级迁移、性能优化或企业级交付支持。

建议阅读：

1. 增值服务：了解服务范围、适用场景、合作流程和联系方式。
2. 升级指南：如果目标是版本升级或存量项目迁移，先确认迁移内容和风险点。
3. 部署总览：如果目标是服务器部署或环境排查，先准备好部署方式、服务器环境和关键日志。
4. 代码生成器：如果目标是快速落地业务 CRUD，可以先确认生成器能力边界。

增值服务不是使用开源项目的前置条件。项目本身仍遵循开源协议免费使用；增值服务主要面向需要节省排查时间、降低交付风险或获得定制支持的场景。

推荐阅读路径速查

当前目标	最短路径
了解项目	在线体验 -> 介绍 -> 技术栈 -> 序言
本地运行	快速开始 -> 登录成功 -> 配置与数据库支持
新增普通 CRUD	代码生成器 -> 规范 -> Liquibase
接入独立业务域	目录结构 -> 业务模块接入 -> 配置 -> Liquibase -> 约定
接入核心能力	约定 -> 对应核心专题 -> 常见问题
查看审计与诊断日志	审计日志 -> 配置 -> 常见问题
部署上线	部署总览 -> Docker 快速部署或 GitHub CI/CD -> 常见问题
存量升级	更新日志 -> 升级指南 -> 业务模块接入 -> Liquibase -> 常见问题
交流支持	加入讨论群 -> 捐赠与支持
增值服务	增值服务 -> 对应专题文档 -> 需求沟通

如果你只是第一次接触 Sz-Admin，推荐从“本地运行”这条线开始。项目跑起来之后，再根据实际业务目标补读规范、约定和核心功能文档，会更容易把知识点和真实代码对应起来。