RUNBOOK：remote_exec 远端只读执行入口

交付物：~/py_public_modules/remote_exec.py（共享库单文件工具）

1. 服务概览

• 干什么用的：Agent（或人）需要在多台远端主机上做只读取数时，用它代替逐条 ssh。它在一个进程内复用 SSH 连接、主机间并发、每台主机把多项探测拼成一段 shell 一次往返取回。
• 组件构成：单文件脚本，依赖共享库 paramiko_module（连接池）与 base_module（并发 + 拼接）。
• 依赖谁：任一挂了共享库的 Python 环境里有 paramiko。脚本自带兜底探测，找不到时从其它 venv 的 site-packages 补路径。
• 异常时的业务影响：无。它是取数工具，不改变任何远端状态；失败最多是这次取数没拿到，不影响远端服务。
• 重要性等级：低（工具类，非服务）。

2. 接入与凭据

• 目标：任意 SSH 可达主机（本环境为 Slurm/LSF 相关节点）。
• 账号：默认 root；密码留空表示用本机密钥认证（~/.ssh/id_*）。
• 凭据取用：不落盘、不写入文档。需要非 root 或密码时用 --user / --password 传入。

3. 日常速查表

场景	命令
多台跑同一条只读命令	python3 ~/py_public_modules/remote_exec.py --hosts 192.168.31.16,192.168.31.17 --cmd hostname
每台一次往返取多项	python3 ~/py_public_modules/remote_exec.py --hosts a,b --probe host=hostname --probe kern='uname -r'
JSON 输出（给程序用）	上面任一命令加 --json
提高并发	加 --max-workers 16
脚本内复用	from remote_exec import run_probe

4. 日常操作

• 查状态（确认工具自身可用）： bash python3 ~/py_public_modules/remote_exec.py --hosts 192.168.31.16 --cmd hostname 预期：== 192.168.31.16 == 与 cmd=<主机名>，退出码 0。
• 只读多项取回（推荐，省往返也省上下文）： bash python3 ~/py_public_modules/remote_exec.py --hosts 192.168.31.16 \ --probe host=hostname --probe kern='uname -r' --probe disk='df -h / | tail -n1'
• JSON 输出：加 --json，stdout 为纯 JSON（日志走 stderr），可直接喂给下游解析。
• 脚本内调用：from remote_exec import run_probe 后 run_probe(hosts, {"host": "hostname"})，同一进程内多次调用共享连接池。

5. 配置管理

无配置文件。行为参数全部走命令行：--hosts、--cmd、--probe（可多次）、--user、--password、--max-workers、--json。

6. 备份与恢复

工具无状态（不写任何持久化数据），无需备份。文件本身在共享库目录，回滚即删除该文件（见 remote-exec-20261011/backup/README.md）。

7. 监控与告警

无独立监控。诊断信息两处：

• 退出码：0 = 全部主机成功；1 = 有主机无输出 / 连接失败；2 = 参数错误。
• 连接计数：脚本结尾调用 connection_pool.shutdown() 会打一行「本任务共新建连接 N 次」，可据此确认「每台只建连一次」。

8. 故障处置

场景一：报 No module named 'paramiko'

症状：直接运行时栈回溯指向 import paramiko。 诊断：python3 -c "import paramiko" 失败。 处置：改用挂了共享库的 venv 解释器，如

~/Documents/slurm/slurm_ins/.venv/bin/python ~/py_public_modules/remote_exec.py --hosts 192.168.31.16 --cmd hostname

验证：输出 == 192.168.31.16 ==，退出码 0。

场景二：某台「无输出/连接失败」

症状：该主机段落为 (无输出/连接失败)，退出码 1。 诊断：stderr 会给出具体原因（连接被拒 / 超时 / 认证失败）。 处置：确认该主机 SSH 可达、密钥已授权；确认目标端口从本机可达。 验证：单独对该台重跑，退出码回到 0。

场景三：并发过高导致连接被拒

症状：多台同时报连接拒绝。 诊断：目标 sshd 的 MaxStartups 被触顶，这是正确性约束，不是变慢。 处置：降低 --max-workers（如 4）后重跑。 验证：全部主机返回结果，退出码 0。

9. 安全与权限

• 默认走密钥认证，不落任何密码；需要密码时由 --password 传入，不写入文件。
• 仅执行只读命令。写操作（安装、改配置、重启服务）不得使用本工具：其底层并发执行对写操作不安全，且写操作须逐条、原子、可回滚地走部署器工程。

10. 容量与性能

• 并发度受目标端 sshd MaxStartups 约束，默认 8 已满足常规批量巡检。
• 性能参照：6 台同批探测，逐条 ssh 5.472 s / 6 轮；本工具 0.927 s / 1 轮。
• 已知瓶颈：单台主机内部仍串行（同一连接不宜并发复用），多探测靠「拼成一段 shell」省往返。

11. 附录

• 交付目录：Documents/services/token_proxy/remote-exec-20261011/（本 RUNBOOK、SOP.md、verify_guard_yz.py、backup/）
• 相关规则：~/.trae-cn/user_rules/rule-ops-evidence-constraints.md「交付物位置」节的跨项目口径
• 相关 skill：ops-execution-efficiency §2「往返与连接」
• 相关 Hook：merge-guard 判据 Y（跨项目写盘提醒）、判据 Z（ssh 直连入口提醒）
• 修订记录：2026-10-11 首版

---

来源：/home/rain/Documents/services/token_proxy/remote-exec-20261011/RUNBOOK.md ｜ 最后更新：2026-10-11 22:19（由 build/sync.py 同步，请勿在站点侧修改）