195 lines
9.8 KiB
Markdown
195 lines
9.8 KiB
Markdown
# 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/私钥权限问题。
|
||
|
||
### 流程图（主线与分叉）
|
||
|
||
```mermaid
|
||
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（文档 + 占位目录存在性）**。
|