Singularity 容器化生信¶

一句话概述：Singularity（现更名为 Apptainer）是 HPC 集群上的容器方案，无需 root 权限就能运行容器，是生信分析在超算上部署工具的首选。

核心知识点¶

概念	白话解释
SIF	Singularity Image Format = 单个不可变镜像文件
Definition File	定义文件 = 类似 Dockerfile 的构建脚本
Sandbox	沙盒 = 可写的目录格式镜像（开发用）
Bind Mount	绑定挂载 = 把宿主机目录映射到容器内
Apptainer	Singularity 的新名字（2021 年捐给 Linux 基金会后改名）

安装配置¶

# Ubuntu 安装 Apptainer（Singularity 的新名字）
sudo apt update
sudo apt install -y software-properties-common
sudo add-apt-repository -y ppa:apptainer/ppa
sudo apt install -y apptainer                   # 安装

# 验证
apptainer --version                             # 查看版本
singularity --version                           # 兼容命令（通常也能用）

# CentOS / Rocky Linux
sudo yum install -y epel-release
sudo yum install -y apptainer

基本使用¶

# 从 Docker Hub 拉取镜像
apptainer pull docker://biocontainers/samtools:v1.20  # 拉取 samtools
apptainer pull docker://staphb/fastp:latest           # 拉取 fastp

# 运行容器中的命令
apptainer exec samtools_v1.20.sif samtools --version  # 执行命令
apptainer exec fastp_latest.sif fastp --help          # 查看帮助

# 交互式进入容器
apptainer shell samtools_v1.20.sif                    # 进入 shell
# Singularity> samtools view input.bam | head         # 容器内操作

# 绑定挂载目录（让容器访问宿主机文件）
apptainer exec --bind /data:/data \
  samtools_v1.20.sif samtools sort \
  /data/input.bam -o /data/sorted.bam                # 排序 BAM 文件

# 多目录挂载
apptainer exec --bind /data:/data,/ref:/ref \
  bwa_latest.sif bwa mem /ref/hg38.fa \
  /data/R1.fq.gz /data/R2.fq.gz > /data/aligned.sam  # 比对

构建自定义镜像¶

# samtools.def — 定义文件
cat > samtools.def << 'EOF'
Bootstrap: docker
From: ubuntu:22.04

%post
    apt-get update && apt-get install -y \
        build-essential wget zlib1g-dev \
        libbz2-dev liblzma-dev libcurl4-openssl-dev
    wget https://github.com/samtools/samtools/releases/download/1.20/samtools-1.20.tar.bz2
    tar xjf samtools-1.20.tar.bz2
    cd samtools-1.20 && ./configure && make && make install
    rm -rf /samtools-1.20*

%environment
    export PATH=/usr/local/bin:$PATH

%runscript
    exec samtools "$@"

%labels
    Author bioinfo_team
    Version 1.20

%test
    samtools --version
EOF

# 构建镜像（需要 root 或 fakeroot）
sudo apptainer build samtools.sif samtools.def        # 构建 SIF
apptainer build --fakeroot samtools.sif samtools.def   # 无 root 构建

高级用法¶

HPC 集群上使用¶

#!/bin/bash
#SBATCH --job-name=variant_call
#SBATCH --cpus-per-task=8
#SBATCH --mem=32G

# 在 SLURM 作业中使用 Singularity 容器
module load apptainer                                  # 加载模块

apptainer exec --bind /scratch:/scratch \
  gatk4.sif gatk HaplotypeCaller \
  -R /scratch/ref/hg38.fa \
  -I /scratch/data/sorted.bam \
  -O /scratch/results/variants.vcf                    # GATK 变异检测

Sandbox 开发模式¶

# 创建可写的 sandbox
apptainer build --sandbox my_env/ docker://ubuntu:22.04  # 创建沙盒
apptainer shell --writable my_env/                       # 可写进入
# 在里面安装软件调试...
apptainer build my_env.sif my_env/                       # 打包为 SIF

常见报错¶

报错信息	原因	解决方法
`FATAL: no SIF`	镜像文件不存在	检查路径和文件名
`permission denied`	无 root 且无 fakeroot	用 `--fakeroot` 或找管理员
`overlay mount failed`	内核不支持 overlay	升级内核或用 `--no-mount`
`容器内找不到文件`	未绑定挂载	添加 `--bind /data:/data`

速查表¶

# === 基本操作 ===
apptainer pull docker://image:tag         # 拉取 Docker 镜像
apptainer exec image.sif command          # 执行命令
apptainer shell image.sif                 # 交互式 shell
apptainer run image.sif                   # 运行默认命令
apptainer build image.sif def_file.def    # 构建镜像
apptainer inspect image.sif               # 查看镜像信息

# === 挂载 ===
--bind /host/path:/container/path         # 绑定挂载
--bind /path                              # 同路径挂载

# === Singularity vs Docker ===
# Singularity: 无需 root、HPC 友好、单文件镜像、可直接用 Docker 镜像
# Docker: 需要 root/daemon、功能更多、生态更大、CI/CD 更方便

参考：Apptainer 文档 | 更新于 2026 年