对齐文件规范

README.md

@@ -5,60 +5,64 @@
 
 如果你是第一次看，不用担心，按下面顺序一步一步来就行。
 
+**路径约定**：下文与总览中的文件路径均相对于**仓库根目录**（在仓库根执行脚本，例如 `./scripts/...`）。
+
 ## 先知道这仓库怎么逛
 
 - 文档主入口：`docs/00-00-构建总览.md`
-- 部署环境说明：`docs/00-04-部署环境说明.md`（节点布局、IP、版本等）
+- 部署环境说明：`docs/00-02-部署环境说明.md`（节点布局、IP、版本等）
 - 脚本主入口：`scripts/README.md`
-- 验证状态一览：`docs/00-02-验证矩阵.md`
-- 测试与验证框架设计：`docs/00-05-测试与验证框架.md`
+- 仓库契约（AI/贡献者必读）：`project-context.md`（真源、验证框架、noop/gate、敏感信息约束）
+- 测试与验证框架设计：`docs/00-03-测试与验证框架.md`
+- **验证入口**：`./scripts/verify.sh`（`full/run-all/run`）
 
-简单理解这三份入口的分工：
+编号语义（用于快速判断“是否必须可执行”）：
 
-- `README.md`：新手入口，看“要做什么、按什么顺序做”；
-- `00-00-构建总览.md`：文档导航，看“下一步该看哪一篇”；
-- `00-01-k3s-基础概念.md`：概念速查，看“不懂的 K3s/Traefik/NetworkPolicy 术语”；
-- `00-02-验证矩阵.md`：状态面板，看「哪些文档已在真实环境跑通过」；自动化复验用 `./scripts/verify.sh run-all`（见 `00-05`），矩阵里的状态/备注建议仍手工维护。
+- `00-**`：纯文档域（索引/说明/状态板等）
+- `XX-00`（`XX>0`）：系列入口/导航页
+- `XX-YY`（`XX>0 && YY>0`）：分项实践页，必须包含可执行物（YAML 路径或命令块）
 
-目录约定很简单：
+简单理解这几份入口的分工：
 
-- 主文档都在 `docs/`
-- 脚本都在 `scripts/`
-- 脚本默认从仓库根目录执行（例如 `./scripts/...`）
+- `README.md`：新手入口，看「要做什么、按什么顺序做」；
+- `docs/00-00-构建总览.md`：文档导航 + **学习主线（6 步）**与**附录长单**；
+- `docs/00-01-k3s-基础概念.md`：概念速查，看「不懂的 K3s/Traefik/NetworkPolicy 术语」；
+- `./scripts/verify.sh`：按 `doc_id` 的自动化验证入口（`full/run-all/run`；清单由 `ansible/playbooks/verify/` 自动生成，且仅包含执行域 `XX>0 && YY>0`）。
 
-## 新手推荐安装顺序（口语版）
+目录约定：
 
-1. **先看总览，别急着装**
-   打开 `docs/00-00-构建总览.md`，先把整体拓扑和机器分工看明白。
+- 主文档：`docs/`
+- 脚本：`scripts/`
 
-2. **装 K3s 集群（两种方式二选一）**
-   - **自动化**：按 `docs/01-06-节点初始化-ansible-实践.md`，或在仓库根执行 `./scripts/deploy-lab.sh k3s`（可选 `K3S_PREPARE_STORAGE=true`），完成 61~64 初始化 + server/worker（详见 `scripts/README.md`）。
-   - **手动**：先按 `docs/01-01-k3s-控制节点含traefik.md` 装控制节点 61，再按 `docs/01-02-k3s-工作节点.md` 加工作节点 62~64。
+## 学习主线（6 步，推荐）
 
-3. **确认节点 Ready**
-   执行 `kubectl get nodes`，确认所有节点 Ready。
+与 `docs/00-00-构建总览.md` 中主线一致；更细的**流程图与分叉说明**也在该篇。
 
-4. **先用 nginx 做最小验证**
-   按 `docs/04-03-k3s-nginx-demo.md`，先打通“能访问”这件事，再上 nodejs。
+1. **总览与环境**：读 `docs/00-00-构建总览.md`；需要对照机器与版本时打开 `docs/00-02-部署环境说明.md`。
+2. **概念速查（可跳过）**：读 `docs/00-01-k3s-基础概念.md`；时间紧可跳过，**碰壁再回来看**。
+3. **安装 K3s（二选一）**：**自动化** — `docs/01-06-节点初始化-ansible-实践.md`，或仓库根执行 `./scripts/deploy-lab.sh k3s`（可选 `K3S_PREPARE_STORAGE=true`，详见 `scripts/README.md`）；**手动** — `docs/01-01-k3s-控制节点含traefik.md` 再 `docs/01-02-k3s-工作节点.md`。
+4. **确认节点 Ready**：`kubectl get nodes`，全部 Ready。
+5. **Nginx 最小验证**：`docs/02-00-nginx-系列说明.md` → `docs/02-05-nginx-验证矩阵-一键部署.md`，先打通「能访问」；也可在装好集群并配置 `.env.verify` 后直接 `./scripts/verify.sh run 02-05`。
+6. **Node.js 主线入口**：`docs/04-01-k3s-nodejs-高级部署.md`；`docs/04-02`～`04-14` 为分项，**按需展开**，不挤进主线编号。
 
-5. **再做 nodejs、dashboard、acme**
-   对应看 `docs/04-01-k3s-nodejs-高级部署.md`、`docs/03-01-k3s-traefik-dashboard.md`、`docs/03-02-k3s-traefik-acme.md`。
+**主线之后（按需，不占主线序号）**：Traefik 面板与证书（如 `docs/03-01-k3s-traefik-dashboard.md`、`docs/03-02-k3s-traefik-acme.md`）、存储与应用（`03-05` 起、`05-**`）等 — 见总览中的「主线之后的分叉」与专题导航。
 
-6. **遇到 502/不通，直接用脚本排障**
-   去 `scripts/README.md` 抄命令，优先跑入口链路诊断和 firewalld 基线脚本。
+**任意一步卡住**：排障见 `scripts/README.md`（如 firewalld 基线、入口链路诊断）；NetworkPolicy 见 `docs/06-01-k3s-networkpolicy-故障排查.md`。
 
-## 30 分钟快速通关（最小必做）
+## 30 分钟快速通关（4 步）
 
-如果你时间有限，先只做这 4 步，跑通再扩展：
+相当于**跳过主线第 2 步（概念）**并**压缩第 1 步（只抓总览要点）**；跑通再按 6 步补全。
 
-1. **装集群**：用 Ansible 按 `docs/01-06-节点初始化-ansible-实践.md` 一键安装（推荐）；或按 `docs/01-01` + `docs/01-02` 手动装控制节点（61）与工作节点（62）
-2. 执行 `kubectl get nodes`，确认节点 Ready
-3. 按 `docs/04-03-k3s-nginx-demo.md` 部署 nginx 示例并访问一次
-4. 若访问不通，按 `scripts/README.md` 先跑 firewalld 基线与入口链路诊断脚本
+1. **装集群**：Ansible 按 `docs/01-06-节点初始化-ansible-实践.md`（推荐）；或 `docs/01-01` + `docs/01-02` 手动装控制节点（61）与工作节点（62）。
+2. `kubectl get nodes`，确认节点 Ready。
+3. 按 `docs/02-05-nginx-验证矩阵-一键部署.md` 部署 nginx 矩阵并访问一次（可先读 `docs/02-00-nginx-系列说明.md`）。
+4. 若访问不通，按 `scripts/README.md` 先跑 firewalld 基线与入口链路诊断脚本。
 
-跑到这里就算「基础链路通关」。后面再继续 nodejs、dashboard、acme 会轻松很多。  
-如果你愿意，也可以顺手在 `docs/00-02-验证矩阵.md` 里，把对应文档的状态改成“已验证”，方便以后回顾。
+跑到这里算「基础链路通关」。后续再补 `04-01`、Traefik、存储等会轻松很多。  
+若愿意，可在对应实验篇文档里补充你自己的“已验证环境/日期/版本”记录（不再维护统一矩阵页）。
 
 ## 一句话建议
 
-先把基础链路（61/62:80）跑通，再叠加业务；每做完一步都做一次 `curl` 验证，排障会轻松很多。
+先把基础链路（如 61/62:80）跑通，再叠加业务；每做完一步做一次 `curl` 验证，排障会轻松很多。
+
+补充：`verify.sh` 支持按范围筛选执行（`--series`、`--id-regex`、`--exclude-noop`、`--require-teardown`），适合做分批回归与 CI 分层跑批。