# 00-05-待验证项：验证前准备任务列表

> 本页是“验证前准备清单”：在实机推进到「已验证」之前，需要具备的环境、变量与动作列表。
>
> 自动化说明见 [`00-03-测试与验证框架.md`](00-03-测试与验证框架.md)；环境变量模板见 [`scripts/.env.verify.example`](../scripts/.env.verify.example)。


## TL;DR

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

---

## A. 全局共用准备（跑任何扩展验证前建议具备）

| 准备项 | 说明 |
|--------|------|
| 控制机 | 与 [`ansible/inventory.ini`](../ansible/inventory.ini) 一致：SSH 私钥存在且 **`chmod 600`**；仓库根执行 [`scripts/verify.sh`](../scripts/verify.sh)。 |
| Ansible 配置 | [`scripts/lib-ansible-lab.sh`](../scripts/lib-ansible-lab.sh) 会设置 `ANSIBLE_CONFIG` 指向 [`ansible/ansible.cfg`](../ansible/ansible.cfg)；无写 `~/.ansible` 权限时可设 `ANSIBLE_LOCAL_TMP=$PWD/.ansible-tmp`（仓库 [`.gitignore`](../.gitignore) 已忽略 `.ansible-tmp/`）。 |
| HTTP 类 | [`scripts/.env.verify`](../scripts/.env.verify) 或环境中设 **`nginx_entry_base`**（如 `http://192.168.2.61`），与 `verify/02-0x.yml` 等一致。 |
| 串联验证 | **`VERIFY_TEARDOWN=1`**（勿在 `.env.verify` 中长期设 `0`），避免用例互相污染。 |
| 预检 | 可选 `VERIFY_PREFLIGHT_CLUSTER=1 ./scripts/verify.sh preflight` 确认集群 Ready。 |

---

## B. 按文档主题的准备（做什么才能「真验证」）

### B1. 特殊硬件 / 拓扑

- **01-03、01-05**：准备 **armv7 实机**；01-03 装 Docker 并跑容器；01-05 在 armv7 上跑通 NFS 导出与权限（与 03-06 可联动）。**默认** `SKIP_ARMV7=1` 时 verify 仅做文档/文件检查；**可选** 在 `.env.verify` 设 `SKIP_ARMV7=0` 并配置 `ARMV7_SSH`（01-05 可另设 `ARMV7_NFS_SSH`）后，`verify.sh run 01-03` / `01-05` 会经 SSH 在 arm 上走 **dnf** 路径（Fedora/RHEL 系），见 **§E**。
- **01-08、03-08**：准备 **双 control-plane + 外部 LB（或等价）** 的可丢环境；按文档做加入/切换演练（当前自动化仅做基线可达性断言，加入/切换演练需按文档手工执行并补齐自动化）。
- **07-01、07-02**：准备 **可重建的实验集群**（换 CNI/双栈）；写好回滚；这两篇验证多为 **noop**，建议以手工记录为准。

### B2. 环境变量 / 外部服务（不配则 gate 跳过或只能 noop）

- **03-06**：在 `.env.verify` 配齐 **`NFS_SERVER_IP`（或 HOST）、`NFS_EXPORT_PATH`**；NFS 服务端导出与防火墙放行；再 `./scripts/verify.sh run 03-06`。
- **03-02、04-12**：有效 **`ACME_EMAIL`**、公网 **80/443**、**DNS**（及文档中的 Cloudflare/Secret）；与 `scripts/.env.verify.example` 中 CF 相关变量对齐。
- **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-07**：**onecloud**（或文档约定第三方机）对 OpenWrt **18080/18443** 做 curl；`scripts/.env.verify.example` 中 **`ONECLOUD_SSH`**。
- **02-00**：通读说明文档，与 02-01～02-05 结论对齐。
- **03-01**：按文档 apply `ansible/files/03-01/`，**浏览器**验收 Dashboard（非仅 Deployment 存在）。
- **03-03**：实机 apply `ansible/files/03-03/` 并验收。
- **03-05**：playbook 层已有较完整验证；若要更“真验证”：按文档补全「业务读写/边界」。
- **03-07**：playbook 已能装删 Longhorn；要 ✅：按 [`03-07-k3s-longhorn-持久化存储.md`](03-07-k3s-longhorn-持久化存储.md) 做 **PVC 读写、副本/故障** 等文档级验收（`longhorn_force_crd_reset` 仅在 CRD 与 Helm 严重冲突时于 `group_vars` 设为 `true`）。

### B4. Node.js 系列（04-01～04-14）

- **共用准备**：可访问的 **镜像仓库**（或私有 registry）、`nodejs_entry_base`、足够节点与资源做调度/HPA。
- **04-01**：已部分验证；04-02～04-14 当前 **`verify.sh` 多为 noop**（仅目录/文档存在性）。要逐项 ✅：**按各篇文档手工或用例化命令验证**，并在 `ansible/playbooks/verify/` **补 `04-0x.yml` 真实 deploy/verify/teardown**（工作量最大的一块）。
- **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-02**：**armv7 段 + K3s 段** 分两环境验证；arm 段与 **§E** 相同：默认跳过远程步骤，按需 `SKIP_ARMV7=0` + SSH 变量启用 01-03/01-05 类自动化后，再在 K3s 侧验证。
- **05-03～05-04**：**大内存/磁盘** 规划、GitLab **域名/证书**、Runner **注册 token**、测试仓库与 `.gitlab-ci.yml`。
- **05-05**：Prometheus Operator 资源与 **Grafana 管理员密码**；Ingress 或 NodePort 访问策略。
- **05-06**：真实 **网盘凭据**、备份目标目录与 Cron 窗口。
- **05-07～05-09**：x86 Docker 主机、K3s 内 **镜像构建/拉取**、OpenClaw 相关 **密钥与入口**；05-09 需 apply 示例清单并验收页面。

### 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-05**（NFS）、**05-02** 中的 arm 段等，依赖 **32 位 ARM（文档多写 armv7）实机**，与四节点 x86_64 K3s 主线 **不在同一 inventory**。

| 项 | 说明 |
|------|------|
| 默认 | **`SKIP_ARMV7=1`（或未设）**：`01-03.yml`、`01-05.yml` 仍跑矩阵基线（含 `_noop-tasks.yml` 文档/文件检查），**不经 SSH 改 arm 机**。 |
| 启用远程步骤 | **`SKIP_ARMV7=0`** 且 **`ARMV7_SSH`** 为一行可执行的 `ssh ...`（BatchMode 建议与 [`scripts/.env.verify.example`](../scripts/.env.verify.example) 一致）：`verify.sh run 01-03` 会经该 SSH 在 arm 上 **dnf 装 docker** 并校验；`run 01-05` 用 **`ARMV7_NFS_SSH`**（若为空则回退 **`ARMV7_SSH`**）装 **nfs-utils**、写 **`/etc/exports`**（路径/客户端网段见 **`ARMV7_NFS_EXPORT_PATH`**、**`ARMV7_NFS_CLIENT_SUBNET`**，默认 `/sdcard` 与 `192.168.2.0/24`）。 |
| 约束 | 远程路径假定 **Fedora/RHEL 系 + dnf**；**Debian/apt 未分支**。`verify.sh` 在 `source scripts/.env.verify` 后调用 `ansible-playbook`，子进程继承上述环境变量。 |
| 门控 | **`SKIP_ARMV7=0` 但未配置有效 SSH** 时，01-03 / 01-05 会 **fail**，避免 `run-all` / `full` 在误以为已启用 arm 时静默跳过。 |
| 手工 | 仍可按 [`01-03-armv7-standalone-docker.md`](01-03-armv7-standalone-docker.md)、[`01-05-armv7-nfs服务安装.md`](01-05-armv7-nfs服务安装.md) 全手工走通后在文档中记录环境与结论。 |

## 排障

- **你在找执行命令**：本文为说明/索引；执行入口见 `00-00-构建总览.md` 与 `scripts/README.md`。
- **verify.sh 报错**：先跑 `./scripts/verify.sh preflight`，再根据提示修复 inventory/SSH/变量。