nf-core 流程部署：常见问题

本节汇集了使用 nf-core 流程时最常遇到的问题及其解决方案。

环境和安装

Q: Docker 总是提示 permission denied？

A: 这是 Docker 权限问题。解决方法：

# 将用户添加到 docker 组
sudo usermod -aG docker $USER

# 注销并重新登录，或运行
newgrp docker

# 验证
docker ps

如果仍不工作，可以：

# 使用 sudo 运行 Nextflow（不推荐长期使用）
sudo nextflow run nf-core/rnaseq -profile docker

Q: 公司网络无法拉取 Docker 镜像？

A: 配置 Docker 镜像加速器：

# 编辑 Docker 配置
sudo nano /etc/docker/daemon.json

# 添加镜像源
{
  "registry-mirrors": [
    "https://mirror.ccs.tencentyun.com",
    "https://registry.docker-cn.com"
  ]
}

# 重启 Docker
sudo systemctl restart docker

或者使用离线模式（需要预先下载镜像）：

# 在有网络的环境下载镜像
docker pull nfcore/rnaseq:3.22.2

# 导出镜像
docker save nfcore/rnaseq:3.22.2 -o rnaseq.tar

# 在目标环境导入
docker load -i rnaseq.tar

Q: Nextflow 版本太旧，如何升级？

A: 使用自更新命令：

# 检查当前版本
nextflow -version

# 升级到最新版本
nextflow self-update

# 或重新安装
curl -s https://get.nextflow.io | bash
chmod +x nextflow
sudo mv nextflow /usr/local/bin/

流程执行

Q: 流程运行很慢，如何加速？

A: 性能优化取决于瓶颈所在：

1. 检查 CPU 使用率：

# 查看任务是否充分利用 CPU
top -u $USER

# 如果 CPU 利用率低，增加并行任务数
nextflow run nf-core/rnaseq \
    --max_cpus 128 \
    --max_tasks 16

2. 检查内存限制：

# 如果任务被 killed，增加内存
nextflow run nf-core/rnaseq \
    --max_memory '256.GB' \
    -resume

3. 使用工作目录在 SSD：

# I/O 密集型任务在 SSD 上更快
nextflow run nf-core/rnaseq \
    -work-dir /ssd/nextflow_work \
    -resume

Q: 流程中途失败，如何从断点恢复？

A: 使用 -resume 参数：

# Nextflow 自动缓存成功完成的结果
nextflow run nf-core/rnaseq \
    --input samplesheet.csv \
    --genome GRCh38

# 修改后重新运行（自动跳过已完成步骤）
nextflow run nf-core/rnaseq \
    --input samplesheet.csv \
    --genome GRCh38 \
    --skip_pseudo_aligner false \
    -resume  # 关键参数

注意：修改参数后，只有受影响的步骤会重新运行。

Q: 如何只运行流程的特定部分？

A: 使用 skip 参数跳过不需要的步骤：

# 只运行质控，不进行完整分析
nextflow run nf-core/rnaseq \
    --input samplesheet.csv \
    --skip_alignment true \
    --skip_quantification false \
    --skip_deseq2 true

# 跳过某些质控步骤
nextflow run nf-core/rnaseq \
    --input samplesheet.csv \
    --skip_fastqc true \
    --skip_multiqc false

Q: 如何查看流程运行了多久？

A: 使用 Nextflow 的内置命令：

# 查看流程执行时间
nextflow log nfcore-rnaseq-run -duration

# 查看每个任务的耗时
nextflow log nfcore-rnaseq-run -process

数据和样本

Q: 样本表格式错误，如何调试？

A: 使用验证脚本检查：

# 验证样本表
python scripts/generate_samplesheet.py \
    --validate samplesheet.csv rnaseq

# 常见错误：
# 1. 路径不是绝对路径
# 2. 缺少必需的列
# 3. Windows 行尾符（\r\n）
# 4. 文件名包含特殊字符

修复 Windows 行尾符：

# 使用 dos2unix
dos2unix samplesheet.csv

# 或使用 sed
sed -i 's/\r$//' samplesheet.csv

Q: FASTQ 文件命名不规范，如何处理？

A: 创建规范命名的符号链接：

# 原始文件名：sample_1.fastq.gz, sample_2.fastq.gz
# 目标命名：sample_R1.fastq.gz, sample_R2.fastq.gz

for file in *_1.fastq.gz; do
    base=$(basename $file _1.fastq.gz)
    ln -s $file ${base}_R1.fastq.gz
    ln -s ${base}_2.fastq.gz ${base}_R2.fastq.gz
done

然后从符号链接生成样本表。

Q: 如何合并多个样本表？

A: 使用 cat 命令，注意保留表头：

# 合并多个样本表
head -n 1 batch1_samplesheet.csv > combined_samplesheet.csv
tail -n +2 batch1_samplesheet.csv >> combined_samplesheet.csv
tail -n +2 batch2_samplesheet.csv >> combined_samplesheet.csv
tail -n +2 batch3_samplesheet.csv >> combined_samplesheet.csv

基因组和参考数据

Q: 流程报错"Genome not found in iGenomes cache"？

A: 检查基因组可用性：

# 检查已安装的基因组
python scripts/manage_genomes.py check GRCh38

# 如果不存在，下载
python scripts/manage_genomes.py download GRCh38

# 查看所有可用基因组
python scripts/manage_genomes.py list

Q: 如何使用自定义基因组？

A: 提供自定义基因组路径：

nextflow run nf-core/rnaseq \
    --input samplesheet.csv \
    --genome 'GRCh38' \
    --igenomes_base /path/to/custom/genomes \
    --fasta /path/to/genome.fa \
    --gtf /path/to/annotations.gtf \
    --star_index /path/to/star/index

基因组准备：

# 构建 STAR 索引
STAR --runThreadN 16 \
     --runMode genomeGenerate \
     --genomeDir /path/to/star/index \
     --genomeFastaFiles genome.fa \
     --sjdbGTFfile annotations.gtf \
     --sjdbOverhang 100

Q: 不同基因组版本如何选择？

A: 根据研究目的选择：

基因组	用途	备注
GRCh38	最新的人类研究	推荐用于新项目
GRCh37	旧研究对比	Legacy 数据
GRCm39	小鼠研究	最新版本
R64-1-1	酵母研究	常用模式生物
BDGP6	果蝇研究	D. melanogaster

注意：基因组版本对注释和坐标影响很大，确保与参考研究一致。

结果和输出

Q: 如何解读 MultiQC 报告？

A: 关注以下关键指标：

FastQC 部分：

Per Base Sequence Quality：所有位置的平均质量 > 30
Per Sequence GC Content：呈正态分布
Sequence Duplication Levels： duplication < 20%
Overrepresented Sequences：无非预期的高丰度序列

比对统计：

Alignment Rate：> 80%（对于 RNA-seq）
Mismatch Rate：< 5%
Insert Size：符合预期片段长度

如果有样本异常：

# 查看特定样本的 FastQC 报告
less results/fastqc/sample_fastqc.html

Q: 基因计数矩阵有很多 0，正常吗？

A: 可能正常，取决于数据类型：

RNA-seq：

低表达基因在所有样本中可能都是 0
稀疏矩阵是正常的
过滤低表达基因（如：至少在 3 个样本中 CPM > 1）

ATAC-seq：

大多数基因组区域应该是 0
只有开放染色质区域有信号
使用峰文件而不是全基因组计数

过滤示例（R）：

# 过滤低表达基因
keep <- rowSums(counts >= 10) >= 3
filtered_counts <- counts[keep, ]

Q: 如何提取特定的结果文件？

A: 使用 find 和 cp 命令：

# 查找所有 VCF 文件
find results/ -name "*.vcf.gz" -exec cp {} ./vcf_output/ \;

# 查找所有基因计数矩阵
find results/ -name "*gene_counts.tsv" -exec cp {} ./counts/ \;

# 查找所有 BAM 文件
find results/ -name "*.bam" -exec cp {} ./bam_files/ \;

错误排查

Q: 任务被 killed，如何解决？

A: 通常是内存或时间限制问题：

1. 内存不足（exit code 137）：

# 增加内存分配
nextflow run nf-core/rnaseq \
    --max_memory '256.GB' \
    -resume

2. 时间超限：

# 增加时间限制
nextflow run nf-core/rnaseq \
    --max_time '48.h' \
    -resume

3. 特定步骤的内存问题：

// 在 nextflow.config 中配置
process {
    withName: 'STAR_ALIGN' {
        memory = '128.GB'
        time = '24.h'
    }
}

Q: 工作目录占用大量空间，如何清理？

A: 安全清理工作目录：

# 1. 确认流程成功完成
grep "Pipeline completed successfully" .nextflow.log

# 2. 备份重要结果
cp -r results/ results_backup/

# 3. 清理工作目录
nextflow clean

# 4. 强制删除（如果确认不需要）
nextflow clean -f

# 5. 清理特定项目
nextflow clean -name nfcore-rnaseq-run

# 6. 清理特定缓存
nextflow clean -cache

注意：清理后无法使用 -resume 恢复。

Q: 如何查看失败的详细错误信息？

A: 检查特定任务的日志：

# 方法 1：使用 nextflow log
nextflow log -task -status failed

# 方法 2：查看工作目录中的错误日志
find work/ -name ".command.err" -exec tail -50 {} \;

# 方法 3：查看主日志
tail -100 .nextflow.log | grep -A 10 "ERROR"

HPC 和集群

Q: 在 SLURM 集群上如何提交任务？

A: 使用 SLURM profile：

nextflow run nf-core/rnaseq \
    -profile slurm,singularity \
    --input samplesheet.csv \
    --genome GRCh38 \
    --slurm_partition compute \
    --slurm_account my_account

自定义 SLURM 配置（nextflow.config）：

process {
    executor = 'slurm'
    clusterOptions = '--account=my_account --partition=compute'

    withName: 'STAR_ALIGN' {
        cpus = 16
        memory = '128.GB'
        time = '8.h'
        clusterOptions = '--qos=high'
    }
}

Q: Singularity 镜像下载很慢？

A: 预先下载镜像：

# 手动下载所有 Singularity 镜像
export SINGULARITY_CACHEDIR=/data/singularity_cache

# 在有网络的环境下载
singularity pull docker://nfcore/rnaseq:3.22.2

# 或使用 Nextflow 预下载
nextflow pull nf-core/rnaseq \
    -profile singularity \
    -singularity-cache-dir /data/singularity_cache

Q: 如何在集群上监控任务？

A: 使用 SLURM 命令：

# 查看所有任务
squeue -u $USER

# 查看任务详情
scontrol show job <JOB_ID>

# 查看 Nextflow 提交的任务
squeue -u $USER | grep "nextflow"

数据隐私和安全

Q: 如何处理包含敏感信息的测序数据？

A: 遵循数据保护最佳实践：

1. 加密存储：

# 加密 FASTQ 文件
gpg -c sensitive_data.fastq.gz
# 产生：sensitive_data.fastq.gz.gpg

# 解密
gpg sensitive_data.fastq.gz.gpg

2. 限制权限：

# 设置严格的文件权限
chmod 700 sensitive_data/
chmod 600 sensitive_data/*.fastq.gz

3. 使用安全传输：

# 使用 SFTP/SCP 传输
scp -C sensitive_data.fastq.gz user@secure-server:/data/

# 使用 rsync over SSH
rsync -avz -e ssh sensitive_data/ user@secure-server:/data/

Q: 结果数据可以公开发布吗？

A: 取决于数据类型和伦理批准：

可以发布：

汇总统计结果
变异频率数据
已去标识化的表达矩阵

需要谨慎：

原始 FASTQ（可能包含个体信息）
完整的基因型数据
罕见变异的精确位置

建议：

查阅伦理批准文件
遵循机构数据政策
使用受控访问数据库（如 dbGaP）

性能和成本

Q: 在云平台运行的成本如何估算？

A: 根据 CPU、内存、存储计算：

AWS EC2 示例（RNA-seq，10 个样本）：

实例类型	vCPU	内存	成本/小时	预计时间	总成本
r5.8xlarge	32	256GB	$2.67	6 小时	~$16

存储成本：

输入数据：10 样本 × 10GB = 100GB
中间文件：~500GB
结果文件：~50GB

总计：650GB × $0.023/GB/月 = ~$15/月

优化成本：

使用 Spot 实例（节省 70-90%）
及时删除中间文件
使用 S3 Glacier 归档旧数据
预留实例（长期项目）

Q: 如何减少云存储费用？

A: 分层存储策略：

# 1. 热数据（频繁访问）：S3 Standard
aws s3 cp results/ s3://my-bucket/results/ --recursive

# 2. 温数据（偶尔访问）：S3 Standard-IA
aws s3 cp results/ s3://my-bucket/results/ \
    --storage-class STANDARD_IA \
    --recursive

# 3. 冷数据（归档）：S3 Glacier
aws s3 cp old_results/ s3://my-bucket/archive/ \
    --storage-class GLACIER \
    --recursive

# 4. 删除不需要的中间文件
aws s3 rm s3://my-bucket/work/ --recursive

其他常见问题

Q: 可以使用其他流程吗？

A: nf-core 有很多流程：

# 查看所有可用流程
nf-core list

# 搜索特定流程
nf-core list | grep chipseq

# 使用其他流程
nextflow run nf-core/chipseq \
    -profile docker \
    --input samplesheet.csv

Q: 如何引用 nf-core 流程？

A: 查看 CITATIONS.md：

# RNA-seq 流程引用
1. nf-core/rnaseq pipeline
   https://doi.org/10.5281/zenodo.XXXXX

2. Nextflow framework
   Di Tommaso et al. (2017) Nat. Biotechnol. 35(4):316-319

3. 各软件工具的引用（见 MultiQC 报告）

在论文中：

RNA-seq analysis was performed using the nf-core/rnaseq pipeline
(v3.22.2) [1]. The pipeline was run with Nextflow (v23.10.0) [2]
using Docker containers for software reproducibility.

Q: 报错时如何获取帮助？

A: 寻求支持的途径：

1. 查看 nf-core 文档：

https://nf-co.re/tools
各流程的详细文档

2. 搜索 GitHub Issues：

https://github.com/nf-core/rnaseq/issues
可能已有相同问题

3. 提问时提供：

Nextflow 版本：nextflow -version
完整命令：运行流程的命令
错误信息：.nextflow.log 中的相关部分
系统信息：OS、Docker 版本等

4. 论坛和社区：

nf-core Slack：https://nf-co.re/join
Nextflow Gitter：https://gitter.im/nextflow-io/nextflow


## 下一步

如果问题未解决：

1. 检查环境配置：`python scripts/check_environment.py`
2. 运行测试配置：`-profile test,docker`
3. 查看详细日志：`nextflow log -duration -process`
4. 在社区寻求帮助（提供详细信息）