docs: 完善 03-05 本地存储文档与 local-path demo

- 落地路径查询优先 spec.local.path，兼容 hostPath - local-path demo 增加 nodeSelector 固定节点 Made-with: Cursor
2026-03-24 06:21:10 +08:00
parent be97836e0d
commit a67788de56
3 changed files with 211 additions and 144 deletions
--- a/ansible/files/local-path-demo/local-path-pvc-demo.yaml
+++ b/ansible/files/local-path-demo/local-path-pvc-demo.yaml
@@ -27,6 +27,8 @@ spec: # Deployment 的期望状态（副本数、选择器、Pod 模板等）
      labels: # Pod 标签：必须与 selector.matchLabels 对齐
        app: nginx-local-pvc-demo # Pod 模板 label：必须与 selector.matchLabels 对上
    spec: # Pod 规范
+      nodeSelector: # 指定调度节点（本地盘绑定节点；请按实际节点主机名修改）
+        kubernetes.io/hostname: ylc61 # 仅调度到主机名为 ylc61 的节点
      containers: # 容器列表
        - name: nginx # 容器名
          image: nginx:alpine # nginx 镜像
--- a/docs/00-02-验证矩阵.md
+++ b/docs/00-02-验证矩阵.md
@@ -85,7 +85,7 @@
  - 状态：✅ 已验证
  - 备注：本实验室集群完整流程（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 本地持久化；待实机验证。
 - `03-06-k3s-使用nfs存储.md`  
  - 状态：❓ 未验证  
--- a/docs/03-05-k3s-local-path-pvc.md
+++ b/docs/03-05-k3s-local-path-pvc.md
@@ -1,187 +1,252 @@
-# 03-05-k3s local-path PVC 本地持久化
+# 03-05-k3s 本地存储目录控制（local-path-config / hostPath / local PV）

-> K3s 自带的 **local-path-provisioner**：通过 PVC 自动创建本地 PersistentVolume，适用于单副本应用、缓存、日志等，无需 NFS 或 Longhorn。
+> 这篇只讲一件事：在 K3s 里，如何控制“数据最终落到宿主机哪个目录”。

-## 与 NFS / Longhorn 的区别
+## 先说结论

-| 方式 | 共享 | 适用场景 |
-|------|------|----------|
-| **local-path**（本页） | 否，单节点 | 单副本应用（Traefik acme.json、单机数据库等），Pod 固定调度到同一节点 |
-| **NFS**（`03-06-k3s-使用nfs存储.md`） | 是，多节点读写 | 多副本共享目录、需跨节点访问 |
-| **Longhorn**（`03-07-k3s-longhorn-持久化存储.md`） | 块存储，CSI | 重状态系统、快照/备份、生产推荐 |
+- **方法一（推荐）`local-path-config`**：给 `local-path` 动态供给指定“基路径”。  
+  适合大多数场景；PVC 仍可自动创建，但要通过 PV 反查落地目录。
+- **方法二 `hostPath`**：在 Pod 里直接写宿主机目录。  
+  目录由你显式指定，不需要再查 provisioner 生成路径。
+- **方法三 `local PV`**：可精确绑定“节点 + 目录”，但维护成本更高。  
+  本文只做介绍，不展开实操。

 ## 前置条件

- K3s 已安装（local-path-provisioner 默认启用）
- 无额外组件，`kubectl get storageclass` 可见 `local-path`（通常为 default），例如：
+- K3s 已安装且 `local-path-provisioner` 正常运行
+- 能执行 `kubectl`
+- `kubectl get storageclass` 能看到 `local-path`（通常为 default）

-```text
-NAME                   PROVISIONER             ...
-local-path (default)   rancher.io/local-path   ...
-```
+## 方法一：`local-path-config` 指定“基路径”（重点）

-## 操作步骤
+### 1) 原理

-### 1. 清单（PVC + Deployment）
+`storageClassName: local-path` 并不会在 PVC 里写死宿主机目录。  
+它表示交给 `local-path-provisioner` 动态创建 PV，PV 的实际目录由 `local-path-config`（`config.json`）里配置的基路径决定，然后在基路径下自动生成子目录。

-**唯一真源**：[`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` 换成清单的绝对路径）：
+### 2) 操作步骤

 ```bash
-kubectl apply -f ansible/files/local-path-demo/local-path-pvc-demo.yaml
+# 1. 备份当前配置
+kubectl -n kube-system get configmap local-path-config -o yaml > /tmp/local-path-config.bak.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
+# 2. 编辑 config.json（把 paths 改成你希望的基路径）
+kubectl -n kube-system edit configmap local-path-config
 ```

-> **勿在 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
-```
-
-## 注意事项
-
- **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 及本地目录会被清理
-
-## storageClass: local-path 与「本地路径」说明
-
-### 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 合并，不要盲目整段覆盖）：

 ```json
 {
  "nodePathMap": [
    {
      "node": "DEFAULT_PATH_FOR_NON_LISTED_NODES",
-      "paths": ["/var/lib/rancher/k3s/storage"]
+      "paths": ["/storage/storage"]
    },
    {
-      "node": "你的节点主机名",
+      "node": "ylc61",
      "paths": ["/data/k3s-local-path"]
    }
  ]
 }
 ```

-保存 ConfigMap 后，通常需 **重启** `local-path-provisioner` 相关负载使配置生效（以你集群实际 Deployment/DaemonSet 名为准）：
+说明：
+
+- `DEFAULT_PATH_FOR_NON_LISTED_NODES` 是兜底规则，不是实际节点名；凡是未单独列出的节点都走它。
+- `ylc61` 是单独覆盖规则；该节点会优先使用这里配置的基路径。
+- `paths` 是数组是因为支持“一个节点多个候选基路径”；示例里每个节点只写了一个路径。
+- 因此这段不是“一个节点两个路径”，而是“两个节点规则（默认 + 指定）”。

 ```bash
+# 3. 重启 provisioner 使配置生效
 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) 文档为准。
+### 3) 用 demo 验证（PVC -> PV -> 节点 -> 落地目录）

-### 与 hostPath 的区别
+Demo 清单：[`ansible/files/local-path-demo/local-path-pvc-demo.yaml`](../ansible/files/local-path-demo/local-path-pvc-demo.yaml)

-| 方式 | 说明 |
-|------|------|
-| **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 目录调整）：
+> 该 demo 已包含 `nodeSelector` 固定节点（示例为 `ylc61`），使用前请按你的节点主机名修改。

 ```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
+kubectl apply -f ansible/files/local-path-demo/local-path-pvc-demo.yaml
+kubectl rollout status deploy/nginx-local-pvc-demo --timeout=180s
 ```

-从 **emptyDir / 无持久卷** 迁到 PVC 时，若旧 Pod 里已有有效 `acme.json`，可先 `kubectl cp` 备份再切换；否则切换后会按新账户重新向 Let’s Encrypt 申请。
+按下面顺序查真实落地路径：

-更多 ACME 排障见 `03-02-k3s-traefik-acme.md`、`03-03-k3s-traefik-dashboard-acme.md`。
+```bash
+# A. PVC 对应的 PV 名
+PV=$(kubectl get pvc local-pvc-demo -o jsonpath='{.spec.volumeName}')
+echo "$PV"

-## 下一步
+# B. PV 绑定到哪个节点
+kubectl get pv "$PV" -o jsonpath='{.spec.nodeAffinity.required.nodeSelectorTerms[0].matchExpressions[0].values[0]}{"\n"}'

- `03-06-k3s-使用nfs存储.md`：需多节点共享时
- `03-07-k3s-longhorn-持久化存储.md`：重状态、快照、备份
+# C. PV 的宿主机物理路径（local-path 在多数集群里是 local.path）
+kubectl get pv "$PV" -o jsonpath='{.spec.local.path}{"\n"}'
+
+# D. 兼容差异：若上面为空，再尝试 hostPath.path 并用 yaml/describe 兜底
+kubectl get pv "$PV" -o jsonpath='{.spec.hostPath.path}{"\n"}'
+kubectl get pv "$PV" -o yaml | grep -E "path:|local:"
+kubectl describe pv "$PV"
+```
+
+> 你之前看到的 `path: /storage/storage/pvc-...` 就是宿主机实际目录。  
+> 若是 `/storage/storage/...`，通常表示 K3s `--data-dir=/storage`，provisioner 再使用其 `storage` 子目录，属于正常现象。
+
+### 4) 常见误区
+
+- `persistence.path`、`volumeMount.mountPath` 是**容器内路径**，不是宿主机路径。
+- `local-path` 是动态供给，不是“每个 PVC 自定义绝对目录”。
+- `WaitForFirstConsumer` 下，Pod 未调度时 PVC Pending 属于正常现象。
+
+### 5) 删除与回收（建议写进日常操作）
+
+先删工作负载，再删 PVC：
+
+```bash
+# 1) 先删 Deployment（避免卷仍在挂载）
+kubectl delete deploy nginx-local-pvc-demo -n default --ignore-not-found
+
+# 2) 再删 PVC
+kubectl delete pvc local-pvc-demo -n default --ignore-not-found
+
+# 3) 确认 PVC/PV 已回收
+kubectl get pvc local-pvc-demo -n default
+kubectl get pv | grep local-pvc-demo || true
+```
+
+检查 `local-path` 的回收策略（通常是 `Delete`）：
+
+```bash
+kubectl get sc local-path -o jsonpath='{.reclaimPolicy}{"\n"}'
+```
+
+- `Delete`：删 PVC 后，PV 和后端目录通常会被 provisioner 自动清理。
+- `Retain`：删 PVC 后，PV/目录可能保留，需要手动处理。
+
+手动删除宿主机目录（仅在异常残留或 `Retain` 场景使用）：
+
+```bash
+# A. 找到 PVC 对应 PV
+PV=$(kubectl get pvc local-pvc-demo -n default -o jsonpath='{.spec.volumeName}')
+
+# B. 查目录和节点
+NODE=$(kubectl get pv "$PV" -o jsonpath='{.spec.nodeAffinity.required.nodeSelectorTerms[0].matchExpressions[0].values[0]}')
+PATH_ON_NODE=$(kubectl get pv "$PV" -o jsonpath='{.spec.hostPath.path}')
+echo "node=$NODE path=$PATH_ON_NODE"
+
+# C. 登录该节点手工删除（示例）
+# ssh <你的节点登录> "sudo rm -rf '$PATH_ON_NODE'"
+```
+
+> 注意：手工删目录前务必确认 Pod/Deployment 已删除且不再挂载该路径。
+
+## 方法二：Pod 里直接用 `hostPath`（路径由你指定）
+
+适用：单节点、实验环境，或者你明确要写死某个宿主机目录。
+
+最小完整示例（可直接 `kubectl apply -f`，非空行逐行注释）：
+
+```yaml
+apiVersion: apps/v1 # Deployment 所属 API 版本
+kind: Deployment # 资源类型：Deployment
+metadata: # 资源元数据
+  name: nginx-hostpath-demo # Deployment 名称
+  namespace: default # 部署命名空间
+spec: # Deployment 规格
+  replicas: 1 # 副本数：1（hostPath 通常用于单副本）
+  selector: # Pod 选择器
+    matchLabels: # 必须与 template.labels 完全一致
+      app: nginx-hostpath-demo # 选择 app=nginx-hostpath-demo 的 Pod
+  template: # Pod 模板
+    metadata: # Pod 元数据
+      labels: # Pod 标签
+        app: nginx-hostpath-demo # 给 Pod 打 app 标签
+    spec: # Pod 规格
+      nodeSelector: # 指定调度节点（本地目录在该节点上生效）
+        kubernetes.io/hostname: ylc61 # 请改成你的目标节点主机名
+      containers: # 容器列表
+        - name: nginx # 容器名称
+          image: nginx:1.27-alpine # 容器镜像
+          ports: # 容器暴露端口
+            - containerPort: 80 # Nginx 容器监听 80
+          volumeMounts: # 容器内挂载列表
+            - name: app-data # 引用下方 volumes 的同名卷
+              mountPath: /usr/share/nginx/html # 挂载到容器内网站目录
+      volumes: # Pod 卷定义
+        - name: app-data # 卷名称（供 volumeMounts 引用）
+          hostPath: # 使用宿主机目录卷
+            path: /data/nginx-hostpath-demo # 你指定的宿主机物理目录
+            type: DirectoryOrCreate # 目录不存在则自动创建
+---
+apiVersion: v1 # Service 所属 API 版本
+kind: Service # 资源类型：Service
+metadata: # 资源元数据
+  name: nginx-hostpath-demo # Service 名称
+  namespace: default # Service 命名空间
+spec: # Service 规格
+  selector: # 选择后端 Pod 的标签
+    app: nginx-hostpath-demo # 指向 app=nginx-hostpath-demo 的 Pod
+  ports: # Service 端口映射
+    - port: 80 # Service 暴露端口
+      targetPort: 80 # 转发到容器 80 端口
+  type: ClusterIP # 集群内访问类型（默认）
+```
+
+应用与最小验证：
+
+```bash
+# 1) 保存上面的 YAML 到 /tmp/nginx-hostpath-demo.yaml 后应用
+kubectl apply -f /tmp/nginx-hostpath-demo.yaml
+
+# 2) 等待就绪
+kubectl rollout status deploy/nginx-hostpath-demo --timeout=180s
+
+# 2.1) 确认 Pod 已调度到你指定的节点
+kubectl get pod -l app=nginx-hostpath-demo -o wide
+
+# 3) 写入一段测试内容到挂载目录
+kubectl exec deploy/nginx-hostpath-demo -- sh -c 'echo hostpath-ok > /usr/share/nginx/html/index.html'
+
+# 4) 通过 Service 在集群内访问验证
+kubectl run curl-test --image=curlimages/curl:8.8.0 --restart=Never -it --rm -- \
+  curl -s http://nginx-hostpath-demo.default.svc.cluster.local/
+```
+
+说明：
+
+- 这里的 `/data/nginx-hostpath-demo` 就是你指定的宿主机目录，不需要通过 PV 反查。
+- 目录只在调度到的那个节点有效；Pod 换节点会找不到原数据。
+- 生产中大量使用 `hostPath` 风险较高（权限、安全、漂移），需额外治理。
+
+## 方法三：`local PV`（仅介绍）
+
+`local PV` 介于上述两者之间：
+
+- 比 `hostPath` 更“标准化”（走 PV/PVC 模型，可声明容量与绑定策略）
+- 比 `local-path` 更“可控”（可固定具体节点和目录）
+- 但需要你手工维护 PV 生命周期、节点关系、回收策略
+
+典型适用：
+
+- 必须固定到某节点某目录
+- 又希望保留 PVC 申领流程，而不是直接在 Pod 里写 `hostPath`
+
+不适用：
+
+- 追求“自动化、低运维成本”的通用应用持久化
+
+## 如何选
+
+- 默认选 **`local-path-config`**：自动化最好，够用且稳。
+- 需要“清单里写死路径”时选 **`hostPath`**（仅限明确单节点场景）。
+- 需要“精确目录 + PVC 模型”时考虑 **`local PV`**。
+
+## 关联文档
+
+- `03-06-k3s-使用nfs存储.md`（多节点共享目录）
+- `03-07-k3s-longhorn-持久化存储.md`（重状态、快照、备份）