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）

```bash
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](../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` 中「常见问题」与「排查」小节。

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

```bash
# 默认路径
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
```

```bash
# 自定义 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 一致）：

```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
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 日志**：

```bash
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`](../ansible/files/traefik-dashboard-acme/tomcat-acme.yaml)。将其中域名改成你实际解析到集群入口 IP 的 FQDN。

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

```bash
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**：

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

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

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

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

```bash
# 自定义 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 节）