部署总览
部署 sz-admin 前，建议先理解后端服务的 jar 运行模型。无论最终使用 sz-deploy-v3、Docker Compose、GitHub Actions CI/CD，还是自行接入企业运维平台，核心都离不开四件事：应用镜像或 jar、外置配置、资源数据目录和日志目录。
一、先理解运行模型
sz-service-admin 是 Spring Boot 服务。以 jar 方式运行时，推荐在 jar 同级目录准备：
deploy/
├── sz-service-admin.jar
├── config/
│ └── prod/
│ ├── knife4j.yml
│ ├── oss.yml
│ ├── mybatis-flex.yml
│ ├── mysql.yml 或 postgresql.yml
│ ├── page-helper.yml
│ ├── redis.yml
│ └── sa-token.yml
├── data/
└── logs/| 目录或文件 | 是否必需 | 说明 |
|---|---|---|
sz-service-admin.jar | 必需 | 后端服务运行产物，由 sz-boot-parent 构建生成。 |
config/{profile} | 必需 | 外置配置目录，保存数据库、Redis、Sa-Token、OSS、MyBatis Flex 等配置。 |
data | 条件必需 | LOCAL 资源存储目录。使用本地资源时必须持久化；全部使用 MinIO/OSS 时可作为预留目录。 |
logs | 运行后生成 | 应用日志目录，建议挂载到宿主机并纳入日志清理策略。 |
启动时通过 profile 和数据库类型选择配置：
DB_TYPE=mysql java -jar sz-service-admin.jar --spring.profiles.active=prod$env:DB_TYPE = "mysql"
java -jar .\sz-service-admin.jar --spring.profiles.active=prodsz-service-websocket 也是独立 Spring Boot 服务，但只依赖 WebSocket 运行所需配置，重点是 Redis 与 Sa-Token。
二、Docker 对运行模型的封装
Docker Compose 不改变服务读取配置和写入资源的方式，只是把目录挂载到容器中：
volumes:
- ./logs:/logs
- ./config:/config
- /home/data/sz-resource:/data可以这样理解：
| jar 部署目录 | Docker 容器目录 | 说明 |
|---|---|---|
./config/{profile} | /config/{profile} | 必须准备完整。缺少配置文件会导致服务启动失败。 |
./data | /data | LOCAL 资源目录，必须持久化。 |
./logs | /logs | 日志目录，建议挂载到宿主机。 |
因此，学习 jar 模型不是为了替代 Docker，而是为了理解 Docker 部署时哪些目录不能丢，哪些配置不能被镜像覆盖。
三、选择部署方式
| 部署方式 | 推荐优先级 | 适合场景 | 阅读入口 |
|---|---|---|---|
| Docker Compose 快速部署 | 新环境推荐 | 全新安装、快速体验、希望用脚本统一编排 Redis、数据库、MinIO、后端、WebSocket、前端和代理。 | Docker 快速部署 |
| GitHub Actions CI/CD | 进阶自动化 | 已完成服务器初始化，希望自动构建后端镜像、推送镜像并远程触发升级。 | GitHub Actions CI/CD |
| 传统 jar 部署 | 基础模型 | 想理解服务运行机制，或已有 JDK、数据库、Redis、Nginx 等完整运维体系。 | 本页运行模型 |
| 旧版 shell 脚本 | 历史参考 | v2.0.0 后不再作为推荐主路径，仅参考构建、挂载和启动思路。 | 传统部署 |
推荐路径：
先阅读部署总览
↓
用 sz-deploy-v3 完成服务器初始化
↓
按需接入 GitHub Actions CI/CD四、部署前确认清单
| 分类 | 需要确认 |
|---|---|
| 操作系统 | sz-deploy-v3 优先适配 RockyLinux 10，其他发行版需确认包管理器、防火墙、时区和系统服务差异。 |
| 数据库 | 使用 MySQL 还是 PostgreSQL；后端镜像 tag、DB_TYPE、PAGE_HELPER_DIALECT 和连接配置必须一致。 |
| Redis | 登录态、缓存和 WebSocket Pub/Sub 是否使用同一 Redis；连接配置是否在服务目录中同步。 |
| 资源存储 | LOCAL 资源目录 RESOURCE_DATA_DIR 是否持久化；MinIO/OSS 地址和访问方式是否对外可达。 |
| 配置文件 | config/{profile} 是否完整，敏感配置是否只保存在服务器侧。 |
| 端口 | 9991、9993、9800、80、81、443、数据库和 Redis 端口是否冲突。 |
| 镜像仓库 | 官方镜像还是自有镜像；服务器 .env 中的 registry、namespace、tag 是否与 CI/CD 输出一致。 |
| 升级策略 | 普通 upgrade.sh 是否允许短暂停机；生产是否需要启用蓝绿部署。 |
| 备份回滚 | 数据库、配置目录、资源目录、镜像版本和旧容器是否有可验证的恢复方案。 |
五、数据库与镜像标签
sz-service-admin 会按数据库类型构建不同镜像：
| 数据库 | 常用镜像 tag | 说明 |
|---|---|---|
| MySQL | latest / test-mysql | MySQL 是默认部署路径，历史上 latest 兼容 MySQL。 |
| PostgreSQL | latest-postgresql / test-postgresql | PostgreSQL 需要使用 PostgreSQL profile 构建出的镜像。 |
如果服务器 .env 中设置：
DB_TYPE=postgresql则必须确保对应镜像 tag 是 PostgreSQL 版本，并且 config/{profile}/postgresql.yml、PostgreSQL 用户、密码和网络访问都已准备好。
六、普通部署与蓝绿部署
sz-deploy-v3 支持两种后端升级方式。
| 模式 | 配置 | 特点 |
|---|---|---|
| 普通模式 | USE_BLUE_GREEN_DEPLOY=false | 单实例，执行 upgrade.sh 拉取镜像并重启容器，适合测试或允许短暂停机的场景。 |
| 蓝绿模式 | USE_BLUE_GREEN_DEPLOY=true | 维护 blue/green 两个槽位，通过健康检查和 Nginx upstream 切换流量，适合生产升级。 |
蓝绿模式依赖 sz-service-admin 的 Actuator 健康检查接口：
/api/actuator/health如果健康检查失败，蓝绿部署会保留旧实例并回滚新槽位。常见失败原因是配置文件缺失、数据库连接失败、Liquibase 执行失败、Redis 不可达或 Actuator 未开放。
七、CI/CD 与服务器部署的关系
GitHub Actions 不直接管理生产配置，它只做三件事：
- 构建
sz-service-admin和sz-service-websocket镜像。 - 推送镜像到镜像仓库。
- SSH 到服务器执行
sz-deploy-v3已生成的upgrade.sh或deploy.sh。
所以接入 CI/CD 前，服务器必须先完成 sz-deploy-v3 初始化，并确保 /home/docker-compose 下的服务目录可用。
八、下一步
- 新环境部署：阅读 Docker 快速部署。
- 已有服务器并想自动发布：阅读 GitHub Actions CI/CD。
- 想理解旧版脚本思路：阅读 传统部署。