02 · 网络

连接与凭据

连接是 bridge 启动时使用的地址与权限。本章介绍保存的字段、两种守护进程模式、主机密钥信任、凭据、部署步骤,以及所有上传的落脚点:远程暂存根目录。

连接是什么

在 DeepSeek Harness(DSH)中,保存的连接不是一张表单,而是一项长期授权。启动它会在对应账号上打开 SSH(Secure Shell)会话和已签名的 bridge 守护进程,智能体随后可以运行 shell 命令、Python 和 SKILL(Cadence 的脚本语言)。因此,新增一行或修改现有行的 SSH 目标,都属于工作区之外的修改。

  • virtuoso_bridge_runtime 会通过 DSH 权限卡片请求批准,除非会话具备 完全权限(danger-full-access)。
  • 批准被拒绝或不可用即为终态。请改用配置页创建这一行,不要绕过。
  • SSH 目标不变、只改备注、暂存根目录、子实例或环境的保存,不需要批准。配置页自身的 保存 按钮由用户操作。
  • 不带 id 的保存会更新同名那一行,结果给出 updated 或 created。host、user、sshPort、jumpHost/jumpUser 或角色主机一变,插件就把现有行重定向到新目标。

两种模式共用其余所有字段。固定端口 连接指向一个稳定的守护进程端点并探测它;自动会话 连接发现已注册的守护进程,端口由操作系统分配。选哪个取决于 CIW(Virtuoso Command Interpreter Window)的 bootstrap 方式,与传输方式无关。

字段

配置页保持主要字段可见,并折叠高级网络设置、主机角色、shell 与 Cadence 环境、凭据以及工作目录子实例。save_connection 接受同样的字段名。

字段默认值说明
namehost,否则 connection显示名称,也是不带 id 保存时的键。
host必填SSH 目标。填回环主机即为本地连接。
user—SSH 账号;也是派生固定端口的输入。
sshPort22SSH 端点端口,与守护进程端口不同。
port由 user 派生固定模式的守护进程端口;autoSessions 为 true 时不使用。
autoSessionsfalse自动发现守护进程,端口由操作系统分配。
instancePort未设置select_instance 记下的已发现端口;重启之前先选定一个实例。
jumpHost、jumpUser空堡垒主机和可选账号。信任时 jump 主机的密钥会单独列出。
remoteWorkDir空绝对远端工作目录;在自动会话下它也是发现过滤器。
daemonSetup空由 virtuoso-bridge install-daemon 安装的共享 virtuoso_setup.il;对客户端只读。
sshBackendopensshopenssh 或 paramiko。
sshProxy空Paramiko SOCKS5 代理,socks5://host:port。
identityFile空为这条连接生成 SSH config,其中也包含用户自己的配置。
sshMaxSessions未设置高级 SSH 设置;映射到上游 SSH 会话上限。
localPort自动Host 托管隧道的本地端口;端口空闲时优先使用。
envShellautoauto、csh 或 sh。auto 会在两种 shell 下运行 Cadence 脚本,并保留能暴露 virtuoso 的那个。
cadenceEnvScript空为远端工作加载的 Cadence 环境脚本。
remoteScratchRoot全局默认建议使用绝对根目录;上传前会展开 ~/ 并解析符号链接。
clientId空随连接记录的可选客户端标识。
daemonHost、deployHost、guiHost、spectreHost空拆分主机拓扑的角色覆盖;见 拆分主机角色。
subInstances无带名称的绝对工作目录;见 工作目录子实例。
notes空随连接行保存的自由文本。

下面是一条完整的自动会话连接,save_connection 可直接接受:

connectionConfigJSON
{
  "name": "lab-virtuoso-auto",
  "host": "virtuoso01.example.com",
  "user": "designer",
  "autoSessions": true,
  "instancePort": null,
  "remoteWorkDir": "/projects/example",
  "daemonSetup": "/opt/virtuoso-bridge/v1/virtuoso_setup.il",
  "sshPort": 22,
  "jumpHost": "",
  "sshBackend": "openssh",
  "spectreHost": "",
  "envShell": "auto",
  "cadenceEnvScript": "/site/cadence/setup.csh",
  "identityFile": "C:\\Users\\me\\.ssh\\id_ed25519"
}

测试 报告四个层面:SSH、远端 Python、暂存根目录和守护进程端口。运行时停止时也会执行。启动 负责隧道和 sidecar。

固定端口与自动会话

固定端口

把 port 留空,插件就用 SSH 用户名派生出每个用户专属的稳定守护进程端口(SHA-1,范围 65000–65499),与 virtuoso_bridge.basic.bridge._default_remote_port 一致。CIW 侧的 setup 在这个端点上启动守护进程。固定端口的旧版部署在 CIW 重启后无法被发现,所以部署结果会带上 recommendedAutoSessions 和一行指引。

自动会话

启用 autoSessions 后,守护进程的端口由操作系统分配,port 不再起作用。插件发现已注册的守护进程,再按端口或工作目录选定一个。

在你保存选择之前,发现过程只读。没有选择或匹配到多个实例时,插件会列出候选并报错,而不是自己挑一个。select_instance 在重启之前把选中的端口记到连接上。发现在建立隧道之前执行,所以 Host 转发到的正是 sidecar 将要选定的实例。

这是部署层面的选择:固定端口为一个 CIW 提供稳定端点,自动会话则跟随已注册且被选中的实例。

部署前挂接

固定端口启动会先探测配置的端口。如果这个账号的守护进程以已签名的 capability 握手应答,运行时直接挂接,完全跳过部署,并在状态里报告 attach.attached 和复用的 setup 路径。找不到可挂接的守护进程时,运行时才准备暂存根目录、部署 setup。

所以暂存根目录损坏或缺失,都挡不住正在运行的实例 —— 别的客户端或机器部署的实例也一样。运行时 一章讲挂接的细节。

工作目录子实例

一条连接可以带一组工作目录子实例,每个都有名称和绝对远端工作目录。每个子实例都用自动会话启动,端口由操作系统分配,并且有自己的 VBL(virtuoso-bridge-lite)profile 和 sidecar。插件按工作目录发现它,而不是按固定端口。

  • 运行时面板为每个子实例显示一张卡片。运行时 id 为 rt_<connection>__<sub-instance>。
  • 工具调用通过 subInstance: "<id|name|/absolute/workdir>" 选定。
  • 于是一条连接就能覆盖多个项目 CIW,不用给每个都分配固定端口。

主机密钥与信任

首次连接时,插件读出对方提供的主机密钥,把它们的 SHA-256 指纹列出来,然后停在 needs-trust 状态。此时运行时有意不启动。

  • 探测的是 SSH 真正连到的端点。它会从 ~/.ssh/config 解析 HostName、Port 和 HostKeyAlias,所以即使保存了别名或非默认端口,也不会报出另一台服务器的指纹。
  • 每个指纹都标明所属主机,jump 主机的密钥单独标记。
  • 用户确认之前,插件不会信任或写入任何密钥。确认途径有两个:运行时面板上的按钮,或你确认指纹后调用 trust_host。一次信任调用只能选择刚刚那次探测实际提供的密钥;参数不决定写入内容。
  • 确认信任后,插件把这一个密钥写进 ~/.ssh/known_hosts,两个可能的查询名都会写上。OpenSSH 用保存的别名,Paramiko 用解析出来的主机名。
结果含义如何处理
某种密钥类型缺失 主机通常会提供多种类型(ed25519、ecdsa、rsa),而 known_hosts 通常只包含其中一部分。 这是未信任,不是密钥变更。只要有一种类型已信任,主机就能正常启动。生成的 config 会把 SSH 固定到已信任的类型。
同一类型出现了不同密钥 这台主机已信任的密钥发生了变化。 这是冲突。插件绝不会自动替换它。请复核并用 ssh-keygen -R <host> 删除过期条目,然后重新启动。
首次连接 尚未信任任何密钥。 needs-trust。确认指纹后重新启动。
删除变更的密钥SHELL
ssh-keygen -R virtuoso01.example.com
信任是显式决定,不是默认行为

只要有活跃的智能体会话,同样的确认会以问题形式出现在会话里,不必打开右侧边栏。启动失败时,运行时面板和工具错误会报告阶段、SSH 与守护进程输出、traceback 以及主机密钥探测结果。

凭据与认证

层存放位置说明
守护进程 token DSH credentials 服务,作为 grant 记录 可选。在 UI 中只写,面板、工具和日志绝不会返回它。通过 sidecar 环境传入。
SSH 认证 系统 SSH 配置(agent、密钥、~/.ssh/config)或 Paramiko identityFile 会为每条连接生成 SSH config,其中包含用户自己的配置。
远端环境 cadenceEnvScript 加上缓存的 shell 检测 envShell: "auto" 会尝试 csh 和 sh,并保留能暴露 virtuoso 的那个。结果按连接缓存,可用 detect_shell 刷新。
本地连接 本地 bridge token 文件 localhost、127.0.0.1 和 ::1 会跳过 SSH,并像 virtuoso-bridge 本地模式一样使用这个文件。

已保存的 token 只显示为“已保存”,可以清除。插件绝不会读回它的值。面板、工具和日志都遵循同一条规则。

凭据隔离是有意设计。插件绝不复制用户的 ~/.virtuoso-bridge/.env;导入 virtuoso_bridge 之前,插件用一个空的运行时 env 文件把每个 Python helper 与这个文件隔开。helper 以 -E -s 从插件 venv 启动,不继承 PYTHONPATH、PYTHONHOME、VIRTUAL_ENV,也拿不到环境里已有的 VB_* 值。只要 virtuoso_bridge 不是来自插件 venv,venv 探测会拒绝报告就绪,唯一例外是显式配置的 editable 本地 checkout。

守护进程部署

部署守护进程设置 只准备并上传生成的 account bootstrap。它不启动隧道,不启动或连接守护进程,也不加载 SKILL。部署成功后,复制返回的那一行,到目标空闲 CIW 里加载:

Virtuoso CIWSKILL
load("/path/to/virtuoso_setup.il")

每个连接行都有这个控件;同样的动作也可以直接调用 virtuoso_bridge_runtime 的 deploy_daemon,replace: true 是覆盖生成文件的显式升级路径。要做站点级 bootstrap,就在 Linux Cadence 主机上用 virtuoso-bridge install-daemon <versioned-directory> 安装上游共享 bundle,再把 daemonSetup 指向打印出的 virtuoso_setup.il。所有自动会话客户端共用这一份 setup。修改客户端环境,无法追溯更新已在运行的 CIW。

结果含义
返回的加载行要在空闲 CIW 中加载的确切行。覆盖后,加载新返回的行。
recommendedAutoSessions在固定端口的旧版部署上设置,并附带指引。这种部署在 CIW 重启后无法被发现,所以长期使用时建议选择自动会话或共享的 install-daemon setup。
errorCode、path、hint部署失败会带上路径与补救方法,例如根目录在主目录之外且缺失时,需要执行的 mkdir -p -m 700。

冲突

如果远端生成的 bundle 与当前 bundle 不一致,普通部署 不会 覆盖它。面板会给出新包版本和插件现用的包版本(已知时),以及现有守护进程版本(已知时);未知则显示 version unknown,并附上后端的冲突详情。

只有用户明确点击红色的 覆盖 按钮,才允许替换,旧 bundle 会留作备份。用 daemonSetup 或 install-daemon 配好的共享 setup 对客户端只读,客户端无法替换。

超时

部署走 SSH,耗时可能超过 dashboard 较短的状态轮询预算。dashboard 为长时间操作单独设置了 timeout,并让打印出的 setup 路径和加载行一直可见。不要仅因为浏览器请求超时就重试部署。

插件不会复用监听在其他端口上的旧版守护进程:守护进程探测会报 no-listener 或 legacy。按提示操作:先部署,再到目标空闲 CIW 中加载返回的那一行,然后重新启动。

重启不是部署

重连或普通重启不会部署文件,也不会重新加载 setup。若 setup 从未加载,先执行打印出的 load("...") 行。只有确认问题出在环境而不是 CIW 时,才需要重装。运行时 介绍了生命周期。

远程暂存根目录

远端暂存根目录是部署、发现、shell 和脚本的写入位置。默认设置 里存着全局默认值,连接自己的 remoteScratchRoot 可以覆盖它。这个值会作为 VB_REMOTE_SCRATCH_ROOT 传给 helper,所以部署和运行时用的是同一个根目录,不会退回 /tmp。

  • 开头的 ~/ 会在远端账号上展开,符号链接会解析成真实目录。每个 helper 以及每一次脚本或 IL 上传,拿到的都是解析后的绝对路径。
  • 建议直接写绝对根目录。Virtuoso 的 load() 不展开 ~,所以带 ~ 的 IL 路径在第一次 load() 就会失败。IC23.1 这类站点和 pack 正是需要固定绝对站点路径的常见场景。~/ 依然可用,并会在任何上传之前展开。
  • 不管固定端口还是自动会话,部署之前插件都会先检查根目录。账号主目录下缺失的根目录,插件会按 0700 创建;存在只差 _ 和 - 的兄弟路径时给出警告;权限过宽但属主正确的根目录,插件会收紧权限;符号链接、属主错误、非目录,以及主目录之外的缺失路径,各自给出明确的错误信息。
部署结果字段说明
configuredScratchRoot连接上配置的值,或全局默认值。
scratchRoot解析后的绝对根目录,实际用于上传和加载路径。
scratchCreated、scratchTightened根目录是否以 0700 创建,插件是否收紧了权限。
warning非致命提示,例如仅 _ 与 - 不同的兄弟路径。

主目录之外的缺失根目录,插件不会创建;错误信息会写明路径和补救办法,例如:

可操作的提示SHELL
mkdir -p -m 700 /projects/example/.virtuoso-bridge
"load: can't access file - ~/..."

首次 IL 加载报出这条消息,说明带 ~ 的路径传到了 Virtuoso —— load() 不展开 ~。在远端账号上配置绝对的 remoteScratchRoot,或保留 ~/ 让插件解析。部署、客户端上传和 IL 上传都不会把 ~ 传给 load()。

拆分主机角色

高级连接可以把角色拆分到多台主机上。主机密钥预检和 SSH 测试只针对主 host;要用拆分拓扑,先用 ssh 和 known_hosts 信任各角色主机的密钥。

角色字段路由
守护进程主机daemonHost运行 bridge 守护进程的 CIW 侧。
部署主机deployHost部署与上传。
GUI 主机guiHost显示与 X11 侧。
Spectre 主机spectreHostSpectre 仿真侧。

高级字段的其余部分映射到上游的拆分主机、私有暂存和代理设置:remoteScratchRoot、clientId、sshMaxSessions,以及 Paramiko 的 sshProxy(socks5://host:port)。