📚 课程目录第2章环境准备

2. 环境准备

说句实话，很多同学把GATK管线跑崩了，八九成不是因为代码写错，而是环境没配好。我见过太多次了——Java版本不对、R包缺依赖、Docker镜像挂载路径写歪一格…结果报错信息满屏飘，其实根源就几个。

这一章我们就把环境这堵墙先砌结实。你按我的习惯来，后面20多章几乎不会再遇到环境类报错。

2.1 Linux 系统：你至少得有个能用的发行版

GATK官方推荐Ubuntu 20.04 / 22.04 LTS，CentOS 7也行，但CentOS 8/9我踩过几个坑——glibc版本不够新，装某些Java包会报错。我个人习惯用Ubuntu 22.04，稳定而且社区文档全。

几个关键的系统工具，先确认装好：

# 基础工具链
sudo apt update
sudo apt install -y build-essential curl wget git cmake

# 如果你用CentOS/RHEL
sudo yum groupinstall -y "Development Tools"
sudo yum install -y curl wget git cmake

⚠ 注意： 千万别在系统自带的 Python 3.6 上折腾。GATK的后台脚本依赖 Python 3.8+，我建议直接用 Anaconda 或 miniforge 来管理 Python 环境，免得污染系统。

2.2 Java：GATK4 只认 JDK 8 和 11

GATK4 是纯 Java 写的，所以 Java 环境是刚需。官方明确规定：仅支持 JDK 8 和 JDK 11。我用 JDK 11 比较多，性能略优，而且 Lambda 表达式用着顺手。

安装示例：

# Ubuntu 安装 OpenJDK 11
sudo apt install -y openjdk-11-jdk

# 验证
java -version
# 输出应看到 OpenJDK 11.0.x

💡 小经验： 我曾经因为系统里装了 JDK 17，跑 GATK HaplotypeCaller 直接抛 “Unsupported class file major version” 错误。查了两小时才发现是 Java 版本太高。所以，别贪新，老老实实装 11。

2.3 R 与 R 包：GATK 的 CNV 模块离不开它

GATK 的 CNV（拷贝数变异）分析管线，比如 CollectReadCounts、DenoiseReadCounts 这些工具，底层调用了 R 和多个 Bioconductor 包。你不装 R 的话，这些模块跑不起来。

我的 R 环境安装清单：

# 安装 R 4.x (Ubuntu)
sudo apt install -y r-base r-base-dev

# 安装必要 Bioconductor 包
R -e "install.packages('BiocManager', repos='https://cloud.r-project.org')"
R -e "BiocManager::install(c('DNAcopy', 'gplots'))"

GATK CNV 常用 R 包列表：

R 包	用途	GATK 调用场景
DNAcopy	分段拷贝数评估	DenoiseReadCounts
gplots	热图可视化	PlotDenoisedCopyRatios
ggplot2	高级统计图	某些后期脚本
BiocGenerics	泛型函数支持	底层依赖

  ✔ 检查命令： 跑 R -e "library(DNAcopy)" 如果不报错，说明 R 环境已经就绪。

2.4 容器技术：让管线真正可复现

环境最大的坑是什么？是你辛辛苦苦调好的管线，换一台机器就崩了。版本差异、路径不一致、权限问题…我第一年做生信时就吃过这个亏——本地跑完的 VCF，放到服务器上用同样的脚本重新跑，结果位点少了 3%。查到最后发现是两台机器的 samtools 版本不同，导致 bam 文件索引格式有差异。

容器技术就是为了解决这个痛点。把整个依赖环境打包成镜像，一次构建，处处运行。主流有两个选择：

Docker：生态最成熟，教程最多。适合个人开发和小团队。
Singularity / Apptainer：HPC（高性能计算集群）标配，不需要 root 权限就能跑，更安全。

2.4.1 Docker 安装与基本用法

# Ubuntu 安装 Docker
sudo apt install -y docker.io
sudo systemctl enable docker
sudo systemctl start docker

# 把当前用户加入 docker 组（避免每次 sudo）
sudo usermod -aG docker $USER
# 重新登录后生效

拉取 GATK 官方镜像并测试：

docker pull broadinstitute/gatk:4.4.0.0
docker run --rm broadinstitute/gatk:4.4.0.0 GATK --help

⚠ 权限注意： 很多生信数据目录权限比较敏感，Docker 默认以 root 运行，会导致创建的文件属主为 root。我个人习惯在运行时加 --user $(id -u):$(id -g) 来匹配宿主用户，避免后续文件删不掉。

2.4.2 Singularity/Apptainer —— HPC 的正确打开方式

如果你在超算中心工作，大概率只能使用 Singularity（现在叫 Apptainer）。它的优势是：不需要 daemon 进程，直接运行容器，完全用用户权限。

# 安装 SingularityCE (Ubuntu)
sudo apt install -y singularity-container

# 从 Docker Hub 构建 GATK 镜像
singularity build gatk-4.4.0.0.sif docker://broadinstitute/gatk:4.4.0.0

# 使用
singularity exec gatk-4.4.0.0.sif GATK --help

Singularity 一个很实用的特性：自动挂载当前目录和 $HOME。你不需要像 Docker 那样写 -v 参数。但要注意，外部路径如果没挂载，容器里看不到。我习惯用 --bind 显式指定数据目录：

singularity exec --bind /path/to/data:/data gatk-4.4.0.0.sif \
  GATK HaplotypeCaller -R /data/ref/hg38.fa -I /data/sample.bam -O /data/sample.vcf.gz

2.5 环境检查清单：装没装好，跑完这块就知道了

检查项	验证命令	预期结果
Linux 版本	`lsb_release -a`	Ubuntu 20.04/22.04 或 CentOS 7
Java	`java -version`	OpenJDK 11.0.x
R 版本	`R --version`	R version 4.x
R 包 DNAcopy	`R -e "library(DNAcopy)"`	无错误
Docker	`docker run hello-world`	显示 Hello from Docker!
Singularity	`singularity --version`	singularity-ce 3.x
GATK 镜像	`singularity exec gatk.sif GATK --version`	显示 4.4.0.0

  ✔ 全绿就过关。 任何一项报错，都建议回看对应的小节重新安装，不要往下走。否则后面每一步都会怀疑是环境问题。

2.6 本章核心逻辑图

我把环境准备的整体关系画成下面这张 SVG，方便你对照着搭建：

嗯，这张图把从操作系统到 GATK 的运行层级理清了。你照着这个层次一步步搭，基本不会出低级问题。

2.7 我踩过的几个坑，一次性说给你听

R 包安装失败：有一次我在没有网络环境的服务器上装 DNAcopy，手动下载源码编译，结果依赖的 zlib 头文件路径不对。后来我改成离线拷贝编译好的 .tar.gz 再用 R CMD INSTALL，就搞定了。如果你也遇到网络限制，这个思路值得参考。
Docker 磁盘占满：GATK 镜像大概 2~3GB，但每次构建会留下中间层。我建议定期执行 docker system prune -a 清理。
Singularity 权限问题：某些 HPC 的 home 目录设置了 noexec，Singularity 运行会报错。解决方案是把 .sif 文件放到 /scratch 或 /tmp 下执行。

💡 我的最佳实践： 平时开发用 Docker，部署到 HPC 时换成 Singularity。两种容器的 GATK 镜像互相兼容，只要你用的版本一致，不用改任何脚本。