对齐文件规范

2026-03-27 16:58:41 +08:00
parent 231b6713c4
commit 31709425e2
235 changed files with 5433 additions and 2850 deletions
--- a/docs/01-01-k3s-控制节点含traefik.md
+++ b/docs/01-01-k3s-控制节点含traefik.md
@@ -1,8 +1,13 @@
 # 01-01-k3s-控制节点含traefik

-> 在控制节点安装 K3s Server，确认基础组件与 Traefik 可用。
->
-> 若需一键自动化安装多节点集群，可直接用 `01-06-节点初始化-ansible-实践.md`。
+## TL;DR
+
+- **自动化验收**：在控制端（如 `ylc65`）执行 `./scripts/verify.sh run 01-01`
+- **手工安装**：控制节点执行 `curl -sfL https://get.k3s.io | sh -s - server --data-dir=/storage`（或默认路径）
+- **成功判据**：node 为 `Ready`；`kube-system` 中 `coredns` / `traefik` Deployment 存在；Traefik 入口可响应（常见为 `404`）
+- **失败排障**：见本文「排障」小节（事件/Pod/日志/磁盘压力）
+
+> 说明：本篇聚焦 **单控制节点安装与基础验收**。若要一键自动化安装多节点集群，见 `01-06-节点初始化-ansible-实践.md`。

 ## 前置条件

@@ -20,7 +25,7 @@ K3s 默认将数据（含 local-path 卷）放在 `--data-dir` 下。系统盘
 | **方案一（默认）** | `/var/lib/rancher/k3s` | 系统盘空间充足 |
 | **方案二（数据盘）** | `/storage` | 系统盘小，数据盘单独挂载在 `/storage` |

-> 自定义 `/storage` 仅解决单节点内系统盘/数据盘分离；节点或数据盘重建后数据不会自动迁移，高可用与备份见 `01-04`、`06-03`。
+> 自定义 `/storage` 仅解决单节点内系统盘/数据盘分离；节点或数据盘重建后数据不会自动迁移，高可用与备份见 `01-08`、`06-03`。

 ## 操作步骤

@@ -42,7 +47,7 @@ curl -sfL https://get.k3s.io | sh -
 curl -sfL https://get.k3s.io | sh -s - server --data-dir=/storage
 ```

- 使用方案二时，token 路径为 `/storage/server/token`（供 01-02 工作节点加入与 01-04 HA 使用）。
+- 使用方案二时，token 路径为 `/storage/server/token`（供 01-02 工作节点加入与 01-08 HA 使用）。

 ## 配置 kubectl（供当前用户使用）

@@ -151,6 +156,16 @@ curl -I --max-time 3 http://127.0.0.1:80
 - `kube-system` 命名空间核心组件正常运行
 - Traefik 服务已创建并可响应（常见为 `404`，表示入口已通）

+## 清理
+
+本篇为安装类文档：手工安装后一般 **不卸载 K3s**，而是继续后续实验。若你仅为排障临时验收，可在运行 `./scripts/verify.sh run 01-01` 时设 `VERIFY_TEARDOWN=0` 保留现场（本篇用例默认不做破坏性清理）。
+
+## 排障
+
+- **节点不 Ready / DiskPressure**：优先确认 `/storage` 为独立挂载点（见 `docs/00-04-部署环境说明.md`），再看 `df -h`、`kubectl describe node <name>` 事件。
+- **Traefik 不就绪**：`kubectl -n kube-system get pods -o wide`；必要时 `kubectl -n kube-system logs deploy/traefik --tail=200`。
+- **CoreDNS 解析异常（影响后续 ACME）**：见下节「CoreDNS 上游 DNS」。
+
 ## CoreDNS 上游 DNS（ACME 用）

 若后续要按 `03-02` / `03-03` 配置 ACME（Let's Encrypt），需确保集群内能解析 `acme-v02.api.letsencrypt.org`。宿主机若使用 **IPv6 DNS**（`/etc/resolv.conf` 含 `240e:...` 等），K3s Pod 网络仅 IPv4 时无法访问，ACME 会报 `server misbehaving` 或 `network is unreachable`。