Deploy-Laboratory/project-context.md

project_name, user_name, date, sections_completed, existing_patterns_found

project_name	user_name	date	sections_completed	existing_patterns_found
Deploy-Laboratory	Jack	2026-03-26	discovery technology_stack critical_implementation_rules	naming_and_ids truth_sources verify_framework gating_and_noop true true true 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/<doc_id>/...（禁止在 docs/ 内复制粘贴出第二份 YAML）。
  • 例外：非 YAML 的源码/生成器/模板（如 scripts/gen-*.py）不受此条限制。
• 执行器唯一真源（强约束）：ansible/playbooks/verify/<doc_id>.yml 为该 doc_id 的唯一 Ansible 入口。
  • 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 的文档进入 ansible/bin/verify.sh 自动验证范围。
• 执行器判定口径（不新增关系文件）：
  • Ansible 执行器：存在 ansible/playbooks/verify/<doc_id>.yml 且可 ./ansible/bin/verify.sh run <doc_id>（仓库根简写：./scripts/cs <doc_id>，与前者等价）。
  • 脚本/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 <doc_id> 对 XX>0 且 YY>0 条目，若缺少 ansible/playbooks/verify/<doc_id>.yml 必须直接失败。

---

gate / 开关（避免误触发重操作）

• 默认安全：verify.sh run <doc_id> 默认应只做“验收”或“轻量可逆操作”。
• 重操作必须显式开关（典型：分区/格式化、全集群安装、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/<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 目录 / 解析器（防误触）

• doc_id 固定为 XX-YY（来自 docs/XX-YY-*.md 文件名），verify.sh run <doc_id> 必须存在 ansible/playbooks/verify/<doc_id>.yml，否则 fail-fast。

规则 2：gate / ✅ 的“证据标准”（防“看似通过”）

• 禁止“通用 noop 模板”：每个 verify/<doc_id>.yml 必须自包含并体现该文档目标的断言；不得用“仅存在性检查”冒充验收。
• gate：外部依赖未满足时允许跳过 apply/断言，但必须满足：
  • playbook 退出码可为 0（表示“框架跑通/条件不足跳过”）
  • 文档中应保持 ⚠️（不可标 ✅）
  • teardown 必须“安全”：仅在 gate 通过且 manifest/资源确实存在时才执行 delete，且删除失败不得导致整条用例 fail-fast
• ✅ 已验证 的最小证据建议（写在文档备注里）：
  • 说明是 自动化实测（deploy+verify+teardown）还是 noop/gate（后者不得 ✅）
  • 说明是否包含 第三方/集群外视角（见规则 3）

规则 2.1：✅ 已验证的“硬门槛”（建议逐步收敛为统一口径）

将条目从 ⚠️/❓ → ✅ 时，建议满足下列最小门槛（能写进 verify/<doc_id>.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。