From 1e01950b2381f3003259624d3ed558ca24bebae6 Mon Sep 17 00:00:00 2001 From: Wanderingss <1624155937@qq.com> Date: Thu, 1 Oct 2026 23:59:28 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9A=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=20CI=20=E9=85=8D=E7=BD=AE=E6=8C=87=E5=8D=97=EF=BC=88Gitea=20Ac?= =?UTF-8?q?tions=20=E5=85=A8=E6=B5=81=E7=A8=8B=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 docs/环境与部署/CI配置指南.md：服务端 [actions] ENABLED 开关、 Windows runner（act_runner）注册（--labels "windows:host" 必须与 runs-on 对应）、 runner 软件环境与 PATH 要求（含 MSVC VS_ROOTS 路径约束）、workflow 位置与触发、 内网拉不到 actions/checkout 的三种处置、端到端验证清单、故障排查表、日常维护。 关联更新：项目部署环境要求 §七（相关文档 + 变更记录）、 测试开发标准流程 §9.4（指向配置指南）+ 关联文档表。 验证：check_doc_links --all 106 文档通过；scripts/ci_local.py rc=0（L0 + L0.5 全过）。 --- docs/测试说明/测试开发标准流程.md | 5 + docs/环境与部署/CI配置指南.md | 293 ++++++++++++++++++++++++++++ docs/环境与部署/项目部署环境要求.md | 2 + 3 files changed, 300 insertions(+) create mode 100644 docs/环境与部署/CI配置指南.md diff --git a/docs/测试说明/测试开发标准流程.md b/docs/测试说明/测试开发标准流程.md index 6e47d256..14219e07 100644 --- a/docs/测试说明/测试开发标准流程.md +++ b/docs/测试说明/测试开发标准流程.md @@ -14,6 +14,7 @@ | `docs/UI设计/UI_自动化测试流程.md` | UI 模拟器回归（ui-verify）细节 | | `docs/代码规范/pre-commit使用说明.md` | pre-commit 门禁配置与范围 | | `docs/环境与部署/项目部署环境要求.md` | 构建 / 测试工具链环境 | +| `docs/环境与部署/CI配置指南.md` | **CI（Gitea Actions）配置全流程与排障** | | `docs/测试说明/<模块>_Test_Guide.md` | 各模块测试规范（CH395F / GD5F / SD2506 / FTP） | --- @@ -496,6 +497,10 @@ CI 只在 push / PR 时跑，且需 runner 就绪。**提交前自查、或 runn | Windows runner | 已注册且 **labels 含 `windows`**；装有 Python 3.x、cppcheck、pre-commit、MSVC（VS2019/2022 C++ 工具链 + Windows SDK） | | 缺 MSVC 时 | L0.5 降级为 WARNING 跳过（不硬失败），但**等于该层裸奔**，须尽快补装 | +> 📖 **配置步骤 / 排障**（服务端开关、runner 注册命令、PATH 与 MSVC 路径要求、 +> 内网拉不到 action 的处置、故障排查表）见 +> [`../环境与部署/CI配置指南.md`](../环境与部署/CI配置指南.md)。 + --- ## 附录 A：test/ 文件清单（现状） diff --git a/docs/环境与部署/CI配置指南.md b/docs/环境与部署/CI配置指南.md new file mode 100644 index 00000000..72834f92 --- /dev/null +++ b/docs/环境与部署/CI配置指南.md @@ -0,0 +1,293 @@ +# CI 配置指南（Gitea Actions） + +> **适用**：为 STM32F4-Base 部署 / 排障 CI（`.gitea/workflows/ci.yml`，L0 + L0.5）。 +> **前置阅读**：`docs/测试说明/测试开发标准流程.md` §9（CI 覆盖边界与判定细节）、 +> `docs/环境与部署/项目部署环境要求.md` §2.11（runner 环境要求）。 +> 本文只讲**怎么配**，不重复"为什么这么设计"。 + +--- + +## 0. 全景：CI 需要三样东西就位 + +``` +① Gitea 服务端开关 ② Windows Runner 注册 ③ 仓库里的 workflow 文件 + [actions] ENABLED=true labels 含 windows .gitea/workflows/ci.yml + │ │ │ + └────────────┬───────────┴──────────────────────────────┘ + ▼ + push / PR 触发 → runner 拉起容器/壳 → 跑 L0 + L0.5 → 结果回显到提交 +``` + +**三者缺一，CI 就是空转的**（workflow 存在但永不执行 / 执行但拉不到 runner）。 +当前仓库状态：**③ 已就绪（本机提交 `e904865`，尚未 push）；① ② 需人工确认。** + +--- + +## 1. 服务端：开启 Gitea Actions + +### 1.1 确认版本与开关 + +Gitea **≥ 1.21** 才内置 Actions（实测本实例 **1.25.4**，满足）。以 **site admin** 登录后： + +- 管理后台 → **站点管理 → 配置 / Site Administration → Configuration**，搜索 `actions`： + +```ini +[actions] +ENABLED = true +``` + +### 1.2 编辑配置文件（推荐，永久生效） + +配置文件位置（按部署方式二选一）： + +| 部署方式 | 配置文件路径 | +|---|---| +| 二进制 / 直接跑 | `/custom/conf/app.ini` | +| Docker | 容器内 `/data/gitea/conf/app.ini`（挂载卷里的 `custom/conf/app.ini`） | + +在 `app.ini` 追加（若无 `[actions]` 段）： + +```ini +[actions] +ENABLED = true +; 可选：限制单仓库并发任务数，防 runner 被占满 +DEFAULT_ACTIONS_URL = https://gitea.com +``` + +改完 **重启 Gitea 服务**（Docker：`docker restart <容器名>`；二进制：重启进程）。 + +### 1.3 验证 + +浏览器打开仓库地址，顶部/侧栏应出现 **Actions** 标签页。 +若仍提示"此仓库未启用 Actions"，说明开关没生效，回到 1.1 检查。 + +> ⚠️ 若实例装在**内网且不能访问公网**，`actions/checkout@v4` 这类官方 action 会拉不下来。 +> 处置见 §4.3。 + +--- + +## 2. Runner 端：注册 Windows Runner + +CI 的两个 job 都是 `runs-on: windows`，所以**必须有一个 labels 含 `windows` 的 runner**。 +推荐用 `act_runner`（Gitea 官方 runner）。 + +### 2.1 获取注册令牌 + +- **仓库级 runner**（推荐，只服务本仓库）： + 仓库 → **设置 / Settings → Actions → Runners → 创建 Runner**，复制页面显示的 + **Registration Token**（形如 `xxxYYYzzz...`）。 +- **全局 runner**（服务整个实例）：站点管理 → Actions → Runners。 + +记下 Gitea 地址，例如 `https://gitea.bitnasdaq.vip`。 + +### 2.2 下载并注册 act_runner + +```powershell +# 1) 下载（示例版本，请取 releases 页最新 Windows amd64） +# https://gitea.com/gitea/act_runner/releases +Invoke-WebRequest -Uri "https://gitea.com/gitea/act_runner/releases/download/v0.2.11/act_runner-0.2.11-windows-amd64.exe" ` + -OutFile "C:\act_runner\act_runner.exe" + +# 2) 注册：URL 用 Gitea 根地址，token 用 2.1 复制的 +cd C:\act_runner +.\act_runner.exe register ` + --no-interactive ` + --instance "https://gitea.bitnasdaq.vip" ` + --token "粘贴 Registration Token" ` + --name "win-stm32-ci" ` + --labels "windows:host" +``` + +**关键点**：`--labels "windows:host"` 中的 `windows` 必须**逐字**与 workflow 的 +`runs-on: windows` 对应（Gitea runner 的 label 名是自定义的，默认是 `ubuntu-latest`， +**不注册 `windows` 这个 label 就永远匹配不到 job**）。 + +> `:host` 表示直接跑在宿主 Windows 上（不是容器）。本场景**必须用 `host`**—— +> 容器里拿不到宿主已装的 Keil/MSVC/cppcheck，且 Windows 容器支持很差。 + +### 2.3 配置 `config.yaml`（可选但建议） + +`C:\act_runner\config.yaml` 里确认/补充： + +```yaml +runner: + labels: + - "windows:host" # 与 register 一致 + capacity: 1 # 并行 job 数；单机建议 1，避免 cppcheck 抢 CPU + timeout: 30m +cache: + enabled: true +``` + +### 2.4 以服务方式常驻 + +```powershell +# 注册为 Windows 服务（管理员权限） +.\act_runner.exe daemon install +.\act_runner.exe daemon start + +# 或前台调试（先看日志通不通，推荐首次这样跑） +.\act_runner.exe daemon +``` + +注册成功后，回到 **仓库 → Settings → Actions → Runners**，应看到 `win-stm32-ci` +状态为 **Idle / 绿色**。 + +--- + +## 3. Runner 软件环境：装什么 + +runner 是一台干净的 Windows，**下面这些必须装**，否则 job 会失败或降级跳过。 + +| 项 | 必需性 | 影响 | 安装 | +|---|---|---|---| +| **Python 3.x** | 🔴 必需 | `l0-gates` 环境自检失败 → **job 硬失败** | `winget install Python.Python.3.12` | +| **cppcheck** | 🔴 必需 | 同上（`cppcheck --version` 探测不过） | `winget install Cppcheck.Cppcheck` | +| **pre-commit** | 🔴 必需 | 同上（`python -m pre_commit --version` 探测） | `pip install pre-commit` 或 `uv tool install pre-commit` | +| **MSVC（VS + Windows SDK）** | 🟡 建议 | 缺则 `l05-host-unit-tests` **告警降级跳过**（不硬失败，但 L0.5 裸奔） | `winget install Microsoft.VisualStudio.2022.BuildTools`，勾"使用 C++ 的桌面开发" | +| Keil / ST-LINK | ⛔ 不需要 | CI 刻意不跑 `@build` | — | +| 开发板 / 串口 | ⛔ 不需要 | L1/L2/L3 不上 CI | — | + +### 3.1 关键：PATH 必须对 + +CI 的环境自检用的是 `Get-Command python` / `cppcheck`，**依赖 PATH**。 +装完后**新开一个终端**（或重启 runner 服务）让 PATH 生效，然后自检： + +```powershell +python --version # 期望 Python 3.x +cppcheck --version # 期望 Cppcheck 2.21.0 或更高 +python -m pre_commit --version +``` + +### 3.2 MSVC 的路径要求（探测逻辑） + +`l05-host-unit-tests` 的 MSVC 探测会去这些**固定根目录**找 +`VC\Tools\MSVC\*\bin\Hostx64\x64\cl.exe`（与 +`test/host/common/unit_test_harness.py` 的 `VS_ROOTS` 保持一致）： + +``` +C:\Program Files (x86)\Microsoft Visual Studio\2019\{BuildTools,Community,Professional} +C:\Program Files\Microsoft Visual Studio\2022\{BuildTools,Community,Professional,Enterprise} +C:\Program Files\Microsoft Visual Studio\2026\{BuildTools,Community} +``` + +> ⚠️ **装在非默认路径（如 D 盘）会探测不到** → 被当成"没装 MSVC"直接跳过 L0.5。 +> 要么用默认路径，要么同步改 `unit_test_harness.py` 的 `VS_ROOTS` **和** workflow +> 里的 `$roots`（两处必须一致，否则本地能跑、CI 跳过）。 + +Windows SDK 同理，默认在 `C:\Program Files (x86)\Windows Kits\10\`。 + +--- + +## 4. 仓库端：workflow 文件 + +### 4.1 文件位置与提交 + +workflow 必须位于**仓库根**的 `.gitea/workflows/` 下（不是 `.github/`）： + +``` +<仓库根>/ +└─ .gitea/ + └─ workflows/ + └─ ci.yml ← 本仓库已有，见该文件 +``` + +**它必须被 push 到远程才能生效**——目前本仓库的 `e904865` 还在本地 +（`origin/v2-on-ui` 尚未包含），所以**现在 push 之前 CI 不会跑**： + +```powershell +git push origin v2-on-ui # ⚠️ 需你明确要求才推送（本仓库约定：默认不推送） +``` + +### 4.2 触发条件 + +```yaml +on: + push: + paths-ignore: ['docs/**', '**/*.md', '.workbuddy-ai/**'] + pull_request: + paths-ignore: ['docs/**', '**/*.md', '.workbuddy-ai/**'] + workflow_dispatch: # 页面可手动触发 +``` + +- 纯文档改动**不触发**（省 runner）； +- 想手动跑一次：仓库 → Actions → 选 `CI` → **Run workflow**。 + +### 4.3 内网无公网时的 action 拉取（重要） + +workflow 用了 `actions/checkout@v4`。Gitea 默认从 **gitea.com** 代理拉取官方 action； +若实例不通外网，会在 checkout 步骤卡住/失败。三种处置： + +1. **开代理**：在 Gitea `app.ini` 配 `[actions] DEFAULT_ACTIONS_URL = https://gitea.com` + 并确保服务器能访问该域名； +2. **镜像**：改 `DEFAULT_ACTIONS_URL` 指向可达的 action 镜像； +3. **零依赖**：把 checkout 换成纯 git 命令（不依赖任何 action）： + +```yaml + - name: Checkout + shell: pwsh + run: | + git init . + git remote add origin $env:GITHUB_SERVER_URL/$env:GITHUB_REPOSITORY.git + git fetch --depth 1 origin $env:GITHUB_SHA + git checkout $env:GITHUB_SHA +``` + +> 方案 3 无需任何外部 action，内网最稳；代价是失去 checkout 的缓存优化。 + +--- + +## 5. 端到端验证清单 + +按顺序确认，任一步不过就停在那里排障： + +| # | 检查 | 期望 | +|---|---|---| +| 1 | 仓库顶部有 **Actions** 标签页 | 服务端开关已开 | +| 2 | Settings → Actions → Runners 里 runner 为 **Idle** | runner 注册成功 | +| 3 | runner 上 `python --version` / `cppcheck --version` / `python -m pre_commit --version` | 三条全通 | +| 4 | `git push` 一次（或页面 Run workflow） | Actions 页出现运行中任务 | +| 5 | `l0-gates` 日志 | `pre-commit ... Passed`；无 `.map` 时 `mem-numbers` 显示 `Skipped` | +| 6 | `l05-host-unit-tests` 日志 | `=== Task Watchdog Tests: 39/39 PASSED (failed=0) ===` | +| 7 | 提交记录旁出现 ✅ | CI 全绿 | + +**本地先自查**（与 CI 同一套判定，避免推上去才发现问题）： + +```powershell +& '.venv\Scripts\python.exe' scripts/ci_local.py +``` + +--- + +## 6. 常见故障排查 + +| 现象 | 根因 | 处置 | +|---|---|---| +| push 后 Actions 页**空白/无任务** | ① 服务端开关未开 ② workflow 没 push 到远程 ③ 只改了 `docs/**`（被 `paths-ignore` 滤掉） | 逐条核对 §1 / §4.1 / §4.2 | +| 任务一直 **Waiting / 排队** | 没有 label 匹配 `windows` 的 runner | 检查 `--labels "windows:host"`；Settings→Runners 是否 Idle | +| `l0-gates` 报 `::error::runner 缺少：Python, cppcheck` | runner 没装或不在 PATH | 装完后**重启 runner 服务**（新进程才吃到新 PATH） | +| `checkout` 步骤卡住/超时 | 拉不到 `actions/checkout@v4`（内网） | 见 §4.3 | +| `l05` 日志出现 `::warning::runner 未安装 MSVC` | VS 装在非默认路径或未装 | 见 §3.2（默认路径 / 同步改两处根目录） | +| `mem-numbers` 显示 `Skipped` | 正常（CI 无 Keil，无 `.map`） | 无需处理；是"不适用"不是"失败" | +| `l05` 报 `fatal error C1083: 无法打开包括文件 "stdio.h"` | Windows SDK 缺失 | 装 VS 时勾"使用 C++ 的桌面开发"+ SDK | +| 单测退出码 2 | 环境错误（多为无 MSVC） | 同上 | +| `pre-commit` 首次运行久 | 首次要下载各钩子的环境 | 正常，runner 缓存后会快 | + +--- + +## 7. 日常维护 + +- **升级 runner**：停服务 → 换 `act_runner.exe` → 起服务（注册信息保留在 `config.yaml`）； +- **改了 `VS_ROOTS` / 工具链探测逻辑**：记得**同步改 workflow 里的探测根目录**（两处一致）； +- **钩子集变化**（`.pre-commit-config.yaml` 增删钩子）：CI 自动跟随，无需改 workflow； +- **`@build` / L1 / L2**：永远留在本地，不要往 CI 加（需 Keil 授权与真机）； +- **runner 长时间不可用**时：CI 只是"多一道网"，**提交前的本地 `ci_local.py` 仍是 L0 的唯一保障**， + 不能因"已经配了 CI"放宽（见 `docs/待处理内容.md` 的部署前置警示块）。 + +--- + +## 变更记录 + +| 日期 | 变更 | +|---|---| +| 2026-10-01 | 初版：Gitea Actions 配置全流程（服务端开关 / Windows runner 注册 / runner 软件环境 / workflow 位置与触发 / 内网 action 拉取 / 端到端验证清单 / 故障排查 / 日常维护） | diff --git a/docs/环境与部署/项目部署环境要求.md b/docs/环境与部署/项目部署环境要求.md index 03e10b15..9fa6e89b 100644 --- a/docs/环境与部署/项目部署环境要求.md +++ b/docs/环境与部署/项目部署环境要求.md @@ -561,6 +561,7 @@ workflow 见 `.gitea/workflows/ci.yml`；覆盖边界与判定细节见 [`../测 | LVGL 模拟器部署 | `docs/UI设计/LVGL模拟器部署与使用说明.md`、`simulator/README.md` | | 串口调试 / 自动化测试 | `docs/测试说明/串口助手使用指南.md`、`docs/测试说明/串口助手设计说明.md`、`docs/测试说明/自动化测试流程.md` | | **测试分层 / L0.5 主机侧单测** | `docs/测试说明/测试开发标准流程.md`（分层与门禁）· `docs/测试说明/看门狗单元测试说明.md`（L0.5 范式：MSVC 离线编译 + 平台桩） | +| **CI（Gitea Actions）** | `docs/环境与部署/CI配置指南.md`（**服务端开关 / runner 注册 / 软件环境 / 排障全流程**）· `docs/测试说明/测试开发标准流程.md` §9（覆盖边界） | | pre-commit / cppcheck | `docs/代码规范/pre-commit使用说明.md`、`docs/代码规范/cppcheck使用说明.md` | | 引用关系图（文件引用） | `docs/架构设计/引用关系图说明.md`（生成工具 `tools/refgraph`；渲染依赖 Graphviz，§2.8） | | 各模块测试指南 | `docs/测试说明/CH395F_Test_Guide.md`、`GD5F2GQ5UE_Test_Guide.md`、`SD2506_Test_Guide.md`、`FTP_Test_Guide.md` | @@ -572,6 +573,7 @@ workflow 见 `.gitea/workflows/ci.yml`；覆盖边界与判定细节见 [`../测 | 日期 | 变更 | |---|---| +| 2026-10-01 | 新增 **`CI配置指南.md`**（Gitea Actions 配置全流程：服务端 `[actions] ENABLED` / Windows runner 注册（`--labels "windows:host"`）/ runner 软件环境与 PATH / workflow 位置与触发 / 内网拉不到 `actions/checkout` 的三种处置 / 端到端验证清单 / 故障排查表 / 日常维护）；§七相关文档登记 | | 2026-10-01 | **新增 §2.11 CI runner 环境（Gitea Actions，T-6）**：Gitea ≥1.21（实测 1.25.4）+ `[actions] ENABLED` + Windows runner（装 Python/cppcheck/pre-commit/MSVC）；**不需要 Keil**（刻意不跑 `@build`，无 `.map` 时 `mem-numbers` 自动跳过）；补"CI 不能替代本地门禁"与 `scripts/ci_local.py` 过渡命令 | | 2026-10-01 | **补主机侧单元测试（L0.5）环境要求**：§2.3 由"PC 模拟器环境"扩为"PC 侧编译环境（模拟器 + 主机侧单元测试）"——明确**同一套 VS 的 `cl.exe` 同时服务模拟器与单测**，MSVC 从"仅模拟器需要"升级为"提交门禁需要"；§2.7 pre-commit 表补 `watchdog-unit-test` 钩子及"未装 VS 会被拦截"；第 3 步 / 第 10 步冒烟 / 搭建清单 / §2.10 下载表（补 VS2022/2026 行）/ 速查表（补 `cl.exe` 缺失与 `C1083 stdio.h` 两条）/ 相关文档同步；总览拓扑图加 `MSVC cl.exe` 节点 | | 2026-09-21 | 更正 SDL2 描述：`simulator/SDL2/` 并不入库（gitignore，fresh clone 缺失），原"**随仓库提供**/不用装"表述有误；第 3 步补全官方预编译包下载（直链 + 内网中转）、解压、`include/SDL2/` 头文件复制、5 文件校验步骤；§2.3 表格与速查表同步修正 |