7 项缺陷本地修复 — 变更 SOP（2026-10-09）

规划产物：.trae/specs/lustre_ins_7fix/{spec.md,tasks.md}（spec-planner 子智能体产出， 作为过程件，不是结案凭据；结案凭据即本文件与 HANDOFF）。

1. 范围与结论

项	结论
#18 client_mount 两处缺陷	已修复（挂载改 systemd mount unit；fstab 改「同挂载点替换」）
#12 fstab_persist 幂等日志瑕疵	已修复（先查现状，exists 走幂等跳过，动作词按实际结果）
#5 幂等探测 unknown 未三态化	已修复（新增三态函数；UNKNOWN 禁止进入 mkfs）
#11 dry-run 下 get_param 无输出误判失败	已修复（降级 WARN，不记失败）
#10 ssh_user 幽灵配置 + lctl dl 固定字段解析	已修复（凭据按节点下发；NID 改正则解析）
#4 RUNBOOK 容量水位基线占位	已修复（填 .21 实测值 + 取数日期 + 原始输出留存）
#1 调优 unit 按角色拆分	代码侧已完成；远端部署 + 重启验证待放行（见 §5）

未纳入：#3、#15（用户尚未裁定是否属本工程范围）。

2. 变更清单

文件	改动摘要
utils/file_utils.py	新增 merge_fstab_entry()（纯函数，exists/replaced/added）、fstab_entry_state()；append_to_fstab() 改为「读全文 → 合并 → 备份 → 一次写回」，返回实际动作
modules/client_mount.py	新增 _mount_unit_name()（systemd-escape -p 推导，带缓存）；execute() 顺序改为 mkdir → fstab → daemon-reload → systemctl start <unit>；删除 mount -t lustre
modules/fstab_persist.py	execute() 先查 fstab_entry_state：exists → idempotent_skipped 不进变更入口；动作词按 替换/追加 实际区分
utils/idempotent_utils.py	新增 lustre_target_formatted_state()（DONE/PENDING/UNKNOWN，SSH 层失败 → UNKNOWN）；is_lustre_target_formatted() 降为 == DONE 兼容包装
modules/target_format.py	pre_check() / execute() 改用三态；UNKNOWN → BLOCK / 拒绝格式化并跳过
modules/lctl_tuning.py	① _apply_params 不可读参数降 WARN、不记失败；② 常量新增 server/client 单元路径；_merge_params / _server_params_for_host / _client_params_for_host 拆参；单元生成按 kind 产出 Before= / After=…server / RequiresMountsFor=；新增 _write_one_unit、_remove_legacy_unit；execute() 改调新 _write_unit
deployer.py	_do_initialize() 从 nodes.{mgs_mds,oss,clients} 收集 ssh_user（缺省 root）构造 credential_map 传入 setup_credentials
utils/lustre_state.py	新增 _extract_nid() + _NID_RE；get_online_targets() 的 host 改全行 NID 正则（不再用 parts[4]）
docs/RUNBOOK.md	第 10 章水位基线表填实测值 + 取数日期 + 原始输出留存路径

3. 验证证据（本机判据，两遍同结果）

判据	命令要点	结果
TR-1.1 fstab 替换（坏样本：同挂载点旧行）	.venv/bin/python 内联：merge_fstab_entry(old,new) 断言 replaced、新行 1 条、旧串消失、二次调用 exists	ALL PASS
TR-1.2 / TR-2.3 / TR-4.2 / TR-5.3 / TR-6.2 / TR-7.3 / TR-8.3	python -m py_compile <file>	COMPILE_OK
TR-2.1 挂载顺序（fake SSH 记录命令序列）	断言 systemctl start mnt-lustre.mount 存在、fstab 写入 < daemon-reload < start、全序列无 mount -t lustre	ALL PASS
TR-2.2 静态检查	grep -n "mount -t lustre" modules/client_mount.py	0 命中
TR-3.1 幂等与动作词（正反例）	exists → 变更入口 0 次；absent → 描述含「追加」；same_mp_different → 含「替换」	ALL PASS
TR-4.1 三态 + UNKNOWN 闭合	DONE/PENDING/UNKNOWN 三态断言；UNKNOWN 下 execute() 命令中 mkfs 计数 = 0、pre_check() 返回 False；DONE 下 pre_check() 返回 True	ALL PASS
TR-5.1 不可读降级	_apply_params 在 get_param 空串时 _failures == []	ALL PASS
TR-6.1 凭据下发	credential_map 中 h1=deploy（同主机多配置取首个）、h2=root、default 仍 root	ALL PASS
TR-7.2 真实样本解析	对 reports/lctl-dl-22-20261009.txt 解析，mgc 行 host = MGC192.168.31.21@tcp；移位合成行解析正确；无 NID 行 host = "" 不抛异常	ALL PASS
TR-8.1 单元内容（坏样本：mdc 出现在 server / OSS 含 mdt）	.21：server 含 mdt.*.max_mod_rpcs_in_flight=32 + Before=mnt-lustre.mount、不含 mdc.；client 含 mdc.*=31 + RequiresMountsFor=/mnt/lustre + After=mnt-lustre.mount lustre-tune-server.service、不含 mdt.*；.22 纯 OSS 只出 server 且两者都不含	ALL PASS
TR-11.1 全量语法	python -m py_compile deployer.py main.py utils/*.py modules/*.py	COMPILE_OK

过程中我方判据曾写错两处表现层预期（mount_point_for_target 对它返回 /mnt/ost0；lctl dl 除 mgc 行本无 NID）， 均为断言写错而非代码错，修正断言后通过——如实登记。 修复过程中发现并修正 1 处真实缺陷：_mount_unit_name 首版多加了 mnt- 前缀（产出 mnt-mnt-lustre.mount）， 由 TR-8.1 拦住。

4. 备份与回滚

• 本地代码备份：backup/7fix-code-20261009-051355/（cp -a --parents，含 utils/ modules/ deployer.py docs/RUNBOOK.md config/*.yaml*）。
• 回滚通式：cp -a backup/7fix-code-20261009-051355/<relpath> <relpath>。
• 远程 /etc/fstab：写入前自动 cp /etc/fstab.bak.<ts>，回滚 cp -f /etc/fstab.bak.<ts> /etc/fstab && systemctl daemon-reload。
• 远程调优单元：写入前自动备份到 /var/backups/lustre-ins/etc/systemd/system/…。

5. 遗留（需用户裁决）

1. #1 远端部署（对应 tasks.md T9）：需放行变更窗口。前置：确认 .21/.22 无在跑 Slurm/LSF 作业；执行顺序先 .22 后 .21；旧单单元备份后停用。
2. 可选重启验证（mdc.* 重启后自动达标）为根治唯一硬证据，影响生产，请单独批准。
3. #3 / #15 是否属本工程范围，未裁定。
4. 子智能体与内置模型调用不走本机 proxy → 本轮部分消耗不在收尾五项表口径内（HANDOFF §3.3「成本口径缺口」）。

---

来源：/home/rain/Documents/lustre_ins/7fix-20261009/SOP.md ｜ 最后更新：2026-10-09 05:24（由 build/sync.py 同步，请勿在站点侧修改）