Deploy-Laboratory/docs/03-03-k3s-traefik-dashboard-acme.md

03-03-k3s Traefik Dashboard + ACME

按顺序完成 Traefik Dashboard 与 ACME 自动证书，为后续应用（GitLab、Homer 等）提供 HTTPS 能力。ACME 配置与 03-03 已实机验证（2026-03，K3s 4 节点、Cloudflare DNS-01、Let's Encrypt），本页为 Dashboard + ACME 合并版。

前置条件

• 已完成 01-02-k3s-工作节点.md（集群与 Traefik 可用）
• 若使用 Cloudflare DNS 验证：域名托管在 Cloudflare，已获取 API Token

1. 创建 Secret（Cloudflare API Token）

kubectl -n kube-system create secret generic cloudflare-api-token \
  --from-literal=api-token='<YOUR_CLOUDFLARE_API_TOKEN>'

Token 与 Secret 验证：建议先按 03-02-k3s-traefik-acme.md 中「Token 与 Secret 验证」一节做 zone 查询与哈希对比，避免 ACME 失败时根因不明。

2. 完整 HelmChartConfig（Dashboard + ACME 合并）

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

创建 traefik-dashboard-acme.yaml，推荐放入 K3s manifests 目录（路径同 03-02）。唯一真源：HelmChartConfig 完整 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 中「常见问题」与「排查」小节。

3. 部署（按实际路径选择其一复制执行）

# 默认路径
kubectl apply -f /var/lib/rancher/k3s/server/manifests/traefik-dashboard-acme.yaml
kubectl -n kube-system rollout status deploy/traefik
kubectl -n kube-system logs deploy/traefik --tail=100 | grep -i acme || true

# 自定义 data-dir（如 /storage）
kubectl apply -f /storage/server/manifests/traefik-dashboard-acme.yaml
kubectl -n kube-system rollout status deploy/traefik
kubectl -n kube-system logs deploy/traefik --tail=100 | grep -i acme || true

4. 验证

Dashboard 访问（推荐经 IngressRoute，与 03-01 一致）：

# 经入口 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 且与浏览器同机时使用）：

kubectl -n kube-system port-forward deploy/traefik 9000:9000
# 浏览器打开 http://127.0.0.1:9000/dashboard/

9000 不可达时：优先用 IngressRoute 路径 /dashboard/。部分 Traefik/Helm 版本可能将 dashboard 放在 8080，可尝试 port-forward ... 8080:8080。

ACME 日志：

kubectl -n kube-system logs deploy/traefik --tail=100 | grep -i acme

为 Ingress 使用 tls + certResolver: cloudflare 后，可通过 curl -Iv https://你的域名 检查证书是否由 Let's Encrypt 签发。

---

5. 使用 Tomcat + test05.jackadam.top 验证 HTTPS

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

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

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

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

# 使用 --resolve 覆盖 DNS，将域名指向入口 IP 验证 HTTPS
curl -Iv https://test05.jackadam.top --resolve test05.jackadam.top:443:192.168.2.61

若 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. 删除部署与文件

后续若改回 03-02（仅 Dashboard）或 03-03（仅 ACME）单独测试时，需先删除本部署并删掉 manifest 文件。

1. 删除集群内 HelmChartConfig：

# 默认路径
kubectl delete -f /var/lib/rancher/k3s/server/manifests/traefik-dashboard-acme.yaml
kubectl -n kube-system rollout status deploy/traefik

# 自定义 data-dir（如 /storage）
kubectl delete -f /storage/server/manifests/traefik-dashboard-acme.yaml
kubectl -n kube-system rollout status deploy/traefik

2. 删除宿主机上的 manifest 文件（否则 K3s 重启会再次加载）：

# 默认路径
sudo rm -f /var/lib/rancher/k3s/server/manifests/traefik-dashboard-acme.yaml

# 自定义 data-dir（如 /storage）
sudo rm -f /storage/server/manifests/traefik-dashboard-acme.yaml

3. 可选：若不再使用 ACME，可删除 Secret：kubectl -n kube-system delete secret cloudflare-api-token。

7. 下一步

• 03-02-k3s-traefik-acme.md：仅 ACME 不合并 Dashboard 时，或 TLS 矩阵（test01～test04）验证、排障详情
• 03-04-k3s-cloudflare-tunnel-配置接入.md：若需 Cloudflare Tunnel 接入
• 01-08-openwrt-haproxy.md：如需调整外部端口/防火墙，参考 HAProxy 监听与转发（第 6 节）