zt-closet-backend/.codebuddy/plans/cicd补充分级钉钉通知_68dac9d1.md

name, overview, todos

name	overview	todos
cicd补充分级钉钉通知	在 3 个 Gitea Actions 工作流中补充分级钉钉通知（成功/失败/危险操作警告），webhook 走 Secret，采用 markdown 富文本样式。	id content status notify-deploy-and-mysqlup 为 deploy.yaml 与 mysqlup.yaml 新增开始计时步骤及成功/失败钉钉通知步骤 completed id content status notify-mysqldown 为 mysqldown.yaml 新增开始计时、危险操作警告（执行前）及成功/失败钉钉通知步骤 completed id content status dependencies verify-workflows 校验三个工作流 YAML 合法、缩进正确、无明文 webhook、变量与条件引用无误 completed notify-deploy-and-mysqlup notify-mysqldown

产品概述

为仓库现有的 3 条 Gitea Actions 流水线（构建部署、数据库迁移升级、数据库迁移回滚）补齐钉钉机器人通知能力。通知按事件级别分级呈现，采用钉钉 markdown 富文本卡片样式，让团队在钉钉群里一眼看清「哪条流水线、什么结果、涉及哪个版本/提交、耗时多久、从哪看日志」。

核心功能

• 分级通知（3 级）：成功、失败、危险操作警告。成功与失败在流水线结束时发送；危险操作警告在「数据库回滚」实际执行前发送，结束后再补一条结果通知。
• 覆盖范围：全部 3 条流水线——部署、迁移升级、迁移回滚；失败通知不做任何 @（不 @所有人、不 @指定人）。
• 富文本样式：使用钉钉 markdown 消息，含三级标题、引用块、加粗、无序列表与可点击链接；不同级别使用不同图标与标题文案，视觉上可快速区分。
• 信息摘要：每条通知包含仓库、分支或标签、提交短哈希、触发者、镜像版本、耗时、发生时间，并附「查看运行详情/失败日志」链接；失败通知额外给出定位指引。
• 安全存放：webhook 地址（含 access_token）以 Gitea 仓库 Secret 形式引用，不出现在流水线文件中，也不打印到日志。
• 不干扰主流程：通知发送失败不会导致流水线失败。

技术选型

• 流水线引擎：Gitea Actions（GitHub Actions 兼容语法），工作流文件为 YAML。
• 通知通道：钉钉自定义机器人 webhook，msgtype: markdown（原生支持标题、引用、加粗、列表、链接，是当前钉钉机器人中样式表达力最好的纯文本消息类型；text 无样式，actionCard 无法体现级别差异）。
• 发送方式：curl 直连 webhook，纯 shell 构造 JSON。不引入任何外部 action——与「checkout 已替换为 Gitee 镜像、避免依赖 GitHub action」的既定方向保持一致，避免新增拉取依赖。
• 无新增语言/框架/依赖：仅使用 runner 自带的 bash、curl、date、cut。

实现方式

在 3 个工作流中新增「通知类」步骤，不动任何既有业务步骤（docker 构建/推送、SSH 部署、迁移执行）及其语义。

分级触发条件

级别	触发条件	位置
成功	if: success()	作业最后（结果步骤之后）
失败	if: failure()	作业最后（结果步骤之后）
危险警告	if: success()	仅 mysqldown：置于「校验确认词」通过之后、拉取代码之前

耗时统计：在每条作业的第一步新增「记录开始时间」，把 epoch 秒写入 $GITHUB_ENV 的 JOB_START；通知步骤用 date +%s 求差并格式化为「X 分 Y 秒」。该步骤位于拉取代码之前，可保证即便后续 checkout 失败也能正确计时。

关键决策与理由

1. 内联步骤而非本地 composite action：本地 action 需要仓库先 checkout 成功才能加载，而本仓库恰好存在 checkout 拉取的现实风险（用户刚做过 checkout 替换），一旦 checkout 失败则失败通知自身也无法发送。内联步骤只依赖 runner 与工作流文件，可在 checkout 失败时照常发出失败通知，可靠性更高。代价是 3 个文件存在少量重复，可接受。
2. 纯 shell 构造 JSON，不依赖 jq：Gitea act runner 镜像中 jq 不保证存在；改为 bash 变量拼接 + 字面量 \n 转义，再以 heredoc 写入临时文件用 curl -d @file 发送。正文刻意不使用双引号、反引号与 `，从根本上规避 JSON 破坏与 shell 命令替换。
3. Secret 而非变量：access_token 属凭据，走 secrets；通知步骤禁用 set -x，且不 echo webhook，避免凭据进入构建日志。
4. continue-on-error: true：通知是旁路能力，任何发送异常都不得影响部署/迁移结果。

实现注意

• 前置人工操作：需在 Gitea 仓库 Settings → Actions → Secrets 中新建 Secret DINGTALK_WEBHOOK，值为完整 webhook URL（含 access_token=）。若未创建，通知步骤会因空 URL 而失败，但被 continue-on-error 吞掉，不影响流水线。
• 钉钉机器人安全设置需匹配：本方案按「自定义关键词」或「IP 白名单」模式发送；若机器人配置的是「加签」模式，需在 URL 后追加 &timestamp=...&sign=...，当前未实现该签名逻辑（需另行补充）。消息正文已包含 zt-closet-backend 等关键词，可满足常见关键词配置。
• 表达式兼容性：优先使用既有文件已证实的 gitea.* 上下文（gitea.repository/ref/sha/actor/run_id/server_url）。其中 gitea.server_url 若在该 Gitea 版本不可用，回退为仓库已知主机 https://git.lzcwy.cn（与 env.REGISTRY 一致）。
• 不影响既有行为：deploy.yaml 的「部署结果」步骤（if: always()）保留；mysqldown.yaml 的确认词校验逻辑与失败退出保持不变。
• 限流：钉钉机器人限 20 条/分钟；本方案单次运行最多 3 条，无风险。
• 日志：仅打印钉钉返回体中的 errcode/errmsg 便于排障，绝不输出 URL。

架构设计

通知能力作为「旁路观测层」附加在各作业末尾，与业务步骤零耦合：

flowchart LR
    A["记录开始时间<br/>写入 JOB_START"] --> B["拉取代码 / 业务步骤"]
    B --> C{"作业结果"}
    C -- success --> D["钉钉通知（成功）<br/>if: success()"]
    C -- failure --> E["钉钉通知（失败）<br/>if: failure()"]
    D --> F["钉钉 markdown 机器人"]
    E --> F
    G["危险操作警告<br/>仅 mysqldown，执行前"] --> F

目录结构

zt-closet-backend/
└── .gitea/
    └── workflows/
        ├── deploy.yaml      # [MODIFY] 新增「记录开始时间」+「钉钉通知（成功）」「钉钉通知（失败）」三步
        ├── mysqlup.yaml     # [MODIFY] 新增「记录开始时间」+「钉钉通知（成功）」「钉钉通知（失败）」三步
        └── mysqldown.yaml   # [MODIFY] 新增「记录开始时间」+「钉钉通知（危险操作警告）」+「钉钉通知（成功）」「钉钉通知（失败）」四步

• deploy.yaml：在 steps 首部插入计时步骤；在「部署结果」之后追加成功/失败两个通知步骤，通知中携带镜像 ${{ env.IMAGE }}:${{ steps.meta.outputs.tag }}。
• mysqlup.yaml：结构同上，镜像字段使用 ${{ env.IMAGE }}:${{ env.MIGRATE_TAG }}。
• mysqldown.yaml：在「校验确认词」之后追加危险操作警告步骤（if: success()，正文强调「删除所有迁移创建的表及其数据，不可恢复」），末尾再追加成功/失败通知。

关键代码结构

通知步骤统一形态（以 deploy.yaml 成功通知为例，失败/警告仅替换图标、文案、条件与链接文案）：

      - name: 记录开始时间
        run: echo "JOB_START=$(date +%s)" >> "$GITHUB_ENV"

      # ... 既有业务步骤保持不变 ...

      - name: 钉钉通知（成功）
        if: success()
        continue-on-error: true
        env:
          WEBHOOK: ${{ secrets.DINGTALK_WEBHOOK }}
          REPO: ${{ gitea.repository }}
          REF: ${{ gitea.ref }}
          SHA: ${{ gitea.sha }}
          ACTOR: ${{ gitea.actor }}
          RUN_URL: ${{ gitea.server_url }}/${{ gitea.repository }}/actions/runs/${{ gitea.run_id }}
          IMAGE_REF: ${{ env.IMAGE }}:${{ steps.meta.outputs.tag }}
        run: |
          set -uo pipefail
          REF_NAME="${REF#refs/heads/}"; REF_NAME="${REF_NAME#refs/tags/}"
          SHORT_SHA="$(printf '%s' "$SHA" | cut -c1-7)"
          COST=$(( $(date +%s) - ${JOB_START:-$(date +%s)} ))
          TEXT="### <状态图标> 构建并部署成功\n\n"
          TEXT="${TEXT}> **zt-closet-backend** · 构建并部署\n\n"
          TEXT="${TEXT}- **仓库**：$REPO\n"
          TEXT="${TEXT}- **分支/标签**：$REF_NAME\n"
          TEXT="${TEXT}- **提交**：$SHORT_SHA\n"
          TEXT="${TEXT}- **触发者**：$ACTOR\n"
          TEXT="${TEXT}- **镜像**：$IMAGE_REF\n"
          TEXT="${TEXT}- **耗时**：$((COST/60)) 分 $((COST%60)) 秒\n"
          TEXT="${TEXT}- **时间**：$(date '+%Y-%m-%d %H:%M:%S')\n\n"
          TEXT="${TEXT}[查看运行详情]($RUN_URL)"
          printf '%s' "{\"msgtype\":\"markdown\",\"markdown\":{\"title\":\"<状态图标> 构建并部署成功 · zt-closet-backend\",\"text\":\"$TEXT\"}}" > /tmp/dingtalk.json
          RESP="$(curl -sS -X POST "$WEBHOOK" -H 'Content-Type: application/json' -d @/tmp/dingtalk.json)"
          echo "钉钉响应: $RESP"

其中 <状态图标> 分别取「对勾」「叉」「警示」三类图标 emoji（实现时填入对应字符），使三级通知在钉钉列表中可被颜色与图形同时区分。失败通知额外增加一行「- 失败定位：请点击下方链接查看失败步骤与日志」，链接文案为「查看失败日志」。