# 00-00-构建总览

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

## 目录约定

- 文档：`docs/`（Kubernetes 等可复用清单见 `ansible/files/`，与 Ansible playbook 共用）
- 脚本：`scripts/`
- 脚本入口：`scripts/README.md`

### 编号含义速查

- `00-**`：总览与基础概念（入口、索引、验证矩阵、部署环境说明、未来规划）
- `01-**`：安装与基础环境（控制节点/工作节点/OpenWrt HAProxy/Cloudflare/NFS 等）
- `02-**`：Nginx 矩阵**分篇场景说明**（M1～M4 各场景独立页；**综合一键部署见 `02-05`**）
- `03-**`：集群侧配置扩展；**03-04～03-10 按推荐阅读顺序编号**（Traefik 自定义端口 → Tunnel → local-path → NFS → Longhorn → HA → GitOps）
- `04-**`：Node.js 高级部署（`04-01` 主入口 + `04-02`～`04-14` 部署分项；与 nginx 矩阵编号无强制对应）
- `05-**`：常用应用部署（Homer、OneNav、GitLab、监控、openlist 等）
- `06-**`：排障与运维总结（NetworkPolicy 排查、运维小结）

---

## 推荐安装顺序

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. `04-03-k3s-nginx-demo.md`
7. `04-01-k3s-nodejs-高级部署.md`
8. `04-02-nodejs-镜像与运行命令.md`
9. `04-03-nodejs-环境变量与配置注入.md`
10. `04-04-nodejs-端口与Service.md`
11. `04-05-nodejs-资源请求与限制.md`
13. `04-06-nodejs-探针与健康检查.md`
14. `04-07-nodejs-调度与亲和.md`
15. `04-08-nodejs-安全上下文.md`
16. `04-09-nodejs-存储与卷.md`
17. `04-10-nodejs-Ingress与Traefik.md`
18. `04-11-nodejs-副本与滚动发布.md`
19. `04-12-nodejs-TLS与证书.md`
20. `04-13-nodejs-HPA.md`
21. `04-14-nodejs-GitOps与CI流水线.md`
22. `02-05-nginx-验证矩阵-一键部署.md`（建议先读 `02-00-nginx-系列说明.md`）
23. `03-01-k3s-traefik-dashboard.md`
24. `03-02-k3s-traefik-acme.md`
25. `03-03-k3s-traefik-dashboard-acme.md`（推荐顺序：先 03-01、03-02）
26. `03-04-k3s-cloudflare-tunnel-配置接入.md`（按需：Cloudflare Tunnel 接入集群）
27. `03-05-k3s-local-path-pvc.md`（K3s 自带 local-path，单副本本地持久化）
28. `03-06-k3s-使用nfs存储.md`（按需：已有 NFS 时 PV/PVC）
29. `03-07-k3s-longhorn-持久化存储.md`（重状态、快照/备份，建议部署 GitLab 等前统一规划）
30. `03-08-k3s-ha-集群配置与切换.md`（按需：双控制节点 HA，配合 `01-04`）
31. `03-09-k3s-gitops-集群配置管理.md`（框架草案：Argo CD / Flux）

> 想确认这些步骤是否已经在真实环境验证，请查看 `00-02-验证矩阵.md`。
> 本仓库验证环境说明见 `00-04-部署环境说明.md`。

---

## 主线导航

- `01-02-k3s-工作节点.md`
- `03-01-k3s-traefik-dashboard.md`
- `04-03-k3s-nginx-demo.md`
- `04-01-k3s-nodejs-高级部署.md`（文末：`04-02`～`04-14` Node.js 部署分项）
- `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`
- `06-01-k3s-networkpolicy-故障排查.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 综合部署）

> **说明**：若曾规划「Node.js 与 nginx 对照」的 M1～M4 矩阵独立文档，**尚未在本仓库落盘**；当前 **`04-05`～`04-08` 已用于** Node.js **部署分项**（资源/探针/调度/安全）。后续若补充 Node.js 矩阵，请**另起编号**（例如 `04-20` 起或归入专题），避免与现有 `04-**` 冲突。

---

## 专题导航

- `00-04-部署环境说明.md`（节点布局、IP、OS、K3s 版本等，便于对照与复现）
- `01-06-节点初始化-ansible-实践.md`（Ansible 一键安装 k3s 集群，已验证）
- `01-07-openwrt-haproxy.md`（按需：网关负载均衡）
- nginx 矩阵：`ansible/playbooks/nginx-matrix-deploy.yml`（02-05）、`ansible/playbooks/nginx-matrix-tls-deploy.yml`（03-02）
- `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-04-双控制节点ha.md`
- `03-08-k3s-ha-集群配置与切换.md`
- `03-09-k3s-gitops-集群配置管理.md`（框架草案）

---

## 排障入口

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

---

## 未来规划

- `00-03-未来规划与待补功能.md`：记录还没做、但已经想到的能力清单与路线图，方便以后按需补齐。