15 KiB
15 KiB
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 |
|
|
项目上下文（给 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 执行器：存在
- 统一入口：
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=true03-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、playbooklookup('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-06WORKSTATION_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 真源）
- 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+ -
IngressAPI（networking.k8s.io/v1）字段结构（尤其pathType、backend 端口）\n+ - Traefik CRD（IngressRoute/Middleware）是否仍存在且版本一致\n+ - K3sHelmChartConfig（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成功、PVCBound、Pod 就绪、关键 CRD/资源Established/Ready等
- 例如：
- 至少 1 条入口/可用性断言（与该文档目标一致）：
- HTTP：
curl返回码 + 关键响应标记（例如X-Backend、body contains） - TLS：必须包含 SNI/证书链验证信号（如
curl --resolve/openssl s_client关键字段），仅rollout不足以标 ✅
- HTTP：
- 明确执行位置：
- 若目标是“集群外链路”，必须经
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），调试才允许关闭并需在备注说明可能污染后续用例
- rollout/就绪检查要带合理
- 失败恢复：对“部分已 apply 的临时清单”允许用清理任务兜底（例如清理
/tmp/...），但不要吞掉核心错误。
规则 5：破坏性操作隔离（必须 gate + 默认不进主线）
- 破坏性内容（如磁盘分区/格式化、换 CNI、HA 切换）必须：
- 用显式开关 gate（例如
k3s_prepare_storage=true）才能触发 - 默认不应混入
verify.sh full/run-all的“安全验收主线”
- 用显式开关 gate（例如
- 文档里写清“可重建环境/回滚前置”，并区分“生产主线”与“破坏性实验”
- 与主线不同的实验（尤其
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。