跳转至

RUNBOOK — IC617 幂等复跑验证工装（ic617_replay）

交付物：ic617_replay_20260927（Python 工程）。本手册面向日常使用与值班排障： 拿着它能判断「工具链是否偏离期望态」，并在复跑出问题时把系统救回来。 变更档案（含实测数据）见 SOP.md。

目录

  1. 服务概览
  2. 接入与凭据
  3. 日常速查表
  4. 日常操作
  5. 配置管理
  6. 备份与恢复
  7. 监控与告警
  8. 故障处置
  9. 安全与权限
  10. 容量与性能
  11. 附录

1. 服务概览

干什么用的：验证「对已装目录重跑 Cadence 安装器（iscape）会不会破坏工具链」，并给出零变更判定； 同时提供工具链期望态的只读漂移检测。

组件 说明
操作机 NFS 宿主（本机 dell-R620），工程在此运行，经 SSH 操作执行端
执行端 192.168.31.18（slurm-work-01），iscape 在此运行并写 NFS 共享盘
变更对象 /tools/cadence/virtuoso/IC617（即宿主 /data/nfs/tools/cadence/virtuoso/IC617）
依赖 介质镜像 /var/tmp/ic617/04.IC06.17.700_Base；patch 介质 /var/tmp/patch/07.cadence_patch；iscape /opt/iscape/iscape.04.23-s010
不碰的东西 license 服务（31.29）、NFS 导出、modulefile、其余五个工具目录

业务影响：本工装只应被用于维护窗口；它会把 /tools 临时改为 rw 并写安装树。 误用时最坏后果是工具链失去 license（可恢复，见第 6 章）。

重要性：中。它是验证与排障工具，不承载业务；但它的误用可能影响全部六台客户端的工具链。

2. 接入与凭据

  • 执行端：ssh root@192.168.31.18（操作机 → 六台 root 免密已配置，密钥在操作机 ~/.ssh/）。
  • license 服务：5280@192.168.31.29（Floating，服务档案见 license_srv_20260926/docs/RUNBOOK.md）。
  • 凭据不落文档、不入版本管理；工程内通过共享库 setup_credentials(default_credential={"username": "root"}) 使用密钥登录。
  • 客户端接入示例（modulefile 两阶段加载）：
module load cadence            # 把 /opt/modulefiles/cadence 加入 MODULEPATH
module load virtuoso/IC06.17.700

3. 日常速查表

目的 命令（工程根执行） 期望
环境与前置体检 .venv/bin/python main.py precheck RC=0；ro 稳态下会报 1 个 BLOCK（/tools 为 ro），属预期
是否偏离期望态 .venv/bin/python main.py drift RC=0 无漂移；1 有漂移；2 探测失败
工具是否可用 .venv/bin/python main.py verify RC=0；含 checked out successfully
取一份快照 .venv/bin/python main.py snapshot 输出 files=<n> sha256=<…>
比对最近两份快照 .venv/bin/python main.py diff RC=0 无差异；3 有差异
复跑验证（会写盘） .venv/bin/python main.py replay 见第 4 章流程
恢复 patch（会写盘） .venv/bin/python main.py restore-patch RC=0 且 license 恢复
看运行日志 tail -f logs/replay.log 每次执行一份
看结论报告 ls -t reports/（*_verdict_*.md） 最近一次判定

退出码约定：0 通过/零变更 · 1 失败 · 2 探测失败（unknown，不得据此判断状态） · 3 有漂移/有变更。

4. 日常操作

4.1 常规复跑（维护窗口）

  1. 确认执行端无在跑作业：ssh root@192.168.31.18 'squeue -h -w slurm-work-01'（应无输出）。
  2. 预检查：.venv/bin/python main.py precheck（预期唯一 BLOCK 是 /tools 为 ro）。
  3. 人工改 rw：ssh root@192.168.31.18 'mount -o remount,rw /tools'。
  4. 执行：.venv/bin/python main.py replay（长任务，建议 setsid nohup .venv/bin/python main.py replay > logs/replay_run.log 2>&1 &， 再 tail -f logs/replay_run.log）。
  5. 必须恢复 ro：ssh root@192.168.31.18 'mount -o remount,ro /tools'，并核验六台均为 ro。
  6. 收尾核验：.venv/bin/python main.py drift（预期 RC=0）。

幂等标记：仅当判定为零变更且功能通过时，工程才写 reports/replay_IC617.done（记录介质指纹）， 之后 replay 会直接跳过（日志「已验证过…跳过」）；确需重跑加 --force。 2026-09-27 实测为非零变更（安装器仍会写收尾文件），故当前无标记，replay 每次都会真跑 —— 这是有意的：标记只在真正零变更时写，避免把"有写入"误记成"已验证零变更"。

4.2 启动 / 停止 / 重启

本工装无常驻进程，无需启停。长任务如需中止： ssh root@192.168.31.18 'pkill -f "iscape.*InstallFromArchive"'（按名终止，勿用 pkill -f 全匹配危险模式）。

4.3 日志位置

日志 位置
工程运行日志 logs/replay.log、每次后台运行的 logs/replay_run.log
预检查报告 reports/precheck_<触发>_<时间戳>.md
变更计划 reports/plan_<时间戳>.yaml
结论报告 reports/replay_verdict_<时间戳>.md
安装器输出 执行端 /var/tmp/ic617_replay/replay_IC617_<时间戳>.out 与同名 .rc
快照与 diff 执行端 /var/tmp/ic617_replay/snap_*.meta、diff_*.txt

5. 配置管理

  • 唯一配置源：config/replay.yaml（样例 config/replay.yaml.example，两者同步维护）。
  • 关键段：nodes（执行端/客户端清单）、replay（安装目录、介质、iscape、工作目录、超时）、 mount（rw 门禁与人工命令）、snapshot（元数据范围）、verify（license 环境 + 检查项）、 precheck（阈值与跳过列表）、patch_restore（恢复资产）。
  • 生效方式：改文件即生效（每次执行重新加载），无需重启。
  • 易错点： ① replay.archive_dir 必须指向介质，不得等于 install_dir（配置校验会 BLOCK）； ② verify.license_env 必须包含 OA_UNSUPPORTED_PLAT 与 LD_PRELOAD，否则验证结论无效； ③ nodes.install_host 只能有一个（多执行端会引入并发写同一安装树的风险）。
  • 不支持的能力（安装、依赖补齐、介质清理）不在本工程，属 ic617_install_20260926 工程。

6. 备份与恢复

  • 本工装不产生文件备份：它不改写自己管理的配置与脚本；安装器的写入由快照留证。
  • 复跑前的恢复能力依赖三份既有资产（precheck 会 BLOCK 缺失）：
  • patch 介质 /var/tmp/patch/07.cadence_patch/{sfk,cadence.pat}；
  • patch 前库备份 /tools/_ic617_media/backup/pre_patch_libs_20260927-004833.tar.gz；
  • 原始镜像 /var/tmp/ic617（重装兜底）。
  • 恢复路径见 SOP.md 第 7 章；三条路径分别为重跑 patch、还原库备份、按 ic617_install_20260926/docs/SOP.md 第 7 章重装。
  • 演练记录：2026-09-27 复跑后未触发恢复路径（lib 差异 0 行）；restore-patch 的幂等性 依赖 verify 判据（license 正常即跳过），尚未实践触发，首次触发时须记录到本节。

7. 监控与告警

无独立监控。需要的观测点：

指标 查看方式 关注点
漂移状态 main.py drift RC≠0 即有偏离
license 服务 ssh root@192.168.31.29 'pgrep -ax lmgrd; pgrep -ax cdslmd' 进程缺失 → 全部工具不可用
/tools 挂载 六台 findmnt -no OPTIONS /tools 非常态 ro 即为异常（rw 是维护窗口态）
iscape 输出 执行端 replay_*.out 尾部 出现 ERROR / 非 0 rc

drift 打印「尚未完成一次通过的幂等复跑验证（缺 replay_IC617.done）」属正常：它表示 尚无"零变更"结论，而非工具链有问题；工具链是否健康只看同一命令的其余判据（主二进制、license）。

8. 故障处置

场景 A：replay 报「启动 iscape 失败（rc=-1）」但远端已有输出

症状：日志报启动失败，但执行端 /var/tmp/ic617_replay/ 下有本次 .out 与 .rc。

诊断 1. 看远端是否已完成：ssh root@192.168.31.18 'cat /var/tmp/ic617_replay/replay_<ts>.rc'（0 即完成）。 2. 看输出尾部：ssh root@192.168.31.18 'tail -n 10 /var/tmp/ic617_replay/replay_<ts>.out'。

处置：属 ssh 通道判据问题（后台进程持有通道 fd），安装器可能已执行完毕—— 先按已完成处理：跑 snapshot + diff 判定写入，再跑 verify 判定 patch。 实现体已修（启动命令补 < /dev/null）。

验证：.venv/bin/python main.py drift 返回 0。

场景 B：verify 报 license 未通过 / 出现 Unable to obtain

症状：license_checkout 不通过，输出含 Unable to obtain ... license。

诊断 1. 确认 license 服务：ssh root@192.168.31.29 'pgrep -ax lmgrd; pgrep -ax cdslmd'。 2. 确认 patch 是否被覆盖：.venv/bin/python main.py diff，看是否出现 tools.lnx86/lib 下的差异。 3. 排除验证环境问题：确认 verify.license_env 含 OA_UNSUPPORTED_PLAT 与 LD_PRELOAD （缺前者会抛 OA sysname unknown，容易被误读为 license 故障）。

处置：服务正常且 lib 被改写 → mount -o remount,rw /tools 后执行 .venv/bin/python main.py restore-patch，再 .venv/bin/python main.py verify。 验证：输出出现 Virtuoso Framework License (111) was checked out successfully。

场景 C：precheck 报 /tools 为 ro（BLOCK）

症状：mount: /tools 当前为 ro，退出码 1。

诊断/处置：这是预期门禁，不是故障。确认在维护窗口后人工执行 ssh root@192.168.31.18 'mount -o remount,rw /tools'；变更结束务必恢复 ro。 验证：precheck 不再出现该 BLOCK；六台 findmnt 首项为 ro。

场景 D：replay 被跳过（未实际执行）

症状：日志显示「已验证过且介质未变（replay_IC617.done @ …），跳过复跑」。

诊断：这是幂等行为。确认是否需要重跑：介质未变则无需；介质已换则该跳转会因指纹不符自动解除。 处置：确需重跑加 --force：.venv/bin/python main.py replay --force。

场景 E：diff 报探测失败（RC=2）

症状：快照不足两份 或 比对失败。

处置：先 main.py snapshot 取一份，确保执行端 work_dir 下至少两份 snap_*.meta； 仍失败则检查执行端磁盘与权限。不得在没有快照证据时宣称「零变更」。

9. 安全与权限

  • 全程 root：操作机 → 执行端 root 免密；precheck 会校验执行身份。
  • /tools 的 rw 窗口是唯一放宽点，由人工开关，工装不代劳；结束必须恢复 ro。
  • 工装不写 /etc、不动 fstab、不动 license 服务、不做删除类动作（无「危险目标判定」需求）。
  • 凭据（SSH 密钥、license 端口）不入文档；license 服务凭据取用方式见 license_srv_20260926/docs/RUNBOOK.md。

10. 容量与性能

项 实测/基线 说明
快照耗时 约 30s（115881 个条目，NFS 元数据遍历） 走元数据而非全量哈希
快照文件体积 约 13 MB/份 留在执行端 work_dir
复跑耗时 约 2 分钟（首次安装约 8 分钟） 差异来自「不重装 kit」
安装树规模 115881 个条目 判定基准，行数异常即说明探测有问题
磁盘占用 /tools 可用 1223G 工装自身几乎不占空间

扩容/清理触发条件：执行端 /var/tmp/ic617_replay/ 累计快照超过数 GB 时可手工清理 （只删该目录内的 snap_* / diff_*，不删 replay_*.out/.rc，后者是留证）。

11. 附录

术语：iscape = Cadence InstallScape 安装器；零变更 = 跑前跑后元数据快照无差异； 三态 = done / pending / unknown（unknown 一律中止，不得据此变更）。

相关文档与交付物

文件 内容
SOP.md 本轮变更实施、实测数据与结论
ic617_install_20260926/docs/SOP.md 工具链安装档案（附录 D.7 = 本轮复跑实测）
ic617_install_20260926/docs/RUNBOOK.md 工具链运维手册（六类故障场景）
docs/HANDOFF.md（项目根） 当前状态与待办

修订记录

日期 修改人 内容
2026-09-27 rain 首版：复跑验证工装交付（基于 IC617 单工具试点实测）

来源：/home/rain/Documents/eda_tools_ins/Cadence/ic617_replay_20260927/docs/RUNBOOK.md ｜ 最后更新：2026-09-27 02:17（由 build/sync.py 同步，请勿在站点侧修改）