chore: 对齐 00-05 §2 的部署与验证脚本

- 新增 deploy-lab.sh（k3s/longhorn/nginx 铺栈）与 ssh/run-phase2-k3s-on-ylc61-as-jack.sh - verify.sh：flow/preflight、VERIFY_TEARDOWN 默认、注释与 §2 对应 - 更新 smoke-verify、README、.env.verify.example、根 README 与主要 playbook 头注释 - k3s-delete-lab-stacks 标明重度清场语义 Made-with: Cursor
2026-03-26 07:32:08 +08:00
parent 8c43761962
commit 231b6713c4
16 changed files with 294 additions and 67 deletions
--- a/scripts/.env.verify.example
+++ b/scripts/.env.verify.example
@@ -21,12 +21,12 @@ export K3S_SERVER_HOSTNAME="${K3S_SERVER_HOSTNAME:-ylc61}"
 # 与 ansible group_vars 一致，验证磁盘/文档 00-04 时引用
 export K3S_DATA_DIR="${K3S_DATA_DIR:-/storage}"

-# --- Ansible（安装/复验 k3s）---
+# --- Ansible（安装/复验 k3s；对应 docs/00-05 §2 步骤 3）---
 export ANSIBLE_INVENTORY="${ANSIBLE_INVENTORY:-$(pwd)/ansible/inventory.ini}"
-# phase2（run-phase2-k3s-on-ylc61-as-jack.sh 或手工）：
-# 为 true 时先跑 k3s-prepare-storage.yml（须与 group_vars 一致）
+# deploy-lab.sh k3s / ssh/run-phase2-k3s-on-ylc61-as-jack.sh：
+# 为 true 时先跑 k3s-prepare-storage.yml（传 -e k3s_prepare_storage=true；磁盘变量见 group_vars）
 export K3S_PREPARE_STORAGE="${K3S_PREPARE_STORAGE:-false}"
-# phase2 建议在控制节点 ylc61 上执行（本机有 ansible-playbook）；办公机无 ansible 时用 phase2-print 复制命令到 ylc61
+# 建议在控制节点或 Linux 工作机执行 deploy-lab.sh；办公机可用 run-phase2-k3s-on-ylc61-as-jack.sh 触发远端

 # --- SSH 密钥命名（与 scripts/ssh/test-ssh.sh 默认一致；脚本内尚为硬编码路径）---
 # test-ssh 使用：$K3S_SSH_KEY_DIR/${K3S_SSH_KEY_PREFIX}<inventory主机名>
@@ -38,8 +38,9 @@ export SSH_USER="${SSH_USER:-jack}"
 # test-ssh.sh：连接超时秒数（脚本已支持环境变量 TIMEOUT_SEC）
 export TIMEOUT_SEC="${TIMEOUT_SEC:-5}"

-# ---（旧自动验证已下线）---
-# 如果你要重新落地自动化验证，请参考 docs/00-05 的测试框架设计说明。
+# --- 矩阵验证（docs/00-05 §2 步骤 4～6）---
+# ./scripts/verify.sh run | run-all | preflight | flow
+# VERIFY_TEARDOWN（默认 1）、VERIFY_PREFLIGHT_CLUSTER（为 1 时 preflight 额外 kubectl get nodes）

 # --- SSH：第三方验证机 onecloud（不忽略：矩阵里多处依赖「集群外」curl/探测）---
 # 用途示例：02-xx nginx 矩阵从第三方访问 Ingress；01-07 经 onecloud 对 OpenWrt:18080/18443 发 curl；
@@ -49,8 +50,9 @@ export ONECLOUD_SSH="${ONECLOUD_SSH:-ssh -o BatchMode=yes onecloud}"
 # 若需显式密钥，可写完整一行，例如：
 # export ONECLOUD_SSH="ssh -o BatchMode=yes -i ~/.ssh/id_ed25519_onecloud onecloud"

-# --- NFS（03-06）：服务端与导出路径；若需在服务端执行清理命令可填 SSH ---
+# --- NFS（03-06）：verify playbook 使用 NFS_SERVER_IP / NFS_EXPORT_PATH ---
 export NFS_SERVER_HOST="${NFS_SERVER_HOST:-YOUR_NFS_IP_OR_HOSTNAME}"
+export NFS_SERVER_IP="${NFS_SERVER_IP:-$NFS_SERVER_HOST}"
 export NFS_EXPORT_PATH="${NFS_EXPORT_PATH:-/export/k3s}"
 # export NFS_SSH="ssh -o BatchMode=yes root@${NFS_SERVER_HOST}"

@@ -96,8 +98,12 @@ export ARMV7_NFS_SSH="${ARMV7_NFS_SSH:-$ARMV7_SSH}"
 # 01-07 文档中第三方 curl 用 --https-hosts 时的主机列表（逗号分隔，与 VERIFY_TLS_HOSTS 可相同）
 # export OPENWRT_VERIFY_HTTPS_HOSTS="test01.jackadam.top,..."

-# --- 与现有 scripts/*.sh 对照（未列出的脚本不在仓库内）---
+# --- 与 scripts/*.sh 对照 ---
+# verify.sh                           → VERIFY_TEARDOWN, VERIFY_PREFLIGHT_CLUSTER, nginx_entry_base, ANSIBLE_INVENTORY
+# deploy-lab.sh                       → ANSIBLE_INVENTORY, K3S_PREPARE_STORAGE
+# ssh/run-phase2-k3s-on-ylc61-as-jack.sh → LAB_REPO_ROOT, K3S_PREPARE_STORAGE（传远端）
+# ssh/smoke-verify-matrix-on-ylc61.sh   → VERIFY_REPO_ROOT, VERIFY_TEARDOWN, nginx_entry_base
 # cloudflare-delete-acme-challenge-dns.sh → CF_API_TOKEN, ZONE_NAME, ZONE_ID
 # k3s-delete-lab-stacks.sh            → KUBECONFIG
 # ssh/test-ssh.sh                     → TIMEOUT_SEC；密钥路径当前固定为 $HOME/.ssh/id_ed25519_k3s_<host>
-# ssh/setup-k3s-workers-ssh.sh      → 交互 inventory + SSH_USER；可选一次性密码勿写入本文件
+# ssh/setup-k3s-workers-ssh.sh        → 交互 inventory + SSH_USER；可选一次性密码勿写入本文件
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -1,70 +1,85 @@
 # Scripts 总览

-本目录集中维护通用运维脚本。统一约定：**在仓库根目录执行**，使用 `./scripts/...` 路径调用。
+本目录集中维护通用运维脚本。约定：**在仓库根目录执行**，使用 `./scripts/...` 路径调用。
+
+流程说明与「部署 / 验证」分工以 [`docs/00-05-测试与验证框架.md`](../docs/00-05-测试与验证框架.md) **§2 自动化验证流程** 为准；下表与之一一对应。
+
+| §2 步骤 | 含义 | 本仓库入口 |
+|--------|------|------------|
+| 1 接入 | inventory、仓库同步、加载 `.env.verify` | 手工；`verify.sh` / `deploy-lab.sh` 会自动 `source scripts/.env.verify`（若存在） |
+| 2 环境/清理 | 轻量：各 verify 的 teardown；重度：清实验负载 / 重装 K3s | 轻量：`VERIFY_TEARDOWN`（默认 1）；重度：`k3s-delete-lab-stacks.sh`、文档中的 `k3s-uninstall`（**勿**默认进 `run-all`） |
+| 3 部署 | K3s、Longhorn、nginx 矩阵等铺栈 | **`./scripts/deploy-lab.sh`**（`k3s` / `longhorn` / `nginx-matrix` / `nginx-matrix-tls`） |
+| 4～5 断言与收尾 | 按 doc 目标 kubectl/curl；本篇 teardown | **`./scripts/verify.sh`** `run` / `run-all` |
+| 6 一键串联 | 按矩阵顺序跑全部 verify | **`./scripts/verify.sh run-all`** |
+
+辅助命令：
+
+- `./scripts/verify.sh flow` — 打印与 §2 对齐的流程说明（不接 Ansible）。
+- `./scripts/verify.sh preflight` — 检查 `ansible-playbook`、矩阵、`inventory`，并对 `k3s_server` 执行 `ping`；若已装集群可设 `VERIFY_PREFLIGHT_CLUSTER=1` 再执行 `kubectl get nodes`。

 ## 验证编排环境变量（可选）

-复制 [`scripts/.env.verify.example`](.env.verify.example) 为 `scripts/.env.verify` 并填写本机值；**勿提交** `scripts/.env.verify`（已在仓库 `.gitignore` 中忽略）。其中 **`ONECLOUD_SSH`**（默认 `ssh … onecloud`）用于矩阵里**集群外**第三方 curl 等验证，与 `SKIP_*` 无关；**`ARMV7_SSH` / `ARMV7_NFS_SSH`** 用于 `01-03` / `01-05` 实机，同样不属「可忽略」项，与 `SKIP_ARMV7=0` 配对使用。**`ACME_EMAIL`** 供 Traefik ACME（`03-02` / `03-03`）；另有 **`VERIFY_TLS_HOSTS`**、`K3S_SERVER_HOSTNAME`、`TIMEOUT_SEC`（`test-ssh.sh` 已读）、`LONGHORN_NAMESPACE` 等，完整列表与「和现有 `scripts/*.sh` 的对照」见 [`.env.verify.example`](.env.verify.example) 文末注释。加载示例：
+复制 [`scripts/.env.verify.example`](.env.verify.example) 为 `scripts/.env.verify` 并填写本机值；**勿提交** `scripts/.env.verify`（已在仓库 `.gitignore` 中忽略）。
+
+其中 **`ONECLOUD_SSH`** 用于矩阵里**集群外**第三方 curl 等；**`ARMV7_SSH` / `ARMV7_NFS_SSH`** 用于 `01-03` / `01-05` 实机；**`ACME_EMAIL`** 供 Traefik ACME（`03-02` / `03-03`）；另有 **`VERIFY_TLS_HOSTS`**、`K3S_SERVER_HOSTNAME`、`TIMEOUT_SEC`、`LONGHORN_NAMESPACE` 等，完整列表见 [`.env.verify.example`](.env.verify.example) 文末注释。

 ```bash
 set -a && source scripts/.env.verify && set +a
 ```

-## 验证框架状态（自动化已移除）
+## 部署 K3s（推荐在控制节点或 Linux 工作机）

-旧的验证矩阵编排与静态校验 CI 已下线；`docs/00-02-验证矩阵.md` 仍作为“待验证列表/状态记录”，当前以手工验证为准。
-
-如果你要重新落地自动化验证框架，请以设计说明 [`docs/00-05-测试与验证框架.md`](../docs/00-05-测试与验证框架.md) 中的分层与 `doc_id` 映射约定为基线。
-
-### 用 ylc61 跑 Ansible 装 K3s（推荐）
-
-如果办公机（Windows）没有 `ansible-playbook`，有两种方式：
-
-1. 方式 A：把仓库同步到 `ylc61`，然后在 `ylc61` 上直接跑 playbook
+1. 在仓库根（或 `cd ansible` 后改用相对路径）执行 **`./scripts/deploy-lab.sh k3s`**。若需先准备数据盘，在 **本机或 `.env.verify`** 中设 `K3S_PREPARE_STORAGE=true`（会传 `-e k3s_prepare_storage=true` 跑 `k3s-prepare-storage.yml`）。
+2. 办公机无 Ansible 时，可 SSH 到 ylc61 再执行上述命令，或使用：

 ```bash
-sudo dnf install -y ansible    # Fedora；未装过时
-cd ~/实验室建设              # 按你实际路径；若在 /home/jack 则相应 cd
-cd ansible
-# 可选：第二块盘 → /storage 先准备
-# ansible-playbook -i inventory.ini playbooks/k3s-prepare-storage.yml
-ansible-playbook -i inventory.ini playbooks/k3s-init-and-install.yml
-```
-
-2. 方式 B：从办公机一键触发（内部通过 SSH 在 `ylc61` 上以 `jack` 身份执行）
-
-```bash
-# 可选：先准备 /storage
-export K3S_PREPARE_STORAGE=false    # 或 true
+export K3S_PREPARE_STORAGE=false   # 或 true
 ./scripts/ssh/run-phase2-k3s-on-ylc61-as-jack.sh
 ```

-**密钥在 jack**：`inventory.ini` 中私钥路径会随执行用户变化。上述方式会确保在 `ylc61` 以 `jack` 身份运行，避免把私钥解析到 `/root/.ssh/`。
+环境变量 **`LAB_REPO_ROOT`**（仅 SSH 包装脚本使用）可指定远端仓库路径，默认 `/home/jack/实验室建设`。

-## 目录
- `scripts/k3s-delete-lab-stacks.sh`
-  - **按集群里实际资源**遍历删除：用 `kubectl get` 枚举各命名空间下的 Deployment/Service/Ingress/IngressRoute 等再 `kubectl delete`（**不读仓库 YAML 目录**）；默认跳过 `kube-system` 等系统命名空间；`--preview` 只列资源；`--namespaces` 限定 NS；`--with-pvc` / `--with-configmaps` / `--with-secrets`（需 `jq`）按需打开
- `scripts/cloudflare-delete-acme-challenge-dns.sh`
-  - 批量删除 Cloudflare 中 `_acme-challenge` 相关 DNS 记录（ACME 残留）；环境变量或脚本内 `DEFAULT_*` 配置二选一，环境变量优先；`--dry-run` 仅列出不删除
- `scripts/ssh/setup-k3s-workers-ssh.sh`
-  - 为 Ansible 自动化准备 SSH：为所有 k3s 节点配置 jack + root 公钥及每节点私钥（配合 `docs/01-06-节点初始化-ansible-实践.md`）
- `scripts/ssh/test-ssh.sh`
-  - 验证 worker/client SSH key 登录与 sudo 可用性
+**密钥与执行用户**：`inventory.ini` 中私钥路径随执行用户变化；在 ylc61 上以 `jack` 执行可避免解析到 `/root/.ssh/`。
+
+## 验证矩阵（run-all / 抽样 smoke）
+
+```bash
+./scripts/verify.sh preflight
+export nginx_entry_base=http://192.168.2.61
+./scripts/verify.sh run-all
+```
+
+从办公机经 SSH 在远端仓库根跑抽样用例：
+
+```bash
+./scripts/ssh/smoke-verify-matrix-on-ylc61.sh
+```
+
+可用 **`VERIFY_REPO_ROOT`** 指定远端路径（默认 `/home/jack/实验室建设`）。
+
+## 目录与脚本对照
+
+- **`verify.sh`** — 矩阵验收：`flow` / `preflight` / `list` / `run` / `run-all`
+- **`deploy-lab.sh`** — 安装/铺栈：`k3s` / `longhorn` / `nginx-matrix` / `nginx-matrix-tls`
+- **`ssh/run-phase2-k3s-on-ylc61-as-jack.sh`** — 办公机触发远端 `deploy-lab.sh k3s`
+- **`ssh/smoke-verify-matrix-on-ylc61.sh`** — 办公机触发远端若干 `verify.sh run`
+- **`k3s-delete-lab-stacks.sh`** — 按 kubectl 实况清命名空间负载（重度清场，非默认 teardown）
+- **`cloudflare-delete-acme-challenge-dns.sh`** — 清理 CF 上 `_acme-challenge` DNS
+- **`ssh/setup-k3s-workers-ssh.sh`** — 为 K3s 节点预配 SSH（配合 `01-06`）
+- **`ssh/test-ssh.sh`** — 验证 worker 密钥登录与 sudo

 ## 从仓库根执行示例

 ```bash
-# 1) 初始化 worker SSH 密钥（可选）
 ./scripts/ssh/setup-k3s-workers-ssh.sh
-
-# 2) 验证 SSH（建议）
 ./scripts/ssh/test-ssh.sh
-
-# 3) 执行批量部署/配置（示例）
-cd ansible
-ansible-playbook -i inventory.ini playbooks/k3s-init-and-install.yml
+./scripts/deploy-lab.sh k3s
+./scripts/verify.sh preflight
+./scripts/verify.sh run 02-05
 ```

 ## 说明文档

- 主文档入口详见 `docs/00-00-构建总览.md`
+- 验证框架：[`docs/00-05-测试与验证框架.md`](../docs/00-05-测试与验证框架.md)
+- 验证矩阵状态：[`docs/00-02-验证矩阵.md`](../docs/00-02-验证矩阵.md)
+- 主文档入口：`docs/00-00-构建总览.md`（若存在）
--- a/scripts/deploy-lab.sh
+++ b/scripts/deploy-lab.sh
@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# 实验室「正式部署」入口（对应 docs/00-05 §2 步骤 1～3，与 verify.sh 的逐条验收 teardown 不同）。
+# 在仓库根执行：./scripts/deploy-lab.sh <子命令>
+#
+# 步骤对应关系（详见 docs/00-05-测试与验证框架.md §2）：
+#   1 接入 — 本机有 ansible-playbook、inventory 可达；可选加载 scripts/.env.verify
+#   2 前置 — 可选 k3s-prepare-storage（磁盘 → /storage），非 k3s-uninstall 类重度清理
+#   3 部署 — k3s-init-and-install 或其它子命令所列 playbook
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+load_env() {
+  if [[ -f "${ROOT}/scripts/.env.verify" ]]; then
+    set -a
+    # shellcheck disable=SC1091
+    source "${ROOT}/scripts/.env.verify"
+    set +a
+    echo "[OK] 已加载 scripts/.env.verify"
+  fi
+}
+
+usage() {
+  cat <<'EOF'
+用法：scripts/deploy-lab.sh <子命令>
+
+子命令：
+  k3s                 安装/复验 K3s（可选先跑数据盘准备，见环境变量）
+  longhorn            Helm 安装 Longhorn（ansible/playbooks/longhorn-install.yml）
+  nginx-matrix        部署 HTTP nginx 矩阵（ansible/playbooks/nginx-matrix-deploy.yml）
+  nginx-matrix-tls    部署 TLS nginx 矩阵（ansible/playbooks/nginx-matrix-tls-deploy.yml）
+
+环境变量（节选，完整见 scripts/.env.verify.example）：
+  ANSIBLE_INVENTORY     默认 <仓库>/ansible/inventory.ini
+  K3S_PREPARE_STORAGE   为 true 时先执行 k3s-prepare-storage.yml，并传 -e k3s_prepare_storage=true
+
+说明：
+  「矩阵级验收」请用 ./scripts/verify.sh run / run-all；本脚本只做安装/铺栈，不负责按 doc_id 做断言与 teardown。
+EOF
+}
+
+ansible_wrap() {
+  local inv="${ANSIBLE_INVENTORY:-${ROOT}/ansible/inventory.ini}"
+  if [[ ! -f "$inv" ]]; then
+    echo "[ERR] inventory 不存在：$inv" >&2
+    exit 1
+  fi
+  if ! command -v ansible-playbook >/dev/null 2>&1; then
+    echo "[ERR] 未找到 ansible-playbook，请先安装 Ansible" >&2
+    exit 1
+  fi
+  echo "[RUN] ansible-playbook -i $inv $*"
+  ansible-playbook -i "$inv" "$@"
+}
+
+cmd_k3s() {
+  if [[ "${K3S_PREPARE_STORAGE:-false}" == "true" ]]; then
+    ansible_wrap "${ROOT}/ansible/playbooks/k3s-prepare-storage.yml" -e 'k3s_prepare_storage=true'
+  fi
+  ansible_wrap "${ROOT}/ansible/playbooks/k3s-init-and-install.yml"
+}
+
+main() {
+  load_env
+  local sub="${1:-}"
+  case "$sub" in
+    ""|-h|--help) usage ;;
+    k3s) cmd_k3s ;;
+    longhorn) ansible_wrap "${ROOT}/ansible/playbooks/longhorn-install.yml" ;;
+    nginx-matrix) ansible_wrap "${ROOT}/ansible/playbooks/nginx-matrix-deploy.yml" ;;
+    nginx-matrix-tls) ansible_wrap "${ROOT}/ansible/playbooks/nginx-matrix-tls-deploy.yml" ;;
+    *)
+      echo "[ERR] 未知子命令：$sub" >&2
+      usage
+      exit 1
+      ;;
+  esac
+}
+
+main "$@"
--- a/scripts/k3s-delete-lab-stacks.sh
+++ b/scripts/k3s-delete-lab-stacks.sh
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 # 按「集群里实际存在的资源」遍历删除（全部由 kubectl 发现，不读仓库 YAML 目录）
+# 对应 docs/00-05 §2 步骤 2「重度清理」方向的实验室内清场（非 verify.sh 默认 teardown，亦非 k3s-uninstall）。
 # 在任意目录执行均可；建议在仓库根：./scripts/k3s-delete-lab-stacks.sh [选项]
 #
 # 默认跳过系统命名空间：kube-system、kube-public、kube-node-lease
--- a/scripts/ssh/run-phase2-k3s-on-ylc61-as-jack.sh
+++ b/scripts/ssh/run-phase2-k3s-on-ylc61-as-jack.sh
@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# 在办公机执行：经 SSH 在控制节点 ylc61 上跑「K3s 安装/复验」部署流水线。
+# 对应 docs/00-05 §2 步骤 1（接入）+ 3（部署）中的 k3s 路径；与 verify.sh 矩阵验收分离。
+#
+# 依赖：本机可 ssh ylc61（BatchMode）；远端仓库路径存在且含 scripts/deploy-lab.sh。
+set -euo pipefail
+
+REMOTE_ROOT="${LAB_REPO_ROOT:-/home/jack/实验室建设}"
+# 将当前 shell 中的 K3S_PREPARE_STORAGE 传到远端（未设置则默认 false）
+KS_PREP="${K3S_PREPARE_STORAGE:-false}"
+
+exec ssh -o BatchMode=yes ylc61 bash -lc "
+  set -euo pipefail
+  cd '${REMOTE_ROOT}'
+  chmod +x scripts/deploy-lab.sh 2>/dev/null || true
+  if [[ -f scripts/.env.verify ]]; then
+    set -a
+    # shellcheck disable=SC1091
+    source scripts/.env.verify
+    set +a
+  fi
+  # 办公机传入的 K3S_PREPARE_STORAGE 覆盖远端 .env 中的默认
+  export K3S_PREPARE_STORAGE='${KS_PREP}'
+  ./scripts/deploy-lab.sh k3s
+"
--- a/scripts/ssh/smoke-verify-matrix-on-ylc61.sh
+++ b/scripts/ssh/smoke-verify-matrix-on-ylc61.sh
@@ -1,6 +1,35 @@
 #!/usr/bin/env bash
-# 从办公机 Git Bash 执行：经 ssh 在 ylc61 上 smoke 跑样板 doc_id。
+# 从办公机 Git Bash 执行：SSH 到 ylc61 上跑若干样板 verify（对应 docs/00-05 §2 步骤 4～6 的抽样）。
+# 步骤 1～3 需已满足：远端仓库路径正确、已 deploy K3s、可选 scripts/.env.verify。
+#
+# 环境变量：
+#   VERIFY_REPO_ROOT  远端仓库根目录（默认 /home/jack/实验室建设）
+#   VERIFY_TEARDOWN / nginx_entry_base / nodejs_entry_base  传给远端 verify.sh
 set -euo pipefail

-exec ssh -o BatchMode=yes ylc61 'bash -lc "cd /home/jack && chmod +x scripts/verify.sh && export VERIFY_TEARDOWN=${VERIFY_TEARDOWN:-1} && export nginx_entry_base=${nginx_entry_base:-http://192.168.2.61} && export nodejs_entry_base=${nodejs_entry_base:-http://192.168.2.61} && ./scripts/verify.sh run 02-05 && ./scripts/verify.sh run 03-05 && ./scripts/verify.sh run 03-07 && ./scripts/verify.sh run 04-01"'
+REMOTE_ROOT="${VERIFY_REPO_ROOT:-/home/jack/实验室建设}"
+TEARDOWN="${VERIFY_TEARDOWN:-1}"
+NGX="${nginx_entry_base:-http://192.168.2.61}"
+NODE="${nodejs_entry_base:-http://192.168.2.61}"

+exec ssh -o BatchMode=yes ylc61 bash -lc "
+  set -euo pipefail
+  cd '${REMOTE_ROOT}'
+  chmod +x scripts/verify.sh 2>/dev/null || true
+  export VERIFY_TEARDOWN='${TEARDOWN}'
+  export nginx_entry_base='${NGX}'
+  export nodejs_entry_base='${NODE}'
+  if [[ -f scripts/.env.verify ]]; then
+    set -a
+    # shellcheck disable=SC1091
+    source scripts/.env.verify
+    set +a
+  fi
+  export VERIFY_TEARDOWN='${TEARDOWN}'
+  export nginx_entry_base='${NGX}'
+  export nodejs_entry_base='${NODE}'
+  ./scripts/verify.sh run 02-05
+  ./scripts/verify.sh run 03-05
+  ./scripts/verify.sh run 03-07
+  ./scripts/verify.sh run 04-01
+"
--- a/scripts/verify.sh
+++ b/scripts/verify.sh
@@ -1,11 +1,19 @@
 #!/usr/bin/env bash
-# Ansible 验证入口：以 docs/00-02-验证矩阵.md 为执行清单，逐个 doc_id 执行 verify playbook（deploy→verify→teardown）。
-# 推荐在 ylc61（控制节点）仓库根执行。
+# 验证矩阵自动化入口（对应 docs/00-05 §2「自动化验证流程」步骤 4～6 的一键串联）：
+#   4 断言 — 各 verify/XX-YY.yml 内 kubectl / curl / helm 等
+#   5 收尾 — 默认 VERIFY_TEARDOWN=1 做本篇资源清理（非整集群卸载）
+#   6 串联 — run-all 按 docs/00-02-验证矩阵.md 顺序 fail-fast
+#
+# 步骤 1～3（接入、环境/轻量清理、部署）由操作者或 scripts/deploy-lab.sh 完成；本脚本不执行 k3s-uninstall。
+# 推荐在 Linux 工作机（如 ylc65）或控制节点仓库根执行。
 set -euo pipefail

 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 MATRIX_MD="${ROOT}/docs/00-02-验证矩阵.md"

+# 默认与 §2 一致：验证后清理临时资源
+export VERIFY_TEARDOWN="${VERIFY_TEARDOWN:-1}"
+
 load_env() {
  if [[ -f "${ROOT}/scripts/.env.verify" ]]; then
    set -a
@@ -14,6 +22,7 @@ load_env() {
    set +a
    echo "[OK] 已加载 scripts/.env.verify"
  fi
+  export VERIFY_TEARDOWN="${VERIFY_TEARDOWN:-1}"
 }

 parse_doc_ids_from_matrix() {
@@ -21,7 +30,6 @@ parse_doc_ids_from_matrix() {
    echo "[ERR] matrix 不存在：${MATRIX_MD}" >&2
    exit 1
  fi
-  # 从矩阵中提取形如 `XX-YY-*.md` 的文件名，输出 XX-YY（按出现顺序）
  # shellcheck disable=SC2016
  awk '
    match($0, /`[0-9][0-9]-[0-9][0-9]-[^`]+\.md`/) {
@@ -32,23 +40,72 @@ parse_doc_ids_from_matrix() {
  ' "${MATRIX_MD}"
 }

+print_flow() {
+  cat <<EOF
+与 docs/00-05-测试与验证框架.md §2「自动化验证流程（一般步骤）」对应：
+
+  1 接入目标环境     inventory + 仓库同步；可选 source scripts/.env.verify（本脚本 run/run-all 会自动加载）
+  2 环境与前置清理   轻量：各 verify playbook 的 teardown；重度 k3s 重装勿混进 run-all
+  3 部署             ./scripts/deploy-lab.sh k3s | longhorn | nginx-matrix* 或手工 ansible-playbook
+  4 断言             本脚本 run <XX-YY> / run-all → ansible/playbooks/verify/<XX-YY>.yml
+  5 收尾与记录       VERIFY_TEARDOWN；矩阵状态见 docs/00-02-验证矩阵.md（建议手工写回）
+  6 一键串联         $0 run-all
+
+相关脚本：deploy-lab.sh（安装/铺栈）、ssh/run-phase2-k3s-on-ylc61-as-jack.sh（办公机触发远端 deploy k3s）
+EOF
+}
+
+preflight() {
+  local inv="${ANSIBLE_INVENTORY:-${ROOT}/ansible/inventory.ini}"
+  if ! command -v ansible-playbook >/dev/null 2>&1; then
+    echo "[ERR] 未找到 ansible-playbook" >&2
+    exit 1
+  fi
+  [[ -f "${MATRIX_MD}" ]] || { echo "[ERR] 缺少验证矩阵：${MATRIX_MD}" >&2; exit 1; }
+  [[ -f "$inv" ]] || { echo "[ERR] inventory 不存在：$inv" >&2; exit 1; }
+
+  echo "[RUN] ansible k3s_server -m ping"
+  ansible k3s_server -i "$inv" -m ping
+
+  if [[ "${VERIFY_PREFLIGHT_CLUSTER:-0}" == "1" ]]; then
+    echo "[RUN] kubectl get nodes（控制节点，需已安装 K3s）"
+    ansible k3s_server -i "$inv" -b -m ansible.builtin.shell -a \
+      'KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl get nodes' \
+      || {
+        echo "[WARN] 集群侧检查失败：若尚未 deploy k3s，可忽略；装好后设 VERIFY_PREFLIGHT_CLUSTER=1 再测" >&2
+        exit 1
+      }
+  else
+    echo "[TIP] 跳过 kubectl 检查。已装 K3s 时可执行：VERIFY_PREFLIGHT_CLUSTER=1 $0 preflight"
+  fi
+  echo "[OK] preflight 通过"
+}
+
 usage() {
  cat <<'EOF'
 用法：scripts/verify.sh <命令> [...]

 命令：
-  list                  从验证矩阵列出 doc_id
-  run <XX-YY>           运行指定 doc_id（执行 ansible/playbooks/verify/<XX-YY>.yml）
+  flow                  打印与 docs/00-05 §2 对齐的「验证流程」说明（不接 Ansible）
+  preflight             检查 ansible-playbook、矩阵与 inventory；对 k3s_server 做 ping
+                          若 VERIFY_PREFLIGHT_CLUSTER=1，额外 kubectl get nodes（未装集群会失败）
+  list                  从验证矩阵列出 doc_id（顺序同 run-all）
+  run <XX-YY>           运行指定 doc_id（ansible/playbooks/verify/<XX-YY>.yml）
  run-all               按验证矩阵顺序运行全部 doc_id（fail-fast）

 环境变量：
-  VERIFY_TEARDOWN=1     验证后清理（默认 1）
-  nginx_entry_base      例如 http://192.168.2.61（用于 02-05）
-  nodejs_entry_base     例如 http://192.168.2.61（用于 04-01）
+  VERIFY_TEARDOWN=1         验证后清理本篇资源（默认 1，对应 §2 轻量 teardown）
+  VERIFY_PREFLIGHT_CLUSTER  为 1 时 preflight 额外执行 kubectl get nodes
+  ANSIBLE_INVENTORY         默认 <仓库>/ansible/inventory.ini
+  nginx_entry_base          例如 http://192.168.2.61（02-xx / 03-02 等 HTTP 校验）
+  nodejs_entry_base         例如 http://192.168.2.61（04-01）
+
+与「部署」分工：安装 K3s / Longhorn / nginx 铺栈请用 ./scripts/deploy-lab.sh；矩阵验收请用本脚本。

 示例：
+  ./scripts/verify.sh flow
+  ./scripts/verify.sh preflight
  export nginx_entry_base=http://192.168.2.61
-  export VERIFY_TEARDOWN=1
  ./scripts/verify.sh run 02-05
 EOF
 }
@@ -74,6 +131,8 @@ main() {
  local cmd="${1:-}"
  case "$cmd" in
    ""|-h|--help) usage ;;
+    flow) print_flow ;;
+    preflight) preflight ;;
    list)
      parse_doc_ids_from_matrix
      ;;
@@ -98,4 +157,3 @@ main() {
 }

 main "$@"
-