GitHub Actions CI/CD 工作流配置说明
概述
本工作流实现了自动化的 Docker 镜像构建和部署流程：
- 构建阶段：当代码推送到指定分支时，自动构建 Docker 镜像
- 推送阶段：将构建好的镜像推送到阿里云容器镜像服务（ACR）
- 部署阶段：通过 SSH 连接到远程服务器，拉取最新镜像并重建容器
工作流触发条件
- 推送到
main、master或develop分支 - 仅当
api/目录或.github/workflows/目录有变更时触发 - 支持手动触发（workflow_dispatch）
配置步骤
1. 配置 GitHub Secrets
在 GitHub 仓库设置中添加以下 Secrets：
必需配置
-
SSH_PRIVATE_KEY: SSH 私钥，用于连接到远程服务器
# 生成 SSH 密钥对（如果还没有） ssh-keygen -t ed25519 -C "github-actions" # 将私钥添加到 GitHub Secrets cat ~/.ssh/id_ed25519 # 复制内容到 SSH_PRIVATE_KEY # 将公钥添加到远程服务器的 ~/.ssh/authorized_keys cat ~/.ssh/id_ed25519.pub | ssh user@your-server "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys" -
SSH_USER: SSH 用户名（例如：
root、ubuntu、deploy） -
SSH_HOST: 远程服务器 IP 地址或域名（例如：
192.168.1.100、example.com）
阿里云容器镜像服务配置（必需）
- ALIYUN_CR_USERNAME: 阿里云容器镜像服务用户名（例如：
zaikunxu） - ALIYUN_CR_PASSWORD: 阿里云容器镜像服务密码
可选配置
- SSH_PORT: SSH 端口（默认：
22） - DEPLOY_PATH: 远程服务器上的部署目录（默认：
/opt/life-echo）
2. 容器镜像仓库配置
本工作流使用**阿里云容器镜像服务（ACR）**作为镜像仓库。
镜像地址
- 镜像仓库地址：
crpi-u2903xccyzd6nqnc.cn-shanghai.personal.cr.aliyuncs.com - 命名空间：
huaga - 镜像名称：
lifecho-api - 完整镜像路径：
crpi-u2903xccyzd6nqnc.cn-shanghai.personal.cr.aliyuncs.com/huaga/lifecho-api:latest
配置说明
工作流已配置为使用阿里云容器镜像服务，无需修改工作流文件。只需在 GitHub Secrets 中配置：
ALIYUN_CR_USERNAME: 阿里云容器镜像服务用户名ALIYUN_CR_PASSWORD: 阿里云容器镜像服务密码
在远程服务器上配置 Docker 登录
确保远程服务器可以拉取私有镜像，需要在远程服务器上执行：
docker login crpi-u2903xccyzd6nqnc.cn-shanghai.personal.cr.aliyuncs.com \
--username=zaikunxu \
--password=57ucV,g4LF2cqm8
或者将登录信息添加到工作流的部署步骤中（已自动配置）。
3. 远程服务器准备
确保远程服务器已安装：
- Docker
- Docker Compose
# 安装 Docker（Ubuntu/Debian）
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# 安装 Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
4. 首次部署准备
在远程服务器上创建部署目录：
mkdir -p /opt/life-echo/api
确保 SSH 用户可以访问该目录并执行 Docker 命令。
工作流执行流程
构建阶段（build-and-push）
- 检出代码
- 设置 Docker Buildx
- 登录到容器镜像仓库
- 提取元数据（标签、标签）
- 构建并推送 Docker 镜像
部署阶段（deploy）
- 设置 SSH 连接
- 登录到容器镜像仓库（在远程服务器上）
- 拉取最新镜像
- 停止现有容器
- 更新 docker-compose.yml 中的镜像标签
- 启动新容器
- 清理旧镜像
- 验证部署状态
镜像标签规则
main/master分支 →latest- 其他分支 → 使用分支名作为标签
- 同时会生成基于 commit SHA 的标签
故障排查
1. SSH 连接失败
- 检查
SSH_PRIVATE_KEY是否正确配置 - 确认远程服务器的 SSH 服务正在运行
- 验证 SSH 公钥已添加到远程服务器的
~/.ssh/authorized_keys
2. Docker 登录失败
- 检查
ALIYUN_CR_USERNAME和ALIYUN_CR_PASSWORD是否正确配置 - 确认阿里云容器镜像服务的账号密码是否正确
- 检查远程服务器是否可以访问阿里云容器镜像服务
3. 镜像拉取失败
- 确认远程服务器可以访问容器镜像仓库
- 检查镜像标签是否正确
- 验证网络连接
4. 容器启动失败
- 检查 docker-compose.yml 文件是否正确
- 查看容器日志：
docker-compose logs - 确认环境变量配置正确
手动触发
可以通过 GitHub Actions 界面手动触发工作流：
- 进入仓库的 Actions 标签页
- 选择 "Docker Build and Deploy" 工作流
- 点击 "Run workflow" 按钮
自定义配置
修改触发分支
编辑 .github/workflows/docker-build-deploy.yml：
on:
push:
branches:
- your-branch-name
修改镜像名称
编辑工作流文件中的 IMAGE_NAME 和 REGISTRY_NAMESPACE 环境变量：
env:
IMAGE_NAME: your-image-name
REGISTRY_NAMESPACE: your-namespace
修改部署路径
在 GitHub Secrets 中设置 DEPLOY_PATH，或直接修改工作流文件中的默认值。
注意事项
- 安全性：确保 SSH 私钥和密码等敏感信息只存储在 GitHub Secrets 中，不要提交到代码仓库
- 权限：确保 SSH 用户在远程服务器上有执行 Docker 命令的权限
- 备份：部署前会自动备份 docker-compose.yml 文件（
.bak后缀） - 回滚：如果部署失败，可以使用备份文件恢复
相关文件
- 工作流文件：
.github/workflows/docker-build-deploy.yml - Dockerfile：
api/Dockerfile - Docker Compose：
api/docker-compose.yml