SOP — 共享库同名副本去遮蔽（paramiko / logger / config 三份一并收）¶
主题目录：
slurm_ins/paramiko_unify_20261007/｜执行日期：2026-10-07｜类型：C 类（改实现体 + 删副本） 触发：收 slurm_ins 最后一项欠账paramiko_module双份并存 → 发现它单独收不掉（见第 1 章）
1. 背景¶
slurm_ins/utils/ 下有三份与共享库同名的副本，deployer.py 等用相对导入取本地副本，
使 .pth 挂载的共享库形同虚设（技能明确：「挂了 .pth ≠ 用了共享库」）：
| 本地副本 | 行数 | 与共享库差异（忽略空白） | 结论 |
|---|---|---|---|
utils/paramiko_module.py |
855 | 203 行（含 _connect_count、acquire_host_lock；缺 keepalive / batch_logger） |
共享库是超集，只多两项能力 |
utils/logger_module.py |
309 | 16 行（仅文档串与单例位置） | 功能等价 |
utils/config_module.py |
148 | 24 行（仅文档串 + 导入写法） | 功能等价 |
关键坑（本次实测）：只把 paramiko_module 指向共享库、却留着 logger_module 副本 →
共享 paramiko 里 from logger_module import log_manager 取的是共享的 logger_module，
而 deployer.py 仍取本地的 → 两个 log_manager 实例分家：
deployer 配置的 handler 挂不到 paramiko 的 logger 上，
实测远端命令日志整段消失（paramiko 日志行 194 → 0，而变更记录数不变——静默丢审计线索）。
故三份必须一起去遮蔽。
2. 目标¶
| # | 目标 | 判据 |
|---|---|---|
| 1 | 把 _connect_count（建连计数/自报）与 acquire_host_lock() 上移共享库 |
离线自测通过；上机日志出现「本任务共新建连接 N 次」 |
| 2 | 三份副本全部删除，全部改走共享库 | 官方遮蔽检测 0 处同名副本 / 0 处版本落后 |
| 3 | 判定与日志行为不变 | 主流程记录 225/25/200、命令数 87、paramiko 日志行 194 全部复位 |
| 4 | 顺带获得「建连数自报」能力（此前 slurm 有、其它工程无） | 8 个挂载工程共享该能力 |
3. 前置条件¶
- 工程根
/home/rain/Documents/slurm/slurm_ins，.venv可用且.pth指向/home/rain/py_public_modules； - 共享库
/home/rain/py_public_modules/paramiko_module.py可写（影响 8 个挂载工程）； - 变更前完成 5.1 备份；上机验证用
--dry-run（只读）。
4. 影响范围¶
| 项 | 内容 |
|---|---|
| 变更对象 | 共享库 1 文件（paramiko_module.py，纯新增 3 处）；slurm_ins 12 文件（9 处导入改写 + deployer.py/utils/file_utils.py/utils/idempotent_utils.py）+ 删除 3 个副本 |
| 影响面 | 共享库改动对其余 7 个挂载工程纯新增、向后兼容；删除副本只影响本工程 |
| 是否停服 | 否 |
| 风险等级 | 中：删副本 = 改导入解析路径，必须上机验证 |
5. 分步操作¶
5.1 备份（高危前置）¶
TOP=/home/rain/Documents/slurm/slurm_ins/paramiko_unify_20261007
STAMP=$(date +%Y%m%d-%H%M%S); cd /home/rain/Documents/slurm/slurm_ins
mkdir -p "$TOP/backup/slurm_ins/utils" "$TOP/backup/py_public_modules"
cp -a /home/rain/py_public_modules/paramiko_module.py "$TOP/backup/py_public_modules/paramiko_module.py.bak.$STAMP"
for f in deployer.py slurm_deployer.py user_mgmt_deployer.py scratch_gc_deployer.py \
storage_layout_deployer.py local_scratch_deployer.py node_env_deployer.py \
module_env_deployer.py health_ensure_deployer.py conn_reuse_20261007/selftest.py \
utils/paramiko_module.py utils/logger_module.py utils/config_module.py \
utils/file_utils.py utils/idempotent_utils.py; do
mkdir -p "$TOP/backup/slurm_ins/$(dirname $f)"; cp -a "$f" "$TOP/backup/slurm_ins/$f.bak.$STAMP"; done
预期：15 份快照（STAMP = 20261007-220238）。
5.2 两项能力上移共享库（py_public_modules/paramiko_module.py）¶
# 概念等价（Python 侧）
# __init__: self._host_locks = {host: threading.RLock()} # 可重入
# self._connect_count: int = 0
# acquire_host_lock(): 返回该主机的 RLock（不存在则创建）
# get_connection(): host_lock = self.acquire_host_lock(host) # 取代内联 Lock
# 新建连接成功处 self._connect_count += 1
# shutdown(): 「SSH连接池已关闭 | 本任务共新建连接 N 次 | 结束时保有 M 条」
坑（必须留痕）：
- 锁必须 RLock：调用方「先持锁、再 get_connection」时普通 Lock 会自锁死；
- _connect_count 只是诊断计数，不参与任何判定；
- 共享库改动对其余挂载工程是纯新增，但按共享库规则仍须确认向后兼容（本次：新增属性/方法 + 文案，无签名变更）。
5.3 删除三份副本 + 改写导入（slurm_ins）¶
# 导入改写（9 处 paramiko）
# from .utils.paramiko_module import X → from paramiko_module import X
# deployer.py 另有两行：
# from .utils.logger_module import log_manager → from logger_module import log_manager
# from .utils.config_module import ConfigLoader → from config_module import ConfigLoader
# utils/file_utils.py、utils/idempotent_utils.py 内的相对导入同样改写
# 删除：utils/paramiko_module.py、utils/logger_module.py、utils/config_module.py
坑：只改 paramiko 不改 logger/config 会静默丢日志（见第 1 章），三份必须一起。
5.4 离线自测（上机前）¶
cd /home/rain/Documents/slurm/slurm_ins
.venv/bin/python -m py_compile deployer.py slurm_deployer.py utils/file_utils.py utils/idempotent_utils.py \
/home/rain/py_public_modules/paramiko_module.py && echo COMPILE_OK
.venv/bin/python paramiko_unify_20261007/selftest.py # 计数 / RLock 可重入 / shutdown 自报
.venv/bin/python conn_reuse_20261007/selftest.py # 连接池复用语义（4 项）
预期：COMPILE_OK + PARAMIKO_UNIFY_SELFTEST_OK + CONN_REUSE_SELFTEST_OK。
5.5 官方遮蔽检测 + 上机验证¶
cd /home/rain/Documents/slurm/slurm_ins
.venv/bin/python /home/rain/.trae-cn/skills/deployment-tool-engineering/references/scripts/shared_lib_divergence_check.py --root "$PWD"
.venv/bin/python main.py --config config/slurm_deploy.yaml --dry-run | grep -E '变更记录总数|待执行|幂等|SSH连接池已关闭'
6. 验证¶
验证一：官方遮蔽检测【已确认】
发现工程内同名副本 0 处
需处理（版本落后）: 0 处
（改前为 3 处副本；这是技能「交付前自检」的阻断项判据，现已通过。）
验证二：离线自测 —— PARAMIKO_UNIFY_SELFTEST_OK（12 项：计数自增/复用不增/RLock 可重入/
持锁期间 get_connection 不死锁/shutdown 自报/共享库含 keepalive 与 batch_logger/副本已删）
+ CONN_REUSE_SELFTEST_OK（复用、失活重建、活跃数）。
验证三：上机行为不变【已确认】
| 项 | 改前 | 改后 |
|---|---|---|
主流程 --dry-run 记录 |
225 / 待执行 25 / 幂等 200 | 225 / 25 / 200 |
| 主流程命令数 / 墙钟 | 87 条 / 11.4 s | 87 条 / 12.2 s |
paramiko 日志行数 |
194 | 194（中间态曾静默为 0，见第 1 章） |
--submit-node |
26 条 / 12.3 s / 31·0·31 | 26 条 / 10.6 s / 31·0·31 |
验证四：新增能力生效 —— 主流程日志末尾出现
SSH连接池已关闭 | 本任务共新建连接 6 次 | 结束时保有 6 条（6 台主机 → 每台恰好 1 次建连）
——这正是此前多轮反复提到「缺建连数自报」的那项，现已具备，且全部 8 个挂载工程共享。
失败判断：遮蔽检测 >0；记录/命令数变化；paramiko 日志行显著减少；任一自测失败 → 按第 7 章回滚。
7. 回滚¶
- 备份位置：
paramiko_unify_20261007/backup/（15 份），台账见同目录backup/README.md。 - 回滚步骤：还原 12 个文件 + 3 个被删副本 + 共享库；注意备份里含被删副本的原文：
cd /home/rain/Documents/slurm/slurm_ins
BAK=paramiko_unify_20261007/backup/slurm_ins
for f in deployer.py slurm_deployer.py user_mgmt_deployer.py scratch_gc_deployer.py \
storage_layout_deployer.py local_scratch_deployer.py node_env_deployer.py \
module_env_deployer.py health_ensure_deployer.py conn_reuse_20261007/selftest.py \
utils/paramiko_module.py utils/logger_module.py utils/config_module.py \
utils/file_utils.py utils/idempotent_utils.py; do cp -a "$BAK/$f".bak.* "$f"; done
cp -a paramiko_unify_20261007/backup/py_public_modules/paramiko_module.py.bak.* /home/rain/py_public_modules/paramiko_module.py
- 回滚后验证：遮蔽检测回到 3 处副本；主流程记录 225/25/200。
- 回滚触发条件：任一验证项不达标；出现导入错误；日志格式异常。
8. 风险说明¶
| 风险 | 缓解 |
|---|---|
| 只收 paramiko 会静默丢日志（两个 log_manager 分家） | 三份副本一起收；上机以「paramiko 日志行数复位」为验收项 |
| 共享库改动波及 7 个其它工程 | 纯新增（属性/方法/文案），无签名变更；shutdown 文案从「已关闭」变为带计数——若某工程解析该文案需注意（已 grep 各工程无解析） |
| 删除副本导致相对导入解析失败 | 删除前 grep 全部引用点并改写；py_compile + 上机 --dry-run 双验证 |
utils/ 下另有同名工具被误删 |
只删与共享库同名的三个；file_utils.py / idempotent_utils.py 是工程私有，保留 |
附录 A 交付物清单¶
| 文件 | 说明 |
|---|---|
SOP.md |
本文件 |
selftest.py |
离线自测（计数 / RLock 可重入 / shutdown 自报 / 副本已删） |
backup/py_public_modules/ |
共享库改前快照 |
backup/slurm_ins/ |
15 份工程侧改前快照（含被删三副本） |
backup/README.md |
备份台账 |
| 变更的实现体 | 共享库 paramiko_module.py；slurm_ins 12 文件导入改写；删 3 副本 |
附录 B 遗留¶
| 项 | 说明 |
|---|---|
slurm_ins/utils/paramiko_module.py 的「两份模块内容拼接」结构 |
副本已删除，该历史痕迹随之消失（共享库是拍平版） |
| 其它挂载工程是否仍有同名副本 | 【2026-10-11 结案】 已对 lsf_ins / lustre_ins / k8s_ins / eda_tools_ins / harbor 各跑官方遮蔽检测：0 处版本落后；eda_tools_ins 有 1 处同名副本但已对齐（且在弃用工程 ic25_install 内） |
来源：
/home/rain/Documents/slurm/slurm_ins/paramiko_unify_20261007/SOP.md｜ 最后更新：2026-10-11 21:15（由build/sync.py同步，请勿在站点侧修改）