对齐文件规范

docs/01-07-openwrt-haproxy.md

@@ -2,6 +2,14 @@
 
 > 在 OpenWrt 上安装并配置 HAProxy，将 80/443 流量转发到 K3s 集群节点（Traefik 入口），实现单一入口与负载均衡。
 
+
+## TL;DR
+
+- **自动化验收**：`./scripts/verify.sh run 01-07`
+- **关键前置**：按本文「前置条件」准备环境变量/Secret/入口 IP
+- **成功判据**：达到本文「预期」且 playbook 断言通过
+- **排障**：见本文「排障」
+
 ## 前置条件
 
 - OpenWrt 与 K3s 节点同网段（如 192.168.2.0/24），OpenWrt 通常为网关（如 192.168.2.1）
@@ -20,9 +28,9 @@ opkg install haproxy
 
 编辑 `/etc/haproxy.cfg` 或包提供的配置路径（部分 OpenWrt 使用 `/etc/haproxy/haproxy.cfg`）。可在 `/etc/init.d/haproxy` 中查看实际配置文件路径。
 
-**配置目录说明与「cfg 是否正确」的验证层次**：见 `ansible/files/01-07-haproxy/README.md`（**仅语法**：`./scripts/01-07-verify-haproxy.sh --cfg-only`）。
+**配置目录说明与「cfg 是否正确」的验证层次**：见 `ansible/files/01-07/`（**仅语法**：`./scripts/01-07-verify-haproxy.sh --cfg-only`）。
 
-**无健康检查最简配置**：`ansible/files/01-07-haproxy/haproxy-no-check.cfg`（与 Ansible 共用，可复制到 OpenWrt 或通过 playbook 下发）。将 `192.168.2.61`～`192.168.2.64` 按实际 K3s 节点 IP 修改。如需健康检查见第 3 节；如需真实客户端 IP 见第 5 节 PROXY Protocol。
+**无健康检查最简配置**：`ansible/files/01-07/haproxy-no-check.cfg`（与 Ansible 共用，可复制到 OpenWrt 或通过 playbook 下发）。将 `192.168.2.61`～`192.168.2.64` 按实际 K3s 节点 IP 修改。如需健康检查见第 3 节；如需真实客户端 IP 见第 5 节 PROXY Protocol。
 
 ## 3. 健康检查
 
@@ -43,15 +51,15 @@ opkg install haproxy
 
 ### 3.2 HTTP（80 明文）
 
-完整配置：`ansible/files/01-07-haproxy/haproxy-http.cfg`。`backend k3s_http` 开头加 `option httpchk GET /`，`k3s_https` 仍为 TCP 检查。
+完整配置：`ansible/files/01-07/haproxy-http.cfg`。`backend k3s_http` 开头加 `option httpchk GET /`，`k3s_https` 仍为 TCP 检查。
 
 ### 3.3 TLS（443 握手，`mode tcp`）
 
-完整配置：`ansible/files/01-07-haproxy/haproxy-tls.cfg`。`backend k3s_https` 中加 `option ssl-hello-chk`，做 TLS 握手层检查。
+完整配置：`ansible/files/01-07/haproxy-tls.cfg`。`backend k3s_https` 中加 `option ssl-hello-chk`，做 TLS 握手层检查。
 
 ### 3.4 HTTPS（443 应用层，`mode http` + `ssl`）
 
-完整配置：`ansible/files/01-07-haproxy/haproxy-https.cfg`。适用于 **HAProxy 在 443 终结 TLS（由 HAProxy 提供证书）** 的场景（frontend 需 `bind *:443 ssl crt ...`）。需与 Traefik 路由匹配的 `Host`；自签/内网 CA 用 `verify none`，生产建议 `ca-file`。若仍为 TCP 透传，用 3.3 即可。
+完整配置：`ansible/files/01-07/haproxy-https.cfg`。适用于 **HAProxy 在 443 终结 TLS（由 HAProxy 提供证书）** 的场景（frontend 需 `bind *:443 ssl crt ...`）。需与 Traefik 路由匹配的 `Host`；自签/内网 CA 用 `verify none`，生产建议 `ca-file`。若仍为 TCP 透传，用 3.3 即可。
 
 ## 4. 启动与验证
 
@@ -66,13 +74,13 @@ opkg install haproxy
 
 **验证**：经 **ssh onecloud**（或你可访问的第三方机器）发起 curl，验证 `http://<OpenWrt-IP>:18080` 与 `https://<域名>:18443`（HTTPS 需正确设置 Host/SNI，例如 `curl --https-hosts ...`）。不部署、不改端口；需 OpenWrt HAProxy 已按 18080/18443 配置。
 
-验证通过后，请**手工**在 `docs/00-02-验证矩阵.md` 补充状态与备注（当前仓库已下线“自动更新矩阵”的执行入口）。
+验证通过后，建议你在本篇文档中**手工**补充状态与备注（环境/日期/覆盖范围）。
 
 ## 5. PROXY Protocol（可选）
 
 若 Traefik 需获取真实客户端 IP，可在 HAProxy 后端每个 `server` 行添加 `send-proxy-v2`，并在 Traefik 配置 `trustedIPs` 包含 OpenWrt 网段（见 `03-02-k3s-traefik-acme.md`）。
 
-**完整配置**：`ansible/files/01-07-haproxy/haproxy-proxy-http-tls.cfg`（HTTP 检查 + TLS 检查 + PROXY）。
+**完整配置**：`ansible/files/01-07/haproxy-proxy-http-tls.cfg`（HTTP 检查 + TLS 检查 + PROXY）。
 
 Traefik 端需启用 PROXY protocol 监听并信任 OpenWrt 的 IP，否则会报错。UCI 配置需参考 OpenWrt HAProxy 文档中的相应选项。
 
@@ -115,3 +123,9 @@ curl -v http://192.168.2.61/
 - `01-02-k3s-工作节点.md`：Traefik 入口与 LB 基线
 - `02-05-nginx-验证矩阵-一键部署.md`：验证矩阵（按入口 IP 访问）
 - `03-02-k3s-traefik-acme.md`：PROXY protocol、trustedIPs
+
+## 排障
+
+- **先看 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`。