# 00-00-构建总览 > 本仓库主文档入口。建议从这里开始阅读。 ## 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-**`：安装与基础环境（见 `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`，再用 `./scripts/verify.sh run ` 或 `./scripts/verify.sh full`。 - **verify.sh 报缺 playbook**：确认存在 `ansible/playbooks/verify/.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. `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-08`） 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-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` --- ## 矩阵导航 矩阵文档（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-06-节点初始化-ansible-实践.md`（Ansible 一键安装 k3s 集群，已验证） - `01-07-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-05-armv7-nfs服务安装.md` - `05-06-openlist挂载网盘与自动备份.md` - `06-02-运维小结.md` - `01-08-双控制节点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-06` + Flannel 安装路径不同；仅在独立实验环境或充分备份后阅读、操作。验证矩阵与 `verify.sh` 对 `07-*` 仅为 **noop（文档 + 占位目录存在性）**。