175 lines
11 KiB
Markdown
175 lines
11 KiB
Markdown
---
|
||
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-04-部署环境说明.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 入口。
|
||
- `scripts/verify.sh` 只基于 `ansible/playbooks/verify/` 自动发现并执行（缺 playbook 必须 fail-fast）。
|
||
- **存在性校验**：`scripts/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 规则**：`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` 自动验证范围。
|
||
- **执行器判定口径（不新增关系文件）**：
|
||
- **Ansible 执行器**：存在 `ansible/playbooks/verify/<doc_id>.yml` 且可 `./scripts/verify.sh run <doc_id>`。
|
||
- **脚本/SSH 执行器**：文档 TL;DR 写清入口命令（`./scripts/...`），且脚本存在、用退出码表达成功/失败。
|
||
- **统一入口**：
|
||
- `scripts/deploy-lab.sh`：铺栈/安装入口（默认保留资源：`DEPLOY_VERIFY_TEARDOWN=0`）。
|
||
- `scripts/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-06.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] ...` 信息，避免“看似通过”。
|
||
|
||
---
|
||
|
||
## 环境变量与密钥安全（强约束）
|
||
|
||
- **永不提交真实环境变量文件**：`scripts/.env.verify`（仓库 `.gitignore` 已忽略）
|
||
- **仅提交模板**：`scripts/.env.verify.example`
|
||
- `scripts/.env.verify` 可能包含外部系统 token/凭据（Cloudflare、WebDAV 等），任何自动化/文档都应默认它只存在于本机
|
||
|
||
---
|
||
|
||
## Critical Implementation Rules
|
||
|
||
### 规则 0：本仓库不是“应用代码仓库”，优先保证可重复验证与真源一致
|
||
|
||
- **真源**：
|
||
- **YAML 唯一真源（强约束）**：`ansible/files/**`
|
||
- `docs/`：说明/操作手册/验收判据（不得复制出第二套 YAML 真源）
|
||
- **入口**：
|
||
- `scripts/deploy-lab.sh`：铺栈（默认保留资源，便于持续使用）
|
||
- `scripts/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/playbooks/verify/tasks/` 共享片段，避免模板漂移。
|
||
- **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` 不足以标 ✅
|
||
- **明确执行位置**：
|
||
- 若目标是“集群外链路”，必须经 `ONECLOUD_SSH`（或等价第三方机）执行探测；仅控制节点自测不足以标 ✅
|
||
- **资源清理策略说明**：
|
||
- 若 `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），必须显式经 `ONECLOUD_SSH`（或等价变量）执行探测：
|
||
- **不得**用“控制节点本机 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：密钥与敏感信息（强约束）
|
||
|
||
- `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` 的检查逻辑）。
|
||
|
||
### 规则 7：验证环境基线（避免“跑得通但不复现”）
|
||
|
||
- 验证环境的机器角色与约定（例如 `ylc65` 仅作为 Ansible 控制端，不是 K3s 节点）以 `docs/00-04-部署环境说明.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`。
|
||
|