common-workflows/README.md

# Common Workflows 模板说明

本目录用于存放通用的 Gitea/GitHub Actions 工作流模板，方便在不同项目之间复制复用。

## 一、可直接复制使用的模板

- **构建镜像工作流模板**：`build-images.yml`  
  - 作用：用于在 `<自定义分支>` 分支上构建 Docker 镜像。  
  - 触发条件：  
    - 推送到 `<自定义分支>` 分支，并且改动包含 `Dockerfile*`、`requirements.txt` 或 `.gitea/workflows/build-images.yml`  
    - 手动触发 (`workflow_dispatch`)  
  - 使用方式：  
    1. 复制该文件到目标项目的 `.gitea/workflows/build-images.yml`（或对应 CI 目录）。  
    2. 根据项目实际情况修改其中的 `<image_name>`、`<version>` 以及 `Dockerfile` 路径等参数。  

- **Docker 部署工作流模板**：`deploy-docker.yml`  
  - 作用：在 `<自定义分支>` 分支上，通过 `docker compose` 部署服务。  
  - 触发条件：  
    - 推送到 `<自定义分支>` 分支  
    - 手动触发 (`workflow_dispatch`)  
  - 使用方式：  
    1. 复制该文件到目标项目的 `.gitea/workflows/deploy-docker.yml`（或对应 CI 目录）。  
    2. 确认项目根目录存在 `docker-compose.yml`，并根据需要调整步骤中的命令。  

- **API 健康检查工作流模板**：`e2e-tests.yml`  
  - 作用：对后端各 API 服务的 `/health` 接口进行健康检查，可支持**多个 IP / 域名**（多个环境）。不再检查前端页面。  
  - 触发条件：  
    - 推送到 `<自定义分支>`（或你自定义的）分支  
    - 手动触发 (`workflow_dispatch`)  
  - 使用方式：  
    1. 复制该文件到目标项目的 `.gitea/workflows/e2e-tests.yml`（或对应 CI 目录）。  
    2. 根据实际环境修改 `jobs.e2e.strategy.matrix.target` 中的配置即可复用，例如：  
       ```yaml
       strategy:
         fail-fast: false
         matrix:
           target:
             - name: env-local
               base_url: http://127.0.0.1
             - name: env-remote
               base_url: http://10.0.0.1
       ```  
    3. 如果你的服务端口与模板中的默认值不同，可在 `services` 变量里调整 `name:port` 列表，例如：`auth:5710`、`project:5711` 等。  
    4. 如需调整重试次数、间隔时间或检查路径，可在对应 `curl` 循环处按需修改脚本逻辑。  


## 二、通用复用 Actions 说明（`common-workflows/actions`）

本目录下包含了一组可在各个仓库中复用的 **Gitea / GitHub composite actions**，统一托管在：

- `https://git.aiot.ml/Obscura/common-workflows`

在具体仓库的 workflow 中，通过 `uses` 引用，例如：

```yaml
uses: https://git.aiot.ml/Obscura/common-workflows/actions/<action-name>@main
```

目前提供的通用 action 如下：

- **build-images**：构建并验证 Docker 镜像  
- **deploy-docker**：使用 `docker compose` 部署服务  
- **api-test**：对一组后端 API 的 `/health` 做健康检查  
- **frontend-test**：对一组前端入口 URL 做可访问性检查  

下面分别说明用法。

---

## `build-images` — Docker 镜像构建

**路径**：`actions/build-images/action.yml`  
**作用**：在 Runner 上本地执行 `docker build`，并对生成的镜像做简单校验与清理悬空镜像。

**引用示例**（节选自 `broccoli-offline`）：

```yaml
- name: Build Docker image
  uses: https://git.aiot.ml/Obscura/common-workflows/actions/build-images@main
  with:
    dockerfile: 'Dockerfile.api'
    context: '.'
    image_name: 'broccoli-api'
    image_tag: 'v3.2.2'
    enable_cache: 'true'
    # build_args: |
    #   HTTP_PROXY=http://...
    #   HTTPS_PROXY=http://...
```

**输入参数**：

- **`dockerfile`**（必填）：Dockerfile 路径，相对于仓库根目录，例如 `Dockerfile`, `Dockerfile.api`。
- **`context`**（可选，默认 `.`）：构建上下文目录，相对于仓库根目录。
- **`image_name`**（必填）：镜像名称，不含 tag，例如 `broccoli-api`。
- **`image_tag`**（必填）：镜像 tag / 版本，例如 `v1.0.0`、`latest`。
- **`enable_cache`**（可选，默认 `'true'`）：是否启用构建缓存（当前主要依赖 Runner 本地 docker layer cache）。
- **`build_args`**（可选）：Docker build 参数，每行一个，格式 `KEY=VALUE`，会被拼接为 `--build-arg KEY=VALUE`。

**依赖环境**：

- Runner 上需要已安装 `docker`，并有构建镜像的权限。

---

## `deploy-docker` — Docker Compose 部署

**路径**：`actions/deploy-docker/action.yml`  
**作用**：在已经 checkout 好代码的前提下，使用 `docker compose` 停止旧服务并重新部署，最后校验服务状态。

**典型用法**（示例）：

```yaml
- name: Checkout code
  uses: https://git.aiot.ml/Obscura/checkout@v4
  with:
    ref: offline
    sparse-checkout: |
      .gitea/workflows/deploy-docker.yml
      config/
      docker-compose-offline.yml      
    sparse-checkout-cone-mode: false

- name: Deploy with reusable action
  uses: https://git.aiot.ml/Obscura/common-workflows/actions/deploy-docker@main
  with:
    compose_file: 'docker-compose-offline.yml'
    # compose_dir: 'config'         # 可选：指定工作目录
    # startup_wait: '30'           # 可选：启动后等待 30s 再校验
```

**输入参数**：

- **`compose_file`**（必填）：`docker-compose` 文件路径，相对于当前工作目录或 `compose_dir`。
- **`compose_dir`**（可选，默认使用 `compose_file` 所在目录）：执行 `docker compose` 时的工作目录。
- **`startup_wait`**（可选，默认 `0`）：`up -d` 后额外等待的秒数，用于等待服务完成初始化。

**行为**：

1. 计算 `compose_file` 与工作目录。
2. 执行 `docker compose -f <file> down` 停止旧服务（失败不终止）。
3. 执行 `docker compose -f <file> up -d` 启动服务。
4. 可选地等待 `startup_wait` 秒。
5. 执行 `docker compose ps` 并检查是否有 `exited` 状态的服务，若有则输出日志并失败。

**依赖环境**：

- Runner 上需要安装 `docker` 与 `docker compose`，并安装 `jq`（用于解析 `docker compose ps --format json`）。

---

## `api-test` — API `/health` 健康检查（完整 URL）

**路径**：`actions/api-test/action.yml`  
**作用**：对一组后端服务的 `/health` 接口做健康检查。  
**约定**：输入的是 **不包含 `/health` 的完整 URL**，action 内部会自动拼接 `/health`。

**示例**（节选自 `broccoli-offline/.gitea/workflows/e2e-tests.yml`）：

```yaml
- name: Run offline API health tests
  uses: https://git.aiot.ml/Obscura/common-workflows/actions/api-test@main
  with:
    urls: |
      http://127.0.0.1:5710
      http://127.0.0.1:5711
      http://127.0.0.1:5712      

```

**输入参数**：

- **`urls`**（必填）：多行字符串，每行一个完整 URL（不含 `/health`），例如：
  - `http://127.0.0.1:5800`
  - `https://service-name`

**行为**：

- 对每一行 URL：
  - 去掉末尾 `/`，拼接 `/health`；
  - 最多重试 10 次 `curl -fsS <url>/health`，每次失败后等待 5 秒；
  - 若所有重试均失败，则记录到失败列表。
- 如果任意服务失败，整个步骤 `exit 1`。

**依赖环境**：

- Runner 上需要安装 `curl`。

---

## `frontend-test` — 前端入口可访问性检查（完整 URL）

**路径**：`actions/frontend-test/action.yml`  
**作用**：对一组前端入口 URL 做可访问性检查（通常是首页）。

**示例**（节选自 `broccoli-offline/.gitea/workflows/e2e-tests.yml`）：

```yaml
- name: Run offline frontend availability tests
  uses: https://git.aiot.ml/Obscura/common-workflows/actions/frontend-test@main
  with:
    urls: |
      http://127.0.0.1:5373      
```

**输入参数**：

- **`urls`**（必填）：多行字符串，每行一个完整 URL，例如：
  - `http://127.0.0.1:3000`
  - `https://frontend-service`

**行为**：

- 对每一行 URL：
  - 最多重试 10 次 `curl -fsS <url>`，每次失败后等待 5 秒；
  - 任意一次成功则认为该前端通过，否则记录失败。
- 如果有任意 URL 访问失败，整个步骤 `exit 1`。

**依赖环境**：

- Runner 上需要安装 `curl`。