06 · 运维
故障排查
大多数 bridge 问题不用重装就能定位。运行时状态覆盖 SSH(Secure Shell)登录、隧道,以及 Virtuoso CIW(Command Interpreter Window)里的守护进程。先读状态,锁定失败的是哪一层,然后只做那一层需要的动作。每一节都从面板或工具实际报出的症状讲起。
分诊
插件会记下失败的是哪一层,所以第一步永远是把它读出来。重装 venv 几乎从来不是第一步。只有探测说守护进程缺失或代际不对时,才重新部署。
| 症状 | 第一步 |
|---|---|
运行时状态为 waiting | 在空闲 CIW 里执行 setupHint 的加载行。 |
运行时状态为 needs-trust | 确认指纹,然后重新启动。 |
守护进程探测为 no-listener 或 legacy | 用 deploy_daemon 部署,再加载它返回的行。 |
守护进程状态为 auth-failed | 部署当前 setup 并加载。 |
| 运行时状态里出现弹窗标题 | 在 Virtuoso 里回答弹窗,然后刷新。 |
| 出现部署冲突卡 | 先看版本,只有确认过期时才覆盖。 |
浏览器出现 Failed to fetch | 重试一次,然后刷新 DSH 页面。 |
| history 卡在加载 | 等本地超时。 |
| 脚本 job 一直不结束 | 用 job id 查 status,再 cancel。 |
| 结果没有附带 CIW 块 | 显式读取 CIW。 |
virtuoso_bridge_runtime 的 status 动作只需一次调用。它给出状态、守护进程状况、弹窗状态、setup 提示和错误。改动任何东西之前先执行它。
运行时处于等待
waiting 表示 SSH 登录和隧道都通了,只是守护进程端口上还没有应答,CIW 尚未加载准备好的 setup。运行时面板会显示确切的命令,状态里则通过 setupHint 给出。状态何时转为 running,见 健康检查循环。
load("/home/username/.virtuoso-bridge/daemon/virtuoso_setup.il")
加载后,每 20 秒一次的健康检查会把运行时转为 running。守护进程恢复应答,加载提示随之清除,健康的连接不会再显示任何 CIW 提示。
隧道和 SSH 会话都已经正确,缺的只有 CIW 那一侧,重新部署不会改变什么。
主机密钥信任
needs-trust 表示主机提供了你还没信任的密钥,运行时会保持停止。先确认指纹,再重新启动。主机密钥与信任 说明了探测如何标注每个密钥,以及信任的密钥写到哪里。
已信任的类型上出现不同的密钥,是另一回事。那是冲突,插件从不替换它。你要先用 ssh-keygen -R <host> 删除过期条目,再重试。
一台主机可以同时提供多种密钥类型,而 known_hosts 里往往只存了一部分。缺失的类型只算未信任,不算变更;只要有一个受信任类型,主机也能正常启动。
守护进程故障
守护进程故障不是 SSH 故障。测试 与 test_connection 分层报告:SSH 可达性与认证、远端 Python 解释器、暂存根目录,以及配置的守护进程端口上是什么在应答。运行时没启动时,它们也能执行。
无监听或旧版
no-listener 表示配置的端口上没有任何监听。legacy 表示那里应答的是另一代 bridge,通常是监听别的端口的旧 bundle。插件不会复用这两种守护进程。部署再加载的完整流程见 守护进程部署。
重连或普通重启不会部署文件。执行 virtuoso_bridge_runtime 的 deploy_daemon 动作,再在目标空闲 CIW 里加载它返回的行。
认证失败
auth-failed 表示 bridge 守护进程在,但它拒绝本客户端的 token。原因可能是守护进程早于 token 认证、属于另一个账号,或 token 已轮换。补救方式和 setup 缺失时一样:部署当前 setup,再在目标 CIW 里加载。
被弹窗阻塞
模态弹窗能在 Virtuoso 本身健康时阻塞守护进程。状态里带弹窗标题,面板显示警告,提示你点击或回答弹窗后刷新。提示从不要求重装守护进程或重新加载 setup。探测已经报告 no-listener 时,插件会跳过弹窗检查,因为那里不可能有弹窗。
守护进程丢失
守护进程原本健康、后来才停止应答时,面板报的是守护进程丢失的原因,而不是首次安装的提示。setup 确实已经加载过一次,所以该看 CIW:长命令占用、会话崩溃,或端口变化。
共享 setup
用 virtuoso-bridge install-daemon 安装的共享 daemonSetup 对客户端只读;修改客户端环境,也无法改变正在运行的 CIW。守护进程部署 说明客户端如何共用它。
部署冲突
普通部署从不覆盖不一致的远端 bundle。冲突卡会给出两边的版本(未知时显示 version unknown)和后端的冲突详情;具体的比较规则见 冲突。
只在生成的 bundle 过期、损坏或 profile 变化时才覆盖。旧 bundle 会留作备份。覆盖之后,把新返回的 setup 行加载到目标空闲 CIW,或者带上 replace: true 调用 deploy_daemon。
部署走 SSH,可能超过 dashboard 的轮询预算。dashboard 会让打印出的 setup 路径和加载行保持可见,所以不要因为浏览器请求超时就重试部署。细节见 超时。
浏览器与 history
Failed to fetch
客户端会先清除过期的 dashboard base 或 token,再重试一次。请求都带超时,并且优先用当前页面的 origin。dashboard 服务重启后,请刷新 DSH 页面;升级插件后也刷新一次,让浏览器用上当前 bundle。
history 一直加载
history 内容在你展开时才获取。本地超时会清除加载状态;取到就显示代码和结果,后端不可达时客户端会报出失败,而不是一直挂着。
SSH 与后端
- 确认
ssh在PATH里,或者显式选 Paramiko。没有 OpenSSH 时,安装会先停下来征求确认,之后只用 Paramiko 后端继续。 - jump host 和非标准端口,检查连接编辑器里的高级网络字段:
sshPort、jumpHost、jumpUser、sshProxy以及角色主机覆盖。 - 主机密钥冲突需要明确的信任决定。见 主机密钥信任。
identityFile会为每条连接生成一份 SSH 配置,其中也包含你自己的配置。其余情况,认证走系统的ssh配置、agent 和密钥。- 本地连接(
localhost、127.0.0.1、::1)跳过 SSH,直接用本地 bridge token 文件,与 virtuoso-bridge 本地模式一致。 - 主机密钥预检和 SSH 测试针对主
host。拆分拓扑里,先用你自己的ssh/known_hosts 信任额外的角色主机密钥。
路径与暂存根目录
首次 IL 加载如果对 ~/... 路径报 load: can't access file,说明带 ~ 的路径传到了 Virtuoso —— load() 不展开 ~。请在远端账号上使用绝对的 remoteScratchRoot,或者保留 ~/,让插件在任何部署或上传之前先解析它。部署、客户端上传和 IL 上传都不会把 ~ 传给 load()。
| 暂存根目录状况 | 部署前会发生什么 |
|---|---|
| 缺失,位于账号主目录下 | 以 0700 创建。同级路径只差 _ 与 - 时,你会收到警告。 |
| 权限宽松但属于用户 | 收紧权限,不拒绝。 |
| 符号链接、所有者错误、非目录,或主目录之外的缺失路径 | 各自给出可操作的错误信息;补救方式是创建目录时,提示 mkdir -p -m 700。 |
部署结果会报告 configuredScratchRoot、解析后的 scratchRoot、scratchCreated/scratchTightened 以及任何警告,所以加载路径不会悄悄偏离配置值。每条连接的 remoteScratchRoot 覆盖全局默认值;这个默认值以 VB_REMOTE_SCRATCH_ROOT 传给部署、发现、shell 和脚本。
缺少 CIW 块
附加在调用或已结束脚本 job 上的 CIW 块只是尽力而为,也可能整块缺失。本地 Windows Virtuoso、缺少 /proc 或通道繁忙,都可能跳过采集;采集本身也绝不会让调用失败。块缺失或来得太晚时,就显式读一次 CIW:先刷出警告端口,再 tail 最新的会话日志。
client.execute_skill('warn("") getWarn()')
log = client.run_shell_command(
'set log = `ls -t ~/CDS.log* | head -1` ; tail -n 40 "$log"')
print(log.output)
run_shell_command 在 Virtuoso 进程环境里运行 csh,所以 .output 里就是这个命令的 stdout 和 stderr。不要每次调用都这样轮询;自动附加的 CIW 块更省。
CIW 与用户以及其他工具共用,所以捕获到的某一行未必属于这次调用。用它定位原因,绝不要当作所属结果的证据。取消勾选 将 CIW 的警告/错误随结果一并报告(ciwReport)即可关闭采集。
安全
- 主机密钥信任必须显式;变更的密钥是冲突,插件永远不会静默替换。
- 创建连接或修改它的 SSH 目标,是工作区之外的访问授权。启动它会让智能体在对应账号上拿到 shell、Python 和 SKILL(Cadence 的脚本语言)。除非会话具备 完全权限,智能体工具会请求批准;批准被拒绝即为终态。
- 守护进程 token 存在 DSH credentials 里,经 sidecar 环境传给守护进程。token 输入框只写,面板从不返回它。
- Dashboard 通过仅回环端点引导每进程 token,并拒绝跨站请求。
- 远程 setup 路径是私有的,所有权由 virtuoso-bridge-lite 校验。
- 客户端不能替换共享的
install-daemonsetup。
被拒绝的批准是一个决定,不是 bug。请从配置页创建连接,而不是重试工具调用。
限制
| 限制 | 后果 |
|---|---|
| 无法自动向运行中的 CIW 加载 SKILL | 打印的 load("...") 行要由人执行。执行之后,运行时会自动转为 running。 |
| 不包含 Cadence 或 Spectre 许可/硬件 | 实际 SKILL、Maestro 和仿真行为取决于已安装的 bridge、SSH 配置和 CIW 状态。 |
| 首次安装要下载 Python 依赖 | 需要包索引。更换 Python 解释器或本地仓库后,要重装或修复。 |
| UI 渲染依赖 DSH 版本和主题 | 面板通过客户端注册和源码检查验证,而不是逐像素验证。 |
报告问题
提交 issue 之前,先收集运行时已经记录下来的字段。它们能把猜测变成诊断。
| 字段 | 出现位置 |
|---|---|
| 阶段 | 运行时详情和工具错误中的失败阶段。 |
| SSH 后端 | OpenSSH 或 Paramiko,以及 SSH 端口。 |
| 守护进程状态 | 守护进程标签、daemonProbe 结论和弹窗检查。 |
| 错误码与提示 | 失败部署或启动给出的 errorCode、路径和提示。 |
请到 仓库 issue 跟踪页报告。贴出的内容一律先去掉 token、真实主机名、账号名和私有主目录路径;项目的发布检查正是为了拦截这类数据。
下一章
指南到此结束。总览页链接每一章和 Markdown 正本。