SOP：优化点总账挂账项落地（k8s_ins 侧，#8 / #1，2026-10-02）¶
本主题为 k8s_ins 侧变更；token_proxy 侧的 backup 清理与 #9/#19 见
~/Documents/services/token_proxy/backlog-20261002/SOP.md。 交付物目录：optimization-backlog-20261002/（本文件、backup/）。
1. 背景¶
「优化点总账」~/.trae-cn/skills/ops-execution-efficiency/references/optimization-backlog.md
的挂账项多源自本工程的任务样本，本轮按用户选定落地两项：
- #8（出处
measured-baselines.md§17 要点 2）：定位"14 台主机怎么取数"曾白花 4 步， 根因是"集群外主机只读取数"的入口命令未落在路由表 / 速查里，只能靠逐个 Grep 源码反推。 - #1（出处 §21 要点 5）：同一主题三次
deploy各带一遍完整 K8s 段（约 1 分钟 + 4~5 步）， 而三次都只为验主机侧——属当前纯无效成本，需一个"只跑主机侧"的开关。
2. 目标（可验证）¶
docs/BASELINE.md第 4 节命令速查、docs/PROJECT-MAP.md第 1 节路由表各出现 「集群外主机只读取数」的入口（utils.cmd.SSHRunner）。env-monitor-deploy的deploy（及verify/drift/rollback）支持--hosts-only： 保留全部主机、仅跳过集群侧接入段；--limit语义不变（筛主机 且 跳过集群侧）。- 总账中 #8/#1 由「挂账」移入「已做」。
3. 前置条件¶
- 权限：本机
rain，可写/home/rain/Documents/k8s_ins/。 - 工具：
env-monitor-deploy/.venv/bin/python。 - 执行前检查：
main.py/deployer.py可py_compile；本步不触碰任何目标主机。
4. 影响范围¶
| 项 | 内容 |
|---|---|
| 主机 | 仅本机编辑文件；未连接任何目标机 |
| 组件 | env-monitor-deploy 命令层（main.py、deployer.py）与 docs/ 两份档案 |
| 是否停服 | 不需要；采集与监控链路不受影响 |
| 窗口 | 无限制 |
| 生效范围 | --hosts-only 为新增开关，缺省行为与改动前完全一致（向后兼容） |
5. 分步操作¶
步骤 1：补「集群外主机只读取数」入口（#8）¶
做什么/为什么：让"要取 14 台集群外主机的数"这类任务一眼看到入口，不必再反推。
实测入口是 monitoring-p2-20261001/utils/cmd.py 的 SSHRunner（基于共享库 paramiko_module
连接池，凭据由共享库处理，无需接触 secrets）——这正是此前白花 4 步才查到的事实。
坑：env-monitor-deploy/utils/cmd.py 没有 SSHRunner（它用注入式的
RemoteShellExecutor + SSHExecutor），故路由表须写明"哪个工程的 utils/cmd.py"，
否则下次仍会找错工程。
cd /home/rain/Documents/k8s_ins
cp -p docs/BASELINE.md optimization-backlog-20261002/backup/docs/BASELINE.md.bak.<YYYYmmdd-HHMMSS>
cp -p docs/PROJECT-MAP.md optimization-backlog-20261002/backup/docs/PROJECT-MAP.md.bak.<YYYYmmdd-HHMMSS>
# 编辑：BASELINE.md 第 4 节与 PROJECT-MAP.md 路由表各增一条（文本以实现体为准）
diff -u optimization-backlog-20261002/backup/docs/BASELINE.md.bak.<TS> docs/BASELINE.md
预期：diff 显示各新增 1 行，无其他改动。
步骤 2：给 deploy 加 --hosts-only（#1）¶
做什么/为什么：新增开关，语义 = 只跑主机侧（node-exporter + 领域采集），跳过集群侧接入段。 实现落点：
main.py：_add_common_options增--hosts-only（store_true）；_reorder_argv的 flag 白名单由("--dry-run","--force")扩为含--hosts-only；日志行与EnvMonitorDeployer(...)构造透传。deployer.py：__init__增hosts_only: bool = False并保存；_prepare_modules中k8s.enabled = not self.limit改为not (self.limit or self.hosts_only)，并加一条--hosts-only 已启用的 warning 日志。
坑：--limit 与 --hosts-only 的组合语义须明确——--limit 是单台试点（筛主机 + 跳过集群侧），
--hosts-only 是全量主机侧验证（不筛主机 + 跳过集群侧）；两者同时给等价于 --limit，
不断言冲突（避免破坏既有脚本）。
cd /home/rain/Documents/k8s_ins/env-monitor-deploy
cp -p main.py ../optimization-backlog-20261002/backup/env-monitor-deploy/main.py.bak.<YYYYmmdd-HHMMSS>
cp -p deployer.py ../optimization-backlog-20261002/backup/env-monitor-deploy/deployer.py.bak.<YYYYmmdd-HHMMSS>
.venv/bin/python -m py_compile main.py deployer.py
.venv/bin/python main.py deploy --help | grep -A3 -- '--hosts-only'
预期：py_compile rc=0；帮助中出现 --hosts-only 及其说明。
注意：本步不跑真实 deploy——deploy --dry-run 仍会执行 _gate()（连远端预检查）
并调用 ensure_backup_ledger()（会在工程 backup/ 落盘），不是零副作用，故不用于离线验证。
6. 验证¶
| 项 | 命令 | 预期 |
|---|---|---|
| 语法 | .venv/bin/python -m py_compile main.py deployer.py |
rc=0 |
| 参数解析 | .venv/bin/python -c 内用 main.build_parser().parse_args(main._reorder_argv([...])) 跑 deploy --hosts-only、deploy --limit X --hosts-only（两种顺序） |
三例均 hosts_only=True，--limit 值正确保留 |
| 开关暴露 | .venv/bin/python main.py deploy --help |
出现 --hosts-only 与说明 |
| #8 落点 | grep -n 'SSHRunner' docs/BASELINE.md docs/PROJECT-MAP.md |
两文件各命中 |
真机验收待办：--hosts-only 的端到端效果（K8s 段确被跳过、主机侧全量照跑、耗时与步数下降）
待下次真实主机侧变更时验证并回填 measured-baselines.md。
7. 回滚¶
| 对象 | 备份位置（相对 optimization-backlog-20261002/） |
回滚命令 |
|---|---|---|
docs/BASELINE.md |
backup/docs/BASELINE.md.bak.20261002-151433 |
cp -p backup/docs/BASELINE.md.bak.20261002-151433 ../docs/BASELINE.md |
docs/PROJECT-MAP.md |
backup/docs/PROJECT-MAP.md.bak.20261002-151433 |
cp -p backup/docs/PROJECT-MAP.md.bak.20261002-151433 ../docs/PROJECT-MAP.md |
env-monitor-deploy/main.py |
backup/env-monitor-deploy/main.py.bak.20261002-151552 |
cp -p backup/env-monitor-deploy/main.py.bak.20261002-151552 ../env-monitor-deploy/main.py |
env-monitor-deploy/deployer.py |
backup/env-monitor-deploy/deployer.py.bak.20261002-151552 |
cp -p backup/env-monitor-deploy/deployer.py.bak.20261002-151552 ../env-monitor-deploy/deployer.py |
备份台账见 optimization-backlog-20261002/backup/README.md。
8. 风险说明¶
| 风险 | 缓解 |
|---|---|
改 deployer.py 影响既有 deploy 行为 |
缺省 hosts_only=False，not (limit or False) 与原 not limit 等价；未在真实链路上跑过，但改动点单一且有备份 |
路由表/速查写错工程（SSHRunner 只在 monitoring-p2） |
条目已写明工程名与替代实现，附「入口命令」示例 |
文档新增行使 PROJECT-MAP 表格错位 |
新增行沿用既有列数与 \| 转义，diff 已核对 |
附录：交付物清单¶
optimization-backlog-20261002/SOP.md（本文件）、backup/README.md（台账）- 修订：
docs/BASELINE.md、docs/PROJECT-MAP.md、env-monitor-deploy/main.py、env-monitor-deploy/deployer.py - token_proxy 侧见
~/Documents/services/token_proxy/backlog-20261002/
来源：
/home/rain/Documents/k8s_ins/optimization-backlog-20261002/SOP.md｜ 最后更新：2026-10-02 15:18（由build/sync.py同步，请勿在站点侧修改）