--- project_name: "Deploy-Laboratory" user_name: "Jack" date: "2026-03-26" sections_completed: - discovery - technology_stack - critical_implementation_rules existing_patterns_found: naming_and_ids: true truth_sources: true verify_framework: true gating_and_noop: true --- ## 项目上下文（给 AI Agent 的实现规则底座） 本文件用于沉淀本仓库中 **不直观但非常关键** 的约定与模式，避免 AI Agent 在实现/改动代码或文档时走偏。 --- ## 技术栈与版本（来自 `docs/00-02-部署环境说明.md`） - **操作系统（验证环境）**：Fedora 43 Server（CoreOS） - **K3s**：v1.34.5+k3s1 - **Ansible**：ansible-core 2.18 - **控制端依赖（典型）**：Git、OpenSSH client、Bash、curl（用于在工作机/控制节点执行 `ansible-playbook` 与仓库脚本） - **配置入口**： - `ansible/ansible.cfg`：已关闭 `host_key_checking`（实验室环境约定） - `ansible/group_vars/all.yml`：k3s/Longhorn/防火墙等关键默认参数 --- ## 仓库结构与“真源”约定 - **文档入口**：`README.md` → `docs/00-00-构建总览.md` - **YAML/配置唯一真源（强约束）**：`ansible/files/**` 为本仓库 Kubernetes YAML / Helm values / 示例配置的**唯一真源**。 - 文档中引用清单路径时，必须引用 `ansible/files//...`（禁止在 `docs/` 内复制粘贴出第二份 YAML）。 - 例外：非 YAML 的源码/生成器/模板（如 `scripts/gen-*.py`）不受此条限制。 - **执行器唯一真源（强约束）**：`ansible/playbooks/verify/.yml` 为该 `doc_id` 的唯一 Ansible 入口。 - `ansible/bin/verify.sh` 只基于 `ansible/playbooks/verify/` 自动发现并执行（缺 playbook 必须 fail-fast）。 - **存在性校验**：`ansible/tools/validate_matrix_playbooks.py`（历史文件名保留）只做 “`verify/.yml` ↔ `docs/-*.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/.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-.md`** 与 `doc_id` **一一对应**，为按 doc_id 全覆盖的 **[CS] 索引**；**`*-baseline-verify-oc.md`** 等同 `doc_id` 的**增强 backlog**，**不替代** `verify/.yml` 与 `docs/-*.md` 的工程真源。 - **doc_id 规则**：`docs/-*.md` 中的 `` 固定为 `XX-YY`。 - **编号语义（极简、一目了然）**： - **`XX=00`**：纯文档域（框架/说明/索引/备忘），不要求执行器，且**不参与自动验证**。 - **`XX>0 且 YY=00`**：系列入口/说明页，不要求执行器，且**不参与自动验证**。 - **`XX>0 且 YY>0`**：必须至少有一种执行器（见下）。 - **自动验证范围（强约束）**：仅 `XX>0 且 YY>0` 的文档进入 `ansible/bin/verify.sh` 自动验证范围。 - **执行器判定口径（不新增关系文件）**： - **Ansible 执行器**：存在 `ansible/playbooks/verify/.yml` 且可 `./ansible/bin/verify.sh run `（仓库根简写：`./scripts/cs `，与前者等价）。 - **脚本/SSH 执行器**：文档 TL;DR 写清入口命令（`./scripts/...`），且脚本存在、用退出码表达成功/失败。 - **统一入口**： - `ansible/bin/deploy-lab.sh`：铺栈/安装入口（默认保留资源：`DEPLOY_VERIFY_TEARDOWN=0`）。 - `ansible/bin/verify.sh`：按 `doc_id` 验收入口（默认清理：`VERIFY_TEARDOWN=1`）。 - **fail-fast（执行域）**：`verify.sh run ` 对 `XX>0 且 YY>0` 条目，若缺少 `ansible/playbooks/verify/.yml` 必须直接失败。 --- ## gate / 开关（避免误触发重操作） - **默认安全**：`verify.sh run ` 默认应只做“验收”或“轻量可逆操作”。 - **重操作必须显式开关**（典型：分区/格式化、全集群安装、TLS 矩阵铺栈等）： - `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 / 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`。 --- ## 环境变量与密钥安全（强约束） - **永不提交真实环境变量文件**：`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` 中必填此二键。 --- ## Critical Implementation Rules ### 规则 0：本仓库不是“应用代码仓库”，优先保证可重复验证与真源一致 - **真源**： - **YAML 唯一真源（强约束）**：`ansible/files/**` - `docs/`：说明/操作手册/验收判据（不得复制出第二套 YAML 真源） - **入口**： - `ansible/bin/deploy-lab.sh`：铺栈（默认保留资源，便于持续使用） - `ansible/bin/verify.sh`：按 doc_id 验收（`list/run/run-all/full`；默认清理本篇临时资源） ### 规则 0.1：维护者备忘的归位（替代 docs/00-06） 将“仓库审查结论/维护者备忘”收敛在本文件，避免在 `docs/00-*` 入口层长期堆积噪音（`docs/00-06-仓库审查备忘.md` 已移除）。以下为保留的最小结论集： - **破坏性操作隔离**：磁盘分区/格式化、换 CNI、HA 切换等必须 gate，且默认不进入 `verify.sh full/run-all` 主线（见规则 5）。 - **Ansible shell 使用口径**： - “分支探测/兼容性场景”可用 `failed_when: false`；但后续必须有明确断言，避免“静默失败”。 - 清理类任务允许 `failed_when: false`，但应 `register` 并输出关键 rc/stdout/stderr（便于审计与排障）。 - 优先保持 `verify/.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 目录 / 解析器（防误触） - `doc_id` 固定为 `XX-YY`（来自 `docs/XX-YY-*.md` 文件名），`verify.sh run ` 必须存在 `ansible/playbooks/verify/.yml`，否则 **fail-fast**。 ### 规则 2：gate / ✅ 的“证据标准”（防“看似通过”） - **禁止“通用 noop 模板”**：每个 `verify/.yml` 必须自包含并体现该文档目标的断言；不得用“仅存在性检查”冒充验收。 - **gate**：外部依赖未满足时允许跳过 apply/断言，但必须满足： - playbook 退出码可为 0（表示“框架跑通/条件不足跳过”） - 文档中应保持 **⚠️**（不可标 ✅） - teardown 必须“安全”：仅在 gate 通过且 manifest/资源确实存在时才执行 delete，且删除失败不得导致整条用例 fail-fast - **✅ 已验证** 的最小证据建议（写在文档备注里）： - 说明是 **自动化实测**（deploy+verify+teardown）还是 **noop/gate**（后者不得 ✅） - 说明是否包含 **第三方/集群外视角**（见规则 3） ### 规则 2.1：✅ 已验证的“硬门槛”（建议逐步收敛为统一口径） 将条目从 **⚠️/❓ → ✅** 时，建议满足下列最小门槛（能写进 `verify/.yml` 的尽量写进 playbook，写不进的写在文档备注并注明“手工”）： - **至少 1 条集群侧断言**（非存在性）： - 例如：`kubectl rollout status` 成功、PVC `Bound`、Pod 就绪、关键 CRD/资源 `Established/Ready` 等 - **至少 1 条入口/可用性断言**（与该文档目标一致）： - HTTP：`curl` 返回码 + 关键响应标记（例如 `X-Backend`、body contains） - TLS：必须包含 SNI/证书链验证信号（如 `curl --resolve`/`openssl s_client` 关键字段），仅 `rollout` 不足以标 ✅ - **明确执行位置**： - 若目标是“集群外链路”，必须经 `WORKSTATION_SSH`（推荐 **Linux 工作机** `ylc65`，非 onecloud/arm 实验机）执行探测；仅控制节点自测不足以标 ✅ - **资源清理策略说明**： - 若 `VERIFY_TEARDOWN=0` 保留现场调试，文档需写明（否则容易污染后续用例，导致“假通过/假失败”） - **外部依赖说明**： - 若依赖 Cloudflare/ACME/NFS/WebDAV 等外部系统，文档需写明依赖已满足与证据（例如：已创建 secret、已开公网端口、已配置 DNS） > 目标：让 ✅ 的含义从“脚本退出码 0”收敛为“有可复现证据的实测通过”。 ### 规则 3：执行位置与“集群外视角”（防自测冒充真实路径） - 默认约定：在 `k3s_server`（如 ylc61）执行 `kubectl/helm/curl`（`KUBECONFIG=/etc/rancher/k3s/k3s.yaml`）。 - 若用例声明需要“集群外/第三方机”视角（例如家庭网络真实访问路径、OpenWrt 入口、外部 curl），必须显式经 `WORKSTATION_SSH`（默认语义：**Linux 工作机**）执行探测： - **不得**用“控制节点本机 curl”替代“第三方机 curl”并仍标记为已验证 ### 规则 4：verify playbook 结构与可靠性约定（可复制模式） - 推荐三段式：**deploy → verify → teardown**（或多个 play 分段），并遵守： - rollout/就绪检查要带合理 `--timeout` - HTTP 探测要有连接/总超时，并对关键判据做显式断言（例如 nginx 矩阵用 `X-Backend`） - teardown 默认开启（`VERIFY_TEARDOWN=1`），调试才允许关闭并需在备注说明可能污染后续用例 - 失败恢复：对“部分已 apply 的临时清单”允许用清理任务兜底（例如清理 `/tmp/...`），但不要吞掉核心错误。 ### 规则 5：破坏性操作隔离（必须 gate + 默认不进主线） - 破坏性内容（如磁盘分区/格式化、换 CNI、HA 切换）必须： - 用显式开关 gate（例如 `k3s_prepare_storage=true`）才能触发 - 默认不应混入 `verify.sh full/run-all` 的“安全验收主线” - 文档里写清“可重建环境/回滚前置”，并区分“生产主线”与“破坏性实验” - 与主线不同的实验（尤其 `07-*`）默认不提供“一键安装”，不可误做“apply 即生产可用” ### 规则 6：密钥与敏感信息（强约束） - `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-02-部署环境说明.md` 为准；新增文档/用例若依赖“在哪台机器执行”，必须写清。 - `ansible/group_vars/all.yml` 中的关键默认值（如 `k3s_data_dir=/storage`、`k3s_verify_storage_mount=true`、`k3s_manage_firewalld=true`、CoreDNS forward）会影响大量文档与用例，修改这些值相当于“改了实验室契约”，应同步更新文档并回退相关条目的验证状态。 ### 规则 8：Ansible 控制端连接约定（实验室特化） - `ansible/ansible.cfg` 已设置 `host_key_checking=False` 且默认 inventory 为同目录的 `inventory.ini`（实验室特化）；不要把依赖写死到 `~/.ansible.cfg`。