Files

iammm0 084075dcdb ci: 新增GitHub Actions CI/CD配置

- 新增.github/工作流配置

2026-01-26 11:54:20 +08:00

5.7 KiB

Raw Blame History

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 后缀）
回滚：如果部署失败，可以使用备份文件恢复

5.7 KiB Raw Blame History Unescape Escape