chore: 清理调试脚本并收敛到 Ansible 流程

移除已废弃的调试/验证脚本与空目录，统一文档与脚本说明到 ansible-playbook 的部署方式，避免失效引用和误用路径。 Made-with: Cursor
2026-03-23 19:18:55 +08:00
parent 8a54cac61f
commit be97836e0d
92 changed files with 3463 additions and 4855 deletions
--- a/docs/00-00-构建总览.md
+++ b/docs/00-00-构建总览.md
@@ -23,17 +23,16 @@
 ## 推荐安装顺序

 1. `00-01-k3s-基础概念.md`
-2. `01-01-k3s-控制节点含traefik.md`（或直接用 `01-07-节点初始化-ansible-实践.md` 一键自动化）
+2. `01-01-k3s-控制节点含traefik.md`（或直接用 `01-06-节点初始化-ansible-实践.md` 一键自动化）
 3. `01-02-k3s-工作节点.md`
 4. `01-03-armv7-standalone-docker.md`
-5. `01-04-cloudflare-tunnel.md`
-6. `01-08-openwrt-haproxy.md`（按需：网关负载均衡）
-7. `04-03-k3s-nginx-demo.md`
-8. `04-01-k3s-nodejs-高级部署.md`
-9. `04-02-nodejs-镜像与运行命令.md`
-10. `04-03-nodejs-环境变量与配置注入.md`
-11. `04-04-nodejs-端口与Service.md`
-12. `04-05-nodejs-资源请求与限制.md`
+5. `01-07-openwrt-haproxy.md`（按需：网关负载均衡）
+6. `04-03-k3s-nginx-demo.md`
+7. `04-01-k3s-nodejs-高级部署.md`
+8. `04-02-nodejs-镜像与运行命令.md`
+9. `04-03-nodejs-环境变量与配置注入.md`
+10. `04-04-nodejs-端口与Service.md`
+11. `04-05-nodejs-资源请求与限制.md`
 13. `04-06-nodejs-探针与健康检查.md`
 14. `04-07-nodejs-调度与亲和.md`
 15. `04-08-nodejs-安全上下文.md`
@@ -51,7 +50,7 @@
 27. `03-05-k3s-local-path-pvc.md`（K3s 自带 local-path，单副本本地持久化）
 28. `03-06-k3s-使用nfs存储.md`（按需：已有 NFS 时 PV/PVC）
 29. `03-07-k3s-longhorn-持久化存储.md`（重状态、快照/备份，建议部署 GitLab 等前统一规划）
-30. `03-08-k3s-ha-集群配置与切换.md`（按需：双控制节点 HA，配合 `01-05`）
+30. `03-08-k3s-ha-集群配置与切换.md`（按需：双控制节点 HA，配合 `01-04`）
 31. `03-09-k3s-gitops-集群配置管理.md`（框架草案：Argo CD / Flux）

 > 想确认这些步骤是否已经在真实环境验证，请查看 `00-02-验证矩阵.md`。
@@ -92,11 +91,10 @@
 ## 专题导航

 - `00-04-部署环境说明.md`（节点布局、IP、OS、K3s 版本等，便于对照与复现）
- `01-07-节点初始化-ansible-实践.md`（Ansible 一键安装 k3s 集群，已验证）
- `01-08-openwrt-haproxy.md`（按需：网关负载均衡）
+- `01-06-节点初始化-ansible-实践.md`（Ansible 一键安装 k3s 集群，已验证）
+- `01-07-openwrt-haproxy.md`（按需：网关负载均衡）
 - nginx 矩阵：`ansible/playbooks/nginx-matrix-deploy.yml`（02-05）、`ansible/playbooks/nginx-matrix-tls-deploy.yml`（03-02）
- `01-04-cloudflare-tunnel.md`（安装准备）
- `03-04-k3s-cloudflare-tunnel-配置接入.md`（集群接入）
+- `03-04-k3s-cloudflare-tunnel-配置接入.md`（Cloudflare Tunnel 完整流程：Zero Trust + 集群接入）

 - `05-03-k3s-安装gitlab-含runner.md`
 - `05-04-k3s-配置gitlab-cicd.md`
@@ -105,10 +103,10 @@
 - `05-05-prometheus与grafana.md`
 - `05-07-openclaw应用部署.md`
 - `05-08-openclaw-k3s-实验部署.md`
- `01-06-armv7-nfs服务安装.md`
+- `01-05-armv7-nfs服务安装.md`
 - `05-06-openlist挂载网盘与自动备份.md`
 - `06-02-运维小结.md`
- `01-05-双控制节点ha.md`
+- `01-04-双控制节点ha.md`
 - `03-08-k3s-ha-集群配置与切换.md`
 - `03-09-k3s-gitops-集群配置管理.md`（框架草案）

--- a/docs/00-01-k3s-基础概念.md
+++ b/docs/00-01-k3s-基础概念.md
@@ -1,4 +1,4 @@
-# 00-01-k3s-基础概念
+# 00-01-k3s-基础概念

 > 入门速查：先把核心概念看明白，再去做安装与排障。

@@ -106,7 +106,7 @@ K3s 自带 **local-path-provisioner**：当你创建 PVC 且不指定 `storageCl

 - **工作机制**：PVC 被创建后，provisioner 会在 **Pod 被调度到的节点** 上，在其本地磁盘创建目录（默认在 `data-dir` 下的 `storage`，例如 `/var/lib/rancher/k3s/storage` 或 `/storage`），并为之创建 PV、与 PVC 绑定。
 - **绑定到节点**：数据只存在于该节点的本地目录，**与该节点绑定**；Pod 被调度到另一节点时，会拿到新的空卷，旧节点上的数据不会自动迁移。
- **适用场景**：单副本应用、缓存、日志等，能接受 Pod 漂移后数据丢失或需手动恢复。**多副本共享数据**应使用 NFS、CSI 等共享存储（见 `01-06`）。
+- **适用场景**：单副本应用、缓存、日志等，能接受 Pod 漂移后数据丢失或需手动恢复。**多副本共享数据**应使用 NFS、CSI 等共享存储（见 `01-05`）。
 - **查看**：`kubectl get storageclass` 可见 `local-path`（通常为默认）；`kubectl get pv,pvc` 可查看已创建的卷。
 - **操作示例**：见 `03-05-k3s-local-path-pvc.md`。

@@ -114,7 +114,7 @@ K3s 自带 **local-path-provisioner**：当你创建 PVC 且不指定 `storageCl

 - **Pod 可以漂移，宿主机本地数据不会跟着漂移**：用 `hostPath` 把宿主机目录挂进容器时，数据只在这台机器上；Pod 被调度到另一台节点后，那台机器没有同样目录和数据，应用就会“丢数据”。
 - **K3s 不会自动帮你搬本地数据**：调度器只管 Pod 放哪台节点，不会同步 `/var/lib/...` 或自建目录；所以“节点故障自动漂移”和“数据高可用”是两件事，要分别设计。
- **常见做法**：重要数据用共享存储（NFS / 云盘 / CSI），通过 PV/PVC 给 Pod 用（参考 `01-06`、`03-07`）；缓存、临时文件用本地目录（`emptyDir` 或 `hostPath`），接受节点挂了可丢；或靠备份/同步把本地目录定期同步到别处，再在新节点恢复。
+- **常见做法**：重要数据用共享存储（NFS / 云盘 / CSI），通过 PV/PVC 给 Pod 用（参考 `01-05`、`03-07`）；缓存、临时文件用本地目录（`emptyDir` 或 `hostPath`），接受节点挂了可丢；或靠备份/同步把本地目录定期同步到别处，再在新节点恢复。

 **用途**：搞清楚数据放哪、节点挂了会不会丢，才能设计备份和高可用，不踩坑。

--- a/docs/00-02-验证矩阵.md
+++ b/docs/00-02-验证矩阵.md
@@ -30,7 +30,7 @@
 - `01-01-k3s-控制节点含traefik.md`  
  - 状态：✅ 已验证  
  - 备注：Fedora 43 Server + K3s v1.34.5+k3s1，单控制节点 61，已按文档装机并确认 Traefik 入口 404 可达（2026-03-10 左右）。
- `01-07-节点初始化-ansible-实践.md`  
+- `01-06-节点初始化-ansible-实践.md`  
  - 状态：✅ 已验证  
  - 备注：Fedora + K3s，4 节点（ylc61~64），Ansible 一键完成初始化、server/agent 安装、firewalld 基线、Traefik 标签及验证输出（2026-03 左右）。
 - `01-02-k3s-工作节点.md`  
@@ -39,12 +39,9 @@
 - `01-03-armv7-standalone-docker.md`  
  - 状态：❓ 未验证  
  - 备注：待在实际 armv7 设备上按文档安装 Docker 并跑一两个容器后更新。
- `01-04-cloudflare-tunnel.md`  
-  - 状态：⚠️ 部分验证  
-  - 备注：Cloudflare 控制台端（Tunnel/域名）已实践使用，需在新环境对完整安装准备流程再跑一遍。
- `01-08-openwrt-haproxy.md`  
+ `01-07-openwrt-haproxy.md`  
  - 状态：✅ 已验证  
-  - 备注：ImmortalWrt + HAProxy 18080/18443；经 `scripts/01-08-verify-haproxy.sh`（ssh onecloud 第三方 curl）验证；cfg 语法、HTTP/HTTPS 后端正确；可选 `--deploy-matrix http|tls` 一键部署矩阵。
+  - 备注：ImmortalWrt + HAProxy 18080/18443；经 `scripts/01-07-verify-haproxy.sh`（ssh onecloud 第三方 curl）验证；cfg 语法、HTTP/HTTPS 后端正确；可选 `--deploy-matrix http|tls` 一键部署矩阵。

 ---

@@ -83,10 +80,10 @@
  - 备注：02-05 的升级版（TLS 矩阵 + ACME）；2026-03 实机跑通。
 - `03-03-k3s-traefik-dashboard-acme.md`  
  - 状态：✅ 已验证  
-  - 备注：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 接入已在其他项目跑通过，本实验室集群的完整接入流程待实机验证。
+  - 备注：03-01 Dashboard 与 03-02 ACME 合并配置已核对；模板 `ansible/files/traefik-dashboard-acme/traefik-dashboard-acme.yaml` 正确（已含 local-path persistence）。实机 apply 需确保集群 DNS 可达 Let's Encrypt；可经 `scripts/03-verify-traefik-dashboard-acme.sh` 验证。2026-03。
+- `03-04-k3s-cloudflare-tunnel-配置接入.md`
+  - 状态：✅ 已验证
+  - 备注：本实验室集群完整流程（Zero Trust、Public Hostname、cloudflared Pod、`traefik.kube-system.svc.cluster.local:80`、Dashboard 子域 + `/dashboard/` 访问）已实机跑通（2026-03）。
 - `03-05-k3s-local-path-pvc.md`  
  - 状态：❓ 未验证  
  - 备注：K3s 自带 local-path-provisioner，PVC 本地持久化；待实机验证。
@@ -105,10 +102,10 @@

 ### 可选：依赖文档

- `01-05-双控制节点ha.md`  
+- `01-04-双控制节点ha.md`  
  - 状态：❓ 未验证  
  - 备注：文档已拆分安装/配置流程，尚未在双控制节点 + 外部 LB 的完整场景下全链路验证。
- `01-06-armv7-nfs服务安装.md`  
+- `01-05-armv7-nfs服务安装.md`  
  - 状态：❓ 未验证  
  - 备注：NFS 安装命令已经过以往经验验证，本仓库对应 armv7 环境需再跑一遍确认导出与权限。

--- a/docs/00-03-未来规划与待补功能.md
+++ b/docs/00-03-未来规划与待补功能.md
@@ -1,4 +1,4 @@
-# 00-03-未来规划与待补功能
+# 00-03-未来规划与待补功能

 > 给未来的自己：这里不是“必须现在就做完”的清单，而是把你已经想到、但还没系统实现的能力先写下来，等有时间再一项项补。

@@ -34,7 +34,7 @@
  - 节点初始化、K3s 配置和应用部署以“手工 + scripts/”为主。
  - 没有一套“从裸机/虚机到完整环境”的幂等自动化流程。
 - **规划方向**
-  - **节点侧**：✅ 已完成 `01-07-节点初始化-ansible-实践.md`，Ansible 一键完成初始化 + k3s 安装 + firewalld 基线 + Traefik 标签（含 8472/udp、6443/tcp 端口开放）。
+  - **节点侧**：✅ 已完成 `01-06-节点初始化-ansible-实践.md`，Ansible 一键完成初始化 + k3s 安装 + firewalld 基线 + Traefik 标签（含 8472/udp、6443/tcp 端口开放）。
  - **集群侧**：引入 GitOps（Argo CD / Flux 二选一）管理：
    - K3s 核心配置与 CRD；
    - Ingress/IngressRoute、Traefik 配置；
@@ -87,7 +87,7 @@
    - 只向极少数管理设备开放；
    - 主要用途为 SSH、kubeconfig、底层网络排障。
 - **建议文档**
-  - `01-08-wireguard-运维vpn-接入与实践.md`
+  - `01-07-wireguard-运维vpn-接入与实践.md`

 ## 7. 其他可选实验方向

--- a/docs/00-04-部署环境说明.md
+++ b/docs/00-04-部署环境说明.md
@@ -22,13 +22,13 @@
 | ------- | ----------------- | --------------------------- |
 | OS      | Fedora 43 Server （CoreOS） | 其他 RHEL 系 / Debian 系按文档说明适配 |
 | K3s     | v1.34.5+k3s1      | 来自 get.k3s.io 默认            |
-| Ansible | ansible-core 2.18 | 用于 `01-07` 自动化安装            |
+| Ansible | ansible-core 2.18 | 用于 `01-06` 自动化安装            |


 ## 3. 网络与存储

 - **网段**：192.168.2.0/24
- **可选**：OpenWrt 网关（如 192.168.2.1）上配置 HAProxy 负载均衡，将 80/443 转发到 K3s 节点，见 `01-08-openwrt-haproxy.md`
+- **可选**：OpenWrt 网关（如 192.168.2.1）上配置 HAProxy 负载均衡，将 80/443 转发到 K3s 节点，见 `01-07-openwrt-haproxy.md`
 - **数据盘方案**：`/storage`，server 与 worker 均使用 `--data-dir=/storage`
 - **token 路径**：`/storage/server/token`

@@ -51,5 +51,5 @@

 ## 6. 验证时间

- 2026-03：4 节点集群按 `01-07` 一次性安装成功，各节点 Traefik 入口 404 可达。
+- 2026-03：4 节点集群按 `01-06` 一次性安装成功，各节点 Traefik 入口 404 可达。

--- a/docs/01-01-k3s-控制节点含traefik.md
+++ b/docs/01-01-k3s-控制节点含traefik.md
@@ -2,7 +2,7 @@

 > 在控制节点安装 K3s Server，确认基础组件与 Traefik 可用。
 >
-> 若需一键自动化安装多节点集群，可直接用 `01-07-节点初始化-ansible-实践.md`。
+> 若需一键自动化安装多节点集群，可直接用 `01-06-节点初始化-ansible-实践.md`。

 ## 前置条件

@@ -20,7 +20,7 @@ K3s 默认将数据（含 local-path 卷）放在 `--data-dir` 下。系统盘
 | **方案一（默认）** | `/var/lib/rancher/k3s` | 系统盘空间充足 |
 | **方案二（数据盘）** | `/storage` | 系统盘小，数据盘单独挂载在 `/storage` |

-> 自定义 `/storage` 仅解决单节点内系统盘/数据盘分离；节点或数据盘重建后数据不会自动迁移，高可用与备份见 `01-05`、`06-03`。
+> 自定义 `/storage` 仅解决单节点内系统盘/数据盘分离；节点或数据盘重建后数据不会自动迁移，高可用与备份见 `01-04`、`06-03`。

 ## 操作步骤

@@ -42,7 +42,7 @@ curl -sfL https://get.k3s.io | sh -
 curl -sfL https://get.k3s.io | sh -s - server --data-dir=/storage
 ```

- 使用方案二时，token 路径为 `/storage/server/token`（供 01-02 工作节点加入与 01-05 HA 使用）。
+- 使用方案二时，token 路径为 `/storage/server/token`（供 01-02 工作节点加入与 01-04 HA 使用）。

 ## 配置 kubectl（供当前用户使用）

@@ -169,7 +169,7 @@ forward . 223.5.5.5 8.8.8.8

 然后重启 CoreDNS：`kubectl -n kube-system rollout restart deploy/coredns`

-> 若使用 Ansible 一键安装（`01-07`），playbook 已自动完成此配置，无需手动修改。
+> 若使用 Ansible 一键安装（`01-06`），playbook 已自动完成此配置，无需手动修改。

 ## 下一步

--- a/docs/01-02-k3s-工作节点.md
+++ b/docs/01-02-k3s-工作节点.md
@@ -3,7 +3,7 @@
 > 本文已合并原 `01-02-k3s-工作节点.md`。
 > 目标：完成工作节点加入 + Traefik 入口部署基线，并验证「**入口节点集合**的 `:80` 可达」。
 >
-> 若需一键自动化安装多节点集群，可直接用 `01-07-节点初始化-ansible-实践.md`。
+> 若需一键自动化安装多节点集群，可直接用 `01-06-节点初始化-ansible-实践.md`。

 ## 前置条件

@@ -57,11 +57,7 @@ curl -sfL https://get.k3s.io | sh -s - agent \
 早期排障时，曾只在控制节点手工执行过少量临时放行命令即可恢复访问，那是因为当时入口 Pod 全在控制节点、所有回包都经由控制节点；  
 但在“Traefik 可跑在任意节点、部分节点被选为入口节点”的设计下，每个启用 firewalld 的 k3s 节点都必须持久放行本机 `flannel.1/cni0`，否则一旦入口 Pod 或业务 Pod 调度到该节点，就可能在该节点上重现同类故障。

-在**每台** k3s 节点上分别执行：
-
-```bash
-./scripts/diag/firewalld/setup-k3s-firewalld-interfaces.sh
-```
+在**每台** k3s 节点上分别执行（当前不再维护 diag 脚本，使用手动命令或 Ansible）：

 ### 2.2 手动方式（不使用脚本）

--- a/docs/01-03-armv7-standalone-docker.md
+++ b/docs/01-03-armv7-standalone-docker.md
@@ -28,4 +28,4 @@ docker ps
 ## 下一步

 - `05-02-onenav首页面板.md`
- `01-06-armv7-nfs服务安装.md`
+- `01-05-armv7-nfs服务安装.md`
--- a/docs/01-04-cloudflare-tunnel.md
+++ b/docs/01-04-cloudflare-tunnel.md
@@ -1,44 +0,0 @@
-# 01-04-Cloudflare Tunnel
-
-> 本文只负责 Cloudflare Tunnel 的安装准备与云端侧创建。
-> K3s 侧 `cloudflared` 部署与验证见：`03-04-k3s-cloudflare-tunnel-配置接入.md`。
-
---
-
-## 前置条件
-
- 控制节点已就绪：`01-01-k3s-控制节点含traefik.md`
- Traefik 已可用（单节点 K3s 也可使用 Cloudflare Tunnel）
- 域名已托管在 Cloudflare
- 已创建 Cloudflare Zero Trust 账号
-
---
-
-## 云端创建 Tunnel
-
-1. 在 Cloudflare Zero Trust 创建一个 Tunnel
-2. 记录 `Tunnel Token` 或凭据 JSON
-3. 规划域名映射，例如：
-   - `git.example.com` -> `http://traefik.kube-system.svc.cluster.local`
-   - `home.example.com` -> 同上
-
-## 安装准备检查
-
- 确认已拿到 Tunnel Token 或凭据文件
- 确认域名与子域映射规划完成
- 确认目标入口指向 Traefik（后续在 K3s 中接入）
-
---
-
-## 注意事项
-
- 没有 token/凭据：回到 Zero Trust 页面重新生成
- 子域规划混乱：先固定一张映射表再做集群接入
- 需要部署到 K3s：转到 `03-04-k3s-cloudflare-tunnel-配置接入.md`
-
---
-
-## 下一步
-
- `03-04-k3s-cloudflare-tunnel-配置接入.md`
-
--- a/docs/01-04-双控制节点ha.md
+++ b/docs/01-04-双控制节点ha.md
@@ -1,4 +1,4 @@
-# 01-05-双控制节点HA（安装与准备）
+# 01-04-双控制节点HA（安装与准备）

 > 本文只讲双控制节点 HA 的安装前准备与基础环境搭建。
 > 具体集群参数切换、server 加入与迁移步骤见 `03-08-k3s-ha-集群配置与切换.md`。
@@ -53,7 +53,7 @@ sudo k3s server \
 1. **确认 worker 节点健康**：  
   - 已按 `01-02-k3s-工作节点.md` 正常加入集群；  
   - 无关键 Pod 仅运行在该节点（可先用 `kubectl drain` 或手动迁移工作负载）。
-2. **在 `01-05` 阶段完成外部 datastore 与 LB 准备**：  
+2. **在 `01-04` 阶段完成外部 datastore 与 LB 准备**：  
   - 不要立即改动现有 server/worker 的 systemd 配置，只确保 datastore/LB 均已就绪。  
 3. **在 `03-09` 中按步骤将该 worker 替换为 server**：  
   - 停止该节点上的 `k3s-agent` 服务（或执行官方卸载脚本）；  
--- a/docs/01-05-armv7-nfs服务安装.md
+++ b/docs/01-05-armv7-nfs服务安装.md
@@ -1,4 +1,4 @@
-# 01-06-armv7 NFS 服务安装
+# 01-05-armv7 NFS 服务安装

 > 本文只讲 armv7 主机侧 NFS 服务安装与导出配置。

--- a/docs/01-06-节点初始化-ansible-实践.md
+++ b/docs/01-06-节点初始化-ansible-实践.md
@@ -1,4 +1,4 @@
-# 01-07-节点初始化与 k3s 自动安装（Ansible 实践）
+# 01-06-节点初始化与 k3s 自动安装（Ansible 实践）

 > 目标：给一组已经装好 OS、可以 SSH 的裸金属/虚机，**一键完成基础初始化 + 安装 k3s server/worker**，得到与 `01-01`、`01-02` 文档一致的集群（含 `/storage` 数据盘方案）。
 >
@@ -22,7 +22,7 @@
  - **数据盘**：若使用 `/storage` 方案，需在每台节点上提前挂载数据盘并创建 `/storage`；
 - 不覆盖：
  - 从「完全裸铁 + 无系统」开始的 PXE 装机；
-  - 高级 HA（多 server + 外部 datastore）——仍按 `01-05`、`03-10` 执行。
+  - 高级 HA（多 server + 外部 datastore）——仍按 `01-04`、`03-10` 执行。

 ## 2. 目录结构

--- a/docs/01-07-openwrt-haproxy.md
+++ b/docs/01-07-openwrt-haproxy.md
@@ -1,11 +1,11 @@
-# 01-08 OpenWrt HAProxy 负载均衡
+# 01-07 OpenWrt HAProxy 负载均衡

 > 在 OpenWrt 上安装并配置 HAProxy，将 80/443 流量转发到 K3s 集群节点（Traefik 入口），实现单一入口与负载均衡。

 ## 前置条件

 - OpenWrt 与 K3s 节点同网段（如 192.168.2.0/24），OpenWrt 通常为网关（如 192.168.2.1）
- 已完成 `01-02-k3s-工作节点.md` 或 `01-07`，Traefik 入口 80/443 已在各节点可达
+- 已完成 `01-02-k3s-工作节点.md` 或 `01-06`，Traefik 入口 80/443 已在各节点可达

 ## 1. 安装 HAProxy

@@ -20,9 +20,9 @@ opkg install haproxy

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

-**配置目录说明与「cfg 是否正确」的验证层次**：见 `ansible/files/01-08-haproxy/README.md`（**仅语法**：`./scripts/01-08-verify-haproxy.sh --cfg-only`）。
+**配置目录说明与「cfg 是否正确」的验证层次**：见 `ansible/files/01-07-haproxy/README.md`（**仅语法**：`./scripts/01-07-verify-haproxy.sh --cfg-only`）。

-**无健康检查最简配置**：`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。
+**无健康检查最简配置**：`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。

 ## 3. 健康检查

@@ -43,19 +43,19 @@ opkg install haproxy

 ### 3.2 HTTP（80 明文）

-完整配置：`ansible/files/01-08-haproxy/haproxy-http.cfg`。`backend k3s_http` 开头加 `option httpchk GET /`，`k3s_https` 仍为 TCP 检查。
+完整配置：`ansible/files/01-07-haproxy/haproxy-http.cfg`。`backend k3s_http` 开头加 `option httpchk GET /`，`k3s_https` 仍为 TCP 检查。

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

-完整配置：`ansible/files/01-08-haproxy/haproxy-tls.cfg`。`backend k3s_https` 中加 `option ssl-hello-chk`，做 TLS 握手层检查。
+完整配置：`ansible/files/01-07-haproxy/haproxy-tls.cfg`。`backend k3s_https` 中加 `option ssl-hello-chk`，做 TLS 握手层检查。

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

-完整配置：`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 即可。
+完整配置：`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 即可。

 ## 4. 启动与验证

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

 ```bash
 /etc/init.d/haproxy enable
@@ -64,13 +64,13 @@ opkg install haproxy

 验证：从内网访问 `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` 跳过）。
+**自动验证**：`./scripts/01-07-verify-haproxy-openwrt.sh` 或 `./scripts/01-07-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-07-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-http-tls.cfg`（HTTP 检查 + TLS 检查 + PROXY）。
+**完整配置**：`ansible/files/01-07-haproxy/haproxy-proxy-http-tls.cfg`（HTTP 检查 + TLS 检查 + PROXY）。

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

--- a/docs/02-05-nginx-验证矩阵-一键部署.md
+++ b/docs/02-05-nginx-验证矩阵-一键部署.md
@@ -43,7 +43,7 @@ kubectl get pod,svc,ing,ingressroute -n default -o wide

 ## 验证（用 IP 访问）

-直接用入口节点 IP 访问（将 `192.168.2.61` 改为你的入口 IP；按 01-02/01-07 已配 LB 时任选节点 IP）。
+直接用入口节点 IP 访问（将 `192.168.2.61` 改为你的入口 IP；按 01-02/01-06 已配 LB 时任选节点 IP）。

 ```bash
 for path in demo-m1 demo-m2 demo-m3 demo-m4; do
--- a/docs/03-01-k3s-traefik-dashboard.md
+++ b/docs/03-01-k3s-traefik-dashboard.md
@@ -43,7 +43,7 @@ kubectl -n kube-system rollout status deploy/traefik
 3. 验证：一键对全部节点 IP 做 curl 测试（按实际环境修改 IP 列表）：

 ```bash
-# 已按 01-02 / 01-07 配置 K3s 默认 LB（Traefik 入口标签 + firewalld 基线），61~64 任一台 :80 均应返回 200/307
+# 已按 01-02 / 01-06 配置 K3s 默认 LB（Traefik 入口标签 + firewalld 基线），61~64 任一台 :80 均应返回 200/307
 for ip in 192.168.2.61 192.168.2.62 192.168.2.63 192.168.2.64; do
  code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 3 "http://${ip}/dashboard/" 2>/dev/null || echo "---")
  echo "${ip}: ${code}"
--- a/docs/03-02-k3s-traefik-acme.md
+++ b/docs/03-02-k3s-traefik-acme.md
@@ -21,7 +21,7 @@

 - **Pod / 部署**：ACME 配置通过 `HelmChartConfig` 注入到 **同一个 Traefik Deployment**。**副本数为 chart 默认值 1**（即 `deployment.replicas` 未在 values 里写时默认为 1），所以只有 1 个 Traefik Pod；与 03-01 的 Traefik 是同一套 Deployment，只是 values 里多了 ACME 参数与 env。
 - **配置存在哪里**：`HelmChartConfig` 存在 **etcd**（控制节点）；K3s 的 chart 控制器据此更新 Traefik 的部署参数，Traefik 进程从 **Kubernetes API** 读取 Ingress/IngressRoute，无需多 Pod 间同步。
- **ACME 存储（证书与账户）**：`acme.storage` 指向容器内 **`/data/acme.json`**。未配 hostPath 时，K3s 默认会为 Traefik 挂载卷到 `/data`（如 emptyDir 或默认持久卷），**仅当前这一个 Traefik Pod 可写**，Pod 重建后若卷不持久则需重新申请证书。若在 values 里配置了 **hostPath**（见本页可选配置），则 `/data` 对应宿主机目录，证书写在物理机路径，便于备份与复用；Traefik 仍为 1 个 Pod，不存在多副本间同步 acme.json 的问题。
+- **ACME 存储（证书与账户）**：`acme.storage` 指向容器内 **`/data/acme.json`**。未配 hostPath 时，K3s 默认会为 Traefik 挂载卷到 `/data`（如 emptyDir 或默认持久卷），**仅当前这一个 Traefik Pod 可写**，Pod 重建后若卷不持久则需重新申请证书。若在 values 里配置了 **hostPath**（见本页可选配置），则 `/data` 对应宿主机目录，证书写在物理机路径，便于备份与复用；Traefik 仍为 1 个 Pod，不存在多副本间同步 acme.json 的问题。**推荐**：Dashboard + ACME 场景直接用 **同一份** [`traefik-dashboard-acme.yaml`](../ansible/files/traefik-dashboard-acme/traefik-dashboard-acme.yaml)（已含 **`persistence`（local-path）+ ACME**），见 `03-05-k3s-local-path-pvc.md`。不要 Dashboard 时按该文件头注释删减。
 - **第一次部署随机节点、重启后怎么办**：Traefik 未指定 nodeSelector 时，首次会**随机调度**到某一节点。若使用了 **hostPath**，证书只存在于该节点的磁盘上；**Pod 被调度到其他节点**（重启、驱逐、缩容再扩容）时，新节点上的同名 hostPath 是另一块盘，**证书不会跟着走**，可能需重新申请。若希望重启或节点故障后仍保留证书，可：**① 把 Traefik 固定到某一节点**（在 HelmChartConfig 的 `deployment` 下配 `nodeSelector`，例如 `nodeSelector: { kubernetes.io/hostname: ylc61 }（节点名使用短主机名 ylc61～ylc64，便于配合 Cloudflare CDN）`），使 hostPath 始终落在同一台机；**② 或不用 hostPath**，依赖 K3s 默认持久卷（若为 local-path，则卷仍绑定某节点，Pod 重建到同节点可复用）；**③ 或改用 NFS 等共享存储**挂到 `/data`，多节点可读同一证书（需自行在 values 里配 PVC/volume）。

 ---
@@ -90,7 +90,7 @@ kubectl -n kube-system get secret cloudflare-api-token \
 >
 > **文件选择**：K3s 自带的 `traefik.yaml` 会被 K3s 覆盖，**不要修改**。所有自定义配置（ACME、nodeSelector、hostPath 以及其他扩展配置）都应写在 **`traefik-acme.yaml`** 这一份 HelmChartConfig 里，与默认 chart 合并生效。

-1. 在控制节点创建 `traefik-acme.yaml`，推荐放入 K3s manifests 目录（路径同 03-01）。**完整配置见 `ansible/files/traefik-acme/traefik-acme.yaml`**（与 Ansible 共用），复制后替换 `<YOUR_REAL_EMAIL>` 等占位符即可。
+1. 在控制节点创建 `traefik-acme.yaml`，推荐放入 K3s manifests 目录（路径同 03-01）。**完整配置见 `ansible/files/traefik-acme/traefik-acme.yaml`**（与 Ansible 共用），复制后替换 `<YOUR_REAL_EMAIL>` 等占位符即可。若走 **Dashboard + ACME** 且需 **证书落盘 local-path PVC**，直接用 [`traefik-dashboard-acme.yaml`](../ansible/files/traefik-dashboard-acme/traefik-dashboard-acme.yaml)（已内置 persistence，说明见 `03-05-k3s-local-path-pvc.md`）。**仅 ACME、无 Dashboard** 时仍可用本目录 [`traefik-acme.yaml`](../ansible/files/traefik-acme/traefik-acme.yaml)，并自行按 `03-05` 在 Helm values 中增加 `persistence` 块（与 `/data/acme.json` 一致）。

 > 将 `<YOUR_REAL_EMAIL>` 改为你的邮箱。`/data/acme.json` 为容器内路径；`caserver` 为测试服务器（staging），正式上线前删除该行即切回生产 CA。Traefik 在容器内监听 8000/8443，由 Service 和 svclb 映射到节点 80/443。
 >
--- 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）。**唯一真源**（已含 **`persistence`（local-path）+ ACME + Dashboard + IngressRoute**，证书落盘 `/data/acme.json`）：[`traefik-dashboard-acme.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`。细节见 `03-05-k3s-local-path-pvc.md`。

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

@@ -145,5 +145,5 @@ sudo rm -f /storage/server/manifests/traefik-dashboard-acme.yaml

 - `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 节）
+- `01-07-openwrt-haproxy.md`：如需调整外部端口/防火墙，参考 HAProxy 监听与转发（第 6 节）

--- a/docs/03-04-k3s-cloudflare-tunnel-配置接入.md
+++ b/docs/03-04-k3s-cloudflare-tunnel-配置接入.md
@@ -1,18 +1,53 @@
-# 03-05-k3s Cloudflare Tunnel 配置接入
+# 03-04-k3s Cloudflare Tunnel 配置接入

-> 本文只讲 K3s 侧如何接入 Cloudflare Tunnel（`cloudflared` 部署、验证、排查）。
+> 本文覆盖 Tunnel 完整流程：Zero Trust 云端创建、域名映射，以及将 `cloudflared` 安装到 K3s 并跑起 Pod，使 **Traefik 通过 Tunnel 对外提供服务**。
+>
+> **状态：已验证**（2026-03，本仓库实验室 K3s 集群；详见 `00-02-验证矩阵.md`）。
+
+---
+
+## 访问链路（如何通过 Tunnel 访问 K3s 资源）
+
+**整体流程**：公网域名 → Cloudflare Edge → Tunnel → `cloudflared` Pod → **Traefik** → 根据 Host/Path 路由到具体 Service（如 Dashboard、GitLab、Homer 等）。
+
+Traefik 是唯一入口。所有流量经 Tunnel 进入后，由 Traefik 的 IngressRoute/Ingress 按 `Host` 和 `Path` 分发到不同后端。**先保证 Traefik 内有对应路由**（如 Dashboard 的 IngressRoute），再在 Zero Trust 中把域名指到 Traefik，即可访问。
+
+---

 ## 前置条件

- 已完成 `01-04-cloudflare-tunnel.md`
- 已拿到 Tunnel Token 或凭据文件
- Traefik 已可用（单节点/多节点均可）
+- 控制节点已就绪：`01-01-k3s-控制节点含traefik.md`
+- Traefik 已可用；若要通过 Tunnel 访问 Dashboard，需先部署 `03-01-k3s-traefik-dashboard.md` 或 `03-03-k3s-traefik-dashboard-acme.md`
+- 域名已托管在 Cloudflare，且 Nameserver 已指向 Cloudflare
+- 已创建 Cloudflare Zero Trust 账号

-## 操作步骤
+---

-1. 在 K3s 中创建保存 token/凭据的 Secret + Deployment。**唯一真源**：[`ansible/files/cloudflare-tunnel/cloudflared.yaml`](../ansible/files/cloudflare-tunnel/cloudflared.yaml)（替换 `TUNNEL_TOKEN` 占位符）。
+## 云端创建 Tunnel（Zero Trust 操作说明）

-2. 部署 `cloudflared` 并确保重启后自动生效（按实际路径选择其一复制执行）：
+### 1. 创建 Tunnel
+
+1. 登录 [Cloudflare Zero Trust Dashboard](https://one.dash.cloudflare.com/)
+2. 左侧导航：**Networks** → **Tunnels**（或 **Connectors** → **Cloudflare Tunnels**）
+3. 点击 **Create a tunnel**
+4. 选择 **Cloudflared** 作为 Connector 类型
+5. 输入 Tunnel 名称（如 `k3s-lab`），点击 **Save tunnel**
+
+### 2. 复制 Tunnel Token
+
+1. 在 Tunnel 创建成功后，会进入 **Install connector** 页面
+2. 选择操作系统（如 Linux）
+3. 在安装命令中，找到形如 `cloudflared tunnel run --token <长串 Token>` 的 **Token**
+4. **复制整个 Token**（点击复制图标，或手动选中），妥善保存
+5. 该 Token 将用于下方 K3s 中 `cloudflared` 部署
+
+> 若已关闭页面：在 Tunnels 列表中点击该 Tunnel → **Configure** → **Install connector**，可重新查看/生成 Token。
+
+### 3. 部署 cloudflared 到 K3s
+
+1. 从 **唯一真源** 复制清单：[`ansible/files/cloudflare-tunnel/cloudflared.yaml`](../ansible/files/cloudflare-tunnel/cloudflared.yaml)
+2. 将 `TUNNEL_TOKEN` 占位符替换为前述 Zero Trust 中复制的 Token
+3. 应用并等待 Pod 就绪（按实际 manifests 路径选择其一）：

 ```bash
 # 默认路径
@@ -26,25 +61,170 @@ kubectl apply -f /storage/server/manifests/cloudflared.yaml
 kubectl -n kube-system rollout status deploy/cloudflared
 ```

-3. 将 `cloudflared.yaml` 放入上述 manifests 目录后，K3s 重启时会自动加载。
+4. 将 `cloudflared.yaml` 放入上述 manifests 目录后，K3s 重启时会自动加载。

 建议要点：

 - 使用官方 `cloudflared` 镜像
 - Secret 不写死在明文 YAML
 - `cloudflared` 放在 `kube-system` 或专用 namespace
+- Tunnel 指向的 URL 在 Zero Trust 中配置为 Traefik Service，无需在 `cloudflared.yaml` 内指定

-## 验证命令
+#### 集群内 Traefik 地址（Public Hostname 的 URL 填什么）
+
+Tunnel 后端应指向 **集群内的 Traefik 入口**，常用写法：
+
+| 写法 | 说明 |
+|------|------|
+| `traefik.kube-system.svc.cluster.local:80` | 见下「与哪份 YAML / 哪些字段对应」。**不要**手写 `http://`，Zero Trust 里选 HTTP 后只填主机与端口。 |
+| `192.168.2.61` | 节点 IP（与 Traefik Service **EXTERNAL-IP** 之一、端口 **80** 等价）。Public Hostname 的 URL **只填到 IP/主机**，path 在浏览器访问时带上（见步骤 6）。 |
+
+**和仓库里哪份 YAML 的关系**
+
+- 本仓库的 [`cloudflared.yaml`](../ansible/files/cloudflare-tunnel/cloudflared.yaml) **只** 定义 `cloudflared` 的 Deployment/Secret，**不包含** Traefik Service；Tunnel 后端地址写的是 **集群里已存在的 Traefik Service**，不是 `cloudflared.yaml` 里的某一行。
+- Traefik 的 **Service** 由 K3s 内置 Traefik（HelmChart）安装时创建，资源名一般为 **`traefik`**，命名空间 **`kube-system`**。若你改过 chart 或 Service 名，以下 FQDN 与端口要以 **实际 `kubectl get svc` 输出** 为准。
+
+**与 `kubectl get svc traefik -o yaml` 里哪些字段对应**
+
+集群 DNS 完整名规则：`<metadata.name>.<metadata.namespace>.svc.cluster.local:<spec.ports 中 web 的 port>`。
+
+| 你填的片段 | 对应 YAML 路径（`kubectl -n kube-system get svc traefik -o yaml`） |
+|------------|-------------------------------------------------------------------|
+| `traefik` | `metadata.name` |
+| `kube-system` | `metadata.namespace` |
+| `:80` | `spec.ports` 里 **name 常为 `web`** 的 `port: 80`（HTTP 入口；若你环境 port 不是 80，Tunnel URL 里端口改成一致） |
+
+示例（节选，以你集群为准）：
+
+```yaml
+metadata:
+  name: traefik                 # → FQDN 第一段
+  namespace: kube-system      # → FQDN 第二段
+spec:
+  ports:
+    - name: web
+      port: 80                  # → Tunnel URL 里冒号后的端口
+      # ...
+  type: LoadBalancer            # EXTERNAL-IP 为节点 IP 列表时，也可用 IP:80 代替集群 DNS
+```
+
+**怎么用 kubectl 查（建议逐条执行）**
+
+```bash
+# 1) 表格式：确认 NAME / PORT(S) / 集群 IP
+kubectl -n kube-system get svc traefik -o wide
+
+# 2) 打印集群 DNS 主机名（无端口）
+kubectl -n kube-system get svc traefik -o jsonpath='{.metadata.name}.{.metadata.namespace}.svc.cluster.local'
+echo
+
+# 2b) 各端口名与端口（核对 HTTP 一般为 name=web、port=80）
+kubectl -n kube-system get svc traefik -o jsonpath='{range .spec.ports[*]}{.name}={.port}{"\n"}{end}'
+
+# 3) 导出完整 YAML，人工对照 metadata / spec.ports
+kubectl -n kube-system get svc traefik -o yaml
+```
+
+HTTP 入口一般为 **name=`web` 的 `port: 80`**；若你环境端口名不是 `web`，以第 1、2、3 条里 **实际 `port` 数字** 为准，Tunnel URL 中冒号后改为该数字。
+
+`cloudflared` 与 Traefik 同集群时，**优先用** `traefik.kube-system.svc.cluster.local:80`，不依赖某台节点 IP 是否变更。
+
+#### 临时验证（集群内 curl）
+
+官方 `cloudflared` 镜像多为 **distroless、无 `sh`**，不要用 `kubectl exec deploy/cloudflared -- sh`。
+
+在 **`kube-system`** 起临时 Pod 探测 Traefik（与 Tunnel 后端同源）：
+
+```bash
+# 根路径（常见 404，无默认路由时正常）
+kubectl run curl-test --rm -n kube-system --restart=Never \
+  --image=curlimages/curl:latest -- \
+  curl -sS -o /dev/null -w "HTTP %{http_code}\n" \
+  http://traefik.kube-system.svc.cluster.local:80/
+
+# Dashboard（已按 03-01/03-03 部署时期望 200）
+kubectl run curl-test --rm -n kube-system --restart=Never \
+  --image=curlimages/curl:latest -- \
+  curl -sS -o /dev/null -w "HTTP %{http_code}\n" \
+  http://traefik.kube-system.svc.cluster.local:80/dashboard/
+```
+
+- **`/` → 404**：多数环境正常（未配置根路径路由）。
+- **`/dashboard/` → 200**：说明集群 DNS 与 Traefik 可达，Public Hostname 可填上述集群内地址。
+
+### 4. 验证连接

 ```bash
 kubectl -n kube-system get pods | grep cloudflared
 kubectl -n kube-system logs deploy/cloudflared --tail=100
 ```

+确认 Pod 为 `Running`，日志中可见 `tunnel connected`。**只有 Connector 已连接后**，才能进行下一步域名配置。
+
+### 5. 配置域名映射（Public Hostnames / Route tunnel）
+
+Zero Trust 向导顺序为：选择类型 → 命名 → **安装并运行 Connector** → **路由流量**。需等 Pod 跑起并显示已连接后，再配置 Public Hostnames。
+
+1. 在 Tunnel 配置页，切换到 **Public Hostnames**（已发布应用程序）标签，点击 **Add a public hostname**
+2. 配置如下：
+
+| 字段               | 填写说明                                                                 |
+|--------------------|------------------------------------------------------------------------|
+| **Subdomain**      | 子域名（如 `k3s`、`git`、`home`），或留空表示根域                         |
+| **Domain**         | 下拉选择已托管在 Cloudflare 的域名（如 `jackadam.top`）                    |
+| **Path**           | 留空表示全路径；或填正则如 `^/blog` 做路径匹配                             |
+| **Service type**   | 选择 **HTTP**（集群内 Traefik 为 HTTP，勿选 HTTPS）                        |
+| **URL**            | 仅填 `traefik.kube-system.svc.cluster.local:80`，**不要加 `http://`**（含义与核对见上文「集群内 Traefik 地址」） |
+
+> **重要**：URL 输入框会根据 Service type 自动加协议前缀。选 HTTP 时只需填 `traefik.kube-system.svc.cluster.local:80`；若手写 `http://` 会变成 `http://http://...`，导致「服务 URL 无效」。
+
+3. 点击 **Save hostname**，按需重复添加其他子域，均指向同一内部地址。
+
+**示例**：Subdomain `k3s` + Domain `jackadam.top` → 公网 `k3s.jackadam.top` 访问 Traefik；不同子域由 Traefik 的 IngressRoute 按 Host 分发。
+
+### 6. 快速验证：以 Dashboard 为例
+
+若已按 03-01 或 03-03 部署 Traefik Dashboard，按上述步骤 5 添加一条 Public Hostname。**Traefik 无需修改**。
+
+> **Public Hostname 的 URL 只能写到「主机 + 端口」**，不能写成 `192.168.2.61/dashboard` 这类带 path 的地址；控制台也不支持在 URL 里做 path patch/转发。路径由浏览器访问时带上，由 Traefik 按路由匹配。
+
+**Dashboard 专用子域**（示例）
+
+| 字段           | 填写值                                      |
+|----------------|---------------------------------------------|
+| Subdomain      | `dashboard`                                 |
+| Domain         | `jackadam.top`（或你的域名）                 |
+| Path           | 留空                                        |
+| Service type   | HTTP                                        |
+| URL            | `traefik.kube-system.svc.cluster.local:80` 或 `192.168.2.61`（仅主机或集群 DNS，**勿**在 URL 里写 `/dashboard`） |
+
+将 `192.168.2.61` 换成你的 Traefik 入口节点 IP（与 `kubectl get svc traefik` 中 EXTERNAL-IP 之一一致即可）。
+
+**访问时在域名后带上 path**：浏览器打开 **`https://dashboard.jackadam.top/dashboard/`**（路径 `/dashboard/` 由 Traefik 的 Dashboard IngressRoute 处理）。
+
+---
+
+**其他用法**：单域名 `k3s.jackadam.top`（URL 同样只填到 `traefik...:80` 或节点 IP），访问时带路径，如 `https://k3s.jackadam.top/dashboard/`；或为每个应用单独配子域。
+
+---
+
+## 架构说明
+
+- **流量路径**：公网 → Cloudflare Edge → Tunnel → `cloudflared` Pod → **Traefik Service** → 各 IngressRoute 后端
+- **配置要点**：Public Hostname 的 URL 为 `traefik.kube-system.svc.cluster.local:80`（Service type 选 HTTP），`cloudflared` 与 Traefik 同集群，可直接通过 Service 访问。
+
+---
+
 ## 预期

- 日志中可见 tunnel connected
- 访问域名可到达 Traefik 路由
+- Pod 为 `Running`，日志中可见 `tunnel connected`
+- 配置域名后，访问公网域名可到达 Traefik 路由
+
+## 注意事项
+
+- 没有 token/凭据：回到 Zero Trust 页面重新生成
+- **顺序**：先跑起 Pod 并确认连接，再配置 Public Hostnames；否则「路由流量」步骤无法生效
+- URL 填写错误：Service type 选 HTTP，URL 只填 `traefik.kube-system.svc.cluster.local:80`，勿加 `http://`

 ## 失败排查

@@ -52,7 +232,10 @@ kubectl -n kube-system logs deploy/cloudflared --tail=100
 - 返回 `404`：通常是 Traefik 路由未命中
 - 返回 `502`：优先排查后端链路（`06-01-k3s-networkpolicy-故障排查.md`）

+---
+
 ## 下一步

+- 其他应用（GitLab、Homer 等）：在集群内创建 IngressRoute/Ingress 指定 Host 与后端，再在 Zero Trust 中添加对应子域的 Public Hostname 即可
 - `05-03-k3s-安装gitlab-含runner.md`
 - `05-01-k3s-部署homer首页面板.md`
--- a/docs/03-05-k3s-local-path-pvc.md
+++ b/docs/03-05-k3s-local-path-pvc.md
@@ -1,4 +1,4 @@
-# 03-06-k3s local-path PVC 本地持久化
+# 03-05-k3s local-path PVC 本地持久化

 > K3s 自带的 **local-path-provisioner**：通过 PVC 自动创建本地 PersistentVolume，适用于单副本应用、缓存、日志等，无需 NFS 或 Longhorn。

@@ -7,42 +7,178 @@
 | 方式 | 共享 | 适用场景 |
 |------|------|----------|
 | **local-path**（本页） | 否，单节点 | 单副本应用（Traefik acme.json、单机数据库等），Pod 固定调度到同一节点 |
-| **NFS**（`03-08`） | 是，多节点读写 | 多副本共享目录、需跨节点访问 |
-| **Longhorn**（`03-09`） | 块存储，CSI | 重状态系统、快照/备份、生产推荐 |
+| **NFS**（`03-06-k3s-使用nfs存储.md`） | 是，多节点读写 | 多副本共享目录、需跨节点访问 |
+| **Longhorn**（`03-07-k3s-longhorn-持久化存储.md`） | 块存储，CSI | 重状态系统、快照/备份、生产推荐 |

 ## 前置条件

 - K3s 已安装（local-path-provisioner 默认启用）
- 无额外组件，`kubectl get storageclass` 可见 `local-path`（通常为默认）
+- 无额外组件，`kubectl get storageclass` 可见 `local-path`（通常为 default），例如：
+
+```text
+NAME                   PROVISIONER             ...
+local-path (default)   rancher.io/local-path   ...
+```

 ## 操作步骤

 ### 1. 清单（PVC + Deployment）

-**唯一真源**：[`ansible/files/local-path-demo/local-path-pvc-demo.yaml`](../ansible/files/local-path-demo/local-path-pvc-demo.yaml)（含 PVC `local-pvc-demo` 与 `nginx-local-pvc-demo` Deployment；`storageClassName` 可省略，K3s 默认多为 `local-path`）。
+**唯一真源**：[`ansible/files/local-path-demo/local-path-pvc-demo.yaml`](../ansible/files/local-path-demo/local-path-pvc-demo.yaml)（含 PVC `local-pvc-demo` 与 `nginx-local-pvc-demo` Deployment；清单内已写 **`storageClassName: local-path`**，与 `kubectl get storageclass` 中名称一致即可）。

 ### 2. 应用与验证

+在**本仓库根目录**执行（或把 `-f` 换成清单的绝对路径）：
+
 ```bash
 kubectl apply -f ansible/files/local-path-demo/local-path-pvc-demo.yaml

+# 等 Pod 调度、PVC 绑定后再操作（local-path 多为 WaitForFirstConsumer，前几秒 Pending 正常）
+kubectl rollout status deploy/nginx-local-pvc-demo --timeout=180s
+
 kubectl get pv,pvc
 kubectl get pod -o wide
 kubectl exec deploy/nginx-local-pvc-demo -- sh -c 'echo hello > /usr/share/nginx/html/test.txt'
 kubectl delete pod -l app=nginx-local-pvc-demo
+kubectl rollout status deploy/nginx-local-pvc-demo --timeout=180s
 kubectl exec deploy/nginx-local-pvc-demo -- cat /usr/share/nginx/html/test.txt  # 应仍为 hello
 ```

+> **勿在 Pod 仍为 Pending 时 `exec`**，否则会报 `does not have a host assigned`。先 `kubectl get pod -o wide` 确认 **NODE** 有值且 **READY 1/1**。
+
+### 3. Pending 排查（PVC / Pod 长时间不 Ready）
+
+```bash
+kubectl describe pvc local-pvc-demo -n default
+kubectl describe pod -l app=nginx-local-pvc-demo -n default
+kubectl get events -n default --sort-by=.lastTimestamp | tail -30
+kubectl get pods -n kube-system | grep -i local-path
+kubectl logs -n kube-system deploy/local-path-provisioner --tail=80 2>/dev/null || \
+  kubectl logs -n kube-system -l app=local-path-provisioner --tail=80
+```
+
+常见原因：**local-path-provisioner** 未就绪或报错、节点磁盘/权限、曾留下异常 PVC。可删除后重试：
+
+```bash
+kubectl delete deploy/nginx-local-pvc-demo -n default --ignore-not-found
+kubectl delete pvc local-pvc-demo -n default --ignore-not-found
+# 等待 PV 回收后再 apply
+kubectl apply -f ansible/files/local-path-demo/local-path-pvc-demo.yaml
+kubectl rollout status deploy/nginx-local-pvc-demo --timeout=180s
+```
+
 ## 注意事项

- **绑定到节点**：PV 创建在 Pod 首次调度到的节点上，Pod 重建后仍会调度到该节点（provisioner 会打 nodeAffinity）
+- **WaitForFirstConsumer**：PVC 在 Pod 未调度前可长期 **Pending**；PV 在 **Pod 首次成功调度到某节点后** 才创建，且会带 nodeAffinity，Pod 重建后仍倾向同一节点
 - **单副本**：`ReadWriteOnce`，同一 PVC 只能被同一节点上的一个 Pod 挂载；多副本需 NFS 或 Longhorn
 - **数据路径**：默认在 K3s `--data-dir` 下的 `storage`，如 `/var/lib/rancher/k3s/storage` 或 `/storage`
 - **回收策略**：`Delete`，删除 PVC 时 PV 及本地目录会被清理

-## Traefik acme.json 示例
+## storageClass: local-path 与「本地路径」说明

-若希望 Traefik 的 ACME 证书走 local-path PVC，需在 HelmChartConfig 的 values 中为 Traefik 配置 volume 与 volumeMount（见 `03-02-k3s-traefik-acme.md` 可选配置）。多数场景下，配合 `nodeSelector` 固定 Traefik 到同一节点，再用 hostPath 或 local-path 均可；无 hostPath 时 K3s 默认会为 Traefik 挂 emptyDir 或默认卷。
+### PVC / StorageClass 里**不能**写宿主机目录
+
+在清单里写 `storageClassName: local-path`（或 Traefik Helm `persistence.storageClass: local-path`）只表示：**交给 K3s 自带的 local-path-provisioner 在某一工作节点上自动创建本地目录并绑定 PV**。
+
+- **不能**在 PVC 或 StorageClass 里指定「数据必须落在 `/mnt/mydata/xxx`」这类**宿主机绝对路径**。
+- 实际在节点磁盘上的目录，由 **provisioner 的全局配置 + 内部命名规则** 生成；通常位于 K3s `--data-dir` 下的 `storage` 子树（与上文「注意事项」一致）。
+
+### Traefik `persistence.path: /data` 是**容器内**挂载点
+
+在 [`traefik-dashboard-acme.yaml`](../ansible/files/traefik-dashboard-acme/traefik-dashboard-acme.yaml) 中：
+
+| 字段 | 含义 |
+|------|------|
+| `persistence.path: /data` | Traefik **容器内**的挂载目录（Helm chart 把 PVC 挂到这里） |
+| `acme.storage=/data/acme.json` | **容器内**证书文件路径，与上面挂载一致 |
+| `storageClass: local-path` | 使用哪种**动态供给**方式，不等价于「宿主机路径」 |
+
+因此：**容器里永远是 `/data/...`**；宿主机上对应哪一块目录，要看该 PVC 绑定的 **PV**。
+
+### 如何查看数据实际落在节点的哪个目录
+
+PVC 绑定后，用 PV 反查（Traefik 示例在 `kube-system`）：
+
+```bash
+# 1) 找到 Traefik 使用的 PVC 名称（chart 创建的 claim 名因版本可能略有差异）
+kubectl -n kube-system get pvc
+
+# 2) 从 PVC 的 Volume / Bound 信息得到 PV 名，再查看 PV（路径在 spec 或 describe 输出中）
+kubectl -n kube-system describe pvc <你的-pvc-名>
+kubectl describe pv <上一步看到的-pv-名>
+kubectl get pv <pv-名> -o yaml   # 在 spec 中查 path、hostPath、local、csi.volumeAttributes 等
+```
+
+不同 K3s / provisioner 版本字段名可能略有差异，以 `describe` / `yaml` 实际输出为准。
+
+### 需要指定「整盘根目录」时：改 local-path-provisioner 配置
+
+若希望**某一类节点**上通过 `local-path` 创建的数据统一落在指定根路径下（仍由 provisioner 在根下自动分子目录），可编辑 **`kube-system`** 中的 ConfigMap **`local-path-config`**（键名多为 `config.json`），使用 **`nodePathMap`** 等为节点配置路径。
+
+> 修改前建议 `kubectl -n kube-system get configmap local-path-config -o yaml` 备份；改错会导致新 PVC 无法创建。
+
+示意（**仅为结构说明，请与集群内现有 JSON 合并修改，勿直接整段覆盖**）：
+
+```json
+{
+  "nodePathMap": [
+    {
+      "node": "DEFAULT_PATH_FOR_NON_LISTED_NODES",
+      "paths": ["/var/lib/rancher/k3s/storage"]
+    },
+    {
+      "node": "你的节点主机名",
+      "paths": ["/data/k3s-local-path"]
+    }
+  ]
+}
+```
+
+保存 ConfigMap 后，通常需 **重启** `local-path-provisioner` 相关负载使配置生效（以你集群实际 Deployment/DaemonSet 名为准）：
+
+```bash
+kubectl -n kube-system rollout restart deploy/local-path-provisioner 2>/dev/null || true
+```
+
+具体字段与默认值以当前 K3s 版本自带的 [rancher local-path-provisioner](https://github.com/rancher/local-path-provisioner) 文档为准。
+
+### 与 hostPath 的区别
+
+| 方式 | 说明 |
+|------|------|
+| **storageClass: local-path** | 动态 PV，路径由 provisioner 管理；适合一般工作负载与 Traefik ACME。 |
+| **hostPath / 手写 PV** | 在清单里直接绑定节点上某一目录；需自行保证节点一致性与权限，与「local-path StorageClass」不是同一条配置路径。 |
+
+若 Traefik Helm chart 支持你也可使用其 **`persistence.hostPath`** 类选项（若版本提供），则属于 **显式 hostPath**，与仅写 `local-path` 的用法不同。
+
+## Traefik ACME：证书固定到 local-path（推荐）
+
+ACME 存储路径在配置里已是 **`/data/acme.json`**（见 `03-02`、`03-03`）。K3s 自带 **Traefik Helm chart** 支持 **`persistence`**：开启后由 chart **自动创建 PVC**（`storageClass: local-path`），挂载到 **`/data`**，与 `acme.storage` 一致，**Pod 重建 / 滚动后证书仍在**。
+
+**前提**：`nodeSelector` 必须把 Traefik **固定在同一节点**（与 local-path **ReadWriteOnce** 一致）；若换节点，需迁卷或重新签发。
+
+| 场景 | 唯一真源 |
+|------|----------|
+| **Dashboard + ACME + local-path（推荐）** | **仅此一份**：[`ansible/files/traefik-dashboard-acme/traefik-dashboard-acme.yaml`](../ansible/files/traefik-dashboard-acme/traefik-dashboard-acme.yaml)（**HelmChart persistence + ACME + Dashboard + IngressRoute**） |
+
+清单内已含：`persistence.enabled: true`、`storageClass: local-path`、`size: 512Mi`、`path: /data`，与 `acme.storage=/data/acme.json` 一致。部署前替换 **`<YOUR_REAL_EMAIL>`**、`nodeSelector` 中的 **主机名**；并确保 **`cloudflare-api-token`** Secret 已存在（同 `03-02` / `03-03`）。**不需要 Dashboard** 时按该 YAML 文件头注释删减。
+
+> **只能有一份** `HelmChartConfig`（`metadata.name: traefik`）。若曾用旧版无 persistence 的清单，请 **合并为** 上述 `traefik-dashboard-acme.yaml`（或 `traefik-acme.yaml` 并自行补全 persistence），避免多文件重复定义。
+
+**应用与核对**（路径按你的 manifests 目录调整）：
+
+```bash
+kubectl apply -f ansible/files/traefik-dashboard-acme/traefik-dashboard-acme.yaml
+
+kubectl -n kube-system rollout status deploy/traefik --timeout=300s
+kubectl -n kube-system get pvc | grep -i traefik
+kubectl -n kube-system exec deploy/traefik -- ls -la /data/acme.json
+kubectl -n kube-system logs deploy/traefik --tail=80 | grep -i acme || true
+```
+
+从 **emptyDir / 无持久卷** 迁到 PVC 时，若旧 Pod 里已有有效 `acme.json`，可先 `kubectl cp` 备份再切换；否则切换后会按新账户重新向 Let’s Encrypt 申请。
+
+更多 ACME 排障见 `03-02-k3s-traefik-acme.md`、`03-03-k3s-traefik-dashboard-acme.md`。

 ## 下一步

--- a/docs/03-06-k3s-使用nfs存储.md
+++ b/docs/03-06-k3s-使用nfs存储.md
@@ -4,7 +4,7 @@

 ## 前置条件

- 已完成 `01-06-armv7-nfs服务安装.md`
+- 已完成 `01-05-armv7-nfs服务安装.md`
 - 可从 K3s 节点访问 NFS 服务器与导出目录

 ## 操作步骤
--- a/docs/03-08-k3s-ha-集群配置与切换.md
+++ b/docs/03-08-k3s-ha-集群配置与切换.md
@@ -4,7 +4,7 @@

 ## 前置条件

- 已完成 `01-05-双控制节点ha.md` 安装准备
+- 已完成 `01-04-双控制节点ha.md` 安装准备
 - 外部 datastore 与 `6443` LB 已可用
 - 已确认可执行变更窗口

@@ -72,7 +72,7 @@ kubectl get pods -A

 ## 参考

- `01-05-双控制节点ha.md`
+- `01-04-双控制节点ha.md`
 - `01-01-k3s-控制节点含traefik.md`
 - `01-02-k3s-工作节点.md`

--- a/docs/03-09-k3s-gitops-集群配置管理.md
+++ b/docs/03-09-k3s-gitops-集群配置管理.md
@@ -1,7 +1,7 @@
-# 03-09-k3s-gitops-集群配置管理（框架草案）
+# 03-09-k3s-gitops-集群配置管理（框架草案）

 > 本文先给出 GitOps 管理 k3s 集群的大致框架，后续可以按需要再细化成完整实践。
-> 目标：在 `01-07` 自动装好 k3s 之后，由 GitOps 工具（Argo CD / Flux）自动把 Traefik、监控、应用等 YAML 下发到集群。
+> 目标：在 `01-06` 自动装好 k3s 之后，由 GitOps 工具（Argo CD / Flux）自动把 Traefik、监控、应用等 YAML 下发到集群。

 ## 1. 选型与边界

@@ -43,7 +43,7 @@ homelab-k3s-gitops/

 ## 4. 与现有文档的衔接

- `01-07-节点初始化-ansible-实践.md`：负责从「可 SSH 裸机」到「k3s 就绪」；
+- `01-06-节点初始化-ansible-实践.md`：负责从「可 SSH 裸机」到「k3s 就绪」；
 - 本篇 `03-11`：负责从「k3s 就绪」到「配置由 Git 驱动下发」；
 - 其他 `02-**`、`04-**`、`05-**` 文档中的部署命令，可以逐步迁移为 GitOps 仓库中的 YAML/Kustomize/Helm 定义。

--- a/docs/04-01-k3s-nodejs-高级部署.md
+++ b/docs/04-01-k3s-nodejs-高级部署.md
@@ -6,8 +6,9 @@
 ## 前置条件

 - 已完成 `01-02-k3s-工作节点.md`
- 已完成 `01-04-cloudflare-tunnel.md`（如需外网入口）
 - 已完成 `03-01-k3s-traefik-dashboard.md`（可选，便于观察路由）
+- 已完成 `03-04-k3s-cloudflare-tunnel-配置接入.md`（如需外网入口）
+

 ## 基础部署步骤

--- a/docs/06-01-k3s-networkpolicy-故障排查.md
+++ b/docs/06-01-k3s-networkpolicy-故障排查.md
@@ -7,7 +7,7 @@

 - 已完成 `01-02-k3s-工作节点.md`
 - 已有至少一个后端服务（如 nginx/nodejs）
- 可执行 `kubectl` 与排障脚本
+- 可执行 `kubectl`

 ## 三条先验结论

@@ -30,16 +30,20 @@ curl -I --max-time 3 http://192.168.2.61:80
 curl -I --max-time 3 http://192.168.2.62:80
 ```

-### 2.3 快速检查脚本
+### 2.3 快速检查命令

 ```bash
-./scripts/diag/netpol/check-net.sh
+kubectl get pod,svc,ing -A
+kubectl get networkpolicy -A
+kubectl -n kube-system get pods -l app=svclb-traefik -o wide
 ```

-### 2.4 全链路诊断
+### 2.4 全链路检查（手工）

 ```bash
-./scripts/diag/entrypath/entrypath.sh run ...
+# 从入口节点IP验证 HTTP 入口
+curl -I --max-time 3 http://192.168.2.61:80
+curl -I --max-time 3 http://192.168.2.62:80
 ```

 ## 关键策略建议
@@ -52,15 +56,7 @@ curl -I --max-time 3 http://192.168.2.62:80

 ## 已验证修复（Fedora/FCOS）

-### 4.1 脚本修复（推荐）
-
-```bash
-./scripts/diag/firewalld/setup-k3s-firewalld-interfaces.sh
-```
-
-该脚本会把 `flannel.1` 与 `cni0` 纳入 `trusted` 并持久化。
-
-### 4.2 手动修复（不使用脚本）
+### 4.1 手动修复

 ```bash
 # 1) 临时生效（当前运行时）