2. 前置条件与系统要求
安装前,先确认三样东西:
- omicos 二进制(程序本体)
- Python 分析环境(跑生信分析的引擎)
- omicOS 云账户
2.1 支持的操作系统与平台
omicos 提供六个平台的预编译二进制:
| 平台 | 架构 | 目标三元组(target triple) |
|---|---|---|
| Linux | x86_64 | x86_64-unknown-linux-musl |
| Linux | ARM64 | aarch64-unknown-linux-musl |
| macOS | Intel | x86_64-apple-darwin |
| macOS | Apple Silicon | aarch64-apple-darwin |
| Windows | x64 | x86_64-pc-windows-msvc |
| Windows | ARM64 | aarch64-pc-windows-msvc |
GLIBC_2.xx not found。musl 静态链接把 libc 打进二进制,因此同一个文件在 Ubuntu、CentOS 7、以及各种 HPC 登录节点上都能直接跑——这正是 HPC 场景的刚需,那些机器的系统库往往比你的笔记本旧好几年,而且你没有 root 去升级。
装好后,运行 omicos --version 确认平台构建:
omicos --version
输出格式(版本号与提交号以实际安装为准):
omicos <版本号>+<提交号>
2.2 安装方式
omicos 通过 npm 安装预编译二进制,只需要 Node.js ≥ 16:
| 安装方式 | 需要什么 | 适合谁 |
|---|---|---|
| npm 安装预编译包 | Node.js ≥ 16 | 所有用户 |
optionalDependencies 来"只装匹配你平台的那一个子包",而正确处理这个字段是 npm 7 才有的行为。Node 16 自带 npm 8,所以只要满足 Node ≥ 16,npm 版本自然够。反过来,如果你用的是很老的 Node(比如系统自带的 Node 12),会出现"包装上了、二进制没装上"的现象——见第 3 章的故障排查。
npm 会自动下载与你系统匹配的平台二进制,无需编译工具链。详见第 3 章。
2.3 Python 分析环境
omicos 只负责调度。真正跑 scanpy / omicverse 的是一个独立 Python 环境(Python 3.11 + omicverse,约 1.5 GB)。
- 推荐用
omicos env setup一键创建(底层用 uv 管理虚拟环境)。 - 也可以指向你已有的 conda / venv 环境。
在 App 中检查环境
打开客户端左侧的 环境 页面,找到目标工作空间,检查卡片底部的 运行位置。下面的原生 App 截图使用默认浅色主题,保留完整界面,个人工作区、环境名称与路径已遮蔽,内置默认环境和状态标签保留;点击图片可查看原尺寸。
图中的内核显示“运行中 / 热·就绪”,但所选 Python 环境仍提示“环境不可用”。内核状态与分析环境状态是两回事;遇到这种提示,先按第 4 章准备环境,不要仅凭内核运行中就开始分析。
点击运行位置中的环境名称,可以展开本机探测到的环境列表:
列表里的名称和路径取决于本机安装,不是需要照抄的环境清单。环境被列出也不代表已经装好 omicverse 及分析依赖;选择前先核对 Python 版本和所需包。
没配环境时,omicos serve 照常启动,聊天也能用。它在后台准备环境,不阻塞启动。只有真正运行分析代码时,才会看到 Python environment unavailable: …(准备中则是 The Python environment is still being prepared…)。
也就是说:「界面能打开」不代表「能跑分析」。磁盘慢的集群上这个准备过程可能很久,所以最佳实践是先把环境装好再 serve,而不是一边等一边试。
2.4 omicOS 云账户
智能体聊天、跨设备查看、图床、订阅分层这些功能依赖云账户:
- 在 auth.omicos.cn 注册。
- 登录方式见第 5 章。
2.5 网络要求
- omicos 需要能访问
auth.omicos.cn,用于登录、进程注册和同步。 - 默认只监听
127.0.0.1,不对外开放端口;远程访问通过 SSH 端口转发实现,详见远程部署配方。
localhost:5055 的连接。表现是"一直连不上",但你的网络其实是通的——很容易误判成 omicos 的 bug。omicos 启动时检测到这种配置会打印一段中英双语提示;工作台的设置 · 诊断里也能看到 Core 视角的网络判定,和浏览器看到的可能不一样,这正是排查这类问题的关键。
检查清单
开始安装前,确认:
- [ ] 操作系统在上面六个平台之列
- [ ] 已安装 Node.js ≥ 16
- [ ] 已在 auth.omicos.cn 注册账户
- [ ] 机器能访问外网(至少能连到
auth.omicos.cn)

