4.8 KiB
实验室建设（新手入口）
这个仓库是一个家庭实验室（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 中主线一致；更细的流程图与分叉说明也在该篇。
- 总览与环境：读
docs/00-00-构建总览.md；需要对照机器与版本时打开docs/00-02-部署环境说明.md。 - 概念速查（可跳过）：读
docs/00-01-k3s-基础概念.md；时间紧可跳过，碰壁再回来看。 - 安装 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。 - 确认节点 Ready：
kubectl get nodes，全部 Ready。 - Nginx 最小验证：
docs/02-00-nginx-系列说明.md→docs/02-05-nginx-验证矩阵-一键部署.md，先打通「能访问」；也可在装好集群并配置.env.verify后直接./ansible/bin/verify.sh run 02-05。 - 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 步补全。
- 装集群：Ansible 按
docs/01-05-节点初始化-ansible-实践.md（推荐）；或docs/01-01+docs/01-02手动装控制节点（61）与工作节点（62）。 kubectl get nodes，确认节点 Ready。- 按
docs/02-05-nginx-验证矩阵-一键部署.md部署 nginx 矩阵并访问一次（可先读docs/02-00-nginx-系列说明.md）。 - 若访问不通，按
scripts/README.md先跑 firewalld 基线与入口链路诊断脚本。
跑到这里算「基础链路通关」。后续再补 04-01、Traefik、存储等会轻松很多。
若愿意，可在对应实验篇文档里补充你自己的“已验证环境/日期/版本”记录（不再维护统一矩阵页）。
一句话建议
先把基础链路（如 61/62:80）跑通，再叠加业务；每做完一步做一次 curl 验证，排障会轻松很多。
补充：verify.sh 支持按范围筛选执行（--series、--id-regex、--exclude-noop、--require-teardown），适合做分批回归与 CI 分层跑批。