阅读路线

这篇文档用于帮助你按当前目标选择阅读顺序。你不需要从头到尾读完整站文档，先找到自己所处阶段，再补齐相关知识即可。

文档目录大致按“入门 -> 开发指南 -> 核心功能 -> 工具 -> 部署 -> 版本与支持”组织。第一次接触项目时先把项目跑起来；开始二开时再看开发约定、业务模块接入和对应核心功能；存量项目升级时优先看更新日志和升级指南。

我想先判断是否适合使用

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

建议阅读顺序：

1. 序言：了解开源协议、当前版本和使用前注意事项。
2. 介绍：了解项目定位、在线体验、仓库地址和主要功能。
3. 技术栈：确认后端、前端、数据库、缓存等基础技术是否符合团队现状。
4. 目录结构：快速判断模块边界、扩展方式和二开隔离方式。
5. 更新日志：了解近期版本变化、兼容影响和迁移重点。

我想先把项目跑起来

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

建议阅读顺序：

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

我准备做业务开发

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

建议阅读顺序：

1. 目录结构：先确认后端模块、前端页面目录和可组合模块的放置规则。
2. 业务模块接入：如果业务具备独立边界，先按审计模块的例子了解后端 module、API 前缀、Liquibase、前端 module 和 edition 注册。
3. 规范：了解代码格式、命名、Controller、Service、DTO、VO 等基础规范。
4. 约定：确认接口响应、权限码、菜单路由、字典、配置等协作约定。
5. Liquibase 版本控制：新增表结构和初始化数据前必须阅读。
6. 代码生成器：如果是标准 CRUD，可先用生成器生成起点，再按规范检查业务细节。

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

我需要使用核心扩展能力

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

按能力阅读：

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

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

我准备部署到服务器

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

建议阅读顺序：

1. 配置：先确认环境变量、数据库、Redis、OSS、客户端、WebSocket 等配置。
2. Shell 部署：了解传统服务器部署方式。
3. Docker 快速部署：了解 Docker 部署方式。
4. GitHub CI/CD：需要自动构建、自动发布时阅读。
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 -> 约定
接入核心能力	约定 -> 对应核心专题 -> 常见问题
查看审计与诊断日志	审计日志 -> 配置 -> 常见问题
部署上线	配置 -> Shell 部署或 Docker 快速部署 -> GitHub CI/CD
存量升级	更新日志 -> 升级指南 -> 业务模块接入 -> Liquibase -> 常见问题
交流支持	加入讨论群 -> 捐赠与支持
增值服务	增值服务 -> 对应专题文档 -> 需求沟通

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