日常更新

2026-03-29 09:08:01 +08:00
parent 31709425e2
commit befdefd222
224 changed files with 7240 additions and 3297 deletions
--- a/docs/00-03-测试与验证框架.md
+++ b/docs/00-03-测试与验证框架.md
@@ -1,12 +1,13 @@
-# 00-05-测试与验证框架（设计说明）
+# 00-03-测试与验证框架（设计说明 + 验证前准备清单）

-> 本页是“测试与验证框架”的设计说明，并与仓库里已落地的 `scripts/verify.sh` + `ansible/playbooks/verify/` 对齐。
+> 本页是“测试与验证框架”的设计说明，并与仓库里已落地的 `ansible/bin/verify.sh` + `ansible/playbooks/verify/` 对齐。


 ## TL;DR

 - **本文性质**：说明/索引类文档（不承载一键部署动作）
- **推荐动作**：按 `00-00-构建总览.md` 进入主线；需要真机验收用 `./scripts/verify.sh full`
+- **推荐动作**：按 `00-00-构建总览.md` 进入主线；需要真机验收用 `./ansible/bin/verify.sh full`
+- **进度视图**：`00-04-验证状态板.md`（自动生成视图；不作为执行真源）
 - **成功判据**：你能据本文定位到下一步文档与对应入口脚本
 - **排障**：执行失败请查看对应实验篇的「排障」与 playbook 输出

@@ -16,7 +17,23 @@

 本页只回答一件事：**如何把文档（`doc_id=XX-YY`）与可执行的验证入口对齐**，并把验证能力收敛为可维护的自动化资产。

-实机验证前需具备的环境与外部依赖，见 [`00-04-待验证项-验证前准备.md`](00-04-待验证项-验证前准备.md)。
+**索引约定**：下文与全库讨论自动化/验收时，**默认以 `doc_id` 为第一关键字**（验收入口 = `ansible/playbooks/verify/<doc_id>.yml`）；BMad 按 `doc_id` 生成的 **[CS] Story** 见 `_bmad-output/implementation-artifacts/stories-by-doc/README.md`（与 Epic/Story 编号并存时，仍以 `doc_id` 对齐工程真源，见 `project-context.md`）。
+
+实机验证前需具备的环境与外部依赖，见本文 **§10 验证前准备清单**。
+
+### 1.1 Helm 与专题文档索引
+
+本仓库里 **Helm** 出现频繁：除验证流程中的 `helm install/upgrade` 外，多篇文档以 chart + values 为真源。建议按主题跳转（**CLI 安装与环境**见 `00-02` §1.1～§1.2）：
+
+| 场景 | 文档与真源 |
+|------|------------|
+| Longhorn | `03-07`；values：`ansible/files/03-07/values-lab.yaml`；自动化：`verify/03-07.yml` |
+| kube-prometheus-stack（Prometheus/Grafana） | `05-05`；示例 values：`ansible/files/05-05/kube-prometheus-stack-values.example.yaml` |
+| Traefik 端口/参数（HelmChartConfig） | `03-10`；`ansible/files/03-10/traefik-custom-ports.yaml` |
+| GitOps（Argo CD 可用 Helm 或官方清单安装） | `03-09` |
+| 查看 k3s 管理的 HelmChart 资源 | `06-02`（`kubectl -n kube-system get helmchart,helmchartconfig`） |
+
+Helm 安装 **超时、重试、`helm status` 排障** 的约定见下文 **§2.1** 表格「Helm 长耗时」一行。

 ## 2. 自动化验证流程（一般步骤）

@@ -24,8 +41,8 @@

 1. **接入目标环境**  
   - 用 SSH 登录**控制节点**（或在本机配置好到控制节点的 Ansible `inventory`，由 Ansible 代你 SSH）。  
-   - 在仓库根（或文档约定目录）准备好代码：`git pull` / `scp` 同步等，与 [`docs/00-04-部署环境说明.md`](00-04-部署环境说明.md) 一致。  
-   - 按需加载验证环境变量：复制并填写 [`scripts/.env.verify.example`](../scripts/.env.verify.example) 为 `scripts/.env.verify`，执行前 `source`（`verify.sh` 会自动尝试加载）。
+   - 在仓库根（或文档约定目录）准备好代码：`git pull` / `scp` 同步等，与 [`00-02-部署环境说明.md`](00-02-部署环境说明.md) 一致。  
+   - 按需加载验证环境变量：复制并填写 [`ansible/env/.env.verify.example`](../ansible/env/.env.verify.example) 为 `ansible/env/.env.verify`，执行前 `source`（`verify.sh` 会自动尝试加载）。

 2. **环境与前置清理（按验证目标选择深度）**  
   - **基本检查**：`kubectl get nodes`、磁盘/内核版本、防火墙与文档是否一致；必要时对照 `00-04`。  
@@ -33,7 +50,7 @@
   - **重度清理（重装/复现安装文档时）**：若你要从「空机」验证 `01-01` 等**整集群安装**流程，才需要按文档执行 `k3s-uninstall.sh`、删数据目录、清 iptables 等——这与日常 `run-all` 的“逐篇快速验收”是**不同场景**，不要默认混进每一次 `run-all`。

 3. **部署**  
-   - **推荐（本仓库）**：用 Ansible playbook 部署——要么是正式安装/初始化类（如 `verify/01-06.yml -e k3s_do_install=true`，或 `./scripts/deploy-lab.sh` 调用之），要么是验证用例里的 `kubectl apply` / `helm install` / `import_playbook`。  
+   - **推荐（本仓库）**：用 Ansible playbook 部署——要么是正式安装/初始化类（如 `verify/01-05.yml -e k3s_do_install=true`，或 `./ansible/bin/deploy-lab.sh` 调用之），要么是验证用例里的 `kubectl apply` / `helm install` / `import_playbook`。  
   - **文档中的 bash 一键命令**：仍可按 `docs/` 逐步执行；适合排障或 playbook 尚未覆盖的边角。自动化验收应尽量**收敛进** `ansible/playbooks/verify/*.yml`，避免「文档一套、手敲一套」长期分叉。

 4. **按设计目标做断言**  
@@ -47,8 +64,8 @@
   - 将结论写回对应实验篇文档（或保留日志），必要时更新 `docs/XX-YY-*.md` 中的命令或版本说明。

 6. **本仓库一键串联**  
-   - **部署**（步骤 3）：`./scripts/deploy-lab.sh k3s` 等，见 [`scripts/README.md`](../scripts/README.md)。  
-   - **验证**（步骤 4～6）：在仓库根执行 **`./scripts/verify.sh full`**（推荐：**preflight +** `run-all`，缺 playbook **fail-fast**）；或仅 `./scripts/verify.sh run-all`（不跑 preflight）；单篇用 `./scripts/verify.sh run <XX-YY>`。`./scripts/verify.sh flow` 可打印与本节对应的步骤摘要。  
+   - **部署**（步骤 3）：`./ansible/bin/deploy-lab.sh k3s` 等，见 [`scripts/README.md`](../scripts/README.md)。  
+   - **验证**（步骤 4～6）：在仓库根执行 **`./ansible/bin/verify.sh full`**（推荐：**preflight +** `run-all`，缺 playbook **fail-fast**）；或仅 `./ansible/bin/verify.sh run-all`（不跑 preflight）；单篇用 `./ansible/bin/verify.sh run <XX-YY>`（仓库根简写 **`./scripts/cs <XX-YY>`**，与前者等价，**对 `ansible/playbooks/verify/` 内全部执行域 doc_id 通用**，无需为每个 doc_id 单独建脚本）。`./ansible/bin/verify.sh flow` 可打印与本节对应的步骤摘要。  
   - **范围说明**：`run-all` 的范围由 `ansible/playbooks/verify/` 目录内存在的 `XX-YY.yml` 自动决定；`full` **不会**自动执行 `deploy-lab.sh`，仍假设集群与铺栈（步骤 3）已由操作者完成。

 ### 2.1 局限与约定补全（建议在文档与 `verify/XX-YY.yml` 中写死）
@@ -58,20 +75,36 @@
 | 主题 | 建议约定 |
 |------|----------|
 | **多节点：在哪台机器 `curl`** | **默认**：在 inventory 的 **`k3s_server`（控制节点）** 上，对 **集群入口** 发 HTTP（如 `nginx_entry_base` / `http://<控制节点或 LB IP>`），与「从集群外经 NodePort/主机网络进 Traefik」一致。**例外**（必须显式写）：要验 worker 仅内网、跨节点路径、或「必须从某台 agent 访问」时，在 playbook 里对指定 host 执行 `curl`（或 `delegate_to` / 专用 play），并在文档「验证命令」中写明 **执行主机与目标 URL**，避免隐含「任意节点等价」。 |
-| **TLS / SNI** | 自签或跳过校验仅用于排障：`curl -k`。**验收**应优先：真实证书路径下用 `curl -v` 看证书链；或用 `curl --resolve <域名>:443:<入口IP> https://<域名>/...` 在 **无 DNS** 时模拟 SNI。需要时用 `openssl s_client -connect host:443 -servername <域名> </dev/null` 看握手。ACME 类用例依赖 **公网 80/443、有效邮箱、DNS/Secret**；gate 跳过 apply 时，应在文档/日志中明确记录“跳过原因与未覆盖范围”。 |
+| **TLS / SNI** | 自签或跳过校验仅用于排障：`curl -k`。**验收**应优先：真实证书路径下用 `curl -v` 看证书链；或用 `curl --resolve <域名>:443:<入口IP> https://<域名>/...` 在 **无 DNS** 时模拟 SNI。需要时用 `openssl s_client -connect host:443 -servername <域名> </dev/null` 看握手。ACME 类用例依赖 **公网 80/443、有效邮箱、DNS/Secret**；gate 跳过 apply 时，应在文档/日志中明确记录“跳过原因与未覆盖范围”。**PRD R13 的 TLS「证据」**见下 **§2.2**；**代表自动化用例**为 **`verify/04-12.yml`**（`NODEJS_TLS_ENTRY_BASE` + `NODEJS_TLS_HOST` 时跑 `tls-openssl-sni` + HTTPS `http-curl-expect`）。**`verify/04-07.yml`** 在相同变量且入口为 `https://` 时可选跑 **仅** `tls-openssl-sni`（Ingress + Traefik 叙事下的第二落点）。矩阵类 playbook（如 **03-02**）中大量 `curl -sk` 仅作吞吐/可用性，**不替代** `openssl s_client` 的证书呈现证据。 |
 | **仅浏览器可用的 UI** | Traefik Dashboard OAuth、依赖 JS/CSP/WebSocket 的交互、文件上传等，`curl` 往往不够。约定三选一：**(1)** 自动化降级为只断言 `IngressRoute`/Deployment/Service 存在 + HTTP 非 5xx；**(2)** 在 `00-02` 备注 **「UI 需手工浏览器验收」**；**(3)** 另起 CI/脚本用 headless（如 Playwright），与 `verify.sh` **并列**，不强行塞进 Ansible。 |
 | **Helm 长耗时：超时与重试** | 安装/升级统一带 **`--wait` 与合理 `--timeout`**（大 chart 可 10m～20m 量级，按实际调）。Ansible 侧对「Pod 未就绪」可用 **`until` + `retries` + `delay`** 轮询，避免单次 `kubectl` 瞬断误判。文档写清 **最短等待** 与失败时要看 **`helm status` / `kubectl describe` / 事件**。调试设 `VERIFY_TEARDOWN=0` 保留现场。 |
 | **CI 无真集群** | 与实验室 **`verify.sh run-all` 不等价**。可选：**kubeconform** 等对清单做离线 schema；有短时 apiserver 时用 **`kubectl apply --dry-run=server`**；或用 **kind/k3d** 起临时集群跑子集用例。应在 CI 配置或 `README` 中写明 **「CI 只保证静态/结构；真机验收仍以控制节点 run-all 为准」**，避免混为一谈。 |

 **原则**：每篇文档至少有一句话说明 **验证命令的执行位置**（控制节点 / 指定 worker / 办公机经 VPN）和 **成功判据**（状态码、响应头、kubectl 资源相位）；playbook 与文档冲突时以 **先修 playbook、再改文档** 对齐。

+### 2.2 PRD R13 与 TLS 探针（`verify_common` / `[OC-ASSERT]`）
+
+PRD **R13** 要求：`✅ 已验证` 的证据可复现且尽量自动化；其中 **TLS 需 SNI/证书链信号**（与 HTTP 入口断言并列）。本仓库将 **TLS 侧可复现信号**落在 `ansible/roles/verify_common/tasks/tls-openssl-sni.yml`，成功/失败路径均打印 **`[OC-ASSERT]`**（含 `assertion=`、`phase=tls`、`probe=`）。
+
+| R13 要点 | 工程落点（probe / 能力） |
+|----------|---------------------------|
+| SNI 与握手可达 | `probe=s_client_log excerpt`（`openssl s_client -servername`） |
+| 证书呈现（subject） | `probe=subject`、`probe=subject_match`（可选子串 `verify_tls_expect_subject_substring`） |
+| 有效期信号 | `probe=cert_not_after` |
+| SAN 信号 | `probe=san excerpt`；可选断言 `verify_tls_expect_san_substring` → `probe=san_match` |
+| 私有/实验 CA 链（可选） | `verify_tls_cafile` → `s_client -CAfile`；缺失文件 → `probe=cafile result=fail` |
+| 仅看呈现证书、不强断言链（实验/排障） | `verify_tls_insecure_skip_verify=true` → 额外打印 `probe=insecure_skip_verify value=1`（默认不设则不打印此行） |
+| 入口 HTTP(S) 可用性 | 与 TLS 探针并列：`http-curl-expect`（如 **04-12**），`assertion` 与 TLS 分离 |
+
+**第三方机 / 集群外视角**：R13 另要求「集群外视角需第三方机」时，须由你在 inventory 或独立 play 中指定 **delegate_to** / 额外 host；本 role 默认在 **`k3s_server`** 上对 `verify_tls_connect_host:443` 发起握手，与「控制节点验入口」一致。
+
 ## 3. 执行框架（与仓库一致）

 此前设想的「静态层（yamllint / kubeconform / ansible-lint）→ 运行时 → 追溯」**未纳入**当前落地实现；若日后在 CI 里加格式或 schema 检查，应与 `verify.sh` **并列**，不必塞进同一脚本。

 本仓库**实际**验收路径只有下面几条，且都以 **Ansible 为执行引擎**（在控制节点上对集群下发 `kubectl` / `helm` / `curl` 等）：

-1. **`scripts/verify.sh`**：调用 `ansible-playbook -i <inventory> ansible/playbooks/verify/<doc_id>.yml`；缺对应 playbook 则 **fail-fast**。
+1. **`ansible/bin/verify.sh`**：调用 `ansible-playbook -i <inventory> ansible/playbooks/verify/<doc_id>.yml`；缺对应 playbook 则 **fail-fast**。
 2. **`ansible/playbooks/verify/<doc_id>.yml`**：单篇用例，通常拆成「部署 → 验证 → 清理」多个 **play**（默认 **`VERIFY_TEARDOWN=1`** 做 teardown）。
 3. **特例**：无集群动作的文档可走 **`verify/_noop-tasks.yml`**（仓库路径/文件存在性）；依赖 NFS、ACME、Cloudflare 等外部条件的可用 **gate 跳过** apply，teardown 需避免「无清单仍删」类失败（各 playbook 已按此收敛）。

@@ -93,7 +126,7 @@
 建议把用例写成“按文档 id 编排的任务集合”。在本仓库里，执行路径固定为 `verify/<doc_id>.yml`，不再维护额外映射文件。
 - 每个文件内一般拆为三段（多个 play 或顺序 tasks）：

-示例（02-05）：`./scripts/verify.sh run 02-05` 执行 `ansible/playbooks/verify/02-05.yml`（HTTP 校验四路径，最后 teardown）。`02-01`～`02-04` 另有单路径 playbook，便于单独调试。
+示例（02-05）：`./ansible/bin/verify.sh run 02-05` 或 `./scripts/cs 02-05` 执行 `ansible/playbooks/verify/02-05.yml`（HTTP 校验四路径，最后 teardown）。`02-01`～`02-04` 另有单路径 playbook，便于单独调试。

 每个 `verify/XX-YY.yml` 的典型结构为三段：

@@ -164,14 +197,14 @@ http_check:

 本仓库将 `docs/` 视为 **Runbook**（可执行手册），并对每篇可执行文档施加 **强绑定**：

- **每个 `doc_id` 必须可执行**：存在 `verify/<doc_id>.yml` 的 `doc_id` 必须能跑 `./scripts/verify.sh run <doc_id>`，且 playbook 内含明确断言（不得仅做“文件存在性”）。
+- **每个 `doc_id` 必须可执行**：存在 `verify/<doc_id>.yml` 的 `doc_id` 必须能跑 `./ansible/bin/verify.sh run <doc_id>`，且 playbook 内含明确断言（不得仅做“文件存在性”）。
 - **文档与断言一致**：文档的“验证命令/预期”必须与对应 playbook 的断言一致；冲突时先修 playbook，再改文档对齐。

 推荐每篇 `docs/<doc_id>-*.md` 采用以下结构（可复制粘贴作为模板）：

 - **H1**：`# <doc_id>-<标题>`
 - **TL;DR（必选，3–8 行）**
-  - 自动化入口：`./scripts/verify.sh run <doc_id>`（必要时补 `export ...`）
+  - 自动化入口：`./ansible/bin/verify.sh run <doc_id>`（必要时补 `export ...`）
  - 最关键 3 条前置（变量/Secret/挂载）
  - 成功判据一句话
  - 失败去哪看（链接到本篇“排障”）
@@ -186,11 +219,11 @@ http_check:
 ## 8. 与旧自动化的关系

 （已抛弃集中式“矩阵状态板”，因此不再有“待验证列表”文档。）
- 自动化执行以 `scripts/verify.sh` 与 `ansible/playbooks/verify/*.yml` 为准；本页描述其约定与扩展方式
+- 自动化执行以 `ansible/bin/verify.sh` 与 `ansible/playbooks/verify/*.yml` 为准；本页描述其约定与扩展方式

 ## 9. 可选扩展（未落地）

-当前「一篇文档 → 一个 `verify/XX-YY.yml`」在规模小时最简单：**入口仍是 `scripts/verify.sh`**，不必为了「架构感」提前建一堆目录。当出现下面任一情况时，再考虑本节里的拆法即可。
+当前「一篇文档 → 一个 `verify/XX-YY.yml`」在规模小时最简单：**入口仍是 `ansible/bin/verify.sh`**，不必为了「架构感」提前建一堆目录。当出现下面任一情况时，再考虑本节里的拆法即可。

 ### 9.1 何时值得拆

@@ -227,4 +260,97 @@ yamllint、ansible-lint、schema 校验等 **不放进 `verify.sh`** 亦可：
 ## 排障

 - **你在找执行命令**：本文为说明/索引；执行入口见 `00-00-构建总览.md` 与 `scripts/README.md`。
- **verify.sh 报错**：先跑 `./scripts/verify.sh preflight`，再根据提示修复 inventory/SSH/变量。
+- **verify.sh 报错**：先跑 `./ansible/bin/verify.sh preflight`，再根据提示修复 inventory/SSH/变量。
+
+## 10. 验证前准备清单（从原 00-04 合并）
+
+### A. 全局共用准备（跑任何扩展验证前建议具备）
+
+| 准备项 | 说明 |
+|--------|------|
+| 控制机 | 与 [`ansible/inventory.ini`](../ansible/inventory.ini) 一致：SSH 私钥存在且 **`chmod 600`**；仓库根执行 [`ansible/bin/verify.sh`](../ansible/bin/verify.sh)。 |
+| Ansible 配置 | [`ansible/lib/lib-ansible-lab.sh`](../ansible/lib/lib-ansible-lab.sh) 会设置 `ANSIBLE_CONFIG` 指向 [`ansible/ansible.cfg`](../ansible/ansible.cfg)；无写 `~/.ansible` 权限时可设 `ANSIBLE_LOCAL_TMP=$PWD/.ansible-tmp`（仓库 [`.gitignore`](../.gitignore) 已忽略 `.ansible-tmp/`）。 |
+| HTTP 类 | `ansible/env/.env.verify` 或环境中设 **`nginx_entry_base`**（如 `http://192.168.2.61`），与 `verify/02-0x.yml` 等一致。 |
+| 串联验证 | **`VERIFY_TEARDOWN=1`**（勿在 `.env.verify` 中长期设 `0`），避免用例互相污染。 |
+| 预检 | 可选 `VERIFY_PREFLIGHT_CLUSTER=1 ./ansible/bin/verify.sh preflight` 确认集群 Ready。 |
+
+### B. 按文档主题的准备（做什么才能「真验证」）
+
+#### B1. 特殊硬件 / 拓扑
+
+- **01-03、01-04**：准备 **armv7 实机**；01-03 经 **`ansible/tools/armv7-docker-verify-install.sh`**（先 **`docker info`**，失败再 **get.docker.com** 官方脚本）装 Docker；01-04 在 armv7 上跑通 NFS 导出与权限（与 03-06 可联动）。**默认** `SKIP_ARMV7=1` 时 verify 仅做文档/文件检查；**可选** 在 `.env.verify` 设 `SKIP_ARMV7=0` 并配置 `ARMV7_SSH`（01-04 可另设 `ARMV7_NFS_SSH`）后，`verify.sh run 01-03` / `01-04` 会经 SSH 执行远程步骤；01-04 仍为 **dnf** 路径（Fedora/RHEL 系），见 **§10.E**。
+- **01-07、03-08**：准备 **双 control-plane + 外部 LB（或等价）** 的可丢环境；按文档做加入/切换演练（当前自动化仅做基线可达性断言，加入/切换演练需按文档手工执行并补齐自动化）。
+- **07-01、07-02**：准备 **可重建的实验集群**（换 CNI/双栈）；写好回滚；这两篇验证多为 **noop**，建议以手工记录为准。
+
+#### B2. 环境变量 / 外部服务（不配则 gate 跳过或只能 noop）
+
+- **03-06**：在 `ansible/env/.env.verify` 配齐 **`NFS_SERVER_IP`（或 HOST）、`NFS_EXPORT_PATH`**；NFS 服务端导出与防火墙放行；再 `./ansible/bin/verify.sh run 03-06`。
+- **03-02、03-03、04-12**：在 **`ansible/env/.env.verify`** 配齐 **`ACME_EMAIL`**；Cloudflare DNS-01 时 **`CF_API_TOKEN`**（或集群已有 `kube-system/cloudflare-api-token`）；公网 **80/443**、**DNS** 等按文档；仓库根 **`set -a && source ansible/env/.env.verify && set +a`** 后执行 **`./ansible/bin/verify.sh run 03-02`** / **`03-03`**（**常规自测不要 `env -u ACME_EMAIL`**，除非刻意测 gated）。
+- **03-04**：**`CF_TUNNEL_TOKEN`**（或等价）与隧道侧配置；办公机/第三方探测路径按文档约定执行。
+- **06-03**：按 [`06-03-k3s-自动备份与恢复-openlist-webdav.md`](06-03-k3s-自动备份与恢复-openlist-webdav.md) 准备 **WebDAV 端点与凭据**；清单真源见 `ansible/files/06-03/`。
+
+#### B3. 部分验证补全为「已验证」（已有集群即可，偏手工/浏览器）
+
+- **01-06**：经 **Linux 工作机**（如 `ylc65`，见 `docs/00-02`）等 **非 k3s 节点** 对 OpenWrt **18080/18443** 做 curl；`ansible/env/.env.verify` 中 **`WORKSTATION_SSH`** 填到该工作机的一行 `ssh …`。
+- **03-01**：按文档 apply `ansible/files/03-01/`，**浏览器**验收 Dashboard（非仅 Deployment 存在）。
+- **03-03**：playbook 会 apply `ansible/files/03-03/` 并做 rollout + Dashboard HTTP 探针；浏览器/UI 可按文档另验。
+- **03-05**：playbook 层已有较完整验证；若要更“真验证”：按文档补全「业务读写/边界」。
+- **03-07**：playbook 已能装删 Longhorn；要 ✅：按 [`03-07-k3s-longhorn-持久化存储.md`](03-07-k3s-longhorn-持久化存储.md) 做 **PVC 读写、副本/故障** 等文档级验收。
+
+#### B4. Node.js 系列（04-01～04-14）
+
+- **共用准备**：可访问的 **镜像仓库**（或私有 registry）、`nodejs_entry_base`、足够节点与资源做调度/HPA。
+- **04-13**：集群需 **metrics-server**；准备压测工具以触发 HPA。
+- **04-14**：依赖 **GitLab CI / GitOps** 任选一条实链路（与 05-03/05-04/03-09 联动）。
+
+#### B5. 应用与监控（05-01～05-09）
+
+- **共用**：镜像拉取、持久化存储类（Longhorn/local-path/NFS）、Ingress 入口与 DNS（若对外）。
+- **05-03～05-04**：**大内存/磁盘** 规划、GitLab **域名/证书**、Runner **注册 token**、测试仓库与 `.gitlab-ci.yml`。
+- **05-05**：Prometheus/Grafana 资源与密码；Ingress 或 NodePort 访问策略。
+
+#### B6. 运维与概念（06-02、03-09）
+
+- **06-02**：经验文档；「验证」可定义为巡检/备份 SOP 在现网执行一轮并在文档里记录结论。
+- **03-09**：先 **选定 Argo CD 或 Flux** 并落地最小 GitOps 回路，再谈 ✅。
+
+### C. 建议执行顺序（减少重复准备）
+
+```mermaid
+flowchart TD
+  base[全局 SSH 与 env.verify]
+  nfs[NFS 与 03-06]
+  acme[ACME 与 03-02]
+  node[04-01 基线加扩 04-02 起]
+  apps[05-xx 大应用]
+  ha[HA 与 CNI 实验集群]
+  base --> nfs
+  base --> acme
+  base --> node
+  acme --> node
+  nfs --> apps
+  base --> ha
+```
+
+1. 先固化 **A** + **03-06 NFS**（若要做存储类应用）。
+2. 再做 **03-02 ACME**，解锁 **04-12** 与 TLS 矩阵深度验收。
+3. **04-02～04-11** 在 **04-01** 基线上增量加 playbook 或手工矩阵。
+4. **05-03/05-04**、**05-05** 单独排期（资源与时间最长）。
+5. **HA / 07-xx** 独立维护窗口与回滚。
+
+### D. 与「自动化」对齐的预期
+
+- `verify.sh run XX-YY` 已通过只保证 **该 playbook 已实现** 的步骤通过；**noop** 文档不会替你完成文档内全部操作。
+- 若你要做“已验证”记录，建议在对应实验篇文档里写清：**环境、日期、是「仅脚本」还是「脚本 + 手工浏览器/第三方机」**。
+
+### E. armv7 / arm32（可选经 `verify.sh` + SSH 远程安装）
+
+实验室矩阵里的 **01-03**（Docker）、**01-04**（NFS）、**05-02** 中的 arm 段等，依赖 **32 位 ARM（文档多写 armv7）实机**，与四节点 x86_64 K3s 主线 **不在同一 inventory**。
+
+| 项 | 说明 |
+|------|------|
+| 默认 | **`SKIP_ARMV7=1`（或未设）**：`01-03.yml`、`01-04.yml` 仍跑矩阵基线（含文档/文件检查），**不经 SSH 改 arm 机**。 |
+| 启用远程步骤 | **`SKIP_ARMV7=0`** 且 **`ARMV7_SSH`** 为一行可执行的 `ssh ...`（BatchMode 建议与 `ansible/env/.env.verify.example` 一致）：`verify.sh run 01-03` 会经该 SSH 调用 **`ansible/tools/armv7-docker-verify-install.sh`**（先 **`docker info`**，必要时 **get.docker.com**）；`run 01-04` 用 **`ARMV7_NFS_SSH`**（若为空则回退 **`ARMV7_SSH`**）装 **nfs-utils**、写 **`/etc/exports`**。 |
+| 约束 | 远程路径假定 **Fedora/RHEL 系 + dnf**；**Debian/apt 未分支**。`verify.sh` 在 `source ansible/env/.env.verify` 后调用 `ansible-playbook`，子进程继承上述环境变量。 |
+| 门控 | **`SKIP_ARMV7=0` 但未配置有效 SSH** 时，01-03 / 01-04 会 **fail**，避免误以为已启用 arm 时静默跳过。 |
+| 手工 | 仍可按 `01-03-armv7-standalone-docker.md`、`01-04-armv7-nfs服务安装.md` 全手工走通后在文档中记录环境与结论。 |