pv挂载路径不匹配踩坑经验 - Forgus

问题描述

在 /mnt/nfs/md-files 目录下放置了 Markdown 文件，但 wiki-server 没有生成索引。

环境信息

部署方式: K3s 集群
存储: NFS 持久化存储
wiki-server 容器内路径: /mnt/nfs/md-files

排查过程

1. 检查目录状态

# 主机上目录有文件
$ ls -la /mnt/nfs/md-files/
-rw-r--r-- 1 root root 10466 Apr  4 17:23 DA.md
-rw-r--r-- 1  501 dialout  2319 Apr  4 17:31 IP划分.md

# 但容器内目录为空
$ kubectl exec deploy/wiki-server -- ls -la /mnt/nfs/md-files/
total 12
drwxr-xr-x 2 root root 4096 Apr  4 07:52 ..

2. 排查日志

wiki-server 日志显示 Periodic scan complete: {'added': 0, 'modified': 0, 'deleted': 0, 'moved': 0}，说明扫描器没有检测到任何文件变更。

3. 检查存储挂载

主机挂载情况

1
2
3

$ mount | grep nfs
192.168.2.20:/volume3/wiki on /mnt/nfs type nfs4
192.168.2.20:/volume3/nfs-share on /var/lib/kubelet/... type nfs4

NFS 服务器导出

1 2	/volume3/wiki * /volume3/nfs-share 192.168.1.0/24,192.168.2.0/24

Kubernetes PV 配置

# 原 PV 配置
nfs:
  server: 192.168.2.20
  path: /volume3/nfs-share   # ❌ 错误路径

根本原因

NFS 路径不匹配

配置项	值
config.yaml md_files_path	`/mnt/nfs/md-files`
主机挂载 `/mnt/nfs`	`/volume3/wiki`
Kubernetes PV nfs.path	`/volume3/nfs-share` ❌

主机写入文件到 /mnt/nfs/md-files/ → 实际写入 /volume3/wiki/md-files/
wiki-server 容器通过 PVC 挂载 → 挂载的是 /volume3/nfs-share
两个 NFS 路径不同，导致容器内看到空目录

解决方案

将 PV 的 NFS path 从 /volume3/nfs-share 修改为 /volume3/wiki，与主机挂载路径一致。

操作步骤

# 1. 删除旧 PV（PV 无法修改，需要重建）
kubectl delete pv nfs-pv-01

# 2. 创建新 PV（使用正确路径）
kubectl apply -f - <<EOF
apiVersion: v1
kind: PersistentVolume
metadata:
  name: nfs-pv-01
spec:
  capacity:
    storage: 450Gi
  accessModes:
    - ReadWriteMany
  storageClassName: nfs-storage
  nfs:
    server: 192.168.2.20
    path: /volume3/wiki
  persistentVolumeReclaimPolicy: Retain
EOF

# 3. 删除旧 PVC 并重建（绑定到新 PV）
kubectl delete pvc nfs-pvc -n default

# 4. 重启应用使挂载生效
kubectl rollout restart deploy/wiki-server -n default

经验总结

多挂载点问题: 当主机使用不同 NFS 路径挂载时，Kubernetes 集群内看到的路径可能与主机不一致
NFS 导出限制: 注意 NFS 服务器的导出路径和权限限制（nfs-share 只允许特定网段访问）
路径一致性: 部署应用前确认：
- 主机挂载路径
- 应用配置文件中的路径
- Kubernetes PV/PVC 中的 NFS 路径
- 三者必须一致
调试技巧: 通过 kubectl exec 检查容器内实际挂载内容，是排查存储问题的最直接方法