对齐文件规范

docs/03-04-k3s-cloudflare-tunnel-配置接入.md

@@ -2,7 +2,15 @@
 
 > 本文覆盖 Tunnel 完整流程：Zero Trust 云端创建、域名映射，以及将 `cloudflared` 安装到 K3s 并跑起 Pod，使 **Traefik 通过 Tunnel 对外提供服务**。
 >
-> **状态：已验证**（2026-03，本仓库实验室 K3s 集群；详见 `00-02-验证矩阵.md`）。
+> **状态：已验证**（2026-03，本仓库实验室 K3s 集群）。
+
+
+## TL;DR
+
+- **自动化验收**：`./scripts/verify.sh run 03-04`
+- **关键前置**：按本文「前置条件」准备环境变量/Secret/入口 IP
+- **成功判据**：达到本文「预期」且 playbook 断言通过
+- **排障**：见本文「排障」
 
 ---
 
@@ -45,7 +53,7 @@ Traefik 是唯一入口。所有流量经 Tunnel 进入后，由 Traefik 的 Ing
 
 ### 3. 部署 cloudflared 到 K3s
 
-1. 从 **唯一真源** 复制清单：[`ansible/files/03-04-cloudflare-tunnel/cloudflared.yaml`](../ansible/files/03-04-cloudflare-tunnel/cloudflared.yaml)
+1. 从 **唯一真源** 复制清单：[`ansible/files/03-04/cloudflared.yaml`](../ansible/files/03-04/cloudflared.yaml)
 2. 将 `TUNNEL_TOKEN` 占位符替换为前述 Zero Trust 中复制的 Token
 3. 应用并等待 Pod 就绪（按实际 manifests 路径选择其一）：
 
@@ -81,7 +89,7 @@ Tunnel 后端应指向 **集群内的 Traefik 入口**，常用写法：
 
 **和仓库里哪份 YAML 的关系**
 
-- 本仓库的 [`cloudflared.yaml`](../ansible/files/03-04-cloudflare-tunnel/cloudflared.yaml) **只** 定义 `cloudflared` 的 Deployment/Secret，**不包含** Traefik Service；Tunnel 后端地址写的是 **集群里已存在的 Traefik Service**，不是 `cloudflared.yaml` 里的某一行。
+- 本仓库的 [`cloudflared.yaml`](../ansible/files/03-04/cloudflared.yaml) **只** 定义 `cloudflared` 的 Deployment/Secret，**不包含** Traefik Service；Tunnel 后端地址写的是 **集群里已存在的 Traefik Service**，不是 `cloudflared.yaml` 里的某一行。
 - Traefik 的 **Service** 由 K3s 内置 Traefik（HelmChart）安装时创建，资源名一般为 **`traefik`**，命名空间 **`kube-system`**。若你改过 chart 或 Service 名，以下 FQDN 与端口要以 **实际 `kubectl get svc` 输出** 为准。
 
 **与 `kubectl get svc traefik -o yaml` 里哪些字段对应**
@@ -239,3 +247,9 @@ Zero Trust 向导顺序为：选择类型 → 命名 → **安装并运行 Conne
 - 其他应用（GitLab、Homer 等）：在集群内创建 IngressRoute/Ingress 指定 Host 与后端，再在 Zero Trust 中添加对应子域的 Public Hostname 即可
 - `05-03-k3s-安装gitlab-含runner.md`
 - `05-01-k3s-部署homer首页面板.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`。