jack/Deploy-Laboratory
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
31709425e27e8a6f23315b084bc28d46ef6be126
Deploy-Laboratory/docs/00-00-构建总览.md
Jack 31709425e2 对齐文件规范
2026-03-27 16:58:41 +08:00

9.4 KiB
Raw Blame History

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 <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/私钥权限问题。

流程图（主线与分叉）

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（文档 + 占位目录存在性）。

Reference in New Issue View Git Blame Copy Permalink