wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity

文档：新增 CI 配置指南（Gitea Actions 全流程）

Browse Source 
新增 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 全过）。
This commit is contained in:
Wanderingss
2026-10-01 23:59:28 +08:00
parent e90486524d
commit 1e01950b23
3 changed files with 300 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/测试说明/测试开发标准流程.md
+5
View File
@@ -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/ 文件清单（现状）
docs/环境与部署/CI配置指南.md
+293
View File
@@ -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 编辑配置文件（推荐，永久生效）
配置文件位置（按部署方式二选一）：
| 部署方式 | 配置文件路径 |
|---|---|
| 二进制 / 直接跑 | `<gitea 目录>/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 拉取 / 端到端验证清单 / 故障排查 / 日常维护） |
docs/环境与部署/项目部署环境要求.md
+2
View File
@@ -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 表格与速查表同步修正 |