日常更新

project-context.md

@@ -19,7 +19,7 @@ existing_patterns_found:
 
 ---
 
-## 技术栈与版本（来自 `docs/00-04-部署环境说明.md`）
+## 技术栈与版本（来自 `docs/00-02-部署环境说明.md`）
 
 - **操作系统（验证环境）**：Fedora 43 Server（CoreOS）
 - **K3s**：v1.34.5+k3s1
@@ -38,26 +38,28 @@ existing_patterns_found:
   - 文档中引用清单路径时，必须引用 `ansible/files/<doc_id>/...`（禁止在 `docs/` 内复制粘贴出第二份 YAML）。
   - 例外：非 YAML 的源码/生成器/模板（如 `scripts/gen-*.py`）不受此条限制。
 - **执行器唯一真源（强约束）**：`ansible/playbooks/verify/<doc_id>.yml` 为该 `doc_id` 的唯一 Ansible 入口。
-  - `scripts/verify.sh` 只基于 `ansible/playbooks/verify/` 自动发现并执行（缺 playbook 必须 fail-fast）。
-- **存在性校验**：`scripts/validate_matrix_playbooks.py`（历史文件名保留）只做 “`verify/<doc_id>.yml` ↔ `docs/<doc_id>-*.md` 存在性” 校验。
+  - `ansible/bin/verify.sh` 只基于 `ansible/playbooks/verify/` 自动发现并执行（缺 playbook 必须 fail-fast）。
+- **存在性校验**：`ansible/tools/validate_matrix_playbooks.py`（历史文件名保留）只做 “`verify/<doc_id>.yml` ↔ `docs/<doc_id>-*.md` 存在性” 校验。
 - **目录命名硬约束**：`ansible/files/` 下仅允许 `XX-YY/`（只用 `doc_id`），内部用文件名区分；不再允许 `XX-YY-slug/` 或 `XX-YY-xxx/`。
 
 ---
 
 ## doc_id 与验证框架（必须遵循）
 
+**以 `doc_id` 为唯一主键（相对 BMad / 规划命名）**：凡与**验收入口、清单真源、自动化范围**对齐时，以执行域 **`doc_id`（`XX-YY`）** 及 **`ansible/playbooks/verify/<doc_id>.yml`** 为准。**BMad Epic/Story 编号**、`_bmad-output/implementation-artifacts/` 下任意 `*.md` 文件名（如 `4-1-acme-real-pass.md`、`01-02-baseline-verify-oc.md`）均为**项目管理或补充叙事**；其中 **`stories-by-doc/story-doc-<doc_id>.md`** 与 `doc_id` **一一对应**，为按 doc_id 全覆盖的 **[CS] 索引**；**`*-baseline-verify-oc.md`** 等同 `doc_id` 的**增强 backlog**，**不替代** `verify/<doc_id>.yml` 与 `docs/<doc_id>-*.md` 的工程真源。
+
 - **doc_id 规则**：`docs/<doc_id>-*.md` 中的 `<doc_id>` 固定为 `XX-YY`。
 - **编号语义（极简、一目了然）**：
   - **`XX=00`**：纯文档域（框架/说明/索引/备忘），不要求执行器，且**不参与自动验证**。
   - **`XX>0 且 YY=00`**：系列入口/说明页，不要求执行器，且**不参与自动验证**。
   - **`XX>0 且 YY>0`**：必须至少有一种执行器（见下）。
-- **自动验证范围（强约束）**：仅 `XX>0 且 YY>0` 的文档进入 `scripts/verify.sh` 自动验证范围。
+- **自动验证范围（强约束）**：仅 `XX>0 且 YY>0` 的文档进入 `ansible/bin/verify.sh` 自动验证范围。
 - **执行器判定口径（不新增关系文件）**：
-  - **Ansible 执行器**：存在 `ansible/playbooks/verify/<doc_id>.yml` 且可 `./scripts/verify.sh run <doc_id>`。
+  - **Ansible 执行器**：存在 `ansible/playbooks/verify/<doc_id>.yml` 且可 `./ansible/bin/verify.sh run <doc_id>`（仓库根简写：`./scripts/cs <doc_id>`，与前者等价）。
   - **脚本/SSH 执行器**：文档 TL;DR 写清入口命令（`./scripts/...`），且脚本存在、用退出码表达成功/失败。
 - **统一入口**：
-  - `scripts/deploy-lab.sh`：铺栈/安装入口（默认保留资源：`DEPLOY_VERIFY_TEARDOWN=0`）。
-  - `scripts/verify.sh`：按 `doc_id` 验收入口（默认清理：`VERIFY_TEARDOWN=1`）。
+  - `ansible/bin/deploy-lab.sh`：铺栈/安装入口（默认保留资源：`DEPLOY_VERIFY_TEARDOWN=0`）。
+  - `ansible/bin/verify.sh`：按 `doc_id` 验收入口（默认清理：`VERIFY_TEARDOWN=1`）。
 - **fail-fast（执行域）**：`verify.sh run <doc_id>` 对 `XX>0 且 YY>0` 条目，若缺少 `ansible/playbooks/verify/<doc_id>.yml` 必须直接失败。
 
 ---
@@ -66,18 +68,29 @@ existing_patterns_found:
 
 - **默认安全**：`verify.sh run <doc_id>` 默认应只做“验收”或“轻量可逆操作”。
 - **重操作必须显式开关**（典型：分区/格式化、全集群安装、TLS 矩阵铺栈等）：
-  - `01-06.yml`：`k3s_do_prepare_storage=true` / `k3s_do_install=true`
+  - `01-05.yml`：`k3s_do_prepare_storage=true` / `k3s_do_install=true`
   - `03-02.yml`：`nginx_matrix_tls_enable=true`（TLS 矩阵铺栈/清理仍用 `mode=deploy|cleanup`）
   - `03-05.yml`：`local_path_apply_lab_config=true`
-- **gate 语义**：外部依赖未满足可 `meta: end_play` 跳过，但必须输出可 grep 的 `[GATE] ...` 信息，避免“看似通过”。
+- **gate / skip 语义**（`ansible/bin/verify.sh` 仅把 **`[GATE]`** 计为 `result=gated`）：
+  - **`[GATE]`**：外部依赖或硬前置未满足，**本 doc 目标验收未执行**（如缺 `NFS_SERVER_IP`、缺 `nodejs-demo-tls`、缺 `CF_TUNNEL_TEST_URL`、缺 `ACME_EMAIL` 等）；必须保留可 grep 行，避免“看似全验过”。
+  - **`[SKIP]`**：**可选段**未开启（如 `k3s_do_install=false`、`nginx_matrix_tls_enable=false`），但**同一 playbook 后续 play 仍会跑**基线验收；不计入 gated， playbook 成功时 OC 为 `verified`。
 
 ---
 
 ## 环境变量与密钥安全（强约束）
 
-- **永不提交真实环境变量文件**：`scripts/.env.verify`（仓库 `.gitignore` 已忽略）
-- **仅提交模板**：`scripts/.env.verify.example`
-- `scripts/.env.verify` 可能包含外部系统 token/凭据（Cloudflare、WebDAV 等），任何自动化/文档都应默认它只存在于本机
+- **永不提交真实环境变量文件**：`ansible/env/.env.verify`（仓库 `.gitignore` 已忽略）
+- **仅提交模板**：`ansible/env/.env.verify.example`
+- `ansible/env/.env.verify` 可能包含外部系统 token/凭据（Cloudflare、WebDAV 等），任何自动化/文档都应默认它只存在于本机
+
+### `.env.verify` 变量组织（与 doc_id / 真源对齐）
+
+- **按 doc_id 分节**：`ansible/env/.env.verify` / `.env.verify.example` 以 **`# --- XX-YY … ---`** 小节组织变量（与 `docs/XX-YY`、playbook `lookup('env')` 对齐）；**`SKIP_*` 写在对应 doc 小节内**（如 `SKIP_ARMV7` 与 01-03/01-04 的 `ARMV7_*` 同块，`SKIP_HA` / `SKIP_GITOPS` 在 03-08/03-09 并标 **可选·预留**）。文件头 **集中式 doc_id 索引** 可后续再补；标注 **预留** 的键当前 playbook **未读取**，仅备忘或手工对照。
+- **文件约定**：只写 `KEY=VALUE`（不写默认展开、命令替换等执行逻辑）；入口脚本用 `set -a; source ...; set +a` 导出；细则以 `ansible/env/.env.verify` 文件头注释为准。
+- **推荐填写顺序**（与 `ansible/env/.env.verify` 小节自上而下一致）：**SSH** → **Ansible（控制端 inventory/tmp）** → **`01-01`～`01-06` 按编号**（其中 **`01-05`** 含 `K3S_PREPARE_STORAGE`、`K3S_DO_*`；紧接 **`deploy-lab.sh`**；**`01-06`** `WORKSTATION_SSH` → 推荐 **Linux 工作机 `ylc65`**）→ **验证入口与 preflight（02-xx / 04-xx）** → **`03-08` / `03-09` 及后续 03-xx、04-xx**（各节内 **单独** 标「可选」的 `SKIP_*` 勿混堆）
+- **`K3S_SERVER_HOSTNAME` / `K3S_DATA_DIR`**：
+  - **`docs/01-01-k3s-控制节点含traefik.md`** 与 **`docs/01-02-k3s-工作节点.md`** 共用：`K3S_SERVER_HOSTNAME` 为控制面短主机名（与 inventory 中 `k3s_server` 一致，工作节点手工 `K3S_URL` 指向该节点 `:6443`）；`K3S_DATA_DIR` 为各节点一致的 k3s **`--data-dir`**（与 **`ansible/group_vars/all.yml`** 中 **`k3s_data_dir`** 一致），供脚本与人工对齐。
+  - **执行真源**：`ansible/playbooks/verify/01-01.yml` 以**节点上** `kubectl`/kubeconfig 为准；**不要求** playbook 通过 `lookup('env', ...)` 读取这两项，避免误以为 01-01 验收依赖 `.env` 中必填此二键。
 
 ---
 
@@ -89,8 +102,8 @@ existing_patterns_found:
   - **YAML 唯一真源（强约束）**：`ansible/files/**`
   - `docs/`：说明/操作手册/验收判据（不得复制出第二套 YAML 真源）
 - **入口**：
-  - `scripts/deploy-lab.sh`：铺栈（默认保留资源，便于持续使用）
-  - `scripts/verify.sh`：按 doc_id 验收（`list/run/run-all/full`；默认清理本篇临时资源）
+  - `ansible/bin/deploy-lab.sh`：铺栈（默认保留资源，便于持续使用）
+  - `ansible/bin/verify.sh`：按 doc_id 验收（`list/run/run-all/full`；默认清理本篇临时资源）
 
 ### 规则 0.1：维护者备忘的归位（替代 docs/00-06）
 
@@ -100,7 +113,7 @@ existing_patterns_found:
 - **Ansible shell 使用口径**：
   - “分支探测/兼容性场景”可用 `failed_when: false`；但后续必须有明确断言，避免“静默失败”。
   - 清理类任务允许 `failed_when: false`，但应 `register` 并输出关键 rc/stdout/stderr（便于审计与排障）。
-  - 优先保持 `verify/<doc_id>.yml` 轻编排；高重复模式应收敛到 `ansible/playbooks/verify/tasks/` 共享片段，避免模板漂移。
+  - 优先保持 `verify/<doc_id>.yml` 轻编排；高重复模式应收敛到 `ansible/roles/verify_common/`（role 复用），避免模板漂移。
 - **API/版本兼容性复核建议**：升级 K3s/Traefik 大版本后，至少复核一次：\n+  - `Ingress` API（`networking.k8s.io/v1`）字段结构（尤其 `pathType`、backend 端口）\n+  - Traefik CRD（`IngressRoute`/`Middleware`）是否仍存在且版本一致\n+  - K3s `HelmChartConfig`（`helm.cattle.io/v1`）行为是否变化\n+  - Longhorn 与 K3s 版本兼容（升级前对照 Longhorn support matrix）
 
 ### 规则 1：`doc_id` / verify 目录 / 解析器（防误触）
@@ -128,7 +141,7 @@ existing_patterns_found:
   - HTTP：`curl` 返回码 + 关键响应标记（例如 `X-Backend`、body contains）
   - TLS：必须包含 SNI/证书链验证信号（如 `curl --resolve`/`openssl s_client` 关键字段），仅 `rollout` 不足以标 ✅
 - **明确执行位置**：
-  - 若目标是“集群外链路”，必须经 `ONECLOUD_SSH`（或等价第三方机）执行探测；仅控制节点自测不足以标 ✅
+  - 若目标是“集群外链路”，必须经 `WORKSTATION_SSH`（推荐 **Linux 工作机** `ylc65`，非 onecloud/arm 实验机）执行探测；仅控制节点自测不足以标 ✅
 - **资源清理策略说明**：
   - 若 `VERIFY_TEARDOWN=0` 保留现场调试，文档需写明（否则容易污染后续用例，导致“假通过/假失败”）
 - **外部依赖说明**：
@@ -139,7 +152,7 @@ existing_patterns_found:
 ### 规则 3：执行位置与“集群外视角”（防自测冒充真实路径）
 
 - 默认约定：在 `k3s_server`（如 ylc61）执行 `kubectl/helm/curl`（`KUBECONFIG=/etc/rancher/k3s/k3s.yaml`）。
-- 若用例声明需要“集群外/第三方机”视角（例如家庭网络真实访问路径、OpenWrt 入口、外部 curl），必须显式经 `ONECLOUD_SSH`（或等价变量）执行探测：
+- 若用例声明需要“集群外/第三方机”视角（例如家庭网络真实访问路径、OpenWrt 入口、外部 curl），必须显式经 `WORKSTATION_SSH`（默认语义：**Linux 工作机**）执行探测：
   - **不得**用“控制节点本机 curl”替代“第三方机 curl”并仍标记为已验证
 
 ### 规则 4：verify playbook 结构与可靠性约定（可复制模式）
@@ -160,12 +173,12 @@ existing_patterns_found:
 
 ### 规则 6：密钥与敏感信息（强约束）
 
-- `scripts/.env.verify` 只允许本机存在，**永不提交**；仓库只保留 `scripts/.env.verify.example`（`.gitignore` 已忽略 `scripts/.env.verify`）。
-- inventory 若声明 `ansible_ssh_private_key_file`，控制端必须确保文件存在且权限仅所有者可读（建议 600/400）；否则应在 preflight 阶段直接失败（见 `scripts/lib-ansible-lab.sh` 的检查逻辑）。
+- `ansible/env/.env.verify` 只允许本机存在，**永不提交**；仓库只保留 `ansible/env/.env.verify.example`（`.gitignore` 已忽略 `ansible/env/.env.verify`）。
+- inventory 若声明 `ansible_ssh_private_key_file`，控制端必须确保文件存在且权限仅所有者可读（建议 600/400）；否则应在 preflight 阶段直接失败（见 `ansible/lib/lib-ansible-lab.sh` 的检查逻辑）。
 
 ### 规则 7：验证环境基线（避免“跑得通但不复现”）
 
-- 验证环境的机器角色与约定（例如 `ylc65` 仅作为 Ansible 控制端，不是 K3s 节点）以 `docs/00-04-部署环境说明.md` 为准；新增文档/用例若依赖“在哪台机器执行”，必须写清。
+- 验证环境的机器角色与约定（例如 `ylc65` 仅作为 Ansible 控制端，不是 K3s 节点）以 `docs/00-02-部署环境说明.md` 为准；新增文档/用例若依赖“在哪台机器执行”，必须写清。
 - `ansible/group_vars/all.yml` 中的关键默认值（如 `k3s_data_dir=/storage`、`k3s_verify_storage_mount=true`、`k3s_manage_firewalld=true`、CoreDNS forward）会影响大量文档与用例，修改这些值相当于“改了实验室契约”，应同步更新文档并回退相关条目的验证状态。
 
 ### 规则 8：Ansible 控制端连接约定（实验室特化）