📚 课程目录第1章 Nextflow简介

1. Nextflow简介：什么是Nextflow，为什么需要版本控制与结果一致性

我第一次接触Nextflow是在几年前处理一个大规模RNA-seq项目的时候。当时整个团队被流程的维护问题折腾得够呛——每个成员的本地环境不一样，跑出来的结果总是对不上，光排查差异就花了一两周。后来发现Nextflow，说实话有种「终于等到你」的感觉。

Nextflow是什么？简单讲，它是一个工作流管理系统。它的核心能力是帮你把数据分析流程写成一个可复用的脚本，然后自动在本地、集群甚至云端跑起来。你不需要操心底层的任务调度、资源管理、数据分发这些琐事。

流程定义即代码

在Nextflow里，一个工作流由多个process（进程）组成。每个process可以是一个独立的任务，比如比对、定量、过滤。这些process通过channel（通道）连接数据流。

看一个最简单的例子：

nextflow.enable.dsl=2

process sayHello {
    input:
        val x

    output:
        stdout

    script:
    """
    echo "Hello $x!"
    """
}

workflow {
    Channel.of('Alice', 'Bob', 'Charlie') | sayHello | view()
}

这段代码定义了一个叫sayHello的进程。它接收一个字符串，返回"Hello xxx!"。然后在workflow块里，创建一个包含三个名字的通道，把数据传进sayHello，最后打印出结果。跑起来很简单：

nextflow run hello.nf

输出长这样：

Hello Alice!
Hello Bob!
Hello Charlie!

是不是很直观？但注意，这只是入门。实际项目里一个流程往往有几十个process，横跨多个计算节点，跑几个小时甚至几天。这时候问题就来了。

一次奇怪的失败

我记得有次帮同事排查一个bug。他的流程跑了一周突然报错，原因是某个依赖的生物信息学工具升级了版本，输出的格式做了微调。下游的process没有兼容这个新格式，直接崩了。他翻日志翻了两天才找到根因。如果一个流程没有明确的版本控制，这种事我敢说你迟早会遇到。

经验之谈：Nextflow的流程定义本身是代码，但它依赖的外部工具、参考数据、参数配置往往不在版本控制范围内。忽略这些，流程就是不可复现的。

版本控制：不只是代码备份

你可能觉得版本控制就是拿Git管理.nf文件。嗯，这当然重要，但远远不够。一个普通的数据分析流程依赖的东西包括：

流程定义（.nf文件）
软件环境（容器镜像名称、版本标签）
参考文件（基因组版本、注释版本）
参数配置（样本列表、阈值、随机种子）
管道脚本的依赖库（Nextflow自身版本）

任何一个环节变了，结果都可能变。所以真正有效的版本控制，是对上述所有要素进行锁定。Nextflow通过配置文件、manifest（清单）、DSL2模块等方式帮你做这件事，但前提是你要用对。

维度	理想管理方式	常见坑点
流程代码	Git仓库 + 语义化版本标签	只备份脚本，不记录数据版本
软件环境	Docker/Singularity镜像 + 固定Digest	用latest标签，下周就变了
参考数据	内容可寻址存储，或用外部资源标识	网盘分享，过期后找不到
配置参数	通过nextflow config统一管理	参数散落在邮件/文档里
Nextflow版本	在manifest中声明，或用conda环境锁定	本地版本和集群版本不一致

记住：版本控制不是存档，而是保证任何时候你都能重现某一个历史版本的结果。

结果一致性：保证每次跑相同数据得相同结果

结果一致性和版本控制是硬币的两面。版本控制管的是「输入」和「流程」，结果一致性管的是「输出」。但实际项目中，很多因素会破坏一致性：

随机性算法：比如降维聚类、深度学习模型初始化，如果不固定随机种子，两次跑结果必然不同。
文件系统时序：并行任务的文件读写顺序可能改变中间结果。
缓存误用：Nextflow有缓存（.nextflow/work目录），如果流程模块更新了，但缓存没正确清除，就会拿旧的中间结果凑数。
计算环境差异：CPU指令集、操作系统内核参数、磁盘性能都会影响某些数值计算。

一个小技巧：在我负责的一个临床分析流程里，我们会在每个process的输出目录里写一个manifest.json，记录所有原始参数、工具版本、参考文件哈希值。这样不管什么时候回去查，都能确认当时跑的是什么东西。

还是那个例子：Git + 流程库 + 正确使用缓存

回到一开始的hello.nf。假设我要把它做成一个可复用的模块，放到团队库中。我会这样做：

# 在main.nf中声明版本
nextflow.enable.dsl=2

include { sayHello } from './modules/utils'

workflow {
    sayHello(Channel.of('Alice', 'Bob', 'Charlie'))
}

然后在nextflow.config里写好容器和参数配置：

process.container = 'myorg/hello-tools:1.2.0'
docker.enabled = true

params.greeting = 'Hello'

workflow {
    // 使用固定随机种子
    seed = 42
}

用Git打上标签：

git tag v1.0.0
git push origin v1.0.0

每次重新跑都要确认.nextflow缓存已经清理干净，或者使用一个新工作目录。然后：

nextflow run main.nf -params-file params.yaml

这样，无论谁在什么机器上跑，只要用同样的仓库版本、同样的容器、同样的输入，结果就可以保证一致。

核心观点：版本控制不是围墙，而是每一个依赖项的锁定；结果一致性不是运气，而是可复现的工程实践。

这张图总结了我前面说的核心思路。左侧是版本控制的四个支柱，右侧是结果一致性的四个落脚点。没有左侧的锁定，右侧的重现就是空谈；没有右侧的校验，左侧的版本控制也只是一堆存档。

避坑提示：我见过不少团队在版本控制上做得很细，但结果一致性还是出问题。为什么？因为他们忽略了Nextflow自身的版本。不同版本的Nextflow处理管道定义、模块导入、缓存行为有细微差异。所以一定在manifest里声明nextflowVersion，或者用conda/mamba锁定版本。

嗯，这一章先搭个骨架。后面的章节我们一个个展开讲——怎么用Git管流程、怎么锁定容器、怎么用哈希校验数据、怎么设计可重现的模块。先把这些概念刻在脑子里，后面实操起来就会顺手得多。