# 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`