云生信学生物信息学

Nextflow 任务失败怎么恢复?保存缓存、work目录和运行日志

作者:发布于 2026-11-19更新于 2026-11-15约 6 分钟阅读
Nextflow失败后可靠恢复

Nextflow失败后可靠恢复:保存项目、cache和work路径;开启trace与report日志;定位失败task和资源错误;同路径修复后用-resume
本文操作与检查路径示意。

Nextflow流水线出错后,直接删掉work目录或换一台机器重跑,可能丢失定位线索,也会让可复用的任务再次计算。要让失败恢复可靠,先明确项目目录、task cache和work目录的位置,再开启运行报告并保存完整命令。Nextflow只有在缓存元数据匹配、对应work输出仍存在时,才能恢复已完成任务。

首次运行先固定项目与工作目录

在项目目录启动流程,记录Nextflow版本、流程提交号、profile、输入清单、参数、容器/Conda配置和资源限制。为该批任务指定持久化work目录;缓存默认放在启动目录下的.nextflow/cache,因此项目启动路径和缓存位置也需保持可追溯。work目录不能放在会自动清理的临时盘,否则运行结束后缓存条目可能还在,但任务输出已不存在,恢复时就必须重跑。

需要保存 包含什么 解决的问题
流程和参数 提交号、配置、profile、完整命令 确定重跑是否改变设置
任务缓存 启动目录中的Nextflow cache 匹配之前的task hash
work目录 每个task的工作目录和输出 允许复用已完成task
运行报告 trace、report、timeline及日志 定位失败阶段和资源瓶颈

首次运行打开追踪文件

下面以Docker profile为例,工作目录设在持久化存储;将流程名、输入参数和路径替换为项目实际值。trace和report可帮助回看任务状态、资源和耗时;timeline适合查看阶段顺序。检查Nextflow版本是否支持对应选项,并确保文件写到本批运行目录。

set -o pipefail
mkdir -p run-001/logs
nextflow run main.nf \
  -profile docker \
  --input samplesheet.csv \
  -work-dir /project/work/run-001 \
  -with-trace run-001/logs/trace.tsv \
  -with-report run-001/logs/report.html \
  -with-timeline run-001/logs/timeline.html \
  2>&1 | tee run-001/logs/nextflow.log

如果命令通过管道输出日志,Shell应启用pipefail或使用支持管道失败状态的调用方式,否则tee成功可能掩盖Nextflow失败退出码。运行后保存Nextflow打印的session ID和失败任务work路径。不要只保留终端截图。

分析失败原因,再用-resume

先从日志和trace找到失败process、错误退出码、输入路径和已申请资源;进入对应work目录查看.command.sh、.command.err、.command.out和.exitcode。判断是输入格式、软件环境、权限、磁盘空间还是资源上限。修复配置后,从同一项目位置、使用同一cache和work目录,带上-resume重新运行。不要在没有保留旧工作目录或缓存时承诺任务可恢复。

nextflow run main.nf \
  -profile docker \
  --input samplesheet.csv \
  -work-dir /project/work/run-001 \
  -resume \
  -with-trace run-001/logs/trace-resume.tsv \
  -with-report run-001/logs/report-resume.html \
  2>&1 | tee run-001/logs/resume.log

Nextflow官方文档说明,cache会记录task元信息,但恢复还要求对应输出文件存在于work目录中。改变输入、脚本、容器镜像或部分配置,都会使相关task重新计算;这是正确性保护,不代表resume失效。运行完成后核对trace中哪些task被复用、哪些重新执行,并验证最终输出清单和关键结果。

设置清理规则前先确认可恢复性

每批任务将流程版本、配置、cache、work路径、session ID、日志和结果校验值登记在运行清单中。结果已迁出且确认不再需要恢复后,才根据机构存储策略清理中间文件;若空间不足,可分批归档或在下一次运行前规划work容量,而不是在任务失败后立即删除目录。共享存储上的并发运行还应使用独立输出位置并保留各自session信息。

复现Nextflow任务需要流程、配置、输入、环境和执行痕迹共同完整。把它们按批次交接后,组员可以判断任务停在哪一步、哪些步骤可复用,以及是否因软件或参数变化而需要从头运行。

参考资料

下载练习材料

下载教程 PDF · 下载代码与示例数据 ZIP

先核对包内SHA256清单,再在独立目录复现。

需要额外算力时

适用前提:确定流程需要稳定执行环境与额外资源。如需额外资源,可评估服务器租赁及按需环境部署。咨询时说明软件版本、任务规模和使用期限,配置与支持范围另行确认。

咨询本任务的服务器配置

咨询本任务的服务器配置

留下手机号,我们会结合本文任务与您沟通服务器配置和报价。

也可联系云生信企业微信客服,说明本文任务。

把知识用于当前任务

下一步可以直接开始分析

按研究目标查找在线工具、课程、计算资源或完整分析服务。

按目标找方案仍有疑问,联系客服 ↗