8. 远程 / SSH / HPC 部署配方

数据和算力在远程服务器或 HPC 上，想在本地笔记本操作。主线是「服务器算、本地浏览器看」。下面给出可直接复制的分步命令，末尾补几个其他场景。

两条贯穿全章的底线：

kernel（算力）跑在哪台机器和你从哪台机器操作界面，是两件独立的事。

omicos 默认只监听 127.0.0.1，不对外开放。所有远程访问方案，本质都是「把流量送到 kernel 所在那台机器的回环地址」。

HPC 标准流程：服务器算、本地浏览器看

照下面四步走（第四步可选）。kernel 调用全程留在远端，带宽和延迟最低。

第一步 · 在服务器上安装 omicos

SSH 到服务器（HPC 就是登录节点），用 npm 全局安装，确认版本：

$ npm install -g @omicverse/omicos
$ omicos --version

预期输出：

omicos 0.3.29+a1b2c3d

第二步的 omicos hpc 向导需要 0.3.29 或更高。版本低了先升级：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                      [✗ missing: omicverse]
  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

随后终端切换到全屏运行面板，Local 那一行显示实际监听地址 http://127.0.0.1:5055。

每个环境后面标 [✓ ready]（已装 omicverse + ipykernel）或 [✗ missing: …]（缺哪些包）。选 [✓ ready] 最省事。选了缺包的，向导会问要不要现在补装。
倒数第二项是内置环境（约 1.5 GB，首次下载）；最后一项是手动输入解释器路径。
选完问 Make this the default startup env?。答 Y 会写入 .kernel_choice，并在 ~/.bashrc 里加 export OMICOS_KERNEL_PYTHON。之后再启动自动复用这个环境、不再询问（想换用 omicos hpc --reselect）。
选完向导直接进入运行界面（监听 127.0.0.1:5055）。改绑定地址，退出后带参数重跑即可（环境已记住）。加 --no-browser 省去服务器上「打不开浏览器」的无害提示。

第二次运行时不会再问：

$ omicos hpc

预期输出：

✓ using saved default env: /home/users/you/miniforge3/envs/omicverse/bin/python3
  (run `omicos hpc --reselect` to choose a different env)

之后同样进入全屏运行面板，监听 127.0.0.1:5055。

强烈建议先跑一遍 omicos hpc 把环境定下来再连——否则首次启动会在后台现装环境，大集群磁盘慢时网页里跑分析会长时间提示「环境正在准备中」。

omicos hpc 是交互式的。在没有终端的批处理脚本里跑它会直接报错，提示改用 OMICOS_KERNEL_PYTHON=/path/to/python + omicos serve。

第三步 · 在本地做端口转发，打开浏览器

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 是远端机器自己的回环地址（kernel 所在）。
查本机哪个进程占了某端口：lsof -nP -iTCP:15055 -sTCP:LISTEN。

情形 2：真 HPC——登录节点 + 计算节点

真正的 HPC（如 Stanford Sherlock）：你从笔记本只能 SSH 到登录节点，第二步的 omicos hpc 通常跑在计算节点（用 salloc / srun / sbatch 申请，不对公网开放）。先在跑 omicos 的终端确认节点名：

$ hostname

预期输出：

sh04-05n13

你可能想用 ProxyJump（-J），但在计算节点上通常会失败：

$ 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)

随后进入运行面板，Local 一行显示 http://0.0.0.0:5055。

然后在笔记本上（注意右边是节点名，不是 127.0.0.1）：

$ ssh -N -L 15055:sh04-05n13:5055 user@login.sherlock.stanford.edu

预期输出：没有输出，命令挂住。

⚠️ --host 0.0.0.0 会把 kernel 暴露在计算节点网卡上。独占节点风险有限；共享节点请用方法二（kernel 不出回环），或用 --host $(hostname) 只绑节点内网 IP 并尽量申请独占节点。

方法二（共享节点更安全）：两段 SSH 隧道。 kernel 保持默认 127.0.0.1，关键在于第二段从登录节点发起。计算节点上正常跑 omicos hpc，然后在笔记本上连登录节点：

$ ssh -L 15055:localhost:15055 user@login.sherlock.stanford.edu

预期输出：正常进入登录节点的 shell 提示符。

进入登录节点后，在它的提示符里再跳计算节点：

$ ssh -N -L 15055:localhost:5055 sh04-05n13

预期输出：没有输出，命令挂住。

链路：笔记本:15055 → 登录节点:15055 → 计算节点:5055（kernel）。两段都起来后再开浏览器。kernel 不出回环，登录→计算那段是加密 SSH 隧道。

打开浏览器

隧道起来后，本机浏览器打开（端口换成你转发的本机端口）：

https://app.omicos.cn/#/?ws=localhost%3A15055&auto=true

ws=localhost:15055（%3A 是冒号的转义）指向本地转发端口；auto=true 表示自动连接。
网页端会自动探测本机 5051–5070；用区间外的端口（如 15055）就必须显式写 ?ws=。
⚠️ omicos 在服务器终端里打印的 opening: 那行是直连场景的地址（?ws=127.0.0.1%3A5055）。做了端口转发就别照抄它——端口要换成你转发的本机端口（这里是 15055）。

第四步（可选）· 指定端口运行

默认端口是 5055。服务器上 5055 被占，或想在同一台机器跑多个实例，用 --port 指定：

$ omicos hpc --port 5060

预期输出：

✓ using saved default env: /home/users/you/miniforge3/envs/omicverse/bin/python3
  (run `omicos hpc --reselect` to choose a different env)

随后进入运行面板，Local 一行显示 http://127.0.0.1:5060。

端口未必是你指定的那个。 指定的端口被占时，omicos 会从下一个端口开始向后找（最多 100 个），并打印一行 [omicos] port 5060 was busy; using 5061 instead。永远以 listening: 那行为准再去配转发。写脚本的话加 --report-port，它会额外打印一行 OMICOS_LISTENING_PORT=5061 供程序读取。

然后本地转发对应到这个端口（右边改成实际端口，左边仍是任意空闲的本机端口）：

$ 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 换成实际端口；方法一把 sh04-05n13:5055 换成 sh04-05n13:<实际端口>，启动加 --host 0.0.0.0。

其他场景

纯终端（不开浏览器）

SSH 进没有图形界面的机器，全程终端搞定。登录和聊天都不需要浏览器：

$ omicos login
$ cd ~/my-analysis
$ omicos cli

预期输出：omicos login 打印 [omicos] logged in as … 三行（见第 5 章），omicos cli 把终端切换到全屏聊天界面。

不方便在这台机器输入密码？改用 omicos cli login 设备码配对，在另一台已登录 omicOS 的设备上确认。

本机笔记本 + 浏览器

数据和分析都在本机，最简单：

$ cd ~/my-analysis
$ omicos login
$ omicos serve

预期输出：omicos login 打印登录信息三行，omicos serve 进入全屏运行面板并自动打开浏览器到 https://app.omicos.cn/#/?ws=127.0.0.1%3A5055&auto=true。

让进程在后台长期存活

普通服务器上，通常希望 omicos 在断开 SSH 后继续跑（都配 --no-browser）：

$ nohup omicos serve --no-browser > omicos.log 2>&1 &
$ disown

预期输出：shell 打印一行作业号（如 [1] 41287）后立即返回；启动横幅写进了 omicos.log：

[omicos] online: my-analysis (local-9f2c4d7a1b8e4f5c8d3a6b0e2f7c1a94)
[omicos] listening: http://127.0.0.1:5055

或用 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'

预期输出：两条命令都没有输出，进程在后台会话里运行（tmux attach -t omicos 可以进去看）。

systemd 服务的 ExecStart：

ExecStart=/usr/local/bin/omicos serve --no-browser

（omicos 检测到不是交互终端时，自动不画仪表盘、日志走 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":{"build_profile":"release","display":"0.3.29+a1b2c3d","git_rev":"a1b2c3d","semver":"0.3.29","target_triple":"x86_64-unknown-linux-musl"}}

$ curl -sS http://127.0.0.1:5055/api/process/info

预期输出（节选）：

{"core_workspace_root":"/home/users/you/my-analysis","hostname":"sh04-05n13","id":"local-9f2c4d7a1b8e4f5c8d3a6b0e2f7c1a94","kernel":"native-python-worker","launched_by":"terminal","name":"my-analysis","pid":41287,"port":5055,"process_id":"local-9f2c4d7a1b8e4f5c8d3a6b0e2f7c1a94","runtime":"rust","version":"0.3.29", …}

/api/process/info 响应里没有 status 字段（那是 /health 的）。hostname 这一行很有用，它告诉你 kernel 到底跑在哪台机器上，隧道搭错时一眼就能看出来。

隧道起来后在笔记本上验证，把端口换成本机转发端口：

$ curl -sS http://127.0.0.1:15055/health

预期输出：与上面在服务器上执行时完全一致。拿不到响应，99% 是节点名写错、kernel 没在那台机器、端口不是你以为的那个、或 SSH 窗口断了。

从网页端管理 SSH 连接

上面是手工搭隧道的做法（在 HPC 上仍然最可靠）。日常用普通服务器时，UI 的设置 · 连接页可以直接管理这件事：

同时连多台远端：保存多台主机，各自独立连接；对话可以按主机过滤（见第二部分 3.3）。每台远端还能单独切换 Python 环境、查看它的实时内核指标。
云端流量走向：一个开关统管这条连接的 LLM、视觉、账号/配置与技能/智能体目录走哪条路——
- 走服务器：远程内核用它自己的账号、区域和网络直接访问云端；
- 走本地：把远程内核的 LLM 与视觉请求经 SSH 隧道回传到本机执行，用你本地的 key 和外网。远端没有外网时（如 HPC 计算节点）必须用这个。
把 API Key 同步到远端：需要远端自己直连时可以推送本地的 key，操作前会有一个逐项列出风险的确认框——key 会离开你的机器，这一步不要顺手点过。
远程 OAuth：需要 OAuth 的供应商也可以在远端完成配置。

云端进程（不经 SSH 隧道）与 SSH 远端不是一回事：前者对话与图片能同步，但文件传不了。三种运行位置的区别见第二部分 3.6。

一个注意点：切换账户会重新登记进程身份

在一个工作区里切换登录账户时，云端会拒绝新账户接管旧账户名下的进程标识。omicos 的处理方式：旋转 workspace_id，用新身份重新登记，整个过程在进程内完成，不会重启，也不会退出。你可能观察到：新账户下会话列表一开始是空的。本地旧会话文件仍在，旧账户那边的记录也仍属于旧账户。

故障：网页里跑分析一直提示环境未就绪

端口转发连上了、界面也能用，但一跑分析就提示环境还在准备，多半是这两类原因：

环境还没装完：首次启动会在后台准备 Python 环境，大集群磁盘慢时会很久。最佳实践：先 omicos hpc（或 omicos env setup）把环境装好，再 serve。
连错端口 / kernel 不在预期机器上：确认隧道的本机端口和浏览器 ?ws= 一致，且 kernel 确实在隧道对端那台机器上（用上面的 curl /health 和 /api/process/info 的 hostname 验证）。

更多排查见第 15 章：故障排查。

8. 远程 / SSH / HPC 部署配方

8. 远程 / SSH / HPC 部署配方

HPC 标准流程：服务器算、本地浏览器看

第一步 · 在服务器上安装 omicos

第二步 · 在服务器上选环境并启动（`omicos hpc`）

第三步 · 在本地做端口转发，打开浏览器

情形 1：能直接 SSH 到跑 kernel 的机器（普通服务器 / 登录节点）

情形 2：真 HPC——登录节点 + 计算节点

打开浏览器

第四步（可选）· 指定端口运行

其他场景

纯终端（不开浏览器）

本机笔记本 + 浏览器

让进程在后台长期存活

健康检查与冒烟测试

从网页端管理 SSH 连接

一个注意点：切换账户会重新登记进程身份

故障：网页里跑分析一直提示环境未就绪

results matching ""

No results matching ""

8. 远程 / SSH / HPC 部署配方

HPC 标准流程：服务器算、本地浏览器看

第一步 · 在服务器上安装 omicos

第二步 · 在服务器上选环境并启动（omicos hpc）

第三步 · 在本地做端口转发，打开浏览器

情形 1：能直接 SSH 到跑 kernel 的机器（普通服务器 / 登录节点）

情形 2：真 HPC——登录节点 + 计算节点

打开浏览器

第四步（可选）· 指定端口运行

其他场景

纯终端（不开浏览器）

本机笔记本 + 浏览器

让进程在后台长期存活

健康检查与冒烟测试

从网页端管理 SSH 连接

一个注意点：切换账户会重新登记进程身份

故障：网页里跑分析一直提示环境未就绪

results matching ""

No results matching ""

第二步 · 在服务器上选环境并启动（`omicos hpc`）