对齐文件规范

docs/00-00-构建总览.md

@@ -2,74 +2,132 @@
 
 > 本仓库主文档入口。建议从这里开始阅读。
 
+## TL;DR
+
+- **本文性质**：目录导航/阅读顺序说明（不对应矩阵验收用例）
+- **真机一键验收**：`./scripts/acceptance.sh`（可选铺栈）或 `./scripts/verify.sh full`（仅验收）
+- **成功判据**：你能从本文快速定位到要跑的 `doc_id`、入口脚本与下一步文档
+- **排障**：若验收失败，先跑 `./scripts/verify.sh preflight`，再看对应 `doc_id` 的 playbook 输出
+
+**路径约定**：本文档中的链接，凡写作 `docs/...`、`ansible/...`、`scripts/...`、`project-context.md` 的，均相对于**仓库根目录**（与在 `docs/` 内打开本文件时的相对路径无关，避免混用 `../`）。
+
 ## 目录约定
 
 - 文档：`docs/`（Kubernetes 等可复用清单见 `ansible/files/`，与 Ansible playbook 共用）
 - 脚本：`scripts/`
 - 脚本入口：`scripts/README.md`
+- 仓库契约（实现与改动规则）：`project-context.md`
 
 ### 编号含义速查
 
-- `00-**`：总览与基础概念（入口、索引、验证矩阵、部署环境说明、未来规划）
-- `01-**`：安装与基础环境（控制节点/工作节点/OpenWrt HAProxy/Cloudflare/NFS 等）
+- `00-**`：基本知识与基础环境（入口、索引、部署环境说明、验证框架与准备清单）
+- `01-**`：安装与基础环境（见 `01-00` 系列说明页）
 - `02-**`：Nginx 矩阵**分篇场景说明**（M1～M4 各场景独立页；**综合一键部署见 `02-05`**）
-- `03-**`：集群侧配置扩展；**03-04～03-10 按推荐阅读顺序编号**（Traefik 自定义端口 → Tunnel → local-path → NFS → Longhorn → HA → GitOps）
-- `04-**`：Node.js 高级部署（`04-01` 主入口 + `04-02`～`04-14` 部署分项；与 nginx 矩阵编号无强制对应）
-- `05-**`：常用应用部署（Homer、OneNav、GitLab、监控、openlist 等）
-- `06-**`：排障与运维总结（NetworkPolicy 排查、运维小结）
+- `03-**`：集群侧配置扩展（见 `03-00` 系列说明页）
+- `04-**`：Node.js 高级部署（见 `04-00` 系列说明页）
+- `05-**`：常用应用部署（见 `05-00` 系列说明页）
+- `06-**`：排障与运维总结（见 `06-00` 系列说明页）
+- `07-**`：网络与 CNI 实验（见 `07-00` 系列说明页；多为破坏性/换 CNI 场景）
+- `00-**` 的 `verify/00-*.yml` 仅做文档/路径一致性校验，不做 `kubectl apply`、Helm 安装或任何变更集群状态的动作
 
 ---
 
-## 推荐安装顺序
+## 学习主线（6 步）
+
+以下为仓库**默认主线**；完整扩展示意见下方流程图。更长的按主题展开顺序见 **附录：完整推荐阅读顺序**。
+
+## 排障
+
+- **不知道该跑哪个命令**：先按本文“学习主线（6 步）”找到对应 `doc_id`，再用 `./scripts/verify.sh run <doc_id>` 或 `./scripts/verify.sh full`。
+- **verify.sh 报缺 playbook**：确认存在 `ansible/playbooks/verify/<doc_id>.yml`，并可运行 `python3 scripts/validate_matrix_playbooks.py` 做存在性校验。
+- **连接不上集群**：在控制端执行 `./scripts/verify.sh preflight`，优先修复 inventory/SSH/私钥权限问题。
+
+### 流程图（主线与分叉）
+
+```mermaid
+flowchart TD
+  S1[1 总览 + 按需 00-04 环境说明]
+  S2[2 概念 00-01]
+  S3[3 装集群 01-06 或 01-01+01-02]
+  S4[4 kubectl 节点全 Ready]
+  S5[5 Nginx 02-00 → 02-05]
+  S6[6 Node.js 04-01]
+  S1 --> S2
+  S2 --> S3
+  S3 --> S4
+  S4 --> S5
+  S5 --> S6
+  S6 --> B1[分叉: Traefik 03-01 / 03-02 等]
+  S6 --> B2[分叉: 存储 03-05～03-07 等]
+  S6 --> B3[分叉: 应用 05-xx]
+  S6 --> B4[排障: 06-xx / scripts]
+  S1 -.->|30分钟版跳过| S3
+  S2 -.->|30分钟版跳过| S3
+```
+
+### 6 步说明
+
+1. **总览与环境**：精读本篇；需要对照节点、IP、版本时打开 `00-02-部署环境说明.md`。
+2. **概念速查**：`00-01-k3s-基础概念.md`。**时间紧可跳过**，卡术语再读。
+3. **安装 K3s**：`01-01-k3s-控制节点含traefik.md` + `01-02-k3s-工作节点.md`，或一键 `01-06-节点初始化-ansible-实践.md`（仓库根亦可配合 `scripts/deploy-lab.sh`）。
+4. **验收**：`kubectl get nodes`，所有节点 Ready。
+5. **HTTP 入口验证**：`02-00-nginx-系列说明.md` → `02-05-nginx-验证矩阵-一键部署.md`（清单真源：`ansible/files/02-05/`）。可选：`./scripts/verify.sh run 02-05`。
+6. **工作负载主线**：`04-01-k3s-nodejs-高级部署.md`。`04-02`～`04-14` 为分项，**按需阅读**，不列入主线编号。
+
+> 推进「已验证」的前置见 `00-04-待验证项-验证前准备.md`。
+
+### 30 分钟快速路径（4 步）
+
+相当于**跳过第 2 步**并**压缩第 1 步**（只抓总览要点）：装集群 → Ready → `02-05` → 不通则 `scripts/README.md` 排障。与仓库根 `README.md` 中「30 分钟快速通关」一致。
+
+---
+
+## 附录：完整推荐阅读顺序（按主题展开）
+
+下列顺序适合**已走完 6 步主线**、或需要按编号通读全库时查阅；**不必一次性做完**。
 
 1. `00-01-k3s-基础概念.md`
 2. `01-01-k3s-控制节点含traefik.md`（或直接用 `01-06-节点初始化-ansible-实践.md` 一键自动化）
 3. `01-02-k3s-工作节点.md`
 4. `01-03-armv7-standalone-docker.md`
 5. `01-07-openwrt-haproxy.md`（按需：网关负载均衡）
-6. `04-03-k3s-nginx-demo.md`
+6. `02-00-nginx-系列说明.md` → `02-05-nginx-验证矩阵-一键部署.md`（HTTP 矩阵与入口验证；清单真源：`ansible/files/02-05/`）
 7. `04-01-k3s-nodejs-高级部署.md`
-8. `04-02-nodejs-镜像与运行命令.md`
-9. `04-03-nodejs-环境变量与配置注入.md`
-10. `04-04-nodejs-端口与Service.md`
-11. `04-05-nodejs-资源请求与限制.md`
-13. `04-06-nodejs-探针与健康检查.md`
-14. `04-07-nodejs-调度与亲和.md`
-15. `04-08-nodejs-安全上下文.md`
-16. `04-09-nodejs-存储与卷.md`
-17. `04-10-nodejs-Ingress与Traefik.md`
-18. `04-11-nodejs-副本与滚动发布.md`
-19. `04-12-nodejs-TLS与证书.md`
-20. `04-13-nodejs-HPA.md`
-21. `04-14-nodejs-GitOps与CI流水线.md`
-22. `02-05-nginx-验证矩阵-一键部署.md`（建议先读 `02-00-nginx-系列说明.md`）
-23. `03-01-k3s-traefik-dashboard.md`
-24. `03-02-k3s-traefik-acme.md`
-25. `03-03-k3s-traefik-dashboard-acme.md`（推荐顺序：先 03-01、03-02）
-26. `03-04-k3s-cloudflare-tunnel-配置接入.md`（按需：Cloudflare Tunnel 接入集群）
-27. `03-05-k3s-local-path-pvc.md`（K3s 自带 local-path，单副本本地持久化）
-28. `03-06-k3s-使用nfs存储.md`（按需：已有 NFS 时 PV/PVC）
-29. `03-07-k3s-longhorn-持久化存储.md`（重状态、快照/备份，建议部署 GitLab 等前统一规划）
-30. `03-08-k3s-ha-集群配置与切换.md`（按需：双控制节点 HA，配合 `01-04`）
-31. `03-09-k3s-gitops-集群配置管理.md`（框架草案：Argo CD / Flux）
-
-> 想确认这些步骤是否已经在真实环境验证，请查看 `00-02-验证矩阵.md`。
-> 本仓库验证环境说明见 `00-04-部署环境说明.md`。
+8. `04-02-nodejs-端口与Service.md`
+9. `04-03-nodejs-镜像与运行命令.md`
+10. `04-04-nodejs-环境变量与配置注入.md`
+11. `04-05-nodejs-探针与健康检查.md`
+12. `04-06-nodejs-副本与滚动发布.md`
+13. `04-07-nodejs-Ingress与Traefik.md`
+14. `04-08-nodejs-资源请求与限制.md`
+15. `04-09-nodejs-调度与亲和.md`
+16. `04-10-nodejs-安全上下文.md`
+17. `04-11-nodejs-存储与卷.md`
+18. `04-12-nodejs-TLS与证书.md`
+19. `04-13-nodejs-HPA.md`
+20. `04-14-nodejs-GitOps与CI流水线.md`
+21. `03-01-k3s-traefik-dashboard.md`
+22. `03-02-k3s-traefik-acme.md`
+23. `03-03-k3s-traefik-dashboard-acme.md`（推荐顺序：先 03-01、03-02）
+24. `03-04-k3s-cloudflare-tunnel-配置接入.md`（按需：Cloudflare Tunnel 接入集群）
+25. `03-05-k3s-local-path-pvc.md`（K3s 自带 local-path，单副本本地持久化）
+26. `03-06-k3s-使用nfs存储.md`（按需：已有 NFS 时 PV/PVC）
+27. `03-07-k3s-longhorn-持久化存储.md`（重状态、快照/备份，建议部署 GitLab 等前统一规划）
+28. `03-08-k3s-ha-集群配置与切换.md`（按需：双控制节点 HA，配合 `01-08`）
+29. `03-09-k3s-gitops-集群配置管理.md`（框架草案：Argo CD / Flux）
 
 ---
 
-## 主线导航
+## 主线之后的分叉（按需）
 
-- `01-02-k3s-工作节点.md`
-- `03-01-k3s-traefik-dashboard.md`
-- `04-03-k3s-nginx-demo.md`
-- `04-01-k3s-nodejs-高级部署.md`（文末：`04-02`～`04-14` Node.js 部署分项）
-- `03-02-k3s-traefik-acme.md`
-- `03-04-k3s-cloudflare-tunnel-配置接入.md`
-- `03-05-k3s-local-path-pvc.md`
-- `03-06-k3s-使用nfs存储.md`
-- `03-07-k3s-longhorn-持久化存储.md`
-- `06-01-k3s-networkpolicy-故障排查.md`
+不占主线 6 步序号；按目标点击即可。
+
+- **Traefik / 入口**：`03-01-k3s-traefik-dashboard.md`、`03-02-k3s-traefik-acme.md`、`03-04-k3s-cloudflare-tunnel-配置接入.md`
+- **存储**：`03-05-k3s-local-path-pvc.md`、`03-06-k3s-使用nfs存储.md`、`03-07-k3s-longhorn-持久化存储.md`
+- **高可用 / GitOps**：`01-08-双控制节点ha.md`、`03-08-k3s-ha-集群配置与切换.md`、`03-09-k3s-gitops-集群配置管理.md`
+- **工作节点与 HTTP 验证**（主线中已覆盖，此处为直达）：`01-02-k3s-工作节点.md`、`02-05-nginx-验证矩阵-一键部署.md`（可先读 `02-00-nginx-系列说明.md`）
+- **Node.js 分项**（`04-02`～`04-14`，从 `04-01` 文末进入）
+- **排障**：`06-01-k3s-networkpolicy-故障排查.md`、`scripts/README.md`
 
 ---
 
@@ -84,16 +142,16 @@
 - `02-04-nginx-worker-ingressroute.md`（M4）
 - `02-05-nginx-验证矩阵-一键部署.md`（HTTP-only 综合部署）
 
-> **说明**：若曾规划「Node.js 与 nginx 对照」的 M1～M4 矩阵独立文档，**尚未在本仓库落盘**；当前 **`04-05`～`04-08` 已用于** Node.js **部署分项**（资源/探针/调度/安全）。后续若补充 Node.js 矩阵，请**另起编号**（例如 `04-20` 起或归入专题），避免与现有 `04-**` 冲突。
+> **说明**：HTTP/nginx 的 M1～M4 分篇与综合一键部署以 **`02-01`～`02-05`** 为真源（与 `04-**` 编号无关）。若曾规划「与 nginx 矩阵逐条对照的 Node.js 独立分册」，**尚未在本仓库落盘**。`04-02`～`04-14` 为 Node.js **分项**（已按 Core→Plus→Pro 从简到繁编号，与 nginx 矩阵无逐条对应）。后续若补充 Node.js 专题矩阵，请**另起编号**（例如 `04-20` 起或归入专题），避免与现有 `04-**` 冲突。
 
 ---
 
 ## 专题导航
 
-- `00-04-部署环境说明.md`（节点布局、IP、OS、K3s 版本等，便于对照与复现）
+- `00-02-部署环境说明.md`（节点布局、IP、OS、K3s 版本等，便于对照与复现）
 - `01-06-节点初始化-ansible-实践.md`（Ansible 一键安装 k3s 集群，已验证）
 - `01-07-openwrt-haproxy.md`（按需：网关负载均衡）
-- nginx 矩阵：`ansible/playbooks/nginx-matrix-deploy.yml`（02-05）、`ansible/playbooks/nginx-matrix-tls-deploy.yml`（03-02）
+- nginx 矩阵：`ansible/playbooks/verify/02-05.yml`（薄封装导入 `ansible/playbooks/verify/02-05.yml`）；TLS 铺栈另见 `ansible/playbooks/verify/03-02.yml`（`deploy-lab nginx-matrix-tls`）。
 - `03-04-k3s-cloudflare-tunnel-配置接入.md`（Cloudflare Tunnel 完整流程：Zero Trust + 集群接入）
 
 - `05-03-k3s-安装gitlab-含runner.md`
@@ -106,7 +164,7 @@
 - `01-05-armv7-nfs服务安装.md`
 - `05-06-openlist挂载网盘与自动备份.md`
 - `06-02-运维小结.md`
-- `01-04-双控制节点ha.md`
+- `01-08-双控制节点ha.md`
 - `03-08-k3s-ha-集群配置与切换.md`
 - `03-09-k3s-gitops-集群配置管理.md`（框架草案）
 
@@ -121,5 +179,13 @@
 
 ## 未来规划
 
-- `00-03-未来规划与待补功能.md`：记录还没做、但已经想到的能力清单与路线图，方便以后按需补齐。
+- 未来规划与维护者审查结论已收敛到 `project-context.md`（作为仓库契约与长期可维护约束），避免 `00` 系列入口层堆积噪音。
 
+---
+
+## 网络与 CNI 实验（07-*，按需）
+
+- `07-01-k3s-calico-dualstack.md`（Calico 双栈实验）
+- `07-02-k3s-cilium-dualstack-ebpf.md`（Cilium 双栈与 eBPF）
+
+> 与主线 `01-06` + Flannel 安装路径不同；仅在独立实验环境或充分备份后阅读、操作。验证矩阵与 `verify.sh` 对 `07-*` 仅为 **noop（文档 + 占位目录存在性）**。