连接与管理 Engine¶

English · 上一章：物理输入 · 下一章：光学与跟踪

Studio 使用系统 OpenSSH 连接 Linux Engine。它不保存 SSH 密码、Authenticator 动态码或私钥；OpenSSH 读取 host alias、密钥和 agent 配置。新目标默认使用“托管隧道”：Studio 持有一个前台 SSH 会话；随应用打包的 headless vm-accelerator-studio-ssh-askpass shim 通过每次 attempt 独有的私有本地通道，把 OpenSSH 提示交给应用内 broker/dialog。回答只返回本次 OpenSSH attempt，不会持久保存；之后所有 Engine RPC 复用这次认证。只有在 SSH 登录完全无需提示时，才建议使用保留的 “每 RPC 一次 SSH”模式。

准备 SSH¶

一个可直接改写的 ~/.ssh/config 例子：

Host vma-engine-v07
    HostName accelerator.example.org
    User beamuser
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

Engine 管理员可在终端诊断该 alias：

ssh vma-engine-v07 true
ssh vma-engine-v07 command -v vm-accelerator-engine

这些命令只是可选诊断，不是普通用户的连接步骤；认证窗口由 Studio 自己打开。第二条只确认路径存在，不确认 Studio 协议和物理能力。

Windows 本机需要启用 Windows OpenSSH Client，并保证 ssh.exe 在 PATH 中。托管模式使用只指向一个远端目标的标准本地端口映射（-L），不依赖 -M、-f、-N 或 ControlMaster；macOS 和 Linux 使用同一方案。远端 Engine 主机仍为 Linux。

新增计算目标¶

打开 Settings → Execution targets → Add…：

字段	普通路线示例	说明
Display name	`Touschek Engine v0.7`	本机可读名称
SSH host alias	`vma-engine-v07`	必须是安全的 OpenSSH host token
SSH connection mode	`Managed tunnel (interactive MFA)`	推荐的持久会话；只有无提示登录才选 per-RPC
Engine executable	`/opt/vma-v07/bin/vm-accelerator-engine`	托管模式必须填写远端绝对路径且不能含空格或 shell 元字符；同目录必须有该环境的 `python` 可执行文件
Connect timeout	`10 s`	1–300 秒

v0.9 轨道修正不再增加目标字段。Studio 在内部提供已接受的 source revision 和 build ID，在专用握手中校验两者，并让 Engine 选择当前主体的默认 state root。已有目标若保存过旧版的显式 v0.9 state binding，仍会继续使用，以保证保留任务可以重连。

经审查的 Engine snapshot installer 会生成上述 launcher 与同目录 Python 布局；只有一个孤立的 Engine 脚本还不能构成完整的托管隧道部署。

一个目标只是本机路由配置，不包含密码、MFA 响应、私钥、gateway session token 或任务重连 token。远端 gateway 只绑定 127.0.0.1，Studio 的窄化本地映射也只绑定本机 127.0.0.1 且只能到达该 gateway；端口和 256-bit session token 仅存于内存。Disconnect 会结束该 SSH 会话拥有的 gateway，但不会取消已接受的持久任务。删除目标也不会修改远端主机或远端任务。

Studio 何时会联系目标¶

普通启动始终不联网。启动、载入项目、发现本地 journal、选中 target 或修改草稿，都不会执行 ssh -G、开始 SSH 认证、探测 Engine、恢复 pending submission 或对账远端 registry。

每次计算遵循同一顺序：

计算按钮先打开 Choose computation source（选择计算源），此时不联系任何目标。
取消窗口不会启动 SSH，也没有远端副作用。
确认 检测计算源（Check source） 后，Studio 才获准检查所选 SSH 路径、按需认证并检查 Engine ready。
具体工作流还会执行精确能力与项目验证，成功后才 Evaluate 或 Submit。普通 Engine 检查成功不代表所有专用路线都兼容。

两种测试不能混淆¶

托管模式下，显式点击 Connect 才会通过应用内 dialog 显示 OpenSSH 所需的每个认证提示，然后保持私有隧道和当前 SSH 用户的 gateway；显示 Connected 仍不代表 Engine 协议可用。Disconnect 释放该会话。旧 per-RPC 模式的 Test SSH 只检查无提示认证和远程命令执行。
Test Engine 会在需要时先自动 Connect，再执行 Hello/Capabilities 协商，检查协议、 CPU、权限、限制和能力摘要。只有成功后才可称为 Engine ready。

如果站点规定每次 SSH 登录都必须输入新的 Authenticator 动态码，托管模式会在每个 Studio 会话认证一次，而不是每个 RPC 都认证。网络中断或主动 Disconnect 后，下次 Connect 或 Test Engine 会再次弹出认证序列。

取消计算源窗口不会启动任何进程。取消活动认证、SSH 启动超时或点击 Disconnect 时，界面会立即让本次 attempt 失效；Studio 在后台异步结束其配置/SSH 进程，先请求 terminate，有界宽限期后再 kill。界面不会同步等待 OpenSSH 退出，已退役 attempt 的迟到消息也不能让连接变成 Ready。

v0.7–v0.18 专用页面还会做自己的精确能力、来源与部署检查。v0.1 Engine 测试成功不代表每个高版本路线都能运行。

为什么建议为不同 Engine 构建创建不同目标¶

部分正式路线要求精确的 Engine source revision。一个可执行文件只有一个 source identity；不要把不同已接受版本的路径覆盖成同一个 target。推荐配置例如：

显示名	可执行文件	用途
`Engine nonlinear v0.8`	`/opt/vma-5253/bin/vm-accelerator-engine`	持久非线性
`Engine orbit v0.9`	`/opt/vma-3b14/bin/vm-accelerator-engine`	持久轨道修正，身份自动校验
`Engine native v0.11–v0.17`	`/opt/vma-ecd9/bin/vm-accelerator-engine`	attached Xsuite 精确源一次性分析
`Engine nonlinear v0.18 CUDA`	`/opt/vma-e967/bin/vm-accelerator-engine`	一 GPU Slurm/CUDA 持久非线性

其他组合应以 Engine 管理员提供的已接受构建为准，不要把“更晚 commit”自动理解为兼容。

任务凭据和重启恢复¶

持久任务被接受后，Studio 保存不含秘密的 job bookmark，并把 reconnect token 放入操作系统凭据库：macOS Keychain、Windows Credential Manager 或 Linux Secret Service。Token 不进入 .vmaproj、项目 JSON 或普通设置。

启动时 Studio 只在本地读取 bookmark 和 pending journal，不会自动连接、恢复或对账。显式 pending recovery 会先请求用户确认；确认后，Studio 只连接 journal 记录的原 target，并用原 idempotency key 精确 replay。恢复不会提供另一个计算源；取消确认则不建立连接。若凭据库不可用，远端任务可能仍在运行，但 Studio 会显示 credential missing 并拒绝伪造重连。

普通启动本身已经不联网；--offline 用于明确标记离线审阅的策略/状态。如果整个会话都必须离线，不要执行任何显式远端操作。

Detach、Abort 和 Cancel 的区别¶

Detach：停止本次观察；远端持久任务继续运行。
Abort client：终止一次性本地/SSH 客户端进程；不是 Engine 持久取消承诺。
Cancel request：向持久任务请求合作式取消。请求被接受、worker 确认和终态取消是三个不同状态。

退出 Studio 不会自动取消已提交的持久任务。

Engine 管理员交付清单¶

向用户至少提供：SSH alias、Engine executable、支持的工作流版本、精确 source revision/build、必要的 state directory、主体权限和大致资源/时长预期。不要只交付一个“SSH 能连”的结论。