GitHub Actions CI/CD

GitHub Actions CI/CD 只负责把代码变成镜像，并在镜像推送成功后通知服务器执行部署脚本。服务器上的运行目录、配置文件、数据库、Redis、资源目录和反向代理仍由 Docker 快速部署 中的 sz-deploy-v3 负责准备。

TIP

首次接入 CI/CD 前，请先在目标服务器完成一次 sz-deploy-v3 初始化。初始化完成后，服务器上应存在 /home/docker-compose/sz-service-admin、/home/docker-compose/sz-service-websocket 等目录，并且服务目录内有 .env、docker-compose.yml、upgrade.sh，蓝绿模式还需要 deploy.sh、gen-conf.sh 和 docker-compose.gen.yml。

一、当前工作流定位

sz-boot-parent 当前提供两个后端服务镜像工作流：

工作流	触发分支	镜像版本	远程部署目标
Docker Sz Services CI.yml	preview	latest / latest-postgresql	REMOTE_HOST
Docker Sz Services Test CI.yml	test	test-mysql / test-postgresql	REMOTE_HOST_TEST

两个工作流都会使用矩阵构建：

服务	模块目录	镜像用途
sz-service-admin	sz-service/sz-service-admin	后台管理 API 服务
sz-service-websocket	sz-service/sz-service-websocket	WebSocket 独立服务

构建逻辑由 .github/scripts/build-sz-service-image.sh 统一处理：先执行 Maven 模块级打包，再使用仓库根目录的 Dockerfile 基于目标模块 target 目录构建镜像。

二、发布链路

完整链路如下：

1. 推送代码到 preview 或 test 分支，或者在 Actions 页面手动触发工作流。
2. GitHub Runner 安装 JDK 21、Maven 3.9.6，并启用 Maven 缓存。
3. 工作流按矩阵分别构建 sz-service-admin 和 sz-service-websocket 镜像。
4. PR 触发时只构建镜像，不登录镜像仓库，也不推送和部署。
5. 非 PR 触发时，工作流登录镜像仓库并推送镜像。
6. 镜像推送成功后，通过 SSH 进入服务器。
7. 服务器进入 /home/docker-compose/sz-service-admin：
   • 如果当前目录是蓝绿模式，则执行 gen-conf.sh 和 deploy.sh。
   • 如果是普通模式，则执行 upgrade.sh。
8. 服务器进入 /home/docker-compose/sz-service-websocket，执行 upgrade.sh。

CI/CD 不会替你生成生产配置，也不会把数据库密码、Redis 密码、Sa-Token 配置写入 workflow。敏感配置必须保存在服务器部署目录的 .env 和 config/{profile} 中。

三、Secrets 与 Variables

1. 镜像仓库凭据

名称	类型	说明
ACR_USERNAME	Secret	容器镜像仓库用户名
ACR_PASSWORD	Secret	容器镜像仓库密码或访问令牌

默认 workflow 使用：

ACR_DOMAIN: registry.cn-beijing.aliyuncs.com
ACR_ZONE: sz-action

如果你使用自己的镜像仓库，需要同步修改 workflow 的 ACR_DOMAIN、ACR_ZONE，并确保服务器 sz-deploy-v3 的 .env 中 IMAGE_REGISTRY、IMAGE_NAMESPACE、镜像 tag 与 workflow 输出一致。

2. preview 环境 SSH 凭据

名称	类型	说明
REMOTE_HOST	Secret	preview 服务器 IP 或域名
REMOTE_USER	Secret	SSH 用户
REMOTE_PASSWORD	Secret	SSH 密码
SZ_DB_TYPE	Variable	可选，默认构建数据库类型，支持 mysql / postgresql

3. test 环境 SSH 凭据

名称	类型	说明
REMOTE_HOST_TEST	Secret	test 服务器 IP 或域名
REMOTE_USER_TEST	Secret	test SSH 用户
REMOTE_PASSWORD_TEST	Secret	test SSH 密码
SZ_TEST_DB_TYPE	Variable	可选，test 环境数据库类型
SZ_DB_TYPE	Variable	可选，通用数据库类型兜底值

test 工作流手动触发时还提供 deploy 开关。设置为 false 时只构建并推送镜像，不远程部署。

四、数据库类型与镜像标签

sz-service-admin 按数据库类型选择 Maven profile 和镜像标签。

工作流	DB_TYPE=mysql	DB_TYPE=postgresql
preview	Maven profile mysql，镜像 tag latest	Maven profile postgresql，镜像 tag latest-postgresql
test	Maven profile mysql，镜像 tag test-mysql	Maven profile postgresql，镜像 tag test-postgresql

sz-service-websocket 不区分数据库类型，使用工作流的基础版本标签，例如 latest 或 test。

服务器侧必须与镜像标签保持一致。例如 preview + PostgreSQL 时，sz-deploy-v3 的 .env 应至少确认：

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

test + MySQL 时通常对应：

DB_TYPE=mysql
IMAGE_REGISTRY=registry.cn-beijing.aliyuncs.com
IMAGE_NAMESPACE=sz-action
IMAGE_TAG=test
ADMIN_MYSQL_IMAGE_TAG=test-mysql

五、服务器目录要求

CI/CD 远程部署默认进入以下目录：

/home/docker-compose/
├── sz-service-admin/
│   ├── .env
│   ├── docker-compose.yml
│   ├── upgrade.sh
│   ├── config/
│   ├── logs/
│   └── blue-green/ 或 deploy.sh/gen-conf.sh 相关文件
└── sz-service-websocket/
    ├── .env
    ├── docker-compose.yml
    ├── upgrade.sh
    ├── config/
    └── logs/

普通模式下，upgrade.sh 会执行：

docker compose down
docker compose pull
docker compose up -d

蓝绿模式下，deploy.sh 会先启动非活跃槽位，等待健康检查通过，再通过 Nginx upstream 切换流量，最后回收旧实例。蓝绿模式依赖 sz-service-admin 的 Actuator 健康检查，默认路径为：

/api/actuator/health

六、接入步骤

1. 先完成服务器初始化

在服务器上按 Docker 快速部署 执行初始化：

bash install.sh

初始化完成后，确认服务目录存在：

ls -la /home/docker-compose/sz-service-admin
ls -la /home/docker-compose/sz-service-websocket

2. 调整服务器镜像来源

如果你要使用 CI/CD 构建出的私有镜像，请在服务器部署根目录的 .env 或服务目录 .env 中设置镜像仓库信息：

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
IMAGE_PULL=true

如果是 test 环境，请把 IMAGE_TAG 和 ADMIN_*_IMAGE_TAG 调整为 test 工作流对应的 tag。

3. 配置 GitHub Secrets

在 GitHub 仓库的 Settings -> Secrets and variables -> Actions 中添加镜像仓库和远程服务器凭据。

不要把生产数据库密码、Redis 密码、OSS 密钥、Sa-Token 配置写入 GitHub workflow。它们应保存在服务器的 config/{profile} 或 .env 中。

4. 手动触发一次验证

在 Actions 页面手动运行对应 workflow：

• preview 环境：选择 Docker Sz Services CI。
• test 环境：选择 Docker Sz Services Test CI。

手动触发时可以选择 db_type。如果不手动选择，workflow 会读取 GitHub Variables，最后兜底为 mysql。

七、常见问题

1. Actions 构建成功，但服务器没有更新

优先检查：

• 当前触发是否来自 PR。PR 只构建，不推送、不部署。
• 服务器目录是否存在 /home/docker-compose/sz-service-admin。
• upgrade.sh 或 deploy.sh 是否有执行权限。
• 服务器 .env 中镜像仓库、命名空间和 tag 是否与 workflow 推送一致。
• 服务器是否能访问镜像仓库并完成 docker compose pull。

2. PostgreSQL 镜像推送成功，但容器仍拉取 MySQL 镜像

检查服务器 .env：

DB_TYPE=postgresql
ADMIN_POSTGRESQL_IMAGE_TAG=latest-postgresql

同时确认 sz-service-admin/.env 是否由 sz-deploy-v3 重新生成。如果修改的是根目录 .env，需要重新执行对应服务安装脚本或手动同步服务目录 .env。

3. 蓝绿部署卡在健康检查

优先检查：

• sz-service-admin 是否保留 spring-boot-starter-actuator。
• management.endpoints.web.exposure.include 是否包含 health。
• Nginx 容器是否能访问 http://<slot-container>:9991/api/actuator/health。
• config/{profile} 中数据库、Redis、Sa-Token 配置是否完整。
• 容器日志中是否存在 Liquibase、数据库连接或端口冲突错误。

4. 是否还需要旧的 docker run 启动脚本

不建议继续使用旧的单容器 docker run workflow 作为主部署方式。当前推荐链路是：

GitHub Actions 构建并推送镜像
        ↓
服务器 sz-deploy-v3 目录拉取镜像
        ↓
普通模式 upgrade.sh 或蓝绿模式 deploy.sh 完成发布

这样可以让手动部署、快速部署和 CI/CD 共用同一套服务器目录、配置和升级逻辑。

八、相关文档

• 部署总览
• Docker 快速部署
• 传统部署