EDA 存储标准化故障排查手册（troubleshoot）¶

1. 主机不可达 / 免密失败¶

现象：pre_check 报 主机不可达或免密登录失败。排查：

ssh -o BatchMode=yes root@<ip> true

处理：确认网络、sshd、~/.ssh/authorized_keys。脚本不自动重试，修复后重跑。

2. 配置错误¶

现象：[配置错误] 配置文件不存在 或 YAML 解析失败。处理：cp config/deploy.yaml.example config/deploy.yaml，用 python3 -c "import yaml;yaml.safe_load(open('config/deploy.yaml'))" 校验语法。

3. 锁冲突¶

现象：检测到正在运行的实例(PID=xxx)，锁冲突直接退出。说明：防并发设计，不排队不重试。处理：确认无其他实例在跑；若是崩溃遗留的孤儿锁，脚本会自动清理（PID 已不存在时）。手动路径：cat /tmp/eda_storage.lock 后按需删除。

4. remount 失败（Device or resource busy）¶

现象：[警告] remount 失败（可能 busy...）。根因：挂载点被占用，或该参数不支持热改。处理： - noatime/actimeo/timeo/retrans/hard 支持 remount； - nconnect、nfsvers 需 umount && mount 或重启，属维护窗口操作； - 确认占用：fuser -m /home；无法卸载时安排维护窗口。

5. 幂等复验仍有变更¶

现象：第二次执行仍报若干项。排查：

ssh root@<ip> "grep ' /home ' /proc/mounts; grep ' /home ' /etc/fstab"

常见原因：remount 未成功（见 4）；实际挂载缺 actimeo/noatime。修复后重跑。

6. Lustre 命令缺失¶

现象：未检测到 lfs 命令。处理：确认该节点已安装 Lustre 客户端内核模块与用户态工具：lsmod | grep lustre。

7. 客户端挂载新目录失败¶

现象：mount /projects 报 access denied 或 No such file。排查：

ssh root@192.168.0.13 "exportfs -v | grep eda; ls -ld /data/eda/projects"

处理：确认导出已生效（exportfs -ra）、目录存在且权限正确、客户端在 192.168.0.0/24 白名单内。NFSv4 下也可用 showmount -e 192.168.0.13 验证。

8. 需要彻底回滚¶

python3 main.py --rollback
ssh root@<host> "ls -lt /etc/fstab.bak.* | head"

如需指定某个历史版本：cp -p /etc/fstab.bak.<时间戳> /etc/fstab。

9. 日志位置¶

运行日志：deploy/logs/eda-storage-standardize.log
排查时可加 --log-level DEBUG 获取堆栈信息。

10. 未纳入本次范围（后续）¶

配额（quotaon/repquota）
快照与备份生命周期
k8s StorageClass / PV 层统一挂载参数

11. 热插虚拟盘容量显示异常（193K 而非 50G）¶

现象：KVM host 附加 qcow2 后，节点内 lsblk 显示 /dev/vdb 只有 193K，但 qemu-img info 显示 virtual size 50G。根因：virsh attach-disk 未指定 --subdriver qcow2，libvirt 以 type='raw' 记录， QEMU 按 raw 读取 qcow2 文件，容量=文件实际大小。验证：

virsh dumpxml k8s-node-01 | grep -B 6 "target dev='vdb'"   # 查看 driver type 是否为 qcow2

修复（重新附加）：

virsh detach-disk k8s-node-01 vdb --persistent
virsh attach-disk k8s-node-01 /kvm/qcow2/k8s-node-01-scratch.qcow2 vdb \
  --targetbus virtio --subdriver qcow2 --persistent

预防：附加 qcow2 磁盘时始终显式带 --subdriver qcow2。

12. NFSv4 不支持 remount（an incorrect mount option was specified）¶

现象：mount -o remount,<任意选项> /home 报 mount.nfs4: an incorrect mount option was specified，即使只 remount 单个选项也如此。根因：本环境 nfs-utils/NFSv4 组合不支持 remount 修改挂载选项，必须 umount + mount 才能生效。处理：

# 脚本自动处理：remount 失败后，--force 模式下执行 umount + mount
python3 main.py --log-level INFO --force

注意：/opt/lsf（LSF 进程占用）、/mnt/nfs（k8s PV 子挂载占用）会 device is busy 无法卸载，需停对应服务或重启节点使 fstab 生效。fstab 已持久化正确，重启必然生效。

13. actimeo 在 /proc/mounts 中被展开（幂等误判）¶

现象：设置 actimeo=30 后，/proc/mounts 显示 acregmin=30,acregmax=30,acdirmax=30 而看不到 actimeo=30，导致幂等巡检永远判定"未达标"、每次执行都报变更。根因：内核把 actimeo=N 展开为三个具体项。处理：脚本已内置归一化（见 normalize_actual_options），把三兄弟还原为 actimeo=N 再比对。

14. umount 报 device is busy¶

现象：umount /opt/lsf 或 umount /mnt/nfs 报 device is busy。排查：

grep ' /mnt/nfs/' /proc/mounts   # 查看该挂载点下的子挂载
fuser -m /opt/lsf 2>/dev/null    # 查看占用进程

处理：停相关服务（LSF、kubelet）后再重挂；或直接重启节点（fstab 已正确，开机自动生效）。

15. 已写入错误 fstab 后的修复¶

若 fstab 中的源/参数写错（如 Lustre 源缺 /），脚本已支持比对源 + 选项，重新执行即会自动修正并备份旧 fstab。

16. FlexLM 重启失败：Failed to open the TCP port number¶

现象：systemctl restart flexlm 后 lmgrd 退出（status=35），日志出现 Failed to open the TCP port number in the license. 根因：FlexLM 的 vendor daemon（cdslmd/mgcld/agileesofd）也会绑定 lmgrd 的端口（如 27000）。若只 pkill lmgrd，vendor daemon 会变成孤儿进程继续占用端口，导致新 lmgrd 无法绑定。处理：彻底清理全部 flexlm 进程后再启动：

pkill -9 lmgrd; pkill -9 cdslmd; pkill -9 mgcld; pkill -9 agileesofd
systemctl start flexlm

已内置防护：脚本生成的 unit 含 ExecStopPost 自动清理，避免复现。

17. 权限巡检把软链接误判为"未达标"¶

现象：chmod 后仍有 find 报告文件/目录权限不符（如 .../jai、divaEXT.rul）。根因：Linux 软链接权限恒为 lrwxrwxrwx（777）且 chmod 无效，会被 -perm -0022 命中。处理：巡检 find 加 ! -type l 排除软链。排除后实测不符项为 0。

18. 改 LDAP homeDirectory 后客户端仍返回旧值（sssd 缓存）¶

现象：LDAP 里 homeDirectory 已改为 /home/lws01，但客户端 getent passwd lws01 仍显示旧路径，用户登录后 $HOME 未变。根因：客户端运行 sssd（systemd 服务，active），存在用户/组缓存。处理：对相关用户在每台客户端清缓存：

for u in lws01 rain01 ...; do sss_cache -u "$u"; done

脚本已在 LDAP 修改成功后自动对所有客户端执行清理。注意 nscd/nslcd 也需检查（本环境 nscd inactive、nslcd+sssd active）。

19. NFS Server / Lustre MDS 未接 LDAP 导致组名与身份解析失败¶

现象：chown root:teama /data/eda/projects/teama 在 NFS Server 上静默失败，目录属组仍是父目录继承的 eda_dev（ls 显示数字 gid，如 3001 3000）。根因：NFS Server(192.168.0.13) 未配置 LDAP 客户端，无法解析 LDAP 组名。 临时处理：用数字 GID 操作（chown 0:2000）；客户端因已接 LDAP，会正确显示组名。 ✅ 已彻底修复（2026-09-12）：在该机安装并启用 sssd（详见第 22 条），身份解析恢复正常，服务端 ls 亦能显示组名。

20. 删除旧 OU 被误跳过（子树内有空 posixGroup）¶

现象：迁移用户后执行 ldapdelete -r ou=dev,... 被判定"仍有子条目"而跳过，旧部门残留。根因：判定用了"子树总条目数 == 1（仅自身）"，但 OU 下还残留空的 posixGroup（cn），总条目数 = 1 + N ≠ 1。处理：改为判断"子树内是否还有 posixAccount（用户）"：

ldapsearch -b <ou_dn> "(objectClass=posixAccount)" dn | grep -c '^dn: '   # == 0 才删

空组会随 ldapdelete -r 级联删除，安全。

21. 改 LDAP 组后客户端组名不刷新¶

现象：改组后部分节点 getent group 2000 仍返回旧组名（如 teama），另一些已是 design。根因：sss_cache -u <user> 只清用户缓存，组缓存需单独清；且部分条目未被失效。处理：用彻底刷新：

sss_cache -E            # 失效所有缓存条目
systemctl restart sssd  # 或直接重启 sssd

22. Lustre MDS identity_upcall 失败导致普通用户无法创建目录（关键）¶

现象：/lustre/eda_fs/scratch/users 权限已是 1777、root 可创建，但普通用户 mkdir 报 Permission denied（多个客户端一致，可排除客户端缓存）。根因：MDS(192.168.0.13) 启用 mdt.*.identity_upcall=/usr/sbin/l_getidentity，但该机 sssd 未运行、且无 /etc/sssd/sssd.conf（nsswitch 却已配 files sss） → MDS 无法解析客户端 uid → upcall 失败 → MDS 拒绝请求（EACCES）。证据：

lctl get_param mdt.*.identity_upcall   # → /usr/sbin/l_getidentity
id lws01                               # → no such user
getent passwd 6001                     # → 无结果

处理（已实施）：

ssh root@192.168.0.13 "yum install -y sssd"
ssh root@192.168.0.5 "cat /etc/sssd/sssd.conf" | ssh root@192.168.0.13 "cat > /etc/sssd/sssd.conf && chmod 600 /etc/sssd/sssd.conf"
ssh root@192.168.0.13 "systemctl enable --now sssd"

验证：id lws01 → uid=6001(lws01) gid=6000(cad)；用户可正常创建 Lustre 目录。预防：MDS / NFS Server 必须与计算节点处于统一身份体系（LDAP/AD）——行业标准要求，否则分布式文件系统的 identity upcall 必然失败。这与第 19 条同根同源（同一台机器）。

23. /etc/exports.bak.* 备份污染（客户端节点被误备份）¶

现象：k8s-master-01 等非 NFS Server 节点上出现大量 /etc/exports.bak.*，而这些机器 /etc/exports 是 0 字节、nfs-server 未运行 —— 看起来像"NFS Server 痕迹"。根因：service_deployer.py 的 backup() 对所有涉及变更的主机无条件备份 /etc/fstab 和 /etc/exports（rollback() 同样），未区分节点角色；且未判断文件是否为空 → 8 台客户端节点堆积了 35 个空备份。证据： - 9 台节点中仅 .13 的 exports 非空，却每台都有 exports 备份 - 计算节点 .5/.6/.7 备份时间（142237/142402/142755）与 .2（142231/142356/142749）几乎同秒 → 同一批脚本产生 - /etc/exports 的 mtime 停在 8/2 23:23（NFS 迁移时被清空）后未再变，故 9/11、9/12 的备份全是 0 字节 修复： 1. 代码：新增 _FILE_CHANGE_CATEGORIES 映射（/etc/fstab ← 客户端类变更； /etc/exports ← 仅 tier1_export），backup()/rollback() 据此精确筛选主机；并增加空文件跳过（[ -s ] 判断），不再产生无效备份 2. 清理：cleanup/cleanup_exports_backup.sh（自动跳过 NFS Server、路径白名单校验、非空备份先归档）—— 已清理 8 台客户端共 35 个文件，.13 的 17 个备份保留；唯一非空备份（/opt/lsf *(rw,sync,no_root_squash)，8/2 迁移前配置）已归档至 cleanup/exports_backup_archive.log 预防：备份/回滚必须按文件类型精确确定目标主机，禁止"某主机有变更就备份它的全部配置文件"。

24. 家目录迁移后旧会话重建残留目录（迁移项反复出现）¶

现象：家目录迁移完成后，main.py --dry-run 反复报告 tier1_move: /data/slurm/users/rain01 -> /home/rain01（源与目标同时存在）。根因：IDE(192.168.0.9) 上存在一套 9/11 15:04 启动的 VNC + GNOME 会话（用户 rain01），其 $HOME 为迁移前的旧路径 /mnt/nfs/slurm/users/rain01。我们在 15:05 迁移家目录后， 这些进程并未退出（cwd 显示为 .../rain01 (deleted)），GNOME 组件（gnome-software / dconf / flatpak）在 9/12 06:00 按旧 $HOME 重建了 .config/.cache/.local。风险：原逻辑在"源与目标同时存在"时仍生成迁移变更，且 mv 未加 -T，会把源嵌套进已存在的目标内部（/home/rain01/rain01/）。证据： - ps -u rain01 → Xvnc / gnome-shell / gnome-software 等，cwd=.../rain01 (deleted)，启动于 9/11 15:04 - tr '\0' '\n' < /proc/<pid>/environ → HOME=/mnt/nfs/slurm/users/rain01 处理： 1. 脚本加固：四处 src_exists and dst_exists 分支改为"告警 + 跳过（转人工确认）"，不再生成 mv；执行处 mv 改为 mv -T（目标已存在即报错，绝不嵌套） 2. 清理残留：rm -rf /data/slurm/users/rain01（内容仅 GNOME 运行时目录，无用户数据） 3. 刷新缓存：6 个 LDAP 客户端执行 sss_cache -E 遗留：IDE 上那套旧 GNOME 会话仍在运行，需用户注销 VNC 后重新登录（新会话才会使用 /home/rain01），否则仍会按旧 $HOME 写入。预防：迁移用户家目录前应确认该用户无活跃会话（ps -u <user>），或迁移后强制重新登录。

来源：/home/rain/Documents/slurm/eda_storage_standardization/deploy/docs/troubleshoot.md ｜最后更新：2026-09-12 13:35（由 build/sync.py 同步，请勿在站点侧修改）

EDA 存储标准化 故障排查手册（troubleshoot）¶