Docker 快速部署（sz-deploy-v3）

sz-deploy-v3 是当前推荐的服务器侧部署仓库。它负责安装基础环境、创建 Docker 网络、生成服务目录、写入运行 .env、启动 Redis、数据库、MinIO、后端、WebSocket、前端和代理服务。

TIP

Docker Compose 快速部署并没有改变后端服务的运行模型：sz-service-admin 仍然依赖 /config、/data、/logs 三类目录。首次部署前建议先阅读部署总览，理解配置、资源和日志目录为什么需要持久化。

一、适用场景

场景	是否推荐
全新服务器快速安装一套 sz-admin	推荐
希望用 Docker Compose 管理数据库、Redis、后端、前端和代理	推荐
已有自己的运维平台，只想参考 Compose 目录和脚本	可参考
只想理解 jar 如何启动	先看部署总览

sz-deploy-v3 当前脚本优先适配 RockyLinux 10。其他 Linux 发行版需要按实际环境调整包管理器、防火墙、时区和系统服务。

二、部署入口

首次部署只需要下载 init 目录下的两个文件：

GitHubGitee

shell

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

shell

wget https://gitee.com/feiyuchuixue/sz-deploy-v3/raw/main/init/install.sh
wget https://gitee.com/feiyuchuixue/sz-deploy-v3/raw/main/init/.env

确保 install.sh 和 .env 位于同一目录，然后根据实际环境编辑 .env。

shell

bash install.sh

install.sh 会读取 .env，安装必要软件，克隆 sz-deploy-v3 到 SCRIPT_DIR 指定目录，然后执行 sz-base.sh 和 sz-service.sh 完成初始化。

三、核心参数

下面是部署前最常改的参数。

properties

# 脚本克隆目录
SCRIPT_DIR=sz-deploy

# 包管理器：dnf / apt / yum
PKG_MGR=dnf

# 仓库来源：github / gitee / gitlab / gitea
GIT_REPO_PLATFORM=github
GIT_BRANCH=main

# 数据库类型：mysql / postgresql
DB_TYPE=mysql

# 是否启用 sz-service-admin 蓝绿部署
USE_BLUE_GREEN_DEPLOY=false

# Spring Boot 运行环境
SPRING_PROFILES_ACTIVE=prod

# 镜像来源
IMAGE_MODE=registry
IMAGE_REGISTRY=registry.cn-beijing.aliyuncs.com
IMAGE_NAMESPACE=sz-dev
IMAGE_TAG=latest
IMAGE_PULL=true

# LOCAL 资源持久化目录
RESOURCE_DATA_DIR=/home/data/sz-resource

# 数据库备份
BACKUP_ENABLED=true
BACKUP_RETENTION_DAYS=90
MYSQL_BACKUP_ROOT=/home/data/mysql_backups
POSTGRES_BACKUP_ROOT=/home/data/postgres_backups

WARNING

示例 .env 中包含默认数据库密码、MinIO 密码等演示值。生产环境必须修改这些密码，并把 .env、config/{profile} 和资源目录纳入备份策略。

四、服务组成

初始化后，默认会在 /home/docker-compose 下生成服务目录：

text

/home/docker-compose/
├── redis/
├── mysql/ 或 postgres/
├── minio/
├── sz-service-admin/
├── sz-service-websocket/
├── sz-admin/
├── sz-nginx-static/
└── nginx-proxy-manager-zh/

主要服务如下：

服务	作用	默认端口
Redis	缓存、登录态、WebSocket Pub/Sub	`6379`
MySQL	默认关系数据库	`3306`
PostgreSQL	可选关系数据库	`5432`
MinIO	S3 兼容对象存储	`9000` / `9001`
`sz-service-admin`	后台管理 API 服务	`9991`
`sz-service-websocket`	WebSocket 独立服务	`9993`
`sz-admin`	前端静态服务	`9800`
Nginx Proxy Manager	统一代理与证书管理	`80` / `81` / `443`

所有服务默认加入 sz-network 网络。服务之间优先通过容器名互访，不建议在内部配置里写宿主机公网 IP。

五、数据库选择

MySQL

使用 MySQL 时：

properties

DB_TYPE=mysql
MYSQL_DATABASE=sz_admin_prod
MYSQL_CONTAINER=mysql8
MYSQL_USER=root
MYSQL_PASSWORD=ChangeMe_Strong_Password

sz-service-admin 会使用 MySQL 镜像标签：

properties

ADMIN_MYSQL_IMAGE_TAG=latest

PostgreSQL

使用 PostgreSQL 时：

properties

DB_TYPE=postgresql
PG_MODE=internal
PG_CONTAINER_NAME=postgres18
PG_DB_NAME=sz_admin_prod
PG_INTERNAL_USER=sz_admin_prod_user_in
PG_INTERNAL_PASSWORD=ChangeMe_Strong_In_Password

sz-service-admin 会使用 PostgreSQL 镜像标签：

properties

ADMIN_POSTGRESQL_IMAGE_TAG=latest-postgresql

IMPORTANT

数据库类型不仅影响容器编排，也影响后端镜像的 Maven profile。通过 GitHub Actions 自行构建镜像时，请确保 workflow 的 db_type 与服务器 .env 中的 DB_TYPE 一致。

六、镜像模式

1. 使用官方公共镜像

默认配置使用官方镜像仓库：

properties

IMAGE_MODE=registry
IMAGE_REGISTRY=registry.cn-beijing.aliyuncs.com
IMAGE_NAMESPACE=sz-dev
IMAGE_TAG=latest

适合快速体验或直接使用官方版本。

官方 sz-dev 镜像由源码仓 main 分支 CI 自动发布：sz-boot-parent 发布 sz-service-admin:latest、sz-service-admin:latest-postgresql 和 sz-service-websocket:latest，sz-admin 发布 sz-admin:latest。sz-deploy-v3 只负责消费这些镜像，不在部署仓库中重新构建源码。

2. 使用自己的镜像仓库

如果你做了二开，需要让服务器拉取自己的 CI/CD 镜像：

properties

IMAGE_MODE=registry
IMAGE_REGISTRY=registry.cn-beijing.aliyuncs.com
IMAGE_NAMESPACE=sz-action
IMAGE_TAG=latest
ADMIN_MYSQL_IMAGE_TAG=latest
ADMIN_POSTGRESQL_IMAGE_TAG=latest-postgresql

test 环境可改为：

properties

IMAGE_TAG=test
ADMIN_MYSQL_IMAGE_TAG=test-mysql
ADMIN_POSTGRESQL_IMAGE_TAG=test-postgresql

对应的自动化构建流程见 GitHub Actions CI/CD。

3. 本地调试镜像

IMAGE_MODE=local 主要用于 tools 下的本地调试脚本，会关闭默认拉取行为：

properties

IMAGE_MODE=local
IMAGE_TAG=test
IMAGE_PULL=false

生产环境建议使用 registry 模式，确保镜像来源可追溯。

七、普通升级模式

默认 USE_BLUE_GREEN_DEPLOY=false 时，sz-service-admin 以单实例运行：

text

/home/docker-compose/sz-service-admin/
├── .env
├── docker-compose.yml
├── upgrade.sh
├── config/
├── logs/
└── data 挂载到 RESOURCE_DATA_DIR

升级时执行：

shell

cd /home/docker-compose/sz-service-admin
bash upgrade.sh

upgrade.sh 会停止旧容器、按需拉取新镜像、重新启动服务。它适合测试环境、单机体验环境和允许短暂停机的场景。

八、蓝绿部署模式

启用方式：

properties

USE_BLUE_GREEN_DEPLOY=true

蓝绿模式会为 sz-service-admin 维护两个槽位：

text

sz-service-admin-green
sz-service-admin-blue

核心目录：

text

/home/docker-compose/sz-service-admin/
└── blue-green/
    ├── .env
    ├── docker-compose.yml.template
    ├── gen-conf.sh
    ├── docker-compose.gen.yml
    ├── deploy.sh
    ├── nginx/
    └── .deploy_state

每次修改蓝绿 .env 后，先重新生成 Compose 配置：

shell

cd /home/docker-compose/sz-service-admin/blue-green
bash gen-conf.sh

发布新版本：

shell

bash deploy.sh

deploy.sh 会完成：

拉取新镜像。
启动非活跃槽位。
调用健康检查接口，确认新实例可用。
让 Nginx upstream 同时包含新旧实例，等待连接平滑迁移。
upstream 切到新实例。
回收旧实例并更新 .deploy_state。

蓝绿部署依赖 Actuator 健康检查：

text

/api/actuator/health

如果你二次裁剪过后端依赖，请确认 sz-service-admin 仍保留：

xml

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

九、资源目录与 Nginx 静态访问

RESOURCE_DATA_DIR 是 LOCAL 资源持久化目录：

properties

RESOURCE_DATA_DIR=/home/data/sz-resource

sz-service-admin 对该目录读写，sz-nginx-static 或蓝绿模式中的 Nginx 通常只读挂载该目录。这样可以避免重新部署或容器重建时丢失本地上传资源。

如果你的全部资源场景都使用 MinIO/OSS，RESOURCE_DATA_DIR 仍建议保留为空目录，便于后续切换或排查。

十、数据库备份

sz-deploy-v3 支持 MySQL 和 PostgreSQL 备份目录：

properties

BACKUP_ENABLED=true
BACKUP_RETENTION_DAYS=90
MYSQL_BACKUP_ROOT=/home/data/mysql_backups
POSTGRES_BACKUP_ROOT=/home/data/postgres_backups

备份脚本会按数据库类型写入对应目录，并按保留天数清理历史备份。

WARNING

自动备份不能替代生产级灾备。上线前请至少验证一次恢复流程，包括数据库恢复、config/{profile} 恢复、RESOURCE_DATA_DIR 恢复和镜像版本回退。

十一、常用运维命令

查看服务状态：

shell

cd /home/docker-compose/sz-service-admin
docker compose ps

查看后端日志：

shell

docker logs -f sz-service-admin

普通模式升级：

shell

cd /home/docker-compose/sz-service-admin
bash upgrade.sh

蓝绿模式发布：

shell

cd /home/docker-compose/sz-service-admin/blue-green
bash gen-conf.sh
bash deploy.sh

WebSocket 服务升级：

shell

cd /home/docker-compose/sz-service-websocket
bash upgrade.sh

十二、常见问题

1. 修改根目录 `.env` 后服务没有变化

根目录 .env 是初始化入口配置。服务目录通常会生成自己的 .env。初始化完成后，如果只改了入口 .env，需要重新执行对应安装脚本，或手动同步服务目录 .env。

2. 切换 PostgreSQL 后启动失败

检查以下内容：

DB_TYPE=postgresql
PAGE_HELPER_DIALECT=postgresql
PostgreSQL 容器是否已启动。
PG_INTERNAL_USER、PG_INTERNAL_PASSWORD 是否与后端服务目录 .env 一致。
sz-service-admin 镜像 tag 是否为 PostgreSQL 版本，例如 latest-postgresql。

3. 蓝绿部署一直回滚

优先看新槽位容器日志：

shell

docker logs --tail 200 sz-service-admin-green
docker logs --tail 200 sz-service-admin-blue

常见原因包括配置目录缺失、数据库连接失败、Liquibase 执行失败、Actuator 未开放、Redis 不可达。

4. CI/CD 推送了镜像但服务器没有拉到

检查服务器 .env 中的：

properties

IMAGE_REGISTRY=
IMAGE_NAMESPACE=
IMAGE_TAG=
ADMIN_MYSQL_IMAGE_TAG=
ADMIN_POSTGRESQL_IMAGE_TAG=
IMAGE_PULL=true

这些值必须与 GitHub Actions 推送的镜像地址和 tag 对齐。

Docker 快速部署（sz-deploy-v3） ​

一、适用场景 ​

二、部署入口 ​

三、核心参数 ​

四、服务组成 ​

五、数据库选择 ​

MySQL ​

PostgreSQL ​

六、镜像模式 ​

1. 使用官方公共镜像 ​

2. 使用自己的镜像仓库 ​

3. 本地调试镜像 ​

七、普通升级模式 ​

八、蓝绿部署模式 ​

九、资源目录与 Nginx 静态访问 ​

十、数据库备份 ​

十一、常用运维命令 ​

十二、常见问题 ​

1. 修改根目录 .env 后服务没有变化 ​

2. 切换 PostgreSQL 后启动失败 ​

3. 蓝绿部署一直回滚 ​

4. CI/CD 推送了镜像但服务器没有拉到 ​

十三、相关文档 ​

Docker 快速部署（sz-deploy-v3）

一、适用场景

二、部署入口

三、核心参数

四、服务组成

五、数据库选择

MySQL

PostgreSQL

六、镜像模式

1. 使用官方公共镜像

2. 使用自己的镜像仓库

3. 本地调试镜像

七、普通升级模式

八、蓝绿部署模式

九、资源目录与 Nginx 静态访问

十、数据库备份

十一、常用运维命令

十二、常见问题

1. 修改根目录 `.env` 后服务没有变化

2. 切换 PostgreSQL 后启动失败

3. 蓝绿部署一直回滚

4. CI/CD 推送了镜像但服务器没有拉到

十三、相关文档