8. 远程 / SSH / HPC 部署配方
很多时候，数据和算力在远程服务器或 HPC 上，而你想在本地笔记本操作。本章以最常见的 「服务器算、本地浏览器看」 为主线，给出可直接复制的分步命令；末尾再补几个其他场景。
两条贯穿全章的底线：
- kernel（算力）跑在哪台机器，和你从哪台机器操作 UI，是两件独立的事。
- omicos kernel 默认只监听
127.0.0.1（本机回环），不对外开放。所有远程访问方案，本质上都是"想办法把流量送到 kernel 所在那台机器的 loopback 上"。
HPC 标准流程：服务器算、本地浏览器看
照下面四步走（第四步可选）。kernel 调用全程留在远端，零云端中继，带宽和延迟最低。
第一步 · 在服务器上安装 omicos（需高于 0.2.29）
SSH 到服务器（HPC 就是登录节点），用 npm 全局安装，并确认版本：
$ npm install -g @omicverse/omicos
$ omicos --version
omicos 0.2.30
版本必须高于
0.2.29——第二步的omicos hpc向导需要它。低于这个版本先升级：npm install -g @omicverse/omicos@latest。
第二步 · 在服务器上选环境并启动（omicos hpc）
omicos hpc 是专为服务器 / HPC 设计的交互式向导：列出机器上所有 Python 环境并标注是否就绪 → 让你选 → 可设为默认 → 启动。第一次运行：
$ cd ~/my-analysis
$ omicos hpc
Select a Python environment for the OmicOS kernel
1) /home/users/you/miniforge3/bin/python3 [✓ ready]
2) /home/users/you/miniforge3/envs/omicverse/bin/python3 [✓ ready]
…
9) /scratch/users/you/env/navigo/bin/python3 [✗ missing: omicverse]
12) /scratch/users/you/envs/dynast/bin/python3 [✗ missing: omicverse, ipykernel]
…
17) [default] OmicOS bundled env (~1.5 GB) → /home/users/you/.omicos/env [will download]
18) Enter a Python path manually
Enter number [1-18]: 2
Make this the default startup env? [Y/n] Y
✓ saved — .kernel_choice + `export OMICOS_KERNEL_PYTHON` in /home/users/you/.bashrc
✓ kernel env ready: /home/users/you/miniforge3/envs/omicverse/bin/python3
- 每个环境后标
[✓ ready]（已装omicverse+ipykernel）或[✗ missing: …]（缺哪些包）——选[✓ ready]的最省事。 17) [default]= 内置环境（~1.5 GB，首次下载）；18)= 手动输入解释器路径。- 选完问
Make this the default startup env?，选Y会写入.kernel_choice并在~/.bashrc里export OMICOS_KERNEL_PYTHON——之后再启动自动复用这个环境、不再询问（想换用omicos hpc --reselect）。 - 选完向导直接进入运行面板（监听
127.0.0.1:5055）。要改绑定地址，按q退出再带参数重跑即可（环境已记住）；加--no-browser可省去服务器上 “failed to open browser” 的无害提示。
强烈建议先跑一遍
omicos hpc把环境定下来再连——否则首次启动现装环境，大集群磁盘慢时网页会长时间卡在「首次启动正在准备运行环境」。
第三步 · 在本地做端口转发，打开浏览器
kernel 在服务器上跑着（监听 127.0.0.1:5055）。现在把笔记本的一个端口接到它上面。怎么接，取决于你能不能直接 SSH 到跑 kernel 的那台机器。
情形 1：能直接 SSH 到跑 kernel 的机器（普通服务器 / 登录节点）
$ ssh -N -L 15055:127.0.0.1:5055 user@your-server
-N只建隧道、不开 shell，命令会"挂住"不动——这是正常的，保持窗口开着即可。-L 15055:127.0.0.1:5055：左边15055是笔记本端口（被占就换成任意空闲端口），右边127.0.0.1:5055是远端机器自己的 loopback（kernel 所在）。- 想知道本机哪个进程占了某端口：
lsof -nP -iTCP:15055 -sTCP:LISTEN。
情形 2：真 HPC——登录节点 + 计算节点
真正的 HPC（如 Stanford Sherlock）：你从笔记本只能 SSH 到登录节点，而第二步的 omicos hpc 通常跑在计算节点（用 salloc / srun / sbatch 申请，如 sh04-05n13，不对公网开放）。先在跑 omicos 的那个终端确认节点名：
$ hostname
sh04-05n13
你可能想用 ProxyJump（-J），但在 Sherlock 计算节点上通常会失败：
$ ssh -N -L 15055:127.0.0.1:5055 -J user@login.sherlock.stanford.edu user@sh04-05n13
user@sh04-05n13: Permission denied (hostbased)
为什么：用 -J 时，到计算节点那段 SSH 是你笔记本发起的，而计算节点只认"从登录节点发起"的 hostbased 连接，不认你的笔记本。Jupyter 不踩这个坑——它让登录节点直接 TCP 连计算节点上已开放的端口（不二次 SSH），前提是服务绑在节点网卡上。于是有两条路。
方法一：照 Jupyter（绑节点网卡 + 单段转发）。 在计算节点上加 --host 0.0.0.0 启动——第二步已存了默认环境，这次直接复用、不再问：
$ omicos hpc --host 0.0.0.0
✓ using saved default env: /home/users/you/miniforge3/envs/omicverse/bin/python3
(run `omicos hpc --reselect` to choose a different env)
然后在笔记本上（和 Jupyter 一模一样，注意右边是节点名）：
$ ssh -N -L 15055:sh04-05n13:5055 user@login.sherlock.stanford.edu
⚠️
--host 0.0.0.0会把 kernel 暴露在计算节点网卡上。独占节点风险有限；共享节点请用方法二（kernel 不出 loopback），或用--host $(hostname)只绑节点内网 IP 并尽量申请独占节点。
方法二（共享节点更安全）：两段 SSH 隧道。 kernel 保持默认的 127.0.0.1，关键在于第二段从登录节点发起（hostbased 才认）。计算节点上正常 omicos hpc（绑 127.0.0.1），然后在笔记本上连登录节点：
$ ssh -L 15055:localhost:15055 user@login.sherlock.stanford.edu
进入登录节点后，在它的提示符里再跳计算节点：
$ ssh -N -L 15055:localhost:5055 sh04-05n13
链路：笔记本:15055 → 登录节点:15055 → 计算节点:5055（kernel）。两段都起来后再开浏览器。kernel 不出 loopback，登录→计算那段是加密 SSH 隧道。
打开浏览器
隧道起来后，本机浏览器打开（端口换成你转发的本机端口）：
https://app.omicos.cn/#/?ws=localhost%3A15055&auto=true
ws=localhost:15055（%3A是冒号的转义）指向你本地转发的端口；auto=true自动连。- 网页端会自动探测本机
5051–5070；用区间外端口（如15055）就必须显式写?ws=。 - ⚠️ kernel 运行面板里 Browser 那行显示的是
…?ws=127.0.0.1%3A5055（直连场景的建议地址）；做了端口转发就别照抄它——端口要换成你转发的本机端口（这里是15055）。
第四步（可选）· 指定端口运行
默认端口是 5055。如果服务器上 5055 被占、或你想在同一台机器跑多个实例，用 --port 指定：
$ omicos hpc --port 5060
然后本地转发对应到这个端口（右边改成 5060，左边仍是任意空闲的本机端口）：
$ ssh -N -L 15055:127.0.0.1:5060 user@your-server
浏览器 ?ws= 依然指向本机端口（15055，不是服务器的 5060）：
https://app.omicos.cn/#/?ws=localhost%3A15055&auto=true
计算节点 + 自定义端口同理：方法二把两段命令里的
5055换成5060；方法一把sh04-05n13:5055换成sh04-05n13:5060，启动加--host 0.0.0.0。
其他场景
纯终端 TUI（不开浏览器）
SSH 进了没有图形界面的机器，全程终端搞定——登录和聊天都不需要浏览器：
$ omicos login
$ cd ~/my-analysis
$ omicos cli
不方便在这台机器输入密码？改用
omicos cli login设备码配对，在另一台已登录 omicOS 的设备上确认配对码。
本机笔记本 + 浏览器
数据和分析都在本机，最简单：
$ cd ~/my-analysis
$ omicos login
$ omicos serve
监听 127.0.0.1:5055 并自动开浏览器到 app.omicos.cn。
让进程在后台长期存活
普通服务器上，你通常希望 omicos 在断开 SSH 后继续跑（都配 --no-browser）：
$ nohup omicos serve --no-browser > omicos.log 2>&1 &
$ disown
或 tmux / screen：
$ tmux new-session -d -s omicos 'cd ~/my-analysis && omicos serve --no-browser'
$ screen -dm -S omicos bash -c 'cd ~/my-analysis && omicos serve --no-browser'
systemd 服务的 ExecStart：
ExecStart=/usr/local/bin/omicos serve --no-browser
（omicos 检测到非 TTY 环境会自动不画仪表盘、日志走 stderr，适配 systemd journal。）
⚠️ 调度型 HPC（SLURM 等）不一样：kernel 跑在
salloc/srun/sbatch申请到的计算节点上，作业一结束 kernel 就没了——登录节点上的 tmux / nohup 救不了它。长时间运行请用sbatch把omicos serve --host 0.0.0.0 --no-browser（或omicos hpc）写进作业脚本并申请足够的墙钟时间，或保持salloc会话不退。
健康检查与冒烟测试
在 kernel 所在机器上确认服务正常：
$ curl -sS http://127.0.0.1:5055/health
{"service":"omicos-core","status":"ok","version":{"semver":"0.2.x"}}
$ curl -sS http://127.0.0.1:5055/api/process/info
{"name":"OmicOS Core","runtime":"rust","version":"0.2.x"}
/api/process/info响应里没有status字段；未登录 / 终端启动时id、process_id、process_name为空串。 隧道起来后想在笔记本上验证，把端口换成你的本机转发端口：curl -sS http://127.0.0.1:15055/health。连不上 99% 是节点名写错、kernel 没在那台机器、或 SSH 窗口断了。
一个注意点：账户切换会触发自愈重启
如果在一个工作区里切换登录账户，云端会以 WebSocket 关闭码 4403 通知，omicos 会旋转 workspace_id 并自动重启自己。这看起来像崩溃，实际是预期的恢复行为。代价是会话同步的高水位被清空，新账户下会话列表可能显示为空（本地旧会话文件仍在）。详见故障排查。
故障：网页一直卡在「首次启动」banner
端口转发连上了、但网页一直显示「首次启动正在准备运行环境」然后卡死，多半是这两类原因：
- 环境还没准备好：首次启动会同步引导 Python 环境（解压 / 装包），大集群磁盘慢时会很久。最佳实践：先
omicos hpc（或omicos env setup）把环境装好，再 serve，别让首次启动现装。 - 连错端口 / kernel 不在预期机器上：确认隧道的本机端口和浏览器
?ws=一致，且 kernel 确实在隧道对端那台机器的端口上（用上面的curl /health验证）。
更多排查见第 14 章：故障排查。