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

00-00-构建总览

本仓库主文档入口。建议从这里开始阅读。

TL;DR

• 本文性质：目录导航/阅读顺序说明（不对应矩阵验收用例）
• 真机一键验收：./scripts/acceptance.sh（可选铺栈）或 ./ansible/bin/verify.sh full（仅验收）
• 成功判据：你能从本文快速定位到要跑的 doc_id、入口脚本与下一步文档
• 排障：若验收失败，先跑 ./ansible/bin/verify.sh preflight，再看对应 doc_id 的 playbook 输出

路径约定：本文档中的链接，凡写作 docs/...、ansible/...、scripts/...、project-context.md 的，均相对于仓库根目录（与在 docs/ 内打开本文件时的相对路径无关，避免混用 ../）。

目录约定

• 文档：docs/（Kubernetes 等可复用清单见 ansible/files/，与 Ansible playbook 共用）
• Helm：CLI 安装与典型场景见 00-02-部署环境说明.md（§1.1～§1.2）、00-03-测试与验证框架.md（§1.1 索引）；chart 实践分散在 03-07、05-05、03-10 等篇。
• 脚本：scripts/
• 脚本入口：scripts/README.md
• 仓库契约（实现与改动规则）：project-context.md

编号含义速查

• 00-**：基本知识与基础环境（入口、索引、部署环境说明、验证框架与准备清单）
• 01-**：安装与基础环境（见 01-00 系列说明页）
• 02-**：Nginx 矩阵分篇场景说明（M1～M4 各场景独立页；综合一键部署见 02-05）
• 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，再用 ./ansible/bin/verify.sh run <doc_id> 或 ./ansible/bin/verify.sh full。
• verify.sh 报缺 playbook：确认存在 ansible/playbooks/verify/<doc_id>.yml，并可运行 python3 ansible/tools/validate_matrix_playbooks.py 做存在性校验。
• 连接不上集群：在控制端执行 ./ansible/bin/verify.sh preflight，优先修复 inventory/SSH/私钥权限问题。

流程图（主线与分叉）

flowchart TD
  S1[1 总览 + 按需 00-04 环境说明]
  S2[2 概念 00-01]
  S3[3 装集群 01-05 或 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-05-节点初始化-ansible-实践.md（仓库根亦可配合 ansible/bin/deploy-lab.sh）。
4. 验收：kubectl get nodes，所有节点 Ready。
5. HTTP 入口验证：02-00-nginx-系列说明.md → 02-05-nginx-验证矩阵-一键部署.md（清单真源：ansible/files/02-05/）。可选：./ansible/bin/verify.sh run 02-05。
6. 工作负载主线：04-01-k3s-nodejs-高级部署.md。04-02～04-14 为分项，按需阅读，不列入主线编号。

推进「已验证」的前置见 00-03-测试与验证框架.md 的 §10 验证前准备清单。

进度视图见 00-04-验证状态板.md（自动生成视图；执行真源仍以 verify playbook 为准）。

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-05-节点初始化-ansible-实践.md 一键自动化）
3. 01-02-k3s-工作节点.md
4. 01-03-armv7-standalone-docker.md
5. 01-06-openwrt-haproxy.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-端口与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-07）
29. 03-09-k3s-gitops-集群配置管理.md（框架草案：Argo CD / Flux）

---

主线之后的分叉（按需）

不占主线 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-07-双控制节点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

---

矩阵导航

矩阵文档（M1~M8）：02-01～02-04 为 M1～M4 分篇说明，02-05 为综合一键部署。实际部署用 02-05 或 Ansible。

• 02-00-nginx-系列说明.md
• 02-01-nginx-control-ingress.md（M1）
• 02-02-nginx-control-ingressroute.md（M2）
• 02-03-nginx-worker-ingress.md（M3）
• 02-04-nginx-worker-ingressroute.md（M4）
• 02-05-nginx-验证矩阵-一键部署.md（HTTP-only 综合部署）

说明：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-02-部署环境说明.md（节点布局、IP、OS、K3s 版本等，便于对照与复现）

• 01-05-节点初始化-ansible-实践.md（Ansible 一键安装 k3s 集群，已验证）

• 01-06-openwrt-haproxy.md（按需：网关负载均衡）

• 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

• 05-04-k3s-配置gitlab-cicd.md

• 05-01-k3s-部署homer首页面板.md

• 05-02-onenav首页面板.md

• 05-05-prometheus与grafana.md

• 05-07-openclaw应用部署.md

• 05-08-openclaw-k3s-实验部署.md

• 01-04-armv7-nfs服务安装.md

• 05-06-openlist挂载网盘与自动备份.md

• 06-02-运维小结.md

• 01-07-双控制节点ha.md

• 03-08-k3s-ha-集群配置与切换.md

• 03-09-k3s-gitops-集群配置管理.md（框架草案）

---

排障入口

• 文档：06-01-k3s-networkpolicy-故障排查.md
• 脚本：scripts/README.md

---

未来规划

• 未来规划与维护者审查结论已收敛到 project-context.md（作为仓库契约与长期可维护约束），避免 00 系列入口层堆积噪音。

---

网络与 CNI 实验（07-*，按需）

• 07-01-k3s-calico-dualstack.md（Calico 双栈实验）
• 07-02-k3s-cilium-dualstack-ebpf.md（Cilium 双栈与 eBPF）

与主线 01-05 + Flannel 安装路径不同；仅在独立实验环境或充分备份后阅读、操作。验证矩阵与 verify.sh 对 07-* 仅为 noop（文档 + 占位目录存在性）。