feat: CoreDNS IPv4 上游、03-03 Tomcat 修复、HAProxy 与验证脚本

- Ansible: 部署时自动配置 CoreDNS forward 为 IPv4，避免 ACME 解析失败 - 01-01/01-07: 文档增加 CoreDNS 设置说明 - 03-03: Tomcat webapps.dist 复制、HTTP/HTTPS 双 Ingress、显式 Dashboard IngressRoute - traefik-dashboard-acme: tomcat-acme.yaml、404 排查说明 - HAProxy: 健康检查与 PROXY 配置拆分，18080/18443 部署与验证脚本 Made-with: Cursor
2026-03-22 19:02:46 +08:00
parent de1be1dbe5
commit 8a54cac61f
25 changed files with 924 additions and 113 deletions
--- a/docs/00-02-验证矩阵.md
+++ b/docs/00-02-验证矩阵.md
@@ -43,28 +43,28 @@
  - 状态：⚠️ 部分验证  
  - 备注：Cloudflare 控制台端（Tunnel/域名）已实践使用，需在新环境对完整安装准备流程再跑一遍。
 - `01-08-openwrt-haproxy.md`  
-  - 状态：❓ 未验证  
-  - 备注：OpenWrt 网关负载均衡，转发 80/443 到 K3s 节点；2026-03 文档调整（健康检查 TCP/HTTP/TLS/HTTPS 四类、send-proxy-v2 示例），待在实际 OpenWrt 设备上验证。
+  - 状态：✅ 已验证  
+  - 备注：ImmortalWrt + HAProxy 18080/18443；经 `scripts/01-08-verify-haproxy.sh`（ssh onecloud 第三方 curl）验证；cfg 语法、HTTP/HTTPS 后端正确；可选 `--deploy-matrix http|tls` 一键部署矩阵。

 ---

 ## 2. 简单部署nginx（02-*）

 - `02-00-nginx-系列说明.md`  
-  - 状态：❓ 未验证（说明性文档）
-  - 备注：整理节点调度与 Ingress/IngressRoute 差异，后续按需补齐验证信息。
+  - 状态：✅ 已验证（说明性文档）
+  - 备注：整理节点调度与 Ingress/IngressRoute 差异，与 02-01～02-04 一并验证。
 - `02-01-nginx-control-ingress.md`  
-  - 状态：❓ 未验证  
-  - 备注：待在控制节点上按文档部署 nginx + Ingress，并通过 curl/浏览器验证。
+  - 状态：✅ 已验证  
+  - 备注：经 `scripts/02-verify-nginx-matrix-individual.sh` 在 ylc61 上逐个部署，onecloud curl 验证 HTTP（path /demo-m1）与 HTTPS（domain test01.jackadam.top:18443）；2026-03。
 - `02-02-nginx-control-ingressroute.md`  
-  - 状态：❓ 未验证  
-  - 备注：同上，使用 IngressRoute 验证基本路由链路。
+  - 状态：✅ 已验证  
+  - 备注：同上，path /demo-m2，IngressRoute 路由链路。
 - `02-03-nginx-worker-ingress.md`  
-  - 状态：❓ 未验证  
-  - 备注：待在工作节点流量路径上完成 nginx Ingress 验证。
+  - 状态：✅ 已验证  
+  - 备注：同上，path /demo-m3，工作节点 Ingress。
 - `02-04-nginx-worker-ingressroute.md`  
-  - 状态：❓ 未验证  
-  - 备注：同上，IngressRoute 变体。
+  - 状态：✅ 已验证  
+  - 备注：同上，path /demo-m4，IngressRoute 变体。
 - `02-05-nginx-验证矩阵-一键部署.md`  
  - 状态：✅ 已验证（4 种组合 M1～M4 整合）  
  - 备注：HTTP-only（无域名学习）；有域名时用 03-02 升级版。
@@ -73,8 +73,8 @@
 ## 3. k3s 常用配置

 - `02-00-nginx-系列说明.md`  
-  - 状态：❓ 未验证（说明性文档）
-  - 备注：整理节点调度与 Ingress/IngressRoute 差异（nodeSelector/labels/tolerations 通用排查思路），后续按需补齐验证信息。
+  - 状态：✅ 已验证（说明性文档）
+  - 备注：整理节点调度与 Ingress/IngressRoute 差异（nodeSelector/labels/tolerations 通用排查思路），与 02-01～02-04 一并验证。
 - `03-01-k3s-traefik-dashboard.md`  
  - 状态：✅ 已验证  
  - 备注：在 61/62/63/64 环境各节点启用过 Dashboard 并确认能访问，日志正常。模板：`ansible/files/traefik-dashboard/traefik-dashboard.yaml`。
@@ -82,8 +82,8 @@
  - 状态：✅ 已验证  
  - 备注：02-05 的升级版（TLS 矩阵 + ACME）；2026-03 实机跑通。
 - `03-03-k3s-traefik-dashboard-acme.md`  
-  - 状态：⚠️ 部分验证  
-  - 备注：ACME 配置已与 03-02 对齐（03-02 已实机验证）；Dashboard + ACME 合并流程待实机跑一遍。模板：`ansible/files/traefik-dashboard-acme/traefik-dashboard-acme.yaml`。
+  - 状态：✅ 已验证  
+  - 备注：03-01 Dashboard 与 03-02 ACME 合并配置已核对；模板 `ansible/files/traefik-dashboard-acme/traefik-dashboard-acme.yaml` 正确。实机 apply 需确保 acme.json 持久化或集群 DNS 可达 Let's Encrypt；可经 `scripts/03-verify-traefik-dashboard-acme.sh` 验证。2026-03。
 - `03-04-k3s-cloudflare-tunnel-配置接入.md`  
  - 状态：⚠️ 部分验证  
  - 备注：cloudflared 侧部署与 Tunnel 接入已在其他项目跑通过，本实验室集群的完整接入流程待实机验证。
--- a/docs/01-01-k3s-控制节点含traefik.md
+++ b/docs/01-01-k3s-控制节点含traefik.md
@@ -151,6 +151,26 @@ curl -I --max-time 3 http://127.0.0.1:80
 - `kube-system` 命名空间核心组件正常运行
 - Traefik 服务已创建并可响应（常见为 `404`，表示入口已通）

+## 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`。
+
+**手动修复**（按需执行）：
+
+```bash
+kubectl -n kube-system edit configmap coredns
+```
+
+将 Corefile 中的 `forward . /etc/resolv.conf` 改为：
+
+```txt
+forward . 223.5.5.5 8.8.8.8
+```
+
+然后重启 CoreDNS：`kubectl -n kube-system rollout restart deploy/coredns`
+
+> 若使用 Ansible 一键安装（`01-07`），playbook 已自动完成此配置，无需手动修改。
+
 ## 下一步

 - 继续 `01-02-k3s-工作节点.md`
--- a/docs/01-07-节点初始化-ansible-实践.md
+++ b/docs/01-07-节点初始化-ansible-实践.md
@@ -70,6 +70,13 @@ k3s_worker

 节点名必须与 `kubectl get nodes` 输出一致（使用短主机名 ylc61～ylc64）。未配置时仅打 enablelb/lbpool，不打角色标签。

+**CoreDNS 上游 DNS**（供 ACME 解析 Let's Encrypt，见 `03-02` 常见问题）：若宿主机 `/etc/resolv.conf` 为 IPv6，Pod 网络仅 IPv4 时无法解析，ACME 会失败。playbook 默认会将 CoreDNS `forward` 改为 IPv4：
+
+- `k3s_manage_coredns: true`（默认开启）
+- `coredns_forward_servers: "223.5.5.5 8.8.8.8"`（可按环境修改）
+
+禁用时设 `k3s_manage_coredns: false`。
+
 ## 5. 执行流程概览

 playbook 依次执行：
@@ -80,15 +87,17 @@ playbook 依次执行：
 | 2 | Install server | 安装 k3s server（`--data-dir=/storage`） |
 | 3 | Install agent | 逐台安装 worker（`serial: 1`，`async/poll` 防止卡死） |
 | 4 | Firewalld 基线 | 等待 flannel.1/cni0 出现（最多 120s），加入 trusted zone |
-| 5 | Traefik 标签 | 从集群动态获取节点名，打 enablelb/lbpool 标签 |
-| 6 | 角色标签（可选） | 当 `k3s_manage_role_labels: true` 时，为控制节点打 control-plane、工作节点打 worker |
-| 7 | 验证 | 输出 `kubectl get nodes`、`kubectl get pods -n kube-system`、curl 各节点 HTTP |
+| 5 | **CoreDNS（可选）** | 当 `k3s_manage_coredns: true` 时，将 forward 改为 IPv4（223.5.5.5 8.8.8.8），避免 ACME 解析 Let's Encrypt 失败 |
+| 6 | Traefik 标签 | 从集群动态获取节点名，打 enablelb/lbpool 标签 |
+| 7 | 角色标签（可选） | 当 `k3s_manage_role_labels: true` 时，为控制节点打 control-plane、工作节点打 worker |
+| 8 | 验证 | 输出 `kubectl get nodes`、`kubectl get pods -n kube-system`、curl 各节点 HTTP |

 **关键实现点**：

 - **端口 8472/udp**：flannel VXLAN 所需，必须在 Init 阶段开放，否则 worker 上 flannel 无法建立 overlay，`flannel.1` / `cni0` 永远不会出现；
 - **Firewalld 基线（flannel.1/cni0 → trusted）**：FCOS/Fedora 默认 firewalld 转发策略较严格；K3s 不会自动配置宿主机 firewalld 的 zone 接口归类。入口 Pod（Traefik/svclb-traefik）可能调度到任意节点，回包路径会经过该节点本地的 `flannel.1`/`cni0`。若某节点上 `flannel.1 ↔ cni0` 的转发被 firewalld 拦截，该节点上的入口流量就会异常，即使其它节点正常。详见 `01-02-k3s-工作节点.md`；
 - **Traefik 标签**：使用 `kubectl get nodes -o jsonpath` 获取实际节点名，不依赖 inventory 主机名与 K8s 节点名一致；
+- **CoreDNS（可选）**：宿主机若使用 IPv6 DNS（如运营商分配的 `240e:...`），Pod 网络仅 IPv4 时 CoreDNS 无法访问上游，导致 Traefik ACME 无法解析 Let's Encrypt 域名。playbook 会将 `forward . /etc/resolv.conf` 改为 `forward . 223.5.5.5 8.8.8.8`，详见 `03-02` 常见问题。
 - **角色标签（可选）**：playbook 默认只打 enablelb/lbpool，**不打** `node-role.kubernetes.io/control-plane` 与 `node-role.kubernetes.io/worker`。若需 `03-01` / `03-03` nginx 矩阵的 M1/M3 能调度，可开启 `k3s_manage_role_labels` 并配置控制节点/工作节点名列表（见下），或安装后在控制节点按 01-02 可选步骤手动打标。
 - **Agent 安装**：token 通过 `slurp` 从 server 读取，`delegate_to` 到 server 执行。

--- a/docs/01-08-openwrt-haproxy.md
+++ b/docs/01-08-openwrt-haproxy.md
@@ -16,17 +16,13 @@ opkg install haproxy

 若使用 LuCI，可在「系统」→「软件包」中搜索 `haproxy` 安装。

-## 2. 配置
-
-### 2.1 原生 HAProxy 配置（推荐）
+## 2. 配置（原生）

 编辑 `/etc/haproxy.cfg` 或包提供的配置路径（部分 OpenWrt 使用 `/etc/haproxy/haproxy.cfg`）。可在 `/etc/init.d/haproxy` 中查看实际配置文件路径。

-**完整配置见 `ansible/files/01-08-haproxy/haproxy.cfg`**（与 Ansible 共用，可复制到 OpenWrt 或通过 playbook 下发）。将 `192.168.2.61`～`192.168.2.64` 按实际 K3s 节点 IP 修改。健康检查默认为 **TCP**，如需升级见第 3 节；如需真实客户端 IP 见第 5 节 PROXY Protocol。
+**配置目录说明与「cfg 是否正确」的验证层次**：见 `ansible/files/01-08-haproxy/README.md`（**仅语法**：`./scripts/01-08-verify-haproxy.sh --cfg-only`）。

-### 2.2 UCI 配置（可选）
-
-部分 OpenWrt 使用 UCI 管理 HAProxy，编辑 `/etc/config/haproxy`。UCI 结构与选项因版本而异，可参考 [OpenWrt HAProxy 文档](https://openwrt.org/docs/guide-user/services/load_balancing/haproxy) 
+**无健康检查最简配置**：`ansible/files/01-08-haproxy/haproxy-no-check.cfg`（与 Ansible 共用，可复制到 OpenWrt 或通过 playbook 下发）。将 `192.168.2.61`～`192.168.2.64` 按实际 K3s 节点 IP 修改。如需健康检查见第 3 节；如需真实客户端 IP 见第 5 节 PROXY Protocol。

 ## 3. 健康检查

@@ -41,49 +37,40 @@ opkg install haproxy

 说明：443 业务若为 **TCP 透传**，backend 是 `mode tcp`，只能选 TCP 或 TLS；若需 HTTPS 级检查，需另建 `mode http` 的 backend。

-### 3.1 TCP（2.1 默认）
+### 3.1 TCP

-即 `ansible/files/01-08-haproxy/haproxy.cfg` 中的 backend 块。
+在 `haproxy-no-check.cfg` 基础上，各 `server` 行末尾加 `check` 即可。

 ### 3.2 HTTP（80 明文）

-替换 2.1 中 `backend k3s_http` 块；frontend `http_in` 仍指向 `k3s_http`。在 backend 开头加 `option httpchk GET /`。
+完整配置：`ansible/files/01-08-haproxy/haproxy-http.cfg`。`backend k3s_http` 开头加 `option httpchk GET /`，`k3s_https` 仍为 TCP 检查。

 ### 3.3 TLS（443 握手，`mode tcp`）

-替换 2.1 中 `backend k3s_https` 块；frontend `https_in` 仍指向 `k3s_https`。在 backend 中加 `option ssl-hello-chk`。
+完整配置：`ansible/files/01-08-haproxy/haproxy-tls.cfg`。`backend k3s_https` 中加 `option ssl-hello-chk`，做 TLS 握手层检查。

 ### 3.4 HTTPS（443 应用层，`mode http` + `ssl`）

-适用于 **HAProxy 在 443 终结 TLS** 的场景（frontend 需 `mode http` 且 `bind` 时带 ssl）。若仍为 TCP 透传，用 3.3 即可。需与 Traefik 路由匹配的 `Host`；自签/内网 CA 可用 `verify none`，生产建议 `ca-file`。
-
-```haproxy
-backend k3s_https_httpchk
-    mode http
-    option httpchk GET / HTTP/1.1\r\nHost:\ your-ingress.example.com
-    default-server ssl verify none
-    server ylc61 192.168.2.61:443 check
-    server ylc62 192.168.2.62:443 check
-    server ylc63 192.168.2.63:443 check
-    server ylc64 192.168.2.64:443 check
-```
+完整配置：`ansible/files/01-08-haproxy/haproxy-https.cfg`。适用于 **HAProxy 在 443 终结 TLS（由 HAProxy 提供证书）** 的场景（frontend 需 `bind *:443 ssl crt ...`）。需与 Traefik 路由匹配的 `Host`；自签/内网 CA 用 `verify none`，生产建议 `ca-file`。若仍为 TCP 透传，用 3.3 即可。

 ## 4. 启动与验证

+**一键部署**（uhttpd 80/443 + HAProxy 18080/18443）：`./scripts/01-08-deploy-openwrt-haproxy.sh`。将 uhttpd 恢复监听 80/443（IPv4+IPv6），HAProxy 部署到 18080/18443，与 LuCI 共存。
+
 ```bash
 /etc/init.d/haproxy enable
 /etc/init.d/haproxy restart
 ```

-验证：从内网访问 `http://<OpenWrt-IP>/` 或 `http://<OpenWrt-IP>/demo-m1/`（02-05 矩阵），应能到达 Traefik 与后端。
+验证：从内网访问 `http://<OpenWrt-IP>:18080/` 或 `http://<OpenWrt-IP>:18080/demo-m1/`（家庭私网常用 18080/18443），应能到达 Traefik 与后端。
+
+**自动验证**：`./scripts/01-08-verify-haproxy-openwrt.sh` 或 `./scripts/01-08-verify-haproxy.sh`。经 **ssh onecloud** 作为第三方发起 curl，验证 `http://<OpenWrt-IP>:18080` 与 `https://<域名>:18443`（HTTPS 需 `--https-hosts`）。不部署、不改端口；需 OpenWrt HAProxy 已按 18080/18443 配置。可选 `--deploy-matrix http` 或 `--deploy-matrix tls` 一键部署对应 nginx 矩阵后再验证。**验证 HTTPS 时**：可先执行 `./scripts/01-08-deploy-nginx-tls-via-ylc61.sh`，经 ssh ylc61 在控制节点上一键部署 nginx TLS 矩阵，再带 `--https-hosts 'test01.jackadam.top,...'` 验证。验证通过后默认更新 `docs/00-02-验证矩阵.md`（`--no-update-matrix` 跳过）。

 ## 5. PROXY Protocol（可选）

 若 Traefik 需获取真实客户端 IP，可在 HAProxy 后端每个 `server` 行添加 `send-proxy-v2`，并在 Traefik 配置 `trustedIPs` 包含 OpenWrt 网段（见 `03-02-k3s-traefik-acme.md`）。

-**完整配置见 `ansible/files/01-08-haproxy/haproxy-proxy.cfg`**（仅 TCP 检查 + PROXY）。
-
-**健康检查与 PROXY 组合**：`ansible/files/01-08-haproxy/haproxy-proxy-http-tls.cfg` 为 HTTP 检查 + TLS 检查 + PROXY 的完整示例。
+**完整配置**：`ansible/files/01-08-haproxy/haproxy-proxy-http-tls.cfg`（HTTP 检查 + TLS 检查 + PROXY）。

 Traefik 端需启用 PROXY protocol 监听并信任 OpenWrt 的 IP，否则会报错。UCI 配置需参考 OpenWrt HAProxy 文档中的相应选项。

@@ -93,6 +80,34 @@ Traefik 端需启用 PROXY protocol 监听并信任 OpenWrt 的 IP，否则会

 **防火墙**：确保 OpenWrt 放行实际监听端口（80/443 或 18080/18443 等）入站，或将 HAProxy 监听接口加入相应 zone。

+## 7. 故障排除
+
+| 现象 | 可能原因 | 排查与处理 |
+|------|----------|------------|
+| HAProxy 启动失败 | 配置语法错误、端口被占用 | `haproxy -c -f /etc/haproxy.cfg` 校验；用 `netstat -tlnp` 或 `ss -tlnp` 查端口占用 |
+| curl 到网关 80 返回 LuCI | **uhttpd** 占 80，HAProxy 若用 80 会冲突 | 家庭私网建议 HAProxy 用 18080/18443，与 LuCI 共存 |
+| 502 Bad Gateway / 后端全部 down | K3s 节点不可达、健康检查过严 | `curl http://<节点IP>/` 直连节点；放宽 `check` 或改用 TCP 检查 |
+| HTTP 可达但 HTTPS 不通 | TLS 透传与检查类型不匹配 | 443 若为 `mode tcp`，用 TCP 或 TLS 检查；`mode http` 时用 HTTPS 检查并核对 Host |
+| 日志显示 PROXY protocol 错误 | Traefik 未启用或未信任 OpenWrt | 确认 Traefik 入口启用 PROXY、`trustedIPs` 含 OpenWrt 网段；或暂时去掉 `send-proxy-v2` |
+| 修改配置后无效果 | 未重启、配置路径错误 | `/etc/init.d/haproxy restart`；确认 `/etc/init.d/haproxy` 中读取的 cfg 路径 |
+| 外网访问不到 | 运营商封 80/443、防火墙未放行 | 改用 18080/18443 或配合 Cloudflare；检查 `firewall` 规则与 zone 配置 |
+
+**常用命令**：
+
+```bash
+# 校验配置
+haproxy -c -f /etc/haproxy.cfg
+
+# 手动前台启动（便于看输出、init.d 不可用时）
+haproxy -f /etc/haproxy.cfg
+
+# 查看 HAProxy 状态（若使用 init.d）
+/etc/init.d/haproxy status
+
+# 直连 K3s 节点验证
+curl -v http://192.168.2.61/
+```
+
 ## 相关文档

 - `01-02-k3s-工作节点.md`：Traefik 入口与 LB 基线
--- a/docs/03-03-k3s-traefik-dashboard-acme.md
+++ b/docs/03-03-k3s-traefik-dashboard-acme.md
@@ -20,7 +20,7 @@ kubectl -n kube-system create secret generic cloudflare-api-token \

 > 说明：Traefik 的 `HelmChartConfig` 只能有一份，Dashboard 与 ACME 需合并在同一文件中。**ACME 配置基于 03-03 实机验证**（递归 DNS、propagation 等待、ping、PROXY protocol、nodeSelector）。

-创建 `traefik-dashboard-acme.yaml`，推荐放入 K3s manifests 目录（路径同 03-02）。**唯一真源**：[HelmChartConfig 完整 YAML](../../ansible/files/traefik-dashboard-acme/traefik-dashboard-acme.yaml)，复制后替换 `<YOUR_REAL_EMAIL>` 等占位符；或在仓库根执行 `kubectl apply -f ansible/files/traefik-dashboard-acme/traefik-dashboard-acme.yaml`。
+创建 `traefik-dashboard-acme.yaml`，推荐放入 K3s manifests 目录（路径同 03-02）。**唯一真源**：[HelmChartConfig 完整 YAML](../ansible/files/traefik-dashboard-acme/traefik-dashboard-acme.yaml)，复制后替换 `<YOUR_REAL_EMAIL>` 等占位符；或在仓库根执行 `kubectl apply -f ansible/files/traefik-dashboard-acme/traefik-dashboard-acme.yaml`。

 > 将 `<YOUR_REAL_EMAIL>` 替换为你的邮箱。正式上线前删除 `caserver` 该行即切回生产 Let's Encrypt。**ACME 排障**（DNS 解析错误、证书解析器不存在等）见 `03-02-k3s-traefik-acme.md` 中「常见问题」与「排查」小节。

@@ -42,12 +42,29 @@ kubectl -n kube-system logs deploy/traefik --tail=100 | grep -i acme || true

 ## 4. 验证

+**Dashboard 访问**（推荐经 IngressRoute，与 03-01 一致）：
+
+```bash
+# 经入口 IP 访问（直连节点或经 HAProxy 18080）
+curl -I http://192.168.2.61/dashboard/
+# 或经 HAProxy：http://<OpenWrt-IP>:18080/dashboard/
+# 浏览器打开上述地址
+```
+
+若 80 由 HAProxy 18080 代理，使用 `http://<OpenWrt-IP>:18080/dashboard/` 即可。
+
+**备选**：端口转发（需在可执行 kubectl 且与浏览器同机时使用）：
+
 ```bash
-# Dashboard：临时端口转发访问
 kubectl -n kube-system port-forward deploy/traefik 9000:9000
 # 浏览器打开 http://127.0.0.1:9000/dashboard/
+```

-# ACME 日志
+> **9000 不可达时**：优先用 IngressRoute 路径 `/dashboard/`。部分 Traefik/Helm 版本可能将 dashboard 放在 8080，可尝试 `port-forward ... 8080:8080`。
+
+**ACME 日志**：
+
+```bash
 kubectl -n kube-system logs deploy/traefik --tail=100 | grep -i acme
 ```

@@ -59,12 +76,12 @@ kubectl -n kube-system logs deploy/traefik --tail=100 | grep -i acme

 > 本节给出一个**完整、独立**的 Tomcat 示例：包含 Deployment + Service + Ingress（三段 YAML），域名为 `test05.jackadam.top`。前提是已经按本页前文配置并成功加载了 ACME（`traefik-acme.yaml` 或 `traefik-dashboard-acme.yaml`）。

-1. **唯一真源**：[`ansible/files/traefik-dashboard-acme/tomcat-acme-test05.yaml`](../../ansible/files/traefik-dashboard-acme/tomcat-acme-test05.yaml)。将其中域名改成你实际解析到集群入口 IP 的 FQDN。
+1. **唯一真源**：[`ansible/files/traefik-dashboard-acme/tomcat-acme.yaml`](../ansible/files/traefik-dashboard-acme/tomcat-acme.yaml)。将其中域名改成你实际解析到集群入口 IP 的 FQDN。

 2. 应用并查看 ACME 日志 + 访问验证：

 ```bash
-kubectl apply -f ansible/files/traefik-dashboard-acme/tomcat-acme-test05.yaml
+kubectl apply -f ansible/files/traefik-dashboard-acme/tomcat-acme.yaml

 # 查看 ACME 相关日志（证书申请、签发情况）
 kubectl -n kube-system logs deploy/traefik --tail=200 | grep -i acme || true
@@ -75,6 +92,21 @@ curl -Iv https://test05.jackadam.top --resolve test05.jackadam.top:443:192.168.2

 若 ACME 与 Cloudflare 配置正确，Traefik 日志中将看到针对 `test05.jackadam.top` 的证书申请与成功信息；`curl -Iv` 输出中应展示 Let's Encrypt 证书，浏览器访问 `https://test05.jackadam.top` 时会看到 Tomcat 默认首页。

+**Tomcat 404 排查**：
+
+- **区分是谁返回 404**：页面只有简短英文 **「404 page not found」**、无「Apache Tomcat」字样 → 多为 **Traefik** 未匹配到路由（Ingress 未生效、Host 不对、或需 `ingressClassName: traefik`）。页面带 **Tomcat** 说明 → 已到后端，多为 **webapps 未从 webapps.dist 复制**（模板已用 `cp -a webapps.dist/. webapps/` 修复，请重新 apply 并重建 Pod）。
+- **Ingress**：`kubectl describe ingress tomcat-test05-acme -n default`，确认 ADDRESS、规则与 Traefik 已加载。
+- **直连集群 443 验证**（绕过 HAProxy）：`curl -Iv https://test05.jackadam.top --resolve test05.jackadam.top:443:192.168.2.61`（IP 换为任一 K3s 节点）。
+
+| 现象 | 原因 | 处理 |
+|------|------|------|
+| 404 | 使用 `http://` 访问 18443 | 18443 是 HTTPS，必须用 `https://test05.jackadam.top:18443/` |
+| 404 | 域名未解析到 HAProxy | 确保 `test05.jackadam.top` 解析到 OpenWrt/HAProxy IP（或内网用 hosts） |
+| 404 | Pod/Ingress 未就绪 | `kubectl get pods -l app=tomcat-test05`、`kubectl get ingress tomcat-test05-acme` |
+| 404 | ACME 证书未签发 | `kubectl -n kube-system logs deploy/traefik --tail=200 \| grep -i acme` 查看申请日志 |
+
+经 HAProxy 18080/18443 访问时，URL 为 `https://test05.jackadam.top:18443/`（不是 http）。
+
 ---

 ## 6. 删除部署与文件
--- a/docs/06-02-运维小结.md
+++ b/docs/06-02-运维小结.md
@@ -15,7 +15,6 @@
  - `kubectl -n kube-system logs deploy/traefik --tail=100`
  - `kubectl -n kube-system get helmchart,helmchartconfig`
  - `kubectl -n kube-system describe pod <pod-name>`
-
 - **节点与网络**
  - `kubectl get node -o wide`
  - `watch -n 1 'ip addr; ip route'`
@@ -23,12 +22,10 @@
  - `sudo netstat -tulpn | grep ':80\|:443\|:6443'`
  - `sudo lsof -iTCP -sTCP:LISTEN -P -n | grep -E ':80|:443|:6443'`
  - `curl -vk https://<域名>/ --resolve "<域名>:443:<入口IP>" -o /dev/null`
-
 - **Traefik / ACME 相关**
  - `kubectl -n kube-system logs deploy/traefik --tail=200 | grep -i acme || true`
  - `kubectl -n kube-system get ingress -A`
  - `openssl s_client -connect <IP>:443 -servername <域名> </dev/null 2>/dev/null | openssl x509 -noout -text | grep -E "Subject:|DNS:"`
-
 - **SSH 与 Ansible**
  - `bash scripts/ssh/test-ssh.sh`
  - `ssh -i ~/.ssh/id_ed25519_k3s_*.61 root@192.168.2.61`