环境准备：安装 Singularity（Linux、macOS、Windows WSL2）

开始动手之前，我得先和你聊聊 Singularity 是什么。说白了，它是专门为 科学计算 和 HPC（高性能计算） 环境设计的容器引擎。Docker 虽然好用，但在集群上跑往往需要 root 权限，而且安全模型不适合多用户共享。Singularity 不一样——普通用户就能跑，还能直接挂载文件系统、兼容 MPI 和 GPU，简直是生信工作流的绝配。

我这些年折腾过十几个 HPC 集群，每次装 Singularity 都会遇到一些奇奇怪怪的坑。这一章我把 Linux、macOS、Windows WSL2 三个平台的经验全抖出来，帮你少走弯路。

Singularity 安装环境总览 Linux apt / yum / 源码编译 macOS Homebrew + Vagrant VM Windows WSL2 Ubuntu 发行版 + apt 安装 SingularityCE 官网 / GitHub Release 验证安装 singularity version 拉取测试镜像 library://alpine 运行 Hello World singularity exec 环境准备完成，可以开始使用

4.1 在 Linux 上安装 Singularity

Linux 是 Singularity 的 一等公民，安装体验最顺畅。我个人偏爱 Ubuntu 20.04/22.04 或者 CentOS 7/8，其他发行版也差不多。

4.1.1 安装依赖

先装一些必要工具。Ubuntu/Debian 系列：

sudo apt update
sudo apt install -y wget git build-essential libssl-dev uuid-dev libgpgme11-dev \
    libseccomp-dev pkg-config squashfs-tools

CentOS/RHEL 系列：

sudo yum install -y epel-release
sudo yum install -y wget git gcc gcc-c++ make libtool openssl-devel \
    libuuid-devel gpgme-devel libseccomp-devel squashfs-tools
个人小建议：如果你是在 HPC 登录节点上安装，很可能没有 root 权限。别怕——Singularity 支持非 root 用户源码编译，我后面会讲。

4.1.2 下载预编译二进制（推荐）

现在 SingularityCE 官方直接提供 预编译的 .deb 和 .rpm，省去了编译时间。我最喜欢这种方式。

# 下载最新稳定版（以 3.11.4 为例）
wget https://github.com/sylabs/singularity/releases/download/v3.11.4/singularity-ce_3.11.4-1_amd64.deb

# 安装
sudo dpkg -i singularity-ce_3.11.4-1_amd64.deb

CentOS 用 .rpm：

wget https://github.com/sylabs/singularity/releases/download/v3.11.4/singularity-ce-3.11.4-1.x86_64.rpm
sudo rpm -ivh singularity-ce-3.11.4-1.x86_64.rpm

4.1.3 从源码编译（无 root 场景）

我曾经在某个集群上没有 sudo，系统是 CentOS 7。那时候只能走源码编译安装到 $HOME/.local。步骤稍微多几步，但完全可行。

# 设置 Go 版本（Singularity 3.x 需要 Go ≥1.16）
export VERSION=1.20.5
wget https://go.dev/dl/go$VERSION.linux-amd64.tar.gz
tar -xzf go$VERSION.linux-amd64.tar.gz -C $HOME
export PATH=$HOME/go/bin:$PATH

# 克隆源码
git clone --branch v3.11.4 https://github.com/sylabs/singularity.git
cd singularity

# 编译并指定安装目录
./mconfig --prefix=$HOME/.local/singularity
make -C builddir
make -C builddir install

# 将二进制加入 PATH
echo 'export PATH=$HOME/.local/singularity/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
注意：非 root 安装的 Singularity 无法使用 --fakeroot 功能（构建容器时需要），但运行已有容器完全没问题。如果你后续要构建容器，建议申请 sudo 或找管理员帮忙。

4.2 在 macOS 上安装 Singularity

macOS 底层不是 Linux，没法直接跑 Singularity。我记得最早我试过 Homebrew 装 singularity，结果发现只是装了客户端，内核还是跑不了。真正的方案是 借助虚拟机，目前最成熟的是用 Vagrant + VirtualBox 启动一个 Ubuntu VM，然后在 VM 里安装 Singularity。

4.2.1 安装 Vagrant 和 VirtualBox

先去官网下载 VirtualBox 和 Vagrant。你也可以用命令行安装：

# Homebrew 安装（需要先安装 Homebrew）
brew install --cask virtualbox vagrant

我遇到过 VirtualBox 和 macOS 系统安全策略冲突的问题，需要在 系统偏好设置 → 安全性与隐私 中允许 VirtualBox 系统扩展加载。切记！

4.2.2 启动 Ubuntu 虚拟机

mkdir ~/singularity-vm && cd ~/singularity-vm

# 初始化一个 Ubuntu 22.04 虚拟机
vagrant init ubuntu/jammy64
vagrant up
vagrant ssh

进入 VM 后，你就拥有一个完整的 Linux 环境了。然后按 4.1 节的 Linux 步骤安装 Singularity 即可。

性能建议：给 VM 分配至少 2 核 CPU + 4 GB 内存，否则后面构建 MaxQuant 容器时会慢到怀疑人生。我自己踩过这个坑，第一次编译花了 40 多分钟……后来加了资源，10 分钟搞定。

4.2.3 替代方案：使用 Lima（实验性）

如果你用的是 Apple Silicon (M1/M2) Mac，VirtualBox 兼容性不佳。我推荐试试 Lima，它基于 QEMU，能跑 x86_64 和 arm64 容器。

brew install lima
limactl start default
limactl shell default
# 然后在 shell 中安装 Singularity 即可

Lima 目前还没有 Vagrant 稳定，但胜在轻量。我个人在 M1 MacBook Pro 上已经用它跑了两个月，没出过大问题。

4.3 在 Windows WSL2 上安装 Singularity

Windows 用户最省心的方式就是 WSL2 + Ubuntu 发行版。WSL2 是一个真正的 Linux 内核虚拟机，完全兼容 Singularity。

4.3.1 确保 WSL2 已启用

以管理员身份打开 PowerShell，运行：

# 启用 WSL 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 设置 WSL2 为默认版本
wsl --set-default-version 2

# 重启计算机

重启后，去 Microsoft Store 搜索并安装 Ubuntu 22.04 LTS。安装后启动 Ubuntu 终端，首次运行会提示创建用户名和密码。

小技巧：我习惯把 WSL2 的内存上限调高一点，因为 Singularity 构建容器时内存消耗不小。在 Windows 用户目录下创建 .wslconfig 文件： 
[wsl2]
memory=4GB
processors=4
localhostForwarding=true
然后运行 wsl --shutdown 再重启 WSL2 即可生效。

4.3.2 在 WSL2 中安装 Singularity

进入 Ubuntu 终端后，就跟 Linux 上一样了：

sudo apt update
sudo apt install -y wget

# 下载 .deb 预编译包（以 3.11.4 为例）
wget https://github.com/sylabs/singularity/releases/download/v3.11.4/singularity-ce_3.11.4-1_amd64.deb
sudo dpkg -i singularity-ce_3.11.4-1_amd64.deb

# 如果缺少依赖，修复一下
sudo apt --fix-broken install -y

安装完成后验证：

singularity version
# 应该输出类似 3.11.4

我最早在 Windows 上跑 Singularity 时也怀疑过能不能行。实际上，WSL2 的 Linux 内核非常完整，GPU 透传（CUDA）也能用，专门做生信一点问题都没有。

4.4 验证安装与测试运行

无论你用的是哪个平台，装完后都要测试一下。我个人习惯拉取一个最小的镜像跑跑看：

# 从 Sylabs Cloud 拉取一个 Alpine 镜像
singularity pull library://alpine:latest

# 执行一个简单命令
singularity exec alpine_latest.sif cat /etc/os-release

如果你看到 Alpine Linux 的版本信息，说明 Singularity 正常运行。

4.4.1 常见的安装后问题排查

问题现象可能原因解决方案
singularity: command not foundSingularity 未安装或 PATH 未包含检查安装步骤是否正确；非 root 安装需要手动添加 $HOME/.local/singularity/bin 到 PATH
FATAL: kernel too old宿主内核版本过低（小于 3.10）更新内核或升级操作系统；WSL2 用户请确保使用 WSL2 内核（不是 WSL1）
failed to create user namespace: operation not permitted缺少 user namespace 支持在 WSL2 中检查 /proc/sys/kernel/unprivileged_userns_clone，设为 1；CentOS 7 需执行 echo 1 | sudo tee /proc/sys/kernel/unprivileged_userns_clone
WARNING: Could not set mount namespaceDocker daemon 冲突或 cgroups 版本不兼容确保没有同时运行 Docker 且使用 cgroups v2；WSL2 中在 .wslconfig 设置 kernelCommandLine=cgroup_no_v1=all

特别注意：在 macOS 和 Windows 上，Singularity 运行在虚拟机内部，文件 I/O 性能受文件共享方式影响很大。我建议你把工作数据放在 虚拟机内部的文件系统 或者 通过挂载点 映射进去，别直接在共享目录里跑大数据量的容器，否则慢到崩溃。

4.5 进阶：在无网络环境下安装 Singularity

有些生信集群完全离线，不能访问 GitHub 或 Sylabs Cloud。这时候你得提前准备安装包。我遇到过好几次，去客户现场才发现防火墙严格得要命。

方法很简单：在能联网的机器上下载好 .deb / .rpm 包 以及所有依赖，用 U 盘拷进去。

  • Ubuntu： sudo apt download singularity-ce && sudo apt-get download $(apt-cache depends singularity-ce | grep Depends | awk '{print $2}')
  • CentOS： yum install --downloadonly --downloaddir=/tmp/rpms singularity-ce

然后把整个目录复制到离线机器上，用 dpkg -i *.deb 或 rpm -ivh *.rpm 批量安装即可。

4.6 安装后检查清单

每次装完 Singularity，我都会快速跑一遍这个清单，确保环境没问题：

  1. 命令可用： singularity version 返回版本号
  2. 拉取镜像： singularity pull library://alpine:latest 成功
  3. 执行命令： singularity exec alpine_latest.sif echo hello 输出 hello
  4. 文件挂载： singularity exec -B /tmp:/mnt alpine_latest.sif ls /mnt 能列出临时目录内容
  5. GPU 可用（如有）： singularity exec --nv docker://nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi 显示 GPU 信息
← 上一章 📖 返回目录 下一章 →