对齐文件规范

docs/05-04-k3s-配置gitlab-cicd.md

@@ -2,6 +2,14 @@
 
 > 把 manifests 与 values 纳入 GitLab 仓库，通过流水线自动部署到 K3s。
 
+
+## TL;DR
+
+- **自动化验收**：`./scripts/verify.sh run 05-04`
+- **关键前置**：按本文「前置条件」准备环境变量/Secret/入口 IP
+- **成功判据**：达到本文「预期」且 playbook 断言通过
+- **排障**：见本文「排障」
+
 ---
 
 ## 建议仓库结构
@@ -33,8 +41,8 @@ homelab-config/
 
 **唯一真源（示例流水线）**：
 
-- 最小：[`ansible/files/05-04-gitlab-cicd/gitlab-ci-minimal.example.yml`](../ansible/files/05-04-gitlab-cicd/gitlab-ci-minimal.example.yml)
-- 多架构 deploy：[`ansible/files/05-04-gitlab-cicd/gitlab-ci-multi-arch-deploy.example.yml`](../ansible/files/05-04-gitlab-cicd/gitlab-ci-multi-arch-deploy.example.yml)
+- 最小：[`ansible/files/05-04/gitlab-ci-minimal.example.yml`](../ansible/files/05-04/gitlab-ci-minimal.example.yml)
+- 多架构 deploy：[`ansible/files/05-04/gitlab-ci-multi-arch-deploy.example.yml`](../ansible/files/05-04/gitlab-ci-multi-arch-deploy.example.yml)
  
 复制到仓库根为 `.gitlab-ci.yml`（或 `include` 引用），并配好 Runner 与 `KUBE_CONFIG_CONTENT` 等变量。
 
@@ -52,3 +60,9 @@ homelab-config/
 
 - `05-05-prometheus与grafana.md`
 - `06-02-运维小结.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`。