207 lines
5.7 KiB
Markdown
207 lines
5.7 KiB
Markdown
# GitHub Actions CI/CD 工作流配置说明
|
||
|
||
## 概述
|
||
|
||
本工作流实现了自动化的 Docker 镜像构建和部署流程：
|
||
|
||
1. **构建阶段**：当代码推送到指定分支时，自动构建 Docker 镜像
|
||
2. **推送阶段**：将构建好的镜像推送到阿里云容器镜像服务（ACR）
|
||
3. **部署阶段**：通过 SSH 连接到远程服务器，拉取最新镜像并重建容器
|
||
|
||
## 工作流触发条件
|
||
|
||
- 推送到 `main`、`master` 或 `develop` 分支
|
||
- 仅当 `api/` 目录或 `.github/workflows/` 目录有变更时触发
|
||
- 支持手动触发（workflow_dispatch）
|
||
|
||
## 配置步骤
|
||
|
||
### 1. 配置 GitHub Secrets
|
||
|
||
在 GitHub 仓库设置中添加以下 Secrets：
|
||
|
||
#### 必需配置
|
||
|
||
- **SSH_PRIVATE_KEY**: SSH 私钥，用于连接到远程服务器
|
||
```bash
|
||
# 生成 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 登录
|
||
|
||
确保远程服务器可以拉取私有镜像，需要在远程服务器上执行：
|
||
|
||
```bash
|
||
docker login crpi-u2903xccyzd6nqnc.cn-shanghai.personal.cr.aliyuncs.com \
|
||
--username=zaikunxu \
|
||
--password=57ucV,g4LF2cqm8
|
||
```
|
||
|
||
或者将登录信息添加到工作流的部署步骤中（已自动配置）。
|
||
|
||
### 3. 远程服务器准备
|
||
|
||
确保远程服务器已安装：
|
||
|
||
- Docker
|
||
- Docker Compose
|
||
|
||
```bash
|
||
# 安装 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. 首次部署准备
|
||
|
||
在远程服务器上创建部署目录：
|
||
|
||
```bash
|
||
mkdir -p /opt/life-echo/api
|
||
```
|
||
|
||
确保 SSH 用户可以访问该目录并执行 Docker 命令。
|
||
|
||
## 工作流执行流程
|
||
|
||
### 构建阶段（build-and-push）
|
||
|
||
1. 检出代码
|
||
2. 设置 Docker Buildx
|
||
3. 登录到容器镜像仓库
|
||
4. 提取元数据（标签、标签）
|
||
5. 构建并推送 Docker 镜像
|
||
|
||
### 部署阶段（deploy）
|
||
|
||
1. 设置 SSH 连接
|
||
2. 登录到容器镜像仓库（在远程服务器上）
|
||
3. 拉取最新镜像
|
||
4. 停止现有容器
|
||
5. 更新 docker-compose.yml 中的镜像标签
|
||
6. 启动新容器
|
||
7. 清理旧镜像
|
||
8. 验证部署状态
|
||
|
||
## 镜像标签规则
|
||
|
||
- `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 界面手动触发工作流：
|
||
|
||
1. 进入仓库的 Actions 标签页
|
||
2. 选择 "Docker Build and Deploy" 工作流
|
||
3. 点击 "Run workflow" 按钮
|
||
|
||
## 自定义配置
|
||
|
||
### 修改触发分支
|
||
|
||
编辑 `.github/workflows/docker-build-deploy.yml`：
|
||
|
||
```yaml
|
||
on:
|
||
push:
|
||
branches:
|
||
- your-branch-name
|
||
```
|
||
|
||
### 修改镜像名称
|
||
|
||
编辑工作流文件中的 `IMAGE_NAME` 和 `REGISTRY_NAMESPACE` 环境变量：
|
||
|
||
```yaml
|
||
env:
|
||
IMAGE_NAME: your-image-name
|
||
REGISTRY_NAMESPACE: your-namespace
|
||
```
|
||
|
||
### 修改部署路径
|
||
|
||
在 GitHub Secrets 中设置 `DEPLOY_PATH`，或直接修改工作流文件中的默认值。
|
||
|
||
## 注意事项
|
||
|
||
1. **安全性**：确保 SSH 私钥和密码等敏感信息只存储在 GitHub Secrets 中，不要提交到代码仓库
|
||
2. **权限**：确保 SSH 用户在远程服务器上有执行 Docker 命令的权限
|
||
3. **备份**：部署前会自动备份 docker-compose.yml 文件（`.bak` 后缀）
|
||
4. **回滚**：如果部署失败，可以使用备份文件恢复
|
||
|
||
## 相关文件
|
||
|
||
- 工作流文件：`.github/workflows/docker-build-deploy.yml`
|
||
- Dockerfile：`api/Dockerfile`
|
||
- Docker Compose：`api/docker-compose.yml`
|