2. 前置条件与系统要求
安装前，先确认三样东西：
- omicos 二进制（程序本体）
- Python 分析环境（跑生信分析的引擎）
- omicOS 云账户
1确认平台›
2装 Node.js›
3注册账户
约 5 分钟
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 |
为什么 Linux 版是 musl 而不是 glibc
glibc 构建的二进制会绑定构建机的 glibc 版本，拿到更老的发行版上就报
GLIBC_2.xx not found。musl 静态链接把 libc 打进二进制，因此同一个文件在 Ubuntu、CentOS 7、以及各种 HPC 登录节点上都能直接跑——这正是 HPC 场景的刚需，那些机器的系统库往往比你的笔记本旧好几年，而且你没有 root 去升级。
装好后，运行 omicos --version 确认平台构建：
omicos --version
预期输出：
omicos 0.3.29+a1b2c3d
2.2 安装方式
omicos 通过 npm 安装预编译二进制，只需要 Node.js ≥ 16：
| 安装方式 | 需要什么 | 适合谁 |
|---|---|---|
| npm 安装预编译包 | Node.js ≥ 16 | 所有用户 |
为什么是 Node ≥ 16，而不是"随便一个 Node"
npm 用
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）。
Python 版本
3.11
环境体积
≈ 1.5 GB
首次准备耗时
数分钟起
- 推荐用
omicos env setup一键创建（底层用 uv 管理虚拟环境）。 - 也可以指向你已有的 conda / venv 环境。
环境问题会延迟暴露——这是最常见的困惑来源
没配环境时，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 端口转发实现，详见远程部署配方。
配了 HTTP 代理时，必须放行回环地址
```bash
export no_proxy=localhost,127.0.0.1
```
否则代理会同时拦掉两条本该走本机的链路：内核的出站请求、以及浏览器到
localhost:5055 的连接。表现是"一直连不上"，但你的网络其实是通的——很容易误判成 omicos 的 bug。omicos 启动时检测到这种配置会打印一段中英双语提示；工作台的设置 · 诊断里也能看到 Core 视角的网络判定，和浏览器看到的可能不一样，这正是排查这类问题的关键。
检查清单
开始安装前，确认：
- [ ] 操作系统在上面六个平台之列
- [ ] 已安装 Node.js ≥ 16
- [ ] 已在 auth.omicos.cn 注册账户
- [ ] 机器能访问外网（至少能连到
auth.omicos.cn）