# 实验室建设（新手入口）

这个仓库是一个家庭实验室（Homelab）实战记录：
从 0 开始搭 K3s 集群、配 Traefik 入口、跑常见服务（比如 GitLab、监控、首页面板），并配好排障脚本。

如果你是第一次看，不用担心，按下面顺序一步一步来就行。

**路径约定**：下文与总览中的文件路径均相对于**仓库根目录**（在仓库根执行脚本，例如 `./scripts/...`）。

## 先知道这仓库怎么逛

- 文档主入口：`docs/00-00-构建总览.md`
- 部署环境说明：`docs/00-02-部署环境说明.md`（节点布局、IP、版本等）
- 脚本主入口：`scripts/README.md`
- 仓库契约（AI/贡献者必读）：`project-context.md`（真源、验证框架、noop/gate、敏感信息约束）
- 测试与验证框架设计：`docs/00-03-测试与验证框架.md`
- **验证入口**：`./ansible/bin/verify.sh`（`full/run-all/run`）；单篇简写 `./scripts/cs <XX-YY>`（与 `verify.sh run` 等价，**任意执行域 doc_id 通用**）
- **Helm**：家庭实验里装 Longhorn、监控栈等常用；CLI 与环境见 `docs/00-02-部署环境说明.md`，各篇索引见 `docs/00-03-测试与验证框架.md` §1.1。

编号语义（用于快速判断“是否必须可执行”）：

- `00-**`：纯文档域（索引/说明/状态板等）
- `XX-00`（`XX>0`）：系列入口/导航页
- `XX-YY`（`XX>0 && YY>0`）：分项实践页，必须包含可执行物（YAML 路径或命令块）

简单理解这几份入口的分工：

- `README.md`：新手入口，看「要做什么、按什么顺序做」；
- `docs/00-00-构建总览.md`：文档导航 + **学习主线（6 步）**与**附录长单**；
- `docs/00-01-k3s-基础概念.md`：概念速查，看「不懂的 K3s/Traefik/NetworkPolicy 术语」；
- `./ansible/bin/verify.sh`：按 `doc_id` 的自动化验证入口（`full/run-all/run`；清单由 `ansible/playbooks/verify/` 自动生成，且仅包含执行域 `XX>0 && YY>0`）。

目录约定：

- 主文档：`docs/`
- 脚本：`scripts/`

## 学习主线（6 步，推荐）

与 `docs/00-00-构建总览.md` 中主线一致；更细的**流程图与分叉说明**也在该篇。

1. **总览与环境**：读 `docs/00-00-构建总览.md`；需要对照机器与版本时打开 `docs/00-02-部署环境说明.md`。
2. **概念速查（可跳过）**：读 `docs/00-01-k3s-基础概念.md`；时间紧可跳过，**碰壁再回来看**。
3. **安装 K3s（二选一）**：**自动化** — `docs/01-05-节点初始化-ansible-实践.md`，或仓库根执行 `./ansible/bin/deploy-lab.sh k3s`（可选 `K3S_PREPARE_STORAGE=true`，详见 `scripts/README.md`）；**手动** — `docs/01-01-k3s-控制节点含traefik.md` 再 `docs/01-02-k3s-工作节点.md`。
4. **确认节点 Ready**：`kubectl get nodes`，全部 Ready。
5. **Nginx 最小验证**：`docs/02-00-nginx-系列说明.md` → `docs/02-05-nginx-验证矩阵-一键部署.md`，先打通「能访问」；也可在装好集群并配置 `.env.verify` 后直接 `./ansible/bin/verify.sh run 02-05`。
6. **Node.js 主线入口**：`docs/04-01-k3s-nodejs-高级部署.md`；`docs/04-02`～`04-14` 为分项，**按需展开**，不挤进主线编号。

**主线之后（按需，不占主线序号）**：Traefik 面板与证书（如 `docs/03-01-k3s-traefik-dashboard.md`、`docs/03-02-k3s-traefik-acme.md`）、存储与应用（`03-05` 起、`05-**`）等 — 见总览中的「主线之后的分叉」与专题导航。

**任意一步卡住**：排障见 `scripts/README.md`（如 firewalld 基线、入口链路诊断）；NetworkPolicy 见 `docs/06-01-k3s-networkpolicy-故障排查.md`。

## 30 分钟快速通关（4 步）

相当于**跳过主线第 2 步（概念）**并**压缩第 1 步（只抓总览要点）**；跑通再按 6 步补全。

1. **装集群**：Ansible 按 `docs/01-05-节点初始化-ansible-实践.md`（推荐）；或 `docs/01-01` + `docs/01-02` 手动装控制节点（61）与工作节点（62）。
2. `kubectl get nodes`，确认节点 Ready。
3. 按 `docs/02-05-nginx-验证矩阵-一键部署.md` 部署 nginx 矩阵并访问一次（可先读 `docs/02-00-nginx-系列说明.md`）。
4. 若访问不通，按 `scripts/README.md` 先跑 firewalld 基线与入口链路诊断脚本。

跑到这里算「基础链路通关」。后续再补 `04-01`、Traefik、存储等会轻松很多。  
若愿意，可在对应实验篇文档里补充你自己的“已验证环境/日期/版本”记录（不再维护统一矩阵页）。

## 一句话建议

先把基础链路（如 61/62:80）跑通，再叠加业务；每做完一步做一次 `curl` 验证，排障会轻松很多。

补充：`verify.sh` 支持按范围筛选执行（`--series`、`--id-regex`、`--exclude-noop`、`--require-teardown`），适合做分批回归与 CI 分层跑批。