SOP — 共享库 `base_module` 新增只读探测缓存（三件套之③）¶

主题目录：py_public_modules_changes/probe_cache_20261008/｜执行日期：2026-10-08｜类型：C 类（改共享库）触发：把「只读探测批量化」推广到 harbor / lustre_ins / eda_tools_ins 时发现，三件套的 ①（拼 shell）②（主机间并发）共享库已有，③ 进程内 (host,命令) 缓存没有 （precheck_module 有 _probe_cache，但只覆盖它自己的 check_*；base_module 完全没有）

1. 背景¶

8 个工程挂载共享库 /home/rain/py_public_modules（.pth），其中多个继承 base_module.BaseModule；
缺缓存 → 同一事实被 pre_check / sync_status / execute / validate 各查一遍，重复往返；
本次为纯新增能力，不改变任何既有方法语义（见第 4 章）。

2. 目标¶

#	目标	判据
1	新增 `query_on_host(host, cmd)`：命中 `(host,命令原文)` 缓存则不下发	离线自测：第二次调用零下发
2	新增 `probe_per_host(hosts, probes)`：每台一条 shell 取回并回填缓存	离线自测：每台 1 条；回填后 `query_on_host` 命中
3	变更后自动失效，避免读到陈旧值	`run_on_host`（默认）/ `apply_change` 执行后清空；`dry-run` 不清
4	向后兼容	`run_on_host` 旧位置参数形态不变；可 `BASE_MODULE_PROBE_CACHE=0` 关闭

3. 前置条件¶

共享库根 /home/rain/py_public_modules（非 git 仓库，故以文件备份留档）；
任一挂载了共享库的解释器（本次用 slurm_ins/.venv/bin/python）；
变更前完成 5.1 备份。

4. 影响范围¶

项	内容
变更对象	`base_module.py`（单文件）
改动性质	纯新增 3 个方法 + `__init__` 2 个字段；`run_on_host` 增一个默认 True 的参数；`apply_change` 末尾加一次清空
受影响方	8 个挂载工程的 `BaseModule` 子类（默认行为不变：不用 `query_on_host` 的代码完全无感）
是否停服	否
回滚风险	低：单文件可整体还原

5. 分步操作¶

5.1 备份¶

TOP=/home/rain/Documents/py_public_modules_changes/probe_cache_20261008
mkdir -p "$TOP/backup"
cp -a /home/rain/py_public_modules/base_module.py "$TOP/backup/base_module.py.bak.$(date +%Y%m%d-%H%M%S)"
chmod 600 "$TOP"/backup/base_module.py.bak.*

5.2 改动点（实现体源码改动，非手工命令）¶

# __init__：
#   self._probe_cache: Dict[Tuple[str, str], str] = {}        # 键 (host, 命令原文) → stdout(strip)
#   self._probe_cache_enabled = os.environ.get("BASE_MODULE_PROBE_CACHE", "1") != "0"
# run_on_host(host, cmd, timeout=300, retry=3, invalidate_cache=True)
#   命令下发后：if invalidate_cache: self.invalidate_probe_cache()
# invalidate_probe_cache()           # 公开，供手工/变更后调用
# query_on_host(host, cmd) -> str    # 只读；命中即返回；未命中走 run_on_host(..., invalidate_cache=False) 并写缓存
# probe_per_host(hosts, probes)      # 每台 run_on_host(_kv_script(probes), invalidate_cache=False)
#                                    # → _parse_kv → 回填 self._probe_cache[(host, cmd)]
# apply_change(...)：action() 之后 invalidate_probe_cache()

关键约束：缓存键是 (host, 命令原文)，故 probe_per_host 里的命令文本必须与后续 query_on_host 的文本逐字相同，否则不命中（退化为逐条，不影响正确性）。

为什么 run_on_host 默认清缓存：命令一旦下发就可能改变远端状态；默认清空可避免后续读到旧值。代价是「仍用 run_on_host 做只读」的老代码享受不到缓存 —— 这是有意的：想让缓存生效就必须显式改用 query_on_host / probe_per_host，语义边界清晰。

5.3 离线自测¶

cd /home/rain/Documents/py_public_modules_changes/probe_cache_20261008
python3 -m py_compile /home/rain/py_public_modules/base_module.py && echo COMPILE_OK
/home/rain/Documents/slurm/slurm_ins/.venv/bin/python selftest.py   # → BASE_MODULE_PROBE_CACHE_SELFTEST_OK

5.4 挂载工程 import 冒烟¶

for p in /home/rain/Documents/slurm/slurm_ins/.venv/bin/python \
         /home/rain/Documents/services/harbor/.venv/bin/python \
         /home/rain/Documents/kvm/kvm_deploy/.venv/bin/python; do
  "$p" -c "import base_module,paramiko_module,precheck_module,ssh_executor; print('OK', base_module.__file__)"
done

6. 验证¶

验证一：离线自测【已确认】BASE_MODULE_PROBE_CACHE_SELFTEST_OK（13 项，桩 connection_pool，不连主机）：

用例	结果
`query_on_host` 命中不再下发 / 不同主机不串	OK
`run_on_host` 默认清缓存；`invalidate_cache=False` 不清	OK
`probe_per_host` 每台 1 条 + 回填 → `query_on_host` 全部命中	OK
`apply_change` 后失效；`dry-run` 的 `apply_change` 不清	OK
缓存关闭（属性 / 环境变量）	OK
`run_on_host` 旧调用形态仍可用	OK

验证二：挂载工程冒烟【已确认】3 个不同 venv 解释器 import base_module 均解析到 /home/rain/py_public_modules/base_module.py（说明 .pth 生效、无遮蔽）。

验证三：下游工程上机对照【已确认】harbor / lustre_ins / eda_tools_ins 各自以此能力改造后 --dry-run / precheck 新旧对照，命令数与墙钟下降、变更清单逐条一致（见各自主题 SOP）。

失败判断：自测或冒烟失败 → 按第 7 章整体还原。

7. 回滚¶

cp -a /home/rain/Documents/py_public_modules_changes/probe_cache_20261008/backup/base_module.py.bak.* \
      /home/rain/py_public_modules/base_module.py

回滚后验证：py_compile + 复跑 5.4 冒烟。

8. 风险说明¶

风险	缓解
共享库改动波及 8 个工程	纯新增 + 默认参数；不用新 API 的代码零影响；回滚为单文件还原
老代码用 `run_on_host` 做只读 → 缓存被频繁清空	不影响正确性，仅少收益；会促使迁移到 `query_on_host`
变更后未清缓存 → 读到旧值	`run_on_host` / `apply_change` 自动清；`invalidate_probe_cache()` 可手工补
命令文本漂移 → 预取白做	约束写入 docstring；下游各自 selftest 断言文本一致
无 git 无法 `git diff` 追溯	备份留档 + 本 SOP 记录改动点

附录 A 交付物清单¶

文件	说明
`SOP.md`	本文件
`selftest.py`	离线自测（13 项）
`backup/base_module.py.bak.YYYYmmdd-HHMMSS`	改造前快照（`chmod 600`）
变更的共享库文件	`/home/rain/py_public_modules/base_module.py`

附录 B RUNBOOK 判定¶

共享库是库、非服务，无独立 RUNBOOK；其使用方式（query_on_host / probe_per_host / invalidate_probe_cache 的语义与约束）已由 docstring 与 deployment-tool-engineering 技能承载。不新增 RUNBOOK。

来源：/home/rain/Documents/py_public_modules_changes/probe_cache_20261008/SOP.md ｜最后更新：2026-10-08 11:45（由 build/sync.py 同步，请勿在站点侧修改）

SOP — 共享库 base_module 新增只读探测缓存（三件套之③）¶