8. 远程 / SSH / HPC 部署配方
很多时候，数据和算力在远程服务器或 HPC 上，而你想在本地笔记本操作。本章给出三种典型场景的可直接复制的命令配方。
先记住一个关键区分：kernel（算力）跑在哪台机器，和你从哪台机器操作 UI，是两件独立的事。下面的方案就是在权衡这两者。
场景 A：本地笔记本 + 浏览器
数据和分析都在本机，最简单：
mkdir -p ~/my-analysis && cd ~/my-analysis
omicos login # 邮箱 / 密码
omicos serve # 监听 127.0.0.1:5055，自动开浏览器到 app.omicos.cn
适合：个人电脑上的日常分析。
场景 B：纯终端 TUI（无图形界面的 HPC）
SSH 进了一台没有图形界面的 HPC 登录节点，全程在终端里搞定——登录和聊天都不需要浏览器：
omicos login # 邮箱 / 密码，纯终端登录（无需浏览器）
cd ~/my-analysis
omicos cli # 进入终端聊天界面
如果不方便在这台机器输入密码，可改用
omicos cli login设备码配对，在另一台已登录 omicOS 的设备上确认配对码。
适合：纯命令行环境、防火墙严格、不方便开浏览器隧道的 HPC。
场景 C：服务器跑分析，笔记本浏览器看
这是最常见也最值得讲清楚的场景。有两种走法。
方法 1：SSH 端口转发（推荐，kernel 重活首选）
让本地浏览器通过 SSH 隧道直连服务器上的 5055 端口，kernel 调用全程留在服务器内部，零云端中继：
# 在笔记本上建立隧道
ssh -L 5055:127.0.0.1:5055 user@sherlock.stanford.edu
# 在同一个 SSH 会话里启动 omicos
cd ~/my-analysis
omicos serve --no-browser
# 回到笔记本，浏览器打开 https://app.omicos.cn
# 网页端会自动找到被转发过来的本地 5055 端口
- 优点：plot、变量详情、kernel 执行都走本地隧道，带宽和延迟最低。
- 代价：必须保持那个 SSH 窗口开着。SSH 一断，浏览器访问
localhost:5055就会connection refused。 - 官方建议：kernel 重活（大数据、频繁画图）走这条路。
方法 2：纯云端中继（免 SSH，跨机器即插即用）
只要服务器上的守护进程已登录，云端中继就是自动的——不需要任何额外 flag。登录后 omicos serve 会主动 outbound 拨一条 wss 到 wss://auth.omicos.cn/ws/process 并注册自己。你从任意浏览器打开网页端、在进程选择器里选中这台实例，云端就会把聊天 / UI 请求沿这条 socket 下推，守护进程再把它们打到自己的本机 runtime（127.0.0.1:5055，kernel 就在那里），并把响应沿同一条 socket 回传：
# 一次性前提：服务器上先登录
omicos login
# 服务器上启动（无需 SSH 隧道，也无需 --upstream-base-url）
cd ~/my-analysis
omicos serve --no-browser
# 笔记本上用任意浏览器打开 https://app.omicos.cn（需同一账户）
# 在进程选择器里选中 sherlock 那台实例 → 云端 ProcessHub 中继 kernel 调用
- 优点：零网络配置，换任何一台能上网的机器都能接入。
- 代价：plot / 变量详情 / kernel 执行都经
wss://auth.omicos.cn中继，带宽吃在云端，延迟更高。 - 建议：偶尔查看、轻量交互用它；重度分析还是走方法 1。
不要把中继归因于
--upstream-base-url。 启用中继的唯一条件是守护进程持有process_token（来自omicos login，或OMICOS_PROCESS_TOKEN环境变量）——与--upstream-base-url无关。--upstream-base-url只配置本地一个 HTTP 代理回退（把未匹配的/api/*转发给后端，即云同步的 escape hatch），不决定 kernel 跑在哪，正常情况下也不需要手动传。kernel 默认在本机 5055，由--kernel-base-url单独控制。
让进程在后台长期存活
服务器上你通常希望 omicos 在你断开 SSH 后继续跑。三种常见做法（都配 --no-browser）：
# nohup
nohup omicos serve --no-browser > omicos.log 2>&1 &
disown
# tmux
tmux new-session -d -s omicos \
'cd ~/my-analysis && omicos serve --no-browser'
# screen
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。）
用 cli 远程挂载到云端进程
如果你想在本地终端里直接挂到远程进程上聊天，用 omicos cli --process：
omicos cli --process local-<远程workspace_id>
这样本地 TUI 直接操作远程那台机器上的分析进程。
健康检查与冒烟测试
不管哪种部署，都可以用这套命令确认服务正常：
curl -sS http://127.0.0.1:5055/health
# 期望 HTTP 200，返回 JSON：
# {"service":"omicos-core","status":"ok","version":{"semver":"0.2.x", ...}}
curl -sS http://127.0.0.1:5055/api/process/info | python3 -m json.tool
# 期望 HTTP 200，形如：
# {"name":"OmicOS Core","runtime":"rust","version":"0.2.x", ...}
# 注意：响应里没有 "status" 字段；未登录 / 终端启动时 id、process_id、process_name 为空串
一个注意点：账户切换会触发自愈重启
如果在一个工作区里切换登录账户，云端会以 WebSocket 关闭码 4403 通知，omicos 会旋转 workspace_id 并自动重启自己。这看起来像崩溃，实际是预期的恢复行为。代价是会话同步的高水位被清空，新账户下会话列表可能显示为空（本地旧会话文件仍在）。详见故障排查。