📚 课程目录第2章安装与配置

2. 安装与配置

你可能会问，装个MultiQC而已，有啥好准备的？

在受监管环境里，这还真不是小事。审计官后面会问三个问题：你装的是哪个版本？依赖链清楚吗？能复现吗？

说白了，安装记录就是审计证据的一部分。

我在项目中遇到过几次因为安装路径混乱导致审计回溯困难的案例。嗯，这完全可以避免——选对方式、留好记录就行。

注意：受监管环境禁止使用 sudo pip install 直接装到系统 Python。这会污染系统环境，审计时根本说不清依赖来源。

目前主流就三种：Conda、Pip、Docker。我全用过，各有利弊。

安装方式	适用场景	核心优点	主要缺点	审计友好度
Conda	本地开发 / 测试验证	环境隔离好，依赖管理强	环境体积大，偶尔依赖冲突	★★★☆☆
Pip	快速部署 / CI 流水线	轻量、命令简单	依赖锁定弱，容易漂移	★★☆☆☆
Docker	受监管生产环境	完整可复现、可签名、可存档	需要 Docker 运行环境	★★★★★

下面这张图帮你理清整体脉络：从安装选型到环境配置，再到验证闭环。

我个人习惯用Conda来管理生物信息学工具。原因很简单——环境隔离做得好，依赖树清晰。

在受监管场景下，你还可以把 environment.yml 纳入版本控制，审计时直接翻文件就行。

conda create -n multiqc_env python=3.9
conda activate multiqc_env
conda install -c bioconda multiqc

小技巧：用 conda list --explicit > multiqc_env_spec.txt 导出精确依赖列表。这份清单就是审计证据的一部分。

如果你只是想快速跑个demo，Pip确实方便。但我建议一定要用虚拟环境，别直接装到系统里。

python -m venv multiqc_venv
source multiqc_venv/bin/activate
pip install multiqc

锁定版本是个好习惯。你想想看，如果哪天依赖包自动升级了，结果报告对不上了，审计时根本解释不清。

pip install multiqc==1.14
pip freeze > requirements.txt

注意：pip freeze 会列出所有包，包括间接依赖。审计时建议只锁定直接依赖，间接依赖交给 pip check 验证一致性。

这是我最推荐的方式，尤其是受监管环境。为什么？因为镜像可以签名、锁定、存档，审计时直接拉出来验证哈希值就行。

docker pull multiqc/multiqc:v1.14
docker run -v $(pwd):/data multiqc/multiqc:v1.14 /data

我建议你在项目的 Dockerfile 里固定版本标签，别用 latest。用过一次 latest 踩坑之后，我就再也不敢了——你永远不知道它哪天变了个版本。

FROM multiqc/multiqc:v1.14
# 可选：添加自定义插件或配置
COPY custom_plugins /opt/multiqc/plugins

审计要点：Docker 镜像的 SHA256 摘要、构建时间戳、签名信息，建议一并存入审计日志。这部分内容在后续"容器化部署"章节会详细展开。

MultiQC本身对环境变量依赖不多，但几个关键的配好了能省不少事。

环境变量	作用	配置示例
`PATH`	确保 `multiqc` 命令可用	`export PATH=/opt/multiqc/bin:$PATH`
`MULTIQC_DIR`	指定自定义配置目录	`export MULTIQC_DIR=/etc/multiqc`
`MULTIQC_NUM_PROCS`	控制并行处理的进程数	`export MULTIQC_NUM_PROCS=4`

MULTIQC_DIR 这个变量挺实用。你可以把公司统一的配置文件、模板、插件都放在这个目录下，团队所有成员共用一套配置。

# 在 ~/.bashrc 或 ~/.profile 中添加
export MULTIQC_DIR=/share/tools/multiqc_config
export PATH=/opt/conda/envs/multiqc_env/bin:$PATH

配好之后记得 source ~/.bashrc 或者重新登录终端。这一步容易忘，我刚开始也犯过这毛病。

装完了怎么确认一切正常？三步走：

multiqc --version
# 输出示例：multiqc, version 1.14

multiqc --help
# 查看所有可用子命令和选项

# 用官方测试数据验证
multiqc /path/to/test_data -o test_report

如果看到版本号和预期一致、帮助信息完整、测试报告顺利生成，那就基本稳了。

快速验证：multiqc --version 输出的版本号建议截图或记录到安装日志里。审计时这就是 "你装了什么版本" 的直接证据。

讲了这么多，最后聊几个我亲身踩过的坑。

路径冲突：我曾经把MultiQC装在了系统Python里，结果另一个工具升级时把依赖搞坏了，MultiQC直接罢工。从那以后我坚持用Conda环境或Docker，再也没出过类似问题。
版本漂移：有次CI流水线里用了 pip install multiqc 没锁版本，三个月后自动升级到了新版本，报告格式变了，比对结果对不上。现在我的所有流水线都锁定了 ==1.14 这种精确版本。
Docker标签陷阱：latest 标签坑过我一次。某天 latest 指向了新版本，配置文件不兼容，报告直接崩了。自那以后我只看具体版本标签。

嗯，这些坑说起来都是小事，但在审计面前，任何一个"说不清"都可能变成finding。提前规避掉，后面就省心了。