对齐文件规范

docs/05-01-k3s-部署homer首页面板.md

@@ -2,6 +2,14 @@
 
 > 在 K3s 中部署 Homer，作为家庭实验室的统一导航页。
 
+
+## TL;DR
+
+- **自动化验收**：`./scripts/verify.sh run 05-01`
+- **关键前置**：按本文「前置条件」准备环境变量/Secret/入口 IP
+- **成功判据**：达到本文「预期」且 playbook 断言通过
+- **排障**：见本文「排障」
+
 ---
 
 ## Homer 相对「纯书签」的优势
@@ -24,10 +32,10 @@
 
 ```bash
 kubectl create ns homer
-kubectl apply -f ansible/files/05-01-homer/homer.yaml
+kubectl apply -f ansible/files/05-01/homer.yaml
 ```
 
-**唯一真源**：[`ansible/files/05-01-homer/homer.yaml`](../ansible/files/05-01-homer/homer.yaml)（ConfigMap + Deployment + Service + Ingress）。
+**唯一真源**：[`ansible/files/05-01/homer.yaml`](../ansible/files/05-01/homer.yaml)（ConfigMap + Deployment + Service + Ingress）。
 
 ### 自定义导航（config.yml）
 
@@ -37,7 +45,7 @@ kubectl apply -f ansible/files/05-01-homer/homer.yaml
 - 修改后重新应用并滚动 Pod 生效：
 
 ```bash
-kubectl apply -f ansible/files/05-01-homer/homer.yaml
+kubectl apply -f ansible/files/05-01/homer.yaml
 kubectl -n homer rollout restart deploy/homer
 ```
 
@@ -49,28 +57,11 @@ kubectl -n homer rollout restart deploy/homer
 
 **示例（摘自 Homer 文档形态，按需改 `url`）：**
 
-```yaml
-- name: "System Metrics"
-  type: "Glances"
-  icon: "fa-solid fa-heart-pulse"
-  url: "https://glances.example.com" # 须指向 Glances 提供的 Web/API 基址
-  stats: [cpu, mem] # 可选：load, cpu, mem, swap（均来自下方「目标」）
-```
+示例真源：[`ansible/files/05-01/homer-glances-item.example.yaml`](../ansible/files/05-01/homer-glances-item.example.yaml)
 
 **在目标机用 Docker 跑 Glances（Web 模式）示例**（Homer 的 `url` 需指向该服务可访问地址，默认端口以镜像说明为准）：
 
-```yaml
-services:
-  glances:
-    image: nicolargo/glances:latest
-    container_name: glances
-    environment:
-      - TZ=Asia/Shanghai
-      - GLANCES_OPT=-w
-    ports:
-      - "61208:61208"
-    restart: unless-stopped
-```
+示例真源：[`ansible/files/05-01/glances-docker-compose.example.yaml`](../ansible/files/05-01/glances-docker-compose.example.yaml)
 
 **要点：**
 
@@ -94,3 +85,9 @@ curl -I --max-time 3 http://192.168.2.61/
 ## 下一步
 
 - `05-02-onenav首页面板.md`
+
+## 排障
+
+- **先看 playbook 输出**：失败时先定位是 deploy/wait/http_check 哪一步。
+- **集群侧总览**：`kubectl get nodes -o wide`、`kubectl -n kube-system get pods -o wide`。
+- **事件与日志**：`kubectl -n <ns> describe ...`、`kubectl -n <ns> logs ... --tail=200`。