RUNBOOK — Synopsys module 体系（环境模块使用手册）¶

适用对象：在 31.28（EDA-HPC）与六台 work 节点上使用 Synopsys EDA 工具的所有人维护对象：/opt/modulefiles 下的 Synopsys module（NFS 共享，来源 192.168.31.249:/data/nfs/modulefiles）最近一次变更：2026-09-29（module 体系修复：SCL 补入、悬空 module 移出、xa 路径修复）变更档案：../docs/SOP.md　备份台账：../backup/README.md

目录¶

服务概览
接入与前置
日常速查表
日常操作
配置管理
备份与恢复
监控与告警
故障处置
安全与权限
容量与性能
附录

1. 服务概览¶

是什么：一套基于 Lmod 的环境模块（environment modules）体系。核心理念是"用哪套工具就加载哪套"——module load 一次，PATH、LD_LIBRARY_PATH、license 变量、兼容层开关全部就位，退出会话即失效，机器默认环境保持干净。

由哪些组件构成

组件	位置（客户端视角）	说明
Lmod 本体	系统包（`module` 命令）	由 OS 提供，任意机器自带
家族入口	`/opt/modulefiles/Core/*.lua`	每家一个入口（`synopsys`、`cadence`、`siemens`、`pdk`、`slurm`、`site`）
具体版本	`/opt/modulefiles/<family>/<tool>/<ver>.lua`	如 `synopsys/eda2018/1.0.lua`
兼容层制品	`/opt/modulefiles/synopsys_compat/`	不是 module，是 `libpthread` shim 与 `uname` 包装，由 module 注入
工具树	`/tools/synopsys/...`（只读挂载）	实际二进制与数据

覆盖范围：Synopsys 2018 批次 20 个工具入口（19 个 + 2026-09-29 追加的老 ICC ICCompiler）+ SCL（lmutil/lmgrd/snpslmd）。

依赖谁：192.168.31.249（NFS 服务端，提供 module 树与工具树）；192.168.31.29（license 服务，2700@）。

异常时的业务影响：模块加载失败 → 工具命令找不到；变量未就位 → 工具起不来（缺库）或拿不到 license。这是所有 EDA 工作的第一道门，重要性：高。

2. 接入与前置¶

在哪用：31.28（有 VNC 桌面）与六台 work（.18/.19/.20 slurm、.25/.26/.27 lsf）。
不需要凭据：module 命令与 module 文件都是公开可读。
license 变量由 module 自动设置，正常情况不需要手工设 license。
前置检查（三条都通过才谈得上用）：

ls /tools/synopsys >/dev/null && echo "工具树可访问 OK" || echo "FAIL 工具树未挂载"
mount | grep -E "on /opt/modulefiles " || echo "FAIL module 树未挂载"
type module >/dev/null 2>&1 && echo "module 命令可用 OK" || echo "FAIL：需 source /etc/profile.d/modules.sh（或登录 shell）"

3. 日常速查表¶

module avail                       # 列出当前可见的 module（家族入口）
module load synopsys               # ① 先加载家族入口
module load eda2018/1.0            # ② 再加载版本（顺序不能反）
module list                        # 看当前已加载什么
module show eda2018/1.0            # 看这个 module 到底设了哪些变量/路径
module purge                       # 卸载全部（清干净环境）
module unload eda2018/1.0          # 卸载单个
module spider eda2018/1.0          # 找不到模块时用它反查加载路径
dc_shell -version                  # 冒烟：确认工具真的能跑
lmutil lmstat -c 2700@192.168.31.29   # 查 license 服务是否在发许可

一行版：module load synopsys && module load eda2018/1.0

4. 日常操作¶

4.1 加载（最常用）¶

module load synopsys && module load eda2018/1.0

预期：无输出即成功（echo $? = 0）。

坑（重要）：必须先 synopsys 后 eda2018/1.0。家族入口的作用是把 /opt/modulefiles/synopsys 挂进 MODULEPATH；没加载 synopsys 时，eda2018/1.0 根本不可见，会报：

Lmod has detected the following error: These module(s) or extension(s) exist but cannot be loaded as requested: "eda2018/1.0"

这不是故障，是顺序问题。

4.2 确认加载成功¶

第一步，看列表（预期输出）：

module list

Currently Loaded Modules:
  1) synopsys   2) eda2018/1.0

第二步，看关键变量（预期：五行全部有值）：

for v in SNPSLMD_LICENSE_FILE LD_PRELOAD EDA_COMPAT_FAKE_UNAME VCS_USE_MALLOC SG_CONSOLE_SE; do echo "$v=${!v}"; done

SNPSLMD_LICENSE_FILE=2700@192.168.31.29
LD_PRELOAD=/opt/modulefiles/synopsys_compat/libexec/libpthread.so.0:/lib64/libz.so.1
EDA_COMPAT_FAKE_UNAME=1
VCS_USE_MALLOC=1
SG_CONSOLE_SE=1

第三步，冒烟：

dc_shell -version | head -2          # 预期：dc_shell version - O-2018.06-SP1
vcs -ID 2>&1 | head -3               # 预期：打印 VCS 版本（可能伴随 LNX_OS_VERUN 告警，属正常）
spyglass -version                    # 预期：SpyGlass_vN-2017.12-SP2

4.3 找不到 module 时怎么反查¶

module spider eda2018/1.0

它会告诉你该 module 属于哪个家族、要先加载什么。先看它列出的 You will need to load all module(s) on any one of the lines below，照做即可。

4.4 卸载 / 清环境¶

module unload eda2018/1.0     # 只卸版本，家族入口保留
module purge                  # 全部卸载（推荐在切项目、切工具前执行）

4.5 在作业脚本里使用（slurm / lsf）¶

作业是非交互 shell，module 可能未被初始化，必须显式初始化：

#!/bin/bash -l                       # -l 让登录 shell 生效，通常会自带 module
# 若仍报 module: command not found，取消下一行注释
# source /etc/profile.d/modules.sh

module load synopsys
module load eda2018/1.0

dc_shell -f synth.tcl

提交（slurm / lsf 分别）：

sbatch run.slurm          # slurm 集群（slurm-work-01/02/03）
bsub < run.lsf            # lsf 集群（lsf-work-01/02/03）

4.6 环境事实（一次讲清）¶

项	值
module 树来源	`192.168.31.249:/data/nfs/modulefiles` → 客户端 `/opt/modulefiles`（rw 挂载，但客户端不用改）
工具树来源	`192.168.31.249:/data/nfs/tools` → 客户端 `/tools`（ro 挂载）
license	`2700@192.168.31.29`（由 module 设置 `SNPSLMD_LICENSE_FILE`）
工具版本	综合 `O-2018.06-SP1`、PT 同版、PrimePower `SP3`、VCS-MX/Verdi `N-2017.12-SP2`、SpyGlass `N-2017.12-SP2`、SCL `2018.06`

5. 配置管理¶

module 文件在哪：服务端（宿主本机）/data/nfs/modulefiles/，客户端看到的是 /opt/modulefiles/。

谁能改：仅宿主本机 root（客户端是 ro 挂载，改不了）。改一处，七台同时生效（新开会话）。

怎么改（给人看的原则）：

先备份：sudo cp -a <原文件> <原文件>.bak.$(date +%Y%m%d-%H%M%S)，并登记到对应主题的 backup/README.md；
在服务端编辑；
在 31.28 上 module purge && module load synopsys && module load eda2018/1.0 验证变量与工具；
抽查一两台 work 节点；
更新该主题 SOP.md 与项目根 docs/HANDOFF.md。

关键变量一览（都不要手工覆盖）：

变量	值	为什么必须有
`SNPSLMD_LICENSE_FILE`	`2700@192.168.31.29`	必须用厂商专用变量；回退读 Cadence 的 `LM_LICENSE_FILE` 会超时重试、拖慢启动
`LD_PRELOAD`	`…/synopsys_compat/libexec/libpthread.so.0:/lib64/libz.so.1`	①补 glibc≥2.34 移除的 pthread 版本声明；②压掉自带老 zlib 与系统 libpng16 的冲突
`EDA_COMPAT_FAKE_UNAME`	`1`	让 `/usr/local/bin/uname` 包装伪造 `uname -sr`（SpyGlass 平台探测需要）
`VCS_USE_MALLOC`	`1`	不设则 `simv` 启动即 SIGSEGV
`SG_CONSOLE_SE`	`1`	不设则 SpyGlass 命令行 lint 起不来（`FT_Get_Advance` 缺失）

红线：

不要手改 /opt/modulefiles/Core/*（家族入口由部署器生成）；
不要动 fstab / exports（挂载关系已稳定）；
不要 pkill lmgrd（license 主机上同时跑着 Cadence 与 Synopsys 两套，误杀会中断全集群许可）；
不要手工 unset SG_CONSOLE_SE（sg_shell 内部还会再设回来，且会引入库冲突）；
不要重跑 slurm 部署器的模块步骤而不检查——它会重建已被移出的悬空 module（见 8.6）。

6. 备份与恢复¶

备份在哪：各变更主题的 backup/ 下，按"相对原路径"层次存放，命名 <原名>.bak.<YYYYmmdd-HHmmss>。与 module 体系相关的：

主题	备份	说明
`../`（本主题）	`backup/data/nfs/modulefiles/synopsys/eda2018/1.0.lua.bak.20260929-012223`	改动前原始版（回滚用这份）
`../`	`backup/data/nfs/modulefiles/synopsys/vcs/2023.12.lua.removed`	被移出的悬空 module
`../`	`backup/data/nfs/tools/synopsys/xa/K-2015.06-SP5/bin/xa_fh.bak.20260929-012459`	xa 修复前
`../../rocky9_eda_compat_20260928/backup/`	`data/nfs/modulefiles/synopsys_compat/bin/uname.bak.`、`synopsys/eda2018/1.0.lua.bak.`	兼容层包装与更早的 modulefile

恢复（高危，仅宿主 root）：

BK=/home/rain/Documents/eda_tools_ins/Synopsys/synopsys_module_fix_20260929/backup/data/nfs
sudo cp -a "$BK/modulefiles/synopsys/eda2018/1.0.lua.bak.20260929-012223" /data/nfs/modulefiles/synopsys/eda2018/1.0.lua
sudo cp -a "$BK/tools/synopsys/xa/K-2015.06-SP5/bin/xa_fh.bak.20260929-012459" /data/nfs/tools/synopsys/xa/K-2015.06-SP5/bin/xa_fh

恢复后验证：module purge && module load synopsys && module load eda2018/1.0 && dc_shell -version。

何时可删备份：确认新 module 长期稳定后由用户对照各主题 backup/README.md 自行删除。

7. 监控与告警¶

监控点	命令	正常判据
NFS 挂载	`mount \\| grep -E "on /(tools\\|opt/modulefiles) "`	两条都在
模块加载	`module load synopsys && module load eda2018/1.0 && echo OK`	输出 `OK`
关键变量	见 §4.2 第二步	五行全部有值
工具冒烟	`dc_shell -version`、`vcs -ID`	打印版本
license 服务	`lmutil lmstat -c 2700@192.168.31.29 \\| head -6`	`license server UP (MASTER) v11.14.1`
license 余量	`lmutil lmstat -a -c 2700@192.168.31.29 \\| grep -c "Users of"`	接近 license 文件的 feature 总数（2026-09-29 实测 2843）

已知缺口：目前没有自动探活。flexlm_systemd 那套 systemd 只能自愈"进程退出"，发现不了"进程活着但不发许可"。用户已计划后续统一接入 Prometheus。

8. 故障处置¶

8.1 `module load synopsys` 报"模块树不存在"¶

症状

LmodError: 模块树不存在：/opt/modulefiles/synopsys（共享目录未挂载？）

诊断

mount | grep "/opt/modulefiles"                      # 预期：有挂载行
ls /opt/modulefiles/Core | head                       # 预期：列出 *.lua

处置：未挂载 → 检查 NFS 服务端与网络；服务端正常而客户端未挂 → 参照该节点既有挂载方式补挂（不要手改 fstab，先与管理员确认）。

验证：module load synopsys && module avail 能看到 eda2018/1.0。

8.2 `module load eda2018/1.0` 报"存在但不能加载"¶

症状：These module(s) or extension(s) exist but cannot be loaded as requested: "eda2018/1.0"

诊断：九成是没先加载家族入口。

module list          # 若列表里没有 synopsys，即为此因

处置

module purge
module load synopsys
module load eda2018/1.0

验证：module list 出现 1) synopsys 2) eda2018/1.0。

8.3 加载成功但工具命令找不到¶

症状：dc_shell: command not found（而 module list 显示已加载）

诊断

echo "$PATH" | tr ':' '\n' | grep -c synopsys     # 预期：21（20 个工具入口 + 兼容层 bin）
ls /tools/synopsys/syn/O-2018.06-SP1/bin/dc_shell  # 文件是否存在
command -v dc_shell

处置：PATH 里没有工具入口 → 工具树未挂载或 module 文件被改坏：

ls /tools/synopsys || echo "工具树未挂载 → 检查 NFS"
module show eda2018/1.0 | grep -c "prepend_path"   # 预期：20（同上，2026-09-29 实测 20）

若 module show 正常但 PATH 无条目 → 重新 module purge 后按 §4.1 顺序加载。

验证：dc_shell -version 打印版本。

8.4 工具启动报库错误¶

症状 A：symbol lookup error: /usr/lib64/libfontconfig.so.1: undefined symbol: FT_Get_Advance → 说明 SG_CONSOLE_SE 丢了（SpyGlass 把自带老 freetype 塞进了库路径）。

症状 B：error while loading shared libraries: libpthread.so.0: … / symbol not found → 说明 LD_PRELOAD 丢了（缺 pthread 版本声明 shim）或工具树自带的库没被系统库压住。

诊断

echo "SG_CONSOLE_SE=${SG_CONSOLE_SE:-（空）}"
echo "LD_PRELOAD=${LD_PRELOAD:-（空）}"

处置：任一为空 → 环境被手工覆盖或 module 未加载。

module purge && module load synopsys && module load eda2018/1.0

若仍为空 → module show eda2018/1.0 | grep setenv 检查 module 文件是否被改坏，参照 §6 恢复。

验证：spyglass -version 正常打印版本。

8.5 VCS 的 `simv` 启动即段错误¶

症状：vcs 编译通过，运行 ./simv 立即 SIGSEGV（栈里常见 mem_free ← snpsCheckFreeFunc ← libvcsnew）。

诊断：echo "VCS_USE_MALLOC=${VCS_USE_MALLOC:-（空）}"。

处置：为 1 才对。为空则按 §4.1 重新加载。

验证：

cd /tmp && printf 'module t; initial $display("OK"); endmodule\n' > x.sv && vcs -full64 -sverilog x.sv -o simv && ./simv

预期输出 OK。

8.6 `module avail` 里出现了不认识的 module¶

症状：例如又看到 vcs/2023.12（2026-09-29 已移出的悬空条目）。

诊断

module show vcs/2023.12      # 看它指向哪里；若指向 /opt/eda/... 即为悬空模板
ls -d /opt/eda 2>&1           # 预期：不存在

处置：这是 slurm 部署器复跑后重建的产物（模板会生成指向 /opt/eda/... 的占位 module）。两种应对，任选其一： 1. 再移出（需宿主 root，参照 ../docs/SOP.md 步骤 3）； 2. 改部署器清单，使其不再生成该 module（根治，需改 kvm_rocky9_deploy 侧配置）。

注意：它带 isDir 守卫，加载时会直接报错，不会静默污染环境，因此不紧急。

验证：module avail 的 synopsys 树只剩 eda2018/1.0。

8.7 `xa` 报 `Error: XA is not properly installed`¶

症状：xa 启动即退出，报找不到 .../GNU/linux64/gcc-4.8.3/bin/gcc 或 XA is not properly installed。

诊断

/tools/synopsys/xa/K-2015.06-SP5/bin/xa_fh

预期输出 /tools/synopsys/xa/K-2015.06-SP5。若输出 /data/nfs/tools/...（宿主视角路径），即为硬编码路径复发（工具重装会复原该文件）。

处置：把 xa_fh 改回动态推导（需宿主 root）：

#!/bin/sh
_p=$(readlink -f "$0" 2>/dev/null) || _p="$0"
echo "$(dirname "$(dirname "$_p")")"

或直接跑本主题实现体：sudo -n python3 ../../fix_modules.py --apply。

验证：xa -h 打印 CustomSim (R) Version K-2015.06-SP5。

8.8 工具报拿不到 license¶

症状：dc_shell / vcs 提示找不到 license 或长时间等待后失败。

诊断（由内向外）

echo "$SNPSLMD_LICENSE_FILE"                 # 预期 2700@192.168.31.29
lmutil lmstat -c 2700@192.168.31.29 | head -6
ssh root@192.168.31.29 'systemctl is-active flexlm-synopsys'

处置 - 变量为空 → 按 §4.1 重新加载； - 服务端未起 → ssh root@192.168.31.29 'systemctl restart flexlm-synopsys'，等 60–70 秒再验（TCP TIME-WAIT 期间会误判失败）； - 服务在但无库存 → 看 lmstat -a 是否有其他会话占满；必要时联系管理员。

验证：lmutil lmstat … | head -1 显示 server UP；重跑工具。

9. 安全与权限¶

模块树与工具树对所有节点只读（客户端视角）；改动只能在宿主本机以 root 进行。
LD_PRELOAD 有全局副作用：它作用于加载 module 之后的所有子进程。因此：
只在用 EDA 工具的会话里加载；
不要把 module load synopsys 写进 ~/.bashrc 之类默认环境；
用完 module purge，尤其在跑非 EDA 的编译/打包任务前。
不要在文档或脚本里写 license 服务器凭据；本文只写地址与端口，凭据存放位置请询问管理员。
兼容层制品位于 /opt/modulefiles/synopsys_compat/，是工具链的一部分，不要当作"多余文件"清理。

10. 容量与性能¶

项	现状	说明
module 文件体积	数十 KB	加载开销毫秒级，可忽略
工具树	41 G（NFS 只读）	首次启动工具时受 NFS 带宽影响
启动延迟	主要来自 NFS 与 license	大工具（icc2/pt）冷启动慢于本地安装
license 并发	keygen 库共 2847 feature	多会话并发时用 `lmutil lmstat -a` 看占用
已知瓶颈	NFS 服务端单点	服务端抖动会同时影响七台；暂未做多副本

扩容/优化触发条件：多用户并发时工具启动明显变慢 → 先量 NFS 带宽与 license 等待时间，再考虑本地缓存或提升服务端 IO。

11. 附录¶

11.1 工具入口对照表（`module load synopsys && module load eda2018/1.0` 后）¶

命令	工具	版本
`vcs`	VCS-MX	N-2017.12-SP2
`verdi`	Verdi	N-2017.12-SP2
`spyglass`	SpyGlass	N-2017.12-SP2
`fm_shell`	Formality	O-2018.06-SP1
`dc_shell`	Design Compiler	O-2018.06-SP1
`icc2_shell`	IC Compiler II	O-2018.06-SP1
`pt_shell`	PrimeTime	O-2018.06-SP1
`pwr_shell`	PrimePower	O-2018.06-SP3
`lc_shell`	Library Compiler	O-2018.06-SP1
`StarXtract`	StarRC	O-2018.06-SP1
`siliconsmart`	SiliconSmart	N-2017.12-SP2
`tmax`	TetraMAX（需 DISPLAY）	O-2018.06-SP1
`hspice`	HSPICE	N-2017.12-SP2
`xa`	CustomSim	K-2015.06-SP5
`custom_compiler`	Custom Compiler（当前缺 OpenAccess，启动会报错）	N-2017.12-SP1-2
`wv`	WaveView（需 DISPLAY）	N-2017.12-SP2
`synplify`	Synplify（需 DISPLAY）	N-2018.03-SP1
`identify_debugger`	Identify（注意命令名，无 `identify`）	N-2018.03-SP1
`lmutil` / `lmgrd` / `snpslmd`	SCL（查/管 license）	2018.06

11.2 其他家族（同机制，供参考）¶

家族入口	子模块	说明
`module load cadence`	`virtuoso/IC06.17.700`	Cadence IC617 + MMSIM + ASSURA
`module load siemens`	`calibre/2015.2_36.27`、`calibre/2026.1`	Calibre
`module load pdk`	`sky130/1.0`（当前悬空，数据未落地，load 会报错）	PDK，Agent 未介入
`module load slurm`	`slurm/26.05.2`	调度器客户端

11.3 相关文档¶

文档	内容
`../docs/SOP.md`	module 体系修复的变更档案 + 全量工具验证矩阵 + 已知问题
`../backup/README.md`	本主题备份台账与回滚命令
`../../rocky9_eda_compat_20260928/docs/SOP.md`	兼容层三根因、modulefile 设计（§10）、GUI 验证（§10.7）
`../../synopsys_license_20260928/docs/RUNBOOK.md`	license 服务的运行手册
`../../docs/HANDOFF.md`	项目根状态、待办与红线

11.4 修订记录¶

日期	修改人	内容
2026-09-29	TraeCode	首次成文：覆盖加载/确认/作业脚本用法、故障处置 8 个场景、配置与备份、工具对照表

来源：/home/rain/Documents/eda_tools_ins/Synopsys/synopsys_module_fix_20260929/docs/RUNBOOK.md ｜最后更新：2026-09-29 03:50（由 build/sync.py 同步，请勿在站点侧修改）