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 中的配置即可复用，例如：

       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 引用，例如：

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）：

- 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 停止旧服务并重新部署，最后校验服务状态。

典型用法（示例）：

- 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）：

- 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）：

- 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。