连接与管理 Engine¶

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

Studio 使用系统 OpenSSH 连接 Linux Engine。它不保存 SSH 密码或私钥；认证来自你的 ~/.ssh/config、密钥和 agent。Engine 不是常驻网页服务，Studio 为每个操作启动受控的 SSH/stdio 进程。

准备 SSH¶

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

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

先在终端确认：

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

第二条只确认路径存在，不确认 Studio 协议和物理能力。

新增计算目标¶

打开 Settings → Execution targets → Add…：

字段	普通路线示例	说明
Display name	`Touschek Engine v0.7`	本机可读名称
SSH host alias	`vma-engine-v07`	必须是安全的 OpenSSH host token
Engine executable	`/opt/vma-v07/bin/vm-accelerator-engine`	远端绝对路径或命令名；不能含空格和 shell 元字符
Connect timeout	`10 s`	1–300 秒

v0.9 轨道修正还要求三项一起填写：专用绝对 state directory、精确 40 位小写 Engine source revision 和 build ID。只要填写其中一项，其他两项就不能留空。普通 v0.1–v0.8 目标可以把这三项全部留空。

一个目标只是本机路由配置，不包含密码、私钥或重连 token。删除目标也不会修改远端主机或远端任务。

两种测试不能混淆¶

Test SSH：检查 SSH 身份验证和远程命令执行。显示 SSH ready 时，Engine 可能仍不可用。
Test v0.1 Engine：执行 Hello/Capabilities 协商，检查协议、CPU、权限、限制和能力摘要。只有成功后才可称为 Engine ready。

v0.7、v0.8 和 v0.9 等专用页面还会做自己的精确能力检查。v0.1 Engine 测试成功不代表每个高版本路线都能运行。

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

部分正式路线要求精确的 Engine source revision。尤其 v0.8 非线性当前要求 Engine 5253d675…，v0.9 轨道修正要求 3b14dbcc…，一个可执行文件不能同时具有两个 source identity。推荐配置例如：

显示名	可执行文件	用途
`Engine nonlinear v0.8`	`/opt/vma-5253/bin/vm-accelerator-engine`	持久非线性
`Engine orbit v0.9`	`/opt/vma-3b14/bin/vm-accelerator-engine`	持久轨道修正，并填写 v0.9 三项

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

任务凭据和重启恢复¶

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

正常启动时 Studio 可恢复未完成任务并对账。--offline 会关闭自动恢复。若凭据库不可用，远端任务可能仍在运行，但 Studio 会显示 credential missing 并拒绝伪造重连。

Detach、Abort 和 Cancel 的区别¶

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

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

Engine 管理员交付清单¶

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