本文还有配套的精品资源点击获取简介一套开箱即用的命令行工具专为批量获取NCBI SRA数据库中的原始测序数据设计。核心脚本sra-download.sh读取SraAccList.txt里的SRA编号如SRR1234567再对照sample_list.txt中的样本名自动创建带命名逻辑的输出目录结构下载完成后直接生成标准FASTQ文件支持gzip压缩。整个流程支持一次处理几十到几百个SRA条目无需人工干预不依赖图形界面。已内置示例数据含ATAC_N1_1.fastq.gz等真实FASTQ、预配置的列表模板和完整README说明还包含重复校验所需的文件结构参考。运行前需在Linux或macOS系统中安装sra-toolkit 3.0.0及以上版本并完成prefetch初始化配置。所有操作均通过终端执行适合生信分析前的数据准备环节可无缝衔接后续质控、比对或组装流程。1. 项目概述为什么你需要这套脚本而不是手动敲几十遍fastq-dump在生物信息分析的日常工作中我几乎每周都要从NCBI SRA数据库拉取公开数据——可能是别人发表的ATAC-seq、ChIP-seq、单细胞RNA-seq也可能是自己实验室上传后需要回溯验证的原始reads。最开始我用prefetch SRR1234567 fastq-dump --gzip --outdir ./fastq SRR1234567一条条复制粘贴处理10个SRA还行到第37个时手抖输错一个SRR编号fastq-dump报错退出前面36个白跑了还得逐个检查.sra文件是否完整、.fastq.gz是否生成成功、文件名是不是带了_1_2后缀……那一刻我就决定必须把这件事交给Shell。这套sra-download.sh不是“又一个下载脚本”它解决的是真实批量场景下的三重断点第一是命名混乱——SRA登录号如SRR1234567对人毫无意义但下游比对、质控工具如fastp、bwa、STAR要求输入文件名体现样本来源比如ATAC_N1_1.fastq.gz。手动重命名百个文件不现实。第二是流程断裂——prefetch只下.srafastq-dump才转FASTQ中间若网络中断、磁盘满、权限不足脚本就卡死你得人工介入查日志、删残缺文件、续传。而这个脚本内置状态检查与断点续传逻辑失败条目自动跳过并记录到failed.log不影响后续任务。第三是环境不可控——Mac用户常被brew install sra-tools后的路径问题折磨/opt/homebrew/binvs/usr/local/binLinux用户可能遇到libcrypto版本冲突。脚本开头就做command -v prefetch和command -v fastq-dump双校验并提示缺失时的精准安装命令含macOS M1/M2芯片适配说明不让你卡在第一步。它面向三类人-刚入门的生信新手不用记--split-files和--gzip参数组合sample_list.txt里写好SRR1234567\tATAC_N1运行脚本就出ATAC_N1_1.fastq.gz和ATAC_N1_2.fastq.gz-跑批量分析的老手支持--dry-run预览将要执行的命令支持--threads 8指定并发数支持--outdir /data/sra_fastq自定义根目录所有配置都集中在一个config.sh里改一处全局生效-需要复现的科研人员SraAccList.txt和sample_list.txt是纯文本可直接Git版本管理每个FASTQ文件生成时自动写入md5sum到checksums.md5确保数据完整性可审计。关键词里的“SRA批量下载”不是指“能下多个”而是指按实验设计逻辑组织输出“FASTQ转换”不是简单调用fastq-dump而是根据--split-3或--split-files策略智能判断单端/双端并补全_1/_2后缀“Shell自动化”意味着它不依赖Python环境、不装额外包、不改系统PATH只要bash和sra-toolkit在PATH里chmod x sra-download.sh ./sra-download.sh就能跑通“sra-toolkit”在这里不是可选依赖而是整个流程的基石——我们后面会深入讲为什么必须用v3.0.0以及如何绕过它最坑的三个默认行为。2. 核心设计思路拆解为什么不用parallelxargs而要自己写状态机很多人第一反应是“不就是循环下载吗用cat SraAccList.txt | parallel -j 4 prefetch {} fastq-dump --gzip {}不就完了”——我试过而且踩了深坑。下面说清楚为什么这个脚本选择“自己造轮子”而不是套用现成的并行工具。2.1 并行不是越多越好sra-toolkit的资源锁机制sra-toolkit底层用libsra访问NCBI的云存储它内部有连接池和缓存锁。实测发现当parallel -j 8同时启动8个prefetch进程时前2个能正常下载后6个会卡在Resolving...状态长达10分钟以上最终超时失败。这是因为sra-toolkit默认只允许2个并发HTTP连接可通过~/.ncbi/user-settings.mkfg修改但普通用户根本找不到这个文件在哪。而我们的脚本采用串行预取并行转换策略先用单线程prefetch把所有.sra文件拉到本地缓存~/ncbi/dbGaP-*/再用多线程fastq-dump从本地缓存读取转换。这样既规避了网络并发瓶颈又保证了转换阶段的CPU利用率。提示脚本中PREFETCH_CONCURRENCY1是硬编码值不是bug是经验之谈。如果你的服务器带宽超1Gbps且磁盘IO极强如NVMe RAID可手动改为2但务必配合--max-size 50G限制单个SRA缓存大小否则prefetch会把整个~/ncbi/塞爆。2.2 状态持久化为什么failed.log比set -e更可靠Shell里常用set -e让脚本在任意命令失败时退出。但sra-toolkit的错误码很“佛系”prefetch下载失败返回124fastq-dump内存不足返回137而网络超时可能返回0因为它把部分数据写进了临时文件。如果只靠set -e脚本会在第5个SRA失败时直接终止剩下95个永远没机会执行。我们的方案是每个SRA处理封装为独立函数函数内用if ! command; then echo SRRxxx failed failed.log; continue; fi显式捕获错误并记录失败原因如curl: (7) Failed to connect或fastq-dump: error while loading shared libraries。这样即使100个里失败30个脚本仍能跑完最后给你一份清晰的failed.log你可以针对性重试而不是重头再来。2.3 命名逻辑的工程化实现从SRR1234567到ATAC_N1_1.fastq.gz的三步映射这是整个脚本最核心的设计。很多教程教你在fastq-dump后用mv重命名但问题在于-fastq-dump SRR1234567默认输出SRR1234567.fastq.gz单端或SRR1234567_1.fastq.gz/SRR1234567_2.fastq.gz双端- 但SRR1234567对应哪个样本哪个测序批次哪个文库类型这些信息不在SRA元数据里必须由你人工维护。我们的解法是引入双列表映射机制1.SraAccList.txt纯SRA登录号列表每行一个无空格无注释SRR1234567\nSRR7654321\n2.sample_list.txtTSV格式第一列SRA号第二列样本名第三列可选文库类型如paired/single第四列可选压缩策略gzip/noneSRR1234567 ATAC_N1 paired gzip SRR7654321 RNA_S2 single none脚本读取时用awk NRFNR{acc[$1]1;next} $1 in acc{print} SraAccList.txt sample_list.txt做交集过滤确保只处理两个文件都存在的SRA号。然后对每个匹配行执行-prefetch --output-directory ./cache $sra_id→ 下载到./cache/SRR1234567.sra-fastq-dump --split-files --gzip --outdir ./fastq --skip-technical --read-filter pass $sra_id→ 输出./fastq/SRR1234567_1.fastq.gz和./fastq/SRR1234567_2.fastq.gz- 最后用mv ./fastq/${sra_id}_1.fastq.gz ./fastq/${sample_name}_1.fastq.gz完成语义化重命名。注意--skip-technical跳过接头、引物等技术序列--read-filter pass只保留质量合格的reads——这两个参数是生信分析的黄金组合避免下游工具因低质量reads报错。脚本默认开启你不需要记住。2.4 安全边界控制为什么--max-size和--verify不是可选项SRA数据库里有些条目是整套WGS数据单个SRA超200GB。如果脚本不加限制prefetch SRR9999999可能一夜之间吃光你1TB硬盘。因此脚本强制要求在config.sh中设置MAX_SRA_SIZE50G单位支持K/M/G/T并在prefetch命令中加入--max-size $MAX_SRA_SIZE。实测发现当--max-size 50G时prefetch对超大SRA会返回错误码255并输出Error: SRA object exceeds maximum allowed size脚本捕获此错误后写入failed.log并继续下一个而不是硬扛。另一个关键是--verify。prefetch默认不校验下载完整性只检查HTTP响应头。而NCBI偶尔会因CDN缓存问题返回截断的.sra文件尤其在中国大陆节点。开启--verify后prefetch会下载完成后用SHA256比对NCBI服务器上的原始哈希值确保字节级一致。虽然耗时增加15%但避免了后续fastq-dump解析时报Invalid SRA file这种让人抓狂的错误。脚本默认启用且在failed.log中明确标注“VERIFY FAILED”便于排查。3. 核心细节解析与实操要点从零配置到首次成功运行现在我们进入实操环节。别急着运行脚本先理解每个配置项背后的物理意义。我以macOS MontereyM1 Pro芯片和Ubuntu 22.04 LTS为例全程演示如何让脚本真正“开箱即用”。3.1 sra-toolkit安装避开官方文档埋的三个雷NCBI官网的安装指南写着“conda install -c bioconda sra-tools”但这是最不推荐的方式。原因有三- Conda环境中的sra-toolkit常与系统Python冲突尤其当你用pyenv管理Python版本时fastq-dump可能加载错误的libpython导致Segmentation Fault- Bioconda频道的sra-tools更新滞后v3.0.0发布半年后Conda版本还是v2.11.3缺少关键的--verify和--max-size支持- Conda安装的二进制文件路径不统一~/miniconda3/bin/or~/anaconda3/bin/脚本检测时容易漏判。正确姿势macOS# 1. 用Homebrew安装M1/M2芯片必须用arm64版本 arch -arm64 brew install sra-tools # 2. 验证安装路径应为/opt/homebrew/bin/ which prefetch fastq-dump # 输出/opt/homebrew/bin/prefetch 和 /opt/homebrew/bin/fastq-dump # 3. 初始化配置关键这步决定后续是否能连上NCBI vdb-config --interactive # 在交互界面中 # - 按2进入Preferences # - 按1进入Network # - 将Cache Directory设为高速磁盘如/Volumes/SSD/ncbi_cache # - 将Network Timeout从30秒改为120秒防国内网络波动 # - 按Esc退出保存配置正确姿势Linux# 1. 下载官方二进制包不要用aptUbuntu源太旧 wget https://ftp-trace.ncbi.nlm.nih.gov/sra/sdk/current/sratoolkit.current-ubuntu64.tar.gz tar -xzf sratoolkit.current-ubuntu64.tar.gz export PATH$PWD/sratoolkit.3.0.3-ubuntu64/bin:$PATH # 2. 创建软链接避免路径硬编码脚本检测时会找prefetch在PATH中 sudo ln -sf $PWD/sratoolkit.3.0.3-ubuntu64/bin/prefetch /usr/local/bin/prefetch sudo ln -sf $PWD/sratoolkit.3.0.3-ubuntu64/bin/fastq-dump /usr/local/bin/fastq-dump # 3. 初始化同macOS但配置文件在~/.ncbi/ vdb-config --interactive提示vdb-config --interactive生成的配置文件在~/.ncbi/user-settings.mkfg里面有一行/repository/user/main/public/root /path/to/cache这就是prefetch默认下载位置。脚本里所有--output-directory参数都基于此路径做相对定位所以初始化这一步绝不能跳过。3.2 配置文件config.sh详解每个变量都是血泪教训脚本根目录下的config.sh是唯一需要你手动编辑的文件。它不是“配置模板”而是运行时的决策中心。以下是逐行解读#!/bin/bash # config.sh —— 所有可调参数集中在此 # 【必填】SRA登录号列表文件路径绝对路径或相对于脚本所在目录 SRA_LISTSraAccList.txt # 【必填】样本映射表路径TSV格式SRA_IDtabSample_NametabLibrary_TypetabCompression SAMPLE_MAPsample_list.txt # 【必填】本地缓存目录prefetch下载.sra文件的位置 # 强烈建议设在SSD或高速NAS避免HDD成为IO瓶颈 CACHE_DIR./cache # 【必填】FASTQ输出根目录最终生成ATAC_N1_1.fastq.gz的地方 FASTQ_DIR./fastq # 【可选】最大单个SRA文件大小防止下载超大WGS数据撑爆磁盘 # 单位K/M/G/T必须带字母如50G、2T MAX_SRA_SIZE50G # 【可选】并发线程数fastq-dump阶段prefetch始终单线程 # 经验值CPU核心数-2留2核给系统和其他进程 THREADS6 # 【可选】是否启用校验强烈建议true避免数据损坏 VERIFYtrue # 【可选】是否启用gzip压缩false则输出未压缩FASTQ占空间但IO快 GZIP_COMPRESSIONtrue # 【可选】是否跳过已存在的FASTQ文件用于增量更新 SKIP_EXISTINGtrue # 【可选】日志级别debug/info/warn/error LOG_LEVELinfo # 【高级】自定义fastq-dump参数慎用覆盖默认安全参数 # 默认已包含--skip-technical --read-filter pass --clip # 如需添加--origfmt请取消下面注释并确认你的下游工具支持 # FASTQ_DUMP_OPTS--origfmt重点解释三个易错点-CACHE_DIR和FASTQ_DIR必须是相对路径或绝对路径不能是~/开头的波浪线。因为Shell脚本中~在非交互式环境下不会展开prefetch --output-directory ~/cache会被当成字面量目录名导致创建./~/cache这种诡异路径。正确写法是CACHE_DIR$HOME/cache或CACHE_DIR/data/ncbi_cache。-SKIP_EXISTINGtrue不是简单的[ -f $out_file ] continue。脚本实际检查的是$FASTQ_DIR/$sample_name_1.fastq.gz和$FASTQ_DIR/$sample_name_2.fastq.gz双端或$FASTQ_DIR/$sample_name.fastq.gz单端是否存在且文件大小1MB排除空文件。这样即使你中途CtrlC重启后也不会重复转换。-LOG_LEVELdebug会输出每一行执行的完整命令如 prefetch --max-size 50G --output-directory ./cache SRR1234567适合排查网络问题error则只记录失败条目适合生产环境静默运行。3.3 示例文件example/的结构意图教你如何组织自己的数据example/目录不是摆设它是最小可行实验单元。里面包含-SraAccList.txt仅两行SRR1234567和SRR7654321-sample_list.txt对应两行SRR1234567\tATAC_N1\tpaired\tgzip和SRR7654321\tRNA_S2\tsingle\tnone-ATAC_N1_1.fastq.gz和ATAC_N1_2.fastq.gz真实的、可直接用zcat ATAC_N1_1.fastq.gz | head -n 4查看的FASTQ内容前4行是第一条read的ID、序列、号、质量值-checksums.md5记录这两个FASTQ文件的MD5值供你验证脚本生成结果是否一致。它的设计逻辑是你能用example/里的文件跑通脚本就证明你的环境100%可用反之如果example/都跑不通一定是环境问题不是数据问题。我建议你首次运行时先cp -r example/* .覆盖当前目录然后./sra-download.sh——如果成功你会看到-./cache/SRR1234567.sra约1.2GB-./fastq/ATAC_N1_1.fastq.gz和./fastq/ATAC_N1_2.fastq.gz各约600MB-./fastq/checksums.md5里新增两行MD5-./sra-download.log里记录时间戳和成功条目。实操心得第一次运行时我总在./fastq/里看到SRR1234567_1.fastq.gz而不是ATAC_N1_1.fastq.gz查了半小时才发现sample_list.txt里SRA号多了一个空格SRR1234567导致awk匹配失败。脚本为此增加了空格trim逻辑sra_id$(echo $sra_id | sed s/^[[:space:]]*//;s/[[:space:]]*$//)但最好的习惯仍是编辑TSV时用VS Code打开开启“显示空白字符”功能。4. 实操过程与核心环节实现一次完整运行的逐帧解析现在我们模拟一次真实运行。假设你要下载某篇Nature论文补充材料里的23个ATAC-seq样本SRA号已整理好目标是生成SAMPLE_A_1.fastq.gz格式的文件存到/data/project_x/atac_fastq/。4.1 准备工作构建你的专属输入文件首先创建干净的工作目录mkdir -p /data/project_x/sra_download cd /data/project_x/sra_download然后准备两个核心输入文件-SraAccList.txt把你从论文Supplementary Table里复制的23个SRA号每行一个确保无空行、无空格、无中文逗号。可以用sed -i s/[[:space:]]*$// SraAccList.txt清理尾部空格。-sample_list.txt用Excel或LibreOffice Calc编辑列为SRA_ID、Sample_Name、Library_Type、Compression。例如SRR1234567 SAMPLE_A paired gzip SRR2345678 SAMPLE_B paired gzip ... SRR9876543 SAMPLE_W paired gzip保存为UTF-8编码的TSV格式不是CSV用file sample_list.txt确认输出sample_list.txt: UTF-8 Unicode text, with CRLF line terminators如果是with CR line terminators用dos2unix sample_list.txt转换。提示Library_Type列必须小写且精确为paired或single。脚本用if [[ $lib_type paired ]]; then ...判断写成Paired或PAIRED会导致fastq-dump不加--split-files参数双端数据全挤在一个文件里下游bwa mem直接报错。4.2 配置config.sh针对本次任务定制编辑config.shSRA_LISTSraAccList.txt SAMPLE_MAPsample_list.txt CACHE_DIR/data/project_x/sra_cache # SSD盘预留200GB FASTQ_DIR/data/project_x/atac_fastq # 目标输出目录 MAX_SRA_SIZE30G # 论文里最大SRA是28G留2G余量 THREADS8 # 服务器有16核留8核给其他任务 VERIFYtrue GZIP_COMPRESSIONtrue SKIP_EXISTINGtrue LOG_LEVELinfo4.3 首次运行观察日志理解每个阶段执行chmod x sra-download.sh time ./sra-download.sh输出日志分四段我们逐段解读阶段一环境与配置检查约5秒[INFO] Checking dependencies... [INFO] prefetch found at /opt/homebrew/bin/prefetch [INFO] fastq-dump found at /opt/homebrew/bin/fastq-dump [INFO] sra-toolkit version: 3.0.3 [INFO] Loading config from config.sh... [INFO] SRA list: SraAccList.txt (23 entries) [INFO] Sample map: sample_list.txt (23 entries) [INFO] Cache dir: /data/project_x/sra_cache [INFO] FASTQ dir: /data/project_x/atac_fastq这里脚本做了三件事-command -v prefetch和command -v fastq-dump确认二进制存在-prefetch --version 21 | grep sratoolkit提取版本号确保≥3.0.0-wc -l SraAccList.txt和wc -l sample_list.txt统计行数并用comm -12 (sort SraAccList.txt) (sort -k1,1 sample_list.txt) | wc -l计算交集数量确保23个SRA在两个文件里都存在。如果交集只有20脚本会报错并列出缺失的3个SRA号。阶段二预取prefetch阶段耗时最长取决于网络[INFO] Starting prefetch phase (1/23)... [INFO] prefetch --max-size 30G --verify --output-directory /data/project_x/sra_cache SRR1234567 [INFO] Downloading SRR1234567... [████████████████████] 100% 1.23G/1.23G 8.2MB/s [INFO] Verification passed for SRR1234567 [INFO] Starting prefetch phase (2/23)... ...注意两点- 进度条是脚本自己用pvPipe Viewer实现的如果系统没装pv会退化为纯文字进度不影响功能-Verification passed表示SHA256校验通过这是数据可靠的铁证。阶段三转换fastq-dump阶段CPU密集型[INFO] Starting fastq-dump phase (1/23)... [INFO] fastq-dump --split-files --gzip --outdir /data/project_x/atac_fastq --skip-technical --read-filter pass --threads 8 /data/project_x/sra_cache/SRR1234567.sra [INFO] Converting SRR1234567 to FASTQ... [████████████████████] 100% 1.23G/1.23G 120MB/s [INFO] Renaming SRR1234567_1.fastq.gz to SAMPLE_A_1.fastq.gz [INFO] Renaming SRR1234567_2.fastq.gz to SAMPLE_A_2.fastq.gz [INFO] Calculating MD5 for SAMPLE_A_1.fastq.gz... [INFO] Calculating MD5 for SAMPLE_A_2.fastq.gz...这里的关键是--threads 8——fastq-dump的多线程是真正的并行解压和格式转换不是伪并行。实测8线程比单线程快5.2倍不是8倍因为有IO和内存带宽瓶颈。阶段四收尾与校验[INFO] All done! 23/23 SRA processed. [INFO] Successful: 23, Failed: 0 [INFO] Output FASTQ files in /data/project_x/atac_fastq/ [INFO] Checksums written to /data/project_x/atac_fastq/checksums.md5 [INFO] Log saved to /data/project_x/sra_download/sra-download.log此时/data/project_x/atac_fastq/下应该有46个文件23×2每个SAMPLE_X_1.fastq.gz文件用zcat查看前4行应该是标准FASTQ格式SRR1234567.1 1 length150 NGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGA IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII4.4 处理失败failed.log里的每一行都是线索假设第7个SRASRR3456789失败failed.log里记录2024-06-15 14:22:33 ERROR SRR3456789: prefetch failed with code 255: Error: SRA object exceeds maximum allowed size这说明该SRA实际大小超30G而你设的MAX_SRA_SIZE30G。解决方案- 查NCBI SRA页面确认该SRA真实大小页面右上角有“Size”字段- 如果确实是35G临时修改config.shMAX_SRA_SIZE40G- 删除./cache/SRR3456789.sra避免prefetch跳过- 运行./sra-download.sh --resume-from SRR3456789脚本支持--resume-from参数从指定SRA继续不重跑前面23个。另一个常见错误2024-06-15 14:25:11 ERROR SRR4567890: fastq-dump failed with code 137: Killed代码1371289表示被SIGKILL杀死通常是内存不足。解决方案- 降低THREADS值如从8降到4- 或在config.sh里加FASTQ_DUMP_OPTS--mem 4G限制单个fastq-dump进程内存上限。5. 常见问题与排查技巧实录那些让我熬夜到凌晨三点的Bug以下是我过去两年用这套脚本处理超过12000个SRA条目时遇到的TOP 5高频问题及独家解决方案。它们不在任何官方文档里但能帮你省下至少20小时调试时间。5.1 问题速查表现象可能原因快速诊断命令解决方案prefetch卡在Resolving...超10分钟DNS污染或NCBI CDN节点异常dig trace.ncbi.nlm.nih.gov short看返回IP是否在国内如114.114.114.114在~/.ncbi/user-settings.mkfg里加/http/proxy/host 127.0.0.1和/http/proxy/port 8123需自建HTTP代理或换DNS为223.5.5.5fastq-dump报error while loading shared libraries: libcrypto.so.1.1macOS/Linux动态库版本冲突otool -L $(which fastq-dump)macOS或ldd $(which fastq-dump)Linux用install_name_tool -changemacOS或patchelfLinux修复库路径或重装sra-toolkit生成的FASTQ文件全是SRRxxxxxx.1开头不是SAMPLE_X.1sample_list.txt编码不是UTF-8或列分隔符不是Tabfile sample_list.txt和hexdump -C sample_list.txt | head用iconv -f GBK -t UTF-8 sample_list.txt tmp mv tmp sample_list.txt转码用sed s/ \/\t/g sample_list.txt把空格转Tab./fastq/里只有SRRxxxxxx.fastq.gz没有_1/_2后缀sample_list.txt里Library_Type写成了paired-end而非pairedawk -F\t {print $3} sample_list.txt | sort -u全局替换sed -i s/paired-end/paired/g sample_list.txt脚本运行后./fastq/为空但./cache/里有.sra文件SKIP_EXISTINGtrue且./fastq/里已有同名文件但文件大小1MBls -lh ./fastq/和find ./fastq/ -size -1M删除小文件find ./fastq/ -size -1M -delete再重试5.2 独家避坑技巧技巧1用--dry-run预演避免误操作加--dry-run参数后脚本不执行任何下载或转换只打印将要运行的完整命令./sra-download.sh --dry-run输出类似DRY RUN: prefetch --max-size 30G --verify --output-directory /data/project_x/sra_cache SRR1234567 DRY RUN: fastq-dump --split-files --gzip --outdir /data/project_x/atac_fastq --skip-technical --read-filter pass --threads 8 /data/project_x/sra_cache/SRR1234567.sra DRY RUN: mv /data/project_x/atac_fastq/SRR1234567_1.fastq.gz /data/project_x/atac_fastq/SAMPLE_A_1.fastq.gz这能让你100%确认路径对不对参数对不对重命名逻辑对不对我在处理一个300样本的项目前必先--dry-run花2分钟看50行命令比跑1小时后发现全错了强百倍。技巧2--force-verify强制重校验已下载的.sra有时你怀疑某个.sra文件损坏比如fastq-dump报Invalid SRA file但又不想重下几GB。脚本提供--force-verify./sra-download.sh --force-verify SRR1234567它会跳过下载直接对./cache/SRR1234567.sra执行prefetch --verify --input-file ./cache/SRR1234567.sra校验失败则删除该文件下次运行自动重下。技巧3用--list-samples快速生成sample_list.txt骨架如果你只有SraAccList.txt但不知道每个SRA对应什么样本名可以先用NCBI E-Utilities API批量获取元数据./sra-download.sh --list-samples SraAccList.txt sample_list_skeleton.txt它会调用esearchesummary输出SRR1234567 SRR1234567_paired paired gzip SRR2345678 SRR2345678_paired paired gzip然后你用Excel打开sample_list_skeleton.txt把第二列SRR1234567_paired手工改成SAMPLE_A保存即可。这比一个个去NCBI网页复制快10倍。技巧4--cleanup-cache安全清理缓存./cache/目录会越积越大。脚本提供--cleanup-cache但它不是简单rm -rf ./cache而是- 先扫描./fastq/里所有已成功生成的FASTQ文件- 对每个FASTQ反向推导其来源SRA号如SAMPLE_A_1.fastq.gz→SRR1234567- 只删除./cache/里不在任何FASTQ文件名中出现的.sra文件- 最后留下./cache/SRR1234567.sra等正在使用的文件确保下次运行无需重下。命令./sra-download.sh --cleanup-cache5.3 性能调优实战从3小时到22分钟我曾用这套脚本处理一个84样本的scRNA-seq项目每个SRA平均8GB初始配置THREADS4耗时3小时12分钟。通过以下三步优化压缩到22分钟Step 1IO瓶颈定位用iostat -x 1监控发现%util长期100%await超200ms说明磁盘是瓶颈。解决方案把CACHE_DIR和FASTQ_DIR都指向同一块NVMe SSD/mnt/nvme/sra/避免HDD和SSD间拷贝。Step 2内存带宽释放fastq-dump默认用全部内存解压。用htop看8个进程共占24GB内存触发系统swap。在config.sh里加FASTQ_DUMP_OPTS--mem 3G限制每个进程最多用3GB8个共24GB刚好占满64GB内存的37.5%避免swap。Step 3并发策略重构原脚本是“prefetch串行→fastq-dump并行”。改为“prefetch分批并行fastq-dump流水线”- 把84个SRA分成4组每组21个- 每组启动一个prefetch进程parallel -j 4- 每组prefetch完成后立即启动该组的fastq-dump--jobs 4脚本内置--batch-size 21参数支持此模式。最终耗时22分钟提速8.3倍。最后分享一个小技巧处理超大项目前先用./sra-download.sh --dry-run | wc -l算出总命令数再除以你的THREADS就能预估fastq-dump阶段的理论最短时间单位秒。比如84个SRATHREADS8fastq-dump平均每个耗时90秒则理论时间≈84/8×90945秒≈15.75分钟。实际22分钟说明IO和内存还有优化空间——这就是工程化的魅力一切可测量一切可优化。本文还有配套的精品资源点击获取简介一套开箱即用的命令行工具专为批量获取NCBI SRA数据库中的原始测序数据设计。核心脚本sra-download.sh读取SraAccList.txt里的SRA编号如SRR1234567再对照sample_list.txt中的样本名自动创建带命名逻辑的输出目录结构下载完成后直接生成标准FASTQ文件支持gzip压缩。整个流程支持一次处理几十到几百个SRA条目无需人工干预不依赖图形界面。已内置示例数据含ATAC_N1_1.fastq.gz等真实FASTQ、预配置的列表模板和完整README说明还包含重复校验所需的文件结构参考。运行前需在Linux或macOS系统中安装sra-toolkit 3.0.0及以上版本并完成prefetch初始化配置。所有操作均通过终端执行适合生信分析前的数据准备环节可无缝衔接后续质控、比对或组装流程。本文还有配套的精品资源点击获取
Linux/macOS下用Shell脚本自动批量下载SRA测序数据并转FASTQ
发布时间：2026/6/2 12:39:24
本文还有配套的精品资源点击获取简介一套开箱即用的命令行工具专为批量获取NCBI SRA数据库中的原始测序数据设计。核心脚本sra-download.sh读取SraAccList.txt里的SRA编号如SRR1234567再对照sample_list.txt中的样本名自动创建带命名逻辑的输出目录结构下载完成后直接生成标准FASTQ文件支持gzip压缩。整个流程支持一次处理几十到几百个SRA条目无需人工干预不依赖图形界面。已内置示例数据含ATAC_N1_1.fastq.gz等真实FASTQ、预配置的列表模板和完整README说明还包含重复校验所需的文件结构参考。运行前需在Linux或macOS系统中安装sra-toolkit 3.0.0及以上版本并完成prefetch初始化配置。所有操作均通过终端执行适合生信分析前的数据准备环节可无缝衔接后续质控、比对或组装流程。1. 项目概述为什么你需要这套脚本而不是手动敲几十遍fastq-dump在生物信息分析的日常工作中我几乎每周都要从NCBI SRA数据库拉取公开数据——可能是别人发表的ATAC-seq、ChIP-seq、单细胞RNA-seq也可能是自己实验室上传后需要回溯验证的原始reads。最开始我用prefetch SRR1234567 fastq-dump --gzip --outdir ./fastq SRR1234567一条条复制粘贴处理10个SRA还行到第37个时手抖输错一个SRR编号fastq-dump报错退出前面36个白跑了还得逐个检查.sra文件是否完整、.fastq.gz是否生成成功、文件名是不是带了_1_2后缀……那一刻我就决定必须把这件事交给Shell。这套sra-download.sh不是“又一个下载脚本”它解决的是真实批量场景下的三重断点第一是命名混乱——SRA登录号如SRR1234567对人毫无意义但下游比对、质控工具如fastp、bwa、STAR要求输入文件名体现样本来源比如ATAC_N1_1.fastq.gz。手动重命名百个文件不现实。第二是流程断裂——prefetch只下.srafastq-dump才转FASTQ中间若网络中断、磁盘满、权限不足脚本就卡死你得人工介入查日志、删残缺文件、续传。而这个脚本内置状态检查与断点续传逻辑失败条目自动跳过并记录到failed.log不影响后续任务。第三是环境不可控——Mac用户常被brew install sra-tools后的路径问题折磨/opt/homebrew/binvs/usr/local/binLinux用户可能遇到libcrypto版本冲突。脚本开头就做command -v prefetch和command -v fastq-dump双校验并提示缺失时的精准安装命令含macOS M1/M2芯片适配说明不让你卡在第一步。它面向三类人-刚入门的生信新手不用记--split-files和--gzip参数组合sample_list.txt里写好SRR1234567\tATAC_N1运行脚本就出ATAC_N1_1.fastq.gz和ATAC_N1_2.fastq.gz-跑批量分析的老手支持--dry-run预览将要执行的命令支持--threads 8指定并发数支持--outdir /data/sra_fastq自定义根目录所有配置都集中在一个config.sh里改一处全局生效-需要复现的科研人员SraAccList.txt和sample_list.txt是纯文本可直接Git版本管理每个FASTQ文件生成时自动写入md5sum到checksums.md5确保数据完整性可审计。关键词里的“SRA批量下载”不是指“能下多个”而是指按实验设计逻辑组织输出“FASTQ转换”不是简单调用fastq-dump而是根据--split-3或--split-files策略智能判断单端/双端并补全_1/_2后缀“Shell自动化”意味着它不依赖Python环境、不装额外包、不改系统PATH只要bash和sra-toolkit在PATH里chmod x sra-download.sh ./sra-download.sh就能跑通“sra-toolkit”在这里不是可选依赖而是整个流程的基石——我们后面会深入讲为什么必须用v3.0.0以及如何绕过它最坑的三个默认行为。2. 核心设计思路拆解为什么不用parallelxargs而要自己写状态机很多人第一反应是“不就是循环下载吗用cat SraAccList.txt | parallel -j 4 prefetch {} fastq-dump --gzip {}不就完了”——我试过而且踩了深坑。下面说清楚为什么这个脚本选择“自己造轮子”而不是套用现成的并行工具。2.1 并行不是越多越好sra-toolkit的资源锁机制sra-toolkit底层用libsra访问NCBI的云存储它内部有连接池和缓存锁。实测发现当parallel -j 8同时启动8个prefetch进程时前2个能正常下载后6个会卡在Resolving...状态长达10分钟以上最终超时失败。这是因为sra-toolkit默认只允许2个并发HTTP连接可通过~/.ncbi/user-settings.mkfg修改但普通用户根本找不到这个文件在哪。而我们的脚本采用串行预取并行转换策略先用单线程prefetch把所有.sra文件拉到本地缓存~/ncbi/dbGaP-*/再用多线程fastq-dump从本地缓存读取转换。这样既规避了网络并发瓶颈又保证了转换阶段的CPU利用率。提示脚本中PREFETCH_CONCURRENCY1是硬编码值不是bug是经验之谈。如果你的服务器带宽超1Gbps且磁盘IO极强如NVMe RAID可手动改为2但务必配合--max-size 50G限制单个SRA缓存大小否则prefetch会把整个~/ncbi/塞爆。2.2 状态持久化为什么failed.log比set -e更可靠Shell里常用set -e让脚本在任意命令失败时退出。但sra-toolkit的错误码很“佛系”prefetch下载失败返回124fastq-dump内存不足返回137而网络超时可能返回0因为它把部分数据写进了临时文件。如果只靠set -e脚本会在第5个SRA失败时直接终止剩下95个永远没机会执行。我们的方案是每个SRA处理封装为独立函数函数内用if ! command; then echo SRRxxx failed failed.log; continue; fi显式捕获错误并记录失败原因如curl: (7) Failed to connect或fastq-dump: error while loading shared libraries。这样即使100个里失败30个脚本仍能跑完最后给你一份清晰的failed.log你可以针对性重试而不是重头再来。2.3 命名逻辑的工程化实现从SRR1234567到ATAC_N1_1.fastq.gz的三步映射这是整个脚本最核心的设计。很多教程教你在fastq-dump后用mv重命名但问题在于-fastq-dump SRR1234567默认输出SRR1234567.fastq.gz单端或SRR1234567_1.fastq.gz/SRR1234567_2.fastq.gz双端- 但SRR1234567对应哪个样本哪个测序批次哪个文库类型这些信息不在SRA元数据里必须由你人工维护。我们的解法是引入双列表映射机制1.SraAccList.txt纯SRA登录号列表每行一个无空格无注释SRR1234567\nSRR7654321\n2.sample_list.txtTSV格式第一列SRA号第二列样本名第三列可选文库类型如paired/single第四列可选压缩策略gzip/noneSRR1234567 ATAC_N1 paired gzip SRR7654321 RNA_S2 single none脚本读取时用awk NRFNR{acc[$1]1;next} $1 in acc{print} SraAccList.txt sample_list.txt做交集过滤确保只处理两个文件都存在的SRA号。然后对每个匹配行执行-prefetch --output-directory ./cache $sra_id→ 下载到./cache/SRR1234567.sra-fastq-dump --split-files --gzip --outdir ./fastq --skip-technical --read-filter pass $sra_id→ 输出./fastq/SRR1234567_1.fastq.gz和./fastq/SRR1234567_2.fastq.gz- 最后用mv ./fastq/${sra_id}_1.fastq.gz ./fastq/${sample_name}_1.fastq.gz完成语义化重命名。注意--skip-technical跳过接头、引物等技术序列--read-filter pass只保留质量合格的reads——这两个参数是生信分析的黄金组合避免下游工具因低质量reads报错。脚本默认开启你不需要记住。2.4 安全边界控制为什么--max-size和--verify不是可选项SRA数据库里有些条目是整套WGS数据单个SRA超200GB。如果脚本不加限制prefetch SRR9999999可能一夜之间吃光你1TB硬盘。因此脚本强制要求在config.sh中设置MAX_SRA_SIZE50G单位支持K/M/G/T并在prefetch命令中加入--max-size $MAX_SRA_SIZE。实测发现当--max-size 50G时prefetch对超大SRA会返回错误码255并输出Error: SRA object exceeds maximum allowed size脚本捕获此错误后写入failed.log并继续下一个而不是硬扛。另一个关键是--verify。prefetch默认不校验下载完整性只检查HTTP响应头。而NCBI偶尔会因CDN缓存问题返回截断的.sra文件尤其在中国大陆节点。开启--verify后prefetch会下载完成后用SHA256比对NCBI服务器上的原始哈希值确保字节级一致。虽然耗时增加15%但避免了后续fastq-dump解析时报Invalid SRA file这种让人抓狂的错误。脚本默认启用且在failed.log中明确标注“VERIFY FAILED”便于排查。3. 核心细节解析与实操要点从零配置到首次成功运行现在我们进入实操环节。别急着运行脚本先理解每个配置项背后的物理意义。我以macOS MontereyM1 Pro芯片和Ubuntu 22.04 LTS为例全程演示如何让脚本真正“开箱即用”。3.1 sra-toolkit安装避开官方文档埋的三个雷NCBI官网的安装指南写着“conda install -c bioconda sra-tools”但这是最不推荐的方式。原因有三- Conda环境中的sra-toolkit常与系统Python冲突尤其当你用pyenv管理Python版本时fastq-dump可能加载错误的libpython导致Segmentation Fault- Bioconda频道的sra-tools更新滞后v3.0.0发布半年后Conda版本还是v2.11.3缺少关键的--verify和--max-size支持- Conda安装的二进制文件路径不统一~/miniconda3/bin/or~/anaconda3/bin/脚本检测时容易漏判。正确姿势macOS# 1. 用Homebrew安装M1/M2芯片必须用arm64版本 arch -arm64 brew install sra-tools # 2. 验证安装路径应为/opt/homebrew/bin/ which prefetch fastq-dump # 输出/opt/homebrew/bin/prefetch 和 /opt/homebrew/bin/fastq-dump # 3. 初始化配置关键这步决定后续是否能连上NCBI vdb-config --interactive # 在交互界面中 # - 按2进入Preferences # - 按1进入Network # - 将Cache Directory设为高速磁盘如/Volumes/SSD/ncbi_cache # - 将Network Timeout从30秒改为120秒防国内网络波动 # - 按Esc退出保存配置正确姿势Linux# 1. 下载官方二进制包不要用aptUbuntu源太旧 wget https://ftp-trace.ncbi.nlm.nih.gov/sra/sdk/current/sratoolkit.current-ubuntu64.tar.gz tar -xzf sratoolkit.current-ubuntu64.tar.gz export PATH$PWD/sratoolkit.3.0.3-ubuntu64/bin:$PATH # 2. 创建软链接避免路径硬编码脚本检测时会找prefetch在PATH中 sudo ln -sf $PWD/sratoolkit.3.0.3-ubuntu64/bin/prefetch /usr/local/bin/prefetch sudo ln -sf $PWD/sratoolkit.3.0.3-ubuntu64/bin/fastq-dump /usr/local/bin/fastq-dump # 3. 初始化同macOS但配置文件在~/.ncbi/ vdb-config --interactive提示vdb-config --interactive生成的配置文件在~/.ncbi/user-settings.mkfg里面有一行/repository/user/main/public/root /path/to/cache这就是prefetch默认下载位置。脚本里所有--output-directory参数都基于此路径做相对定位所以初始化这一步绝不能跳过。3.2 配置文件config.sh详解每个变量都是血泪教训脚本根目录下的config.sh是唯一需要你手动编辑的文件。它不是“配置模板”而是运行时的决策中心。以下是逐行解读#!/bin/bash # config.sh —— 所有可调参数集中在此 # 【必填】SRA登录号列表文件路径绝对路径或相对于脚本所在目录 SRA_LISTSraAccList.txt # 【必填】样本映射表路径TSV格式SRA_IDtabSample_NametabLibrary_TypetabCompression SAMPLE_MAPsample_list.txt # 【必填】本地缓存目录prefetch下载.sra文件的位置 # 强烈建议设在SSD或高速NAS避免HDD成为IO瓶颈 CACHE_DIR./cache # 【必填】FASTQ输出根目录最终生成ATAC_N1_1.fastq.gz的地方 FASTQ_DIR./fastq # 【可选】最大单个SRA文件大小防止下载超大WGS数据撑爆磁盘 # 单位K/M/G/T必须带字母如50G、2T MAX_SRA_SIZE50G # 【可选】并发线程数fastq-dump阶段prefetch始终单线程 # 经验值CPU核心数-2留2核给系统和其他进程 THREADS6 # 【可选】是否启用校验强烈建议true避免数据损坏 VERIFYtrue # 【可选】是否启用gzip压缩false则输出未压缩FASTQ占空间但IO快 GZIP_COMPRESSIONtrue # 【可选】是否跳过已存在的FASTQ文件用于增量更新 SKIP_EXISTINGtrue # 【可选】日志级别debug/info/warn/error LOG_LEVELinfo # 【高级】自定义fastq-dump参数慎用覆盖默认安全参数 # 默认已包含--skip-technical --read-filter pass --clip # 如需添加--origfmt请取消下面注释并确认你的下游工具支持 # FASTQ_DUMP_OPTS--origfmt重点解释三个易错点-CACHE_DIR和FASTQ_DIR必须是相对路径或绝对路径不能是~/开头的波浪线。因为Shell脚本中~在非交互式环境下不会展开prefetch --output-directory ~/cache会被当成字面量目录名导致创建./~/cache这种诡异路径。正确写法是CACHE_DIR$HOME/cache或CACHE_DIR/data/ncbi_cache。-SKIP_EXISTINGtrue不是简单的[ -f $out_file ] continue。脚本实际检查的是$FASTQ_DIR/$sample_name_1.fastq.gz和$FASTQ_DIR/$sample_name_2.fastq.gz双端或$FASTQ_DIR/$sample_name.fastq.gz单端是否存在且文件大小1MB排除空文件。这样即使你中途CtrlC重启后也不会重复转换。-LOG_LEVELdebug会输出每一行执行的完整命令如 prefetch --max-size 50G --output-directory ./cache SRR1234567适合排查网络问题error则只记录失败条目适合生产环境静默运行。3.3 示例文件example/的结构意图教你如何组织自己的数据example/目录不是摆设它是最小可行实验单元。里面包含-SraAccList.txt仅两行SRR1234567和SRR7654321-sample_list.txt对应两行SRR1234567\tATAC_N1\tpaired\tgzip和SRR7654321\tRNA_S2\tsingle\tnone-ATAC_N1_1.fastq.gz和ATAC_N1_2.fastq.gz真实的、可直接用zcat ATAC_N1_1.fastq.gz | head -n 4查看的FASTQ内容前4行是第一条read的ID、序列、号、质量值-checksums.md5记录这两个FASTQ文件的MD5值供你验证脚本生成结果是否一致。它的设计逻辑是你能用example/里的文件跑通脚本就证明你的环境100%可用反之如果example/都跑不通一定是环境问题不是数据问题。我建议你首次运行时先cp -r example/* .覆盖当前目录然后./sra-download.sh——如果成功你会看到-./cache/SRR1234567.sra约1.2GB-./fastq/ATAC_N1_1.fastq.gz和./fastq/ATAC_N1_2.fastq.gz各约600MB-./fastq/checksums.md5里新增两行MD5-./sra-download.log里记录时间戳和成功条目。实操心得第一次运行时我总在./fastq/里看到SRR1234567_1.fastq.gz而不是ATAC_N1_1.fastq.gz查了半小时才发现sample_list.txt里SRA号多了一个空格SRR1234567导致awk匹配失败。脚本为此增加了空格trim逻辑sra_id$(echo $sra_id | sed s/^[[:space:]]*//;s/[[:space:]]*$//)但最好的习惯仍是编辑TSV时用VS Code打开开启“显示空白字符”功能。4. 实操过程与核心环节实现一次完整运行的逐帧解析现在我们模拟一次真实运行。假设你要下载某篇Nature论文补充材料里的23个ATAC-seq样本SRA号已整理好目标是生成SAMPLE_A_1.fastq.gz格式的文件存到/data/project_x/atac_fastq/。4.1 准备工作构建你的专属输入文件首先创建干净的工作目录mkdir -p /data/project_x/sra_download cd /data/project_x/sra_download然后准备两个核心输入文件-SraAccList.txt把你从论文Supplementary Table里复制的23个SRA号每行一个确保无空行、无空格、无中文逗号。可以用sed -i s/[[:space:]]*$// SraAccList.txt清理尾部空格。-sample_list.txt用Excel或LibreOffice Calc编辑列为SRA_ID、Sample_Name、Library_Type、Compression。例如SRR1234567 SAMPLE_A paired gzip SRR2345678 SAMPLE_B paired gzip ... SRR9876543 SAMPLE_W paired gzip保存为UTF-8编码的TSV格式不是CSV用file sample_list.txt确认输出sample_list.txt: UTF-8 Unicode text, with CRLF line terminators如果是with CR line terminators用dos2unix sample_list.txt转换。提示Library_Type列必须小写且精确为paired或single。脚本用if [[ $lib_type paired ]]; then ...判断写成Paired或PAIRED会导致fastq-dump不加--split-files参数双端数据全挤在一个文件里下游bwa mem直接报错。4.2 配置config.sh针对本次任务定制编辑config.shSRA_LISTSraAccList.txt SAMPLE_MAPsample_list.txt CACHE_DIR/data/project_x/sra_cache # SSD盘预留200GB FASTQ_DIR/data/project_x/atac_fastq # 目标输出目录 MAX_SRA_SIZE30G # 论文里最大SRA是28G留2G余量 THREADS8 # 服务器有16核留8核给其他任务 VERIFYtrue GZIP_COMPRESSIONtrue SKIP_EXISTINGtrue LOG_LEVELinfo4.3 首次运行观察日志理解每个阶段执行chmod x sra-download.sh time ./sra-download.sh输出日志分四段我们逐段解读阶段一环境与配置检查约5秒[INFO] Checking dependencies... [INFO] prefetch found at /opt/homebrew/bin/prefetch [INFO] fastq-dump found at /opt/homebrew/bin/fastq-dump [INFO] sra-toolkit version: 3.0.3 [INFO] Loading config from config.sh... [INFO] SRA list: SraAccList.txt (23 entries) [INFO] Sample map: sample_list.txt (23 entries) [INFO] Cache dir: /data/project_x/sra_cache [INFO] FASTQ dir: /data/project_x/atac_fastq这里脚本做了三件事-command -v prefetch和command -v fastq-dump确认二进制存在-prefetch --version 21 | grep sratoolkit提取版本号确保≥3.0.0-wc -l SraAccList.txt和wc -l sample_list.txt统计行数并用comm -12 (sort SraAccList.txt) (sort -k1,1 sample_list.txt) | wc -l计算交集数量确保23个SRA在两个文件里都存在。如果交集只有20脚本会报错并列出缺失的3个SRA号。阶段二预取prefetch阶段耗时最长取决于网络[INFO] Starting prefetch phase (1/23)... [INFO] prefetch --max-size 30G --verify --output-directory /data/project_x/sra_cache SRR1234567 [INFO] Downloading SRR1234567... [████████████████████] 100% 1.23G/1.23G 8.2MB/s [INFO] Verification passed for SRR1234567 [INFO] Starting prefetch phase (2/23)... ...注意两点- 进度条是脚本自己用pvPipe Viewer实现的如果系统没装pv会退化为纯文字进度不影响功能-Verification passed表示SHA256校验通过这是数据可靠的铁证。阶段三转换fastq-dump阶段CPU密集型[INFO] Starting fastq-dump phase (1/23)... [INFO] fastq-dump --split-files --gzip --outdir /data/project_x/atac_fastq --skip-technical --read-filter pass --threads 8 /data/project_x/sra_cache/SRR1234567.sra [INFO] Converting SRR1234567 to FASTQ... [████████████████████] 100% 1.23G/1.23G 120MB/s [INFO] Renaming SRR1234567_1.fastq.gz to SAMPLE_A_1.fastq.gz [INFO] Renaming SRR1234567_2.fastq.gz to SAMPLE_A_2.fastq.gz [INFO] Calculating MD5 for SAMPLE_A_1.fastq.gz... [INFO] Calculating MD5 for SAMPLE_A_2.fastq.gz...这里的关键是--threads 8——fastq-dump的多线程是真正的并行解压和格式转换不是伪并行。实测8线程比单线程快5.2倍不是8倍因为有IO和内存带宽瓶颈。阶段四收尾与校验[INFO] All done! 23/23 SRA processed. [INFO] Successful: 23, Failed: 0 [INFO] Output FASTQ files in /data/project_x/atac_fastq/ [INFO] Checksums written to /data/project_x/atac_fastq/checksums.md5 [INFO] Log saved to /data/project_x/sra_download/sra-download.log此时/data/project_x/atac_fastq/下应该有46个文件23×2每个SAMPLE_X_1.fastq.gz文件用zcat查看前4行应该是标准FASTQ格式SRR1234567.1 1 length150 NGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGATCGA IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII4.4 处理失败failed.log里的每一行都是线索假设第7个SRASRR3456789失败failed.log里记录2024-06-15 14:22:33 ERROR SRR3456789: prefetch failed with code 255: Error: SRA object exceeds maximum allowed size这说明该SRA实际大小超30G而你设的MAX_SRA_SIZE30G。解决方案- 查NCBI SRA页面确认该SRA真实大小页面右上角有“Size”字段- 如果确实是35G临时修改config.shMAX_SRA_SIZE40G- 删除./cache/SRR3456789.sra避免prefetch跳过- 运行./sra-download.sh --resume-from SRR3456789脚本支持--resume-from参数从指定SRA继续不重跑前面23个。另一个常见错误2024-06-15 14:25:11 ERROR SRR4567890: fastq-dump failed with code 137: Killed代码1371289表示被SIGKILL杀死通常是内存不足。解决方案- 降低THREADS值如从8降到4- 或在config.sh里加FASTQ_DUMP_OPTS--mem 4G限制单个fastq-dump进程内存上限。5. 常见问题与排查技巧实录那些让我熬夜到凌晨三点的Bug以下是我过去两年用这套脚本处理超过12000个SRA条目时遇到的TOP 5高频问题及独家解决方案。它们不在任何官方文档里但能帮你省下至少20小时调试时间。5.1 问题速查表现象可能原因快速诊断命令解决方案prefetch卡在Resolving...超10分钟DNS污染或NCBI CDN节点异常dig trace.ncbi.nlm.nih.gov short看返回IP是否在国内如114.114.114.114在~/.ncbi/user-settings.mkfg里加/http/proxy/host 127.0.0.1和/http/proxy/port 8123需自建HTTP代理或换DNS为223.5.5.5fastq-dump报error while loading shared libraries: libcrypto.so.1.1macOS/Linux动态库版本冲突otool -L $(which fastq-dump)macOS或ldd $(which fastq-dump)Linux用install_name_tool -changemacOS或patchelfLinux修复库路径或重装sra-toolkit生成的FASTQ文件全是SRRxxxxxx.1开头不是SAMPLE_X.1sample_list.txt编码不是UTF-8或列分隔符不是Tabfile sample_list.txt和hexdump -C sample_list.txt | head用iconv -f GBK -t UTF-8 sample_list.txt tmp mv tmp sample_list.txt转码用sed s/ \/\t/g sample_list.txt把空格转Tab./fastq/里只有SRRxxxxxx.fastq.gz没有_1/_2后缀sample_list.txt里Library_Type写成了paired-end而非pairedawk -F\t {print $3} sample_list.txt | sort -u全局替换sed -i s/paired-end/paired/g sample_list.txt脚本运行后./fastq/为空但./cache/里有.sra文件SKIP_EXISTINGtrue且./fastq/里已有同名文件但文件大小1MBls -lh ./fastq/和find ./fastq/ -size -1M删除小文件find ./fastq/ -size -1M -delete再重试5.2 独家避坑技巧技巧1用--dry-run预演避免误操作加--dry-run参数后脚本不执行任何下载或转换只打印将要运行的完整命令./sra-download.sh --dry-run输出类似DRY RUN: prefetch --max-size 30G --verify --output-directory /data/project_x/sra_cache SRR1234567 DRY RUN: fastq-dump --split-files --gzip --outdir /data/project_x/atac_fastq --skip-technical --read-filter pass --threads 8 /data/project_x/sra_cache/SRR1234567.sra DRY RUN: mv /data/project_x/atac_fastq/SRR1234567_1.fastq.gz /data/project_x/atac_fastq/SAMPLE_A_1.fastq.gz这能让你100%确认路径对不对参数对不对重命名逻辑对不对我在处理一个300样本的项目前必先--dry-run花2分钟看50行命令比跑1小时后发现全错了强百倍。技巧2--force-verify强制重校验已下载的.sra有时你怀疑某个.sra文件损坏比如fastq-dump报Invalid SRA file但又不想重下几GB。脚本提供--force-verify./sra-download.sh --force-verify SRR1234567它会跳过下载直接对./cache/SRR1234567.sra执行prefetch --verify --input-file ./cache/SRR1234567.sra校验失败则删除该文件下次运行自动重下。技巧3用--list-samples快速生成sample_list.txt骨架如果你只有SraAccList.txt但不知道每个SRA对应什么样本名可以先用NCBI E-Utilities API批量获取元数据./sra-download.sh --list-samples SraAccList.txt sample_list_skeleton.txt它会调用esearchesummary输出SRR1234567 SRR1234567_paired paired gzip SRR2345678 SRR2345678_paired paired gzip然后你用Excel打开sample_list_skeleton.txt把第二列SRR1234567_paired手工改成SAMPLE_A保存即可。这比一个个去NCBI网页复制快10倍。技巧4--cleanup-cache安全清理缓存./cache/目录会越积越大。脚本提供--cleanup-cache但它不是简单rm -rf ./cache而是- 先扫描./fastq/里所有已成功生成的FASTQ文件- 对每个FASTQ反向推导其来源SRA号如SAMPLE_A_1.fastq.gz→SRR1234567- 只删除./cache/里不在任何FASTQ文件名中出现的.sra文件- 最后留下./cache/SRR1234567.sra等正在使用的文件确保下次运行无需重下。命令./sra-download.sh --cleanup-cache5.3 性能调优实战从3小时到22分钟我曾用这套脚本处理一个84样本的scRNA-seq项目每个SRA平均8GB初始配置THREADS4耗时3小时12分钟。通过以下三步优化压缩到22分钟Step 1IO瓶颈定位用iostat -x 1监控发现%util长期100%await超200ms说明磁盘是瓶颈。解决方案把CACHE_DIR和FASTQ_DIR都指向同一块NVMe SSD/mnt/nvme/sra/避免HDD和SSD间拷贝。Step 2内存带宽释放fastq-dump默认用全部内存解压。用htop看8个进程共占24GB内存触发系统swap。在config.sh里加FASTQ_DUMP_OPTS--mem 3G限制每个进程最多用3GB8个共24GB刚好占满64GB内存的37.5%避免swap。Step 3并发策略重构原脚本是“prefetch串行→fastq-dump并行”。改为“prefetch分批并行fastq-dump流水线”- 把84个SRA分成4组每组21个- 每组启动一个prefetch进程parallel -j 4- 每组prefetch完成后立即启动该组的fastq-dump--jobs 4脚本内置--batch-size 21参数支持此模式。最终耗时22分钟提速8.3倍。最后分享一个小技巧处理超大项目前先用./sra-download.sh --dry-run | wc -l算出总命令数再除以你的THREADS就能预估fastq-dump阶段的理论最短时间单位秒。比如84个SRATHREADS8fastq-dump平均每个耗时90秒则理论时间≈84/8×90945秒≈15.75分钟。实际22分钟说明IO和内存还有优化空间——这就是工程化的魅力一切可测量一切可优化。本文还有配套的精品资源点击获取简介一套开箱即用的命令行工具专为批量获取NCBI SRA数据库中的原始测序数据设计。核心脚本sra-download.sh读取SraAccList.txt里的SRA编号如SRR1234567再对照sample_list.txt中的样本名自动创建带命名逻辑的输出目录结构下载完成后直接生成标准FASTQ文件支持gzip压缩。整个流程支持一次处理几十到几百个SRA条目无需人工干预不依赖图形界面。已内置示例数据含ATAC_N1_1.fastq.gz等真实FASTQ、预配置的列表模板和完整README说明还包含重复校验所需的文件结构参考。运行前需在Linux或macOS系统中安装sra-toolkit 3.0.0及以上版本并完成prefetch初始化配置。所有操作均通过终端执行适合生信分析前的数据准备环节可无缝衔接后续质控、比对或组装流程。本文还有配套的精品资源点击获取
相关文章
Seq2Seq（Sequence-to-Sequence，序列到序列）工作原理
Seq2Seq（Sequence-to-Sequence，序列到序列） 是一种基于 Encoder-Decoder（编码器-解码器） 架构的深度学习模型，核心是将任意长度的输入序列转换为任意长度的输出序列，主要用于机器翻译、文本摘要…
抖音去水印下载器终极指南：3分钟快速上手批量下载视频、封面和音乐
抖音去水印下载器终极指南：3分钟快速上手批量下载视频、封面和音乐 【免费下载链接】douyin-downloader A practical Douyin downloader for both single-item and profile batch downloads, with progress display, retries, SQLite deduplication, and browser fa…
--和equals区别
一、 Java 中的对象相等判断（核心重点）1. 基本原则：vs equals()：比较内存地址。判断两个引用是否指向堆内存中的同一个对象。适用场景：判断是否为 null，或明确需要判断是否为单例/同一实例时。equals()&…
手把手教你用Multisim仿真MOS管电源开关电路（从N-MOS到P-MOS配置）
从零构建MOS管电源开关电路：Multisim仿真实战指南 在硬件设计领域，仿真验证已成为现代工程师不可或缺的核心技能。想象一下这样的场景：当你熬夜设计的电路板终于打样回来，焊接完成后却发现电源控制部分无法正常工作——这种挫败感…
基于 PaddleOCR 和 Flask 的学生证借书证识别与档案录入系统实战
摘要 学生证、借书证、校园卡、图书馆读者证这类证件在学校信息化系统中非常常见。教务处、图书馆、实验室、二级学院在整理学生档案、借阅权限、门禁白名单或活动报名信息时，经常会遇到一个重复问题：纸质证件、拍照图片、截图材料中有很多结构化字段&am…
2026实测盘点：16款降AI率网站实测，这款降AI率效果一骑绝尘！
随着AI写作工具的广泛应用，学术界对AIGC内容的检测标准愈发严格，2026年的高校与科研机构对论文中AI痕迹的识别能力已达到前所未有的精准度。在这一背景下，如何有效降低论文的AIGC率、去除AI写作痕迹、同时保持内容的专业性与原创性࿰…
DETR玩转医学图像：我是如何用‘变形自注意力’解决白细胞检测中的尺度与特征难题的
DETR在医学图像分析中的革新实践：多尺度特征融合与变形自注意力破解白细胞检测难题当显微镜下的血液样本遇见深度学习，一场关于生命微观世界的解码之旅就此展开。白细胞作为人体免疫系统的"哨兵"，其形态与数量的异常往往是疾病诊断…
Unlock-Music音乐解锁工具：释放你的数字音乐收藏
Unlock-Music音乐解锁工具：释放你的数字音乐收藏 【免费下载链接】unlock-music 在浏览器中解锁加密的音乐文件。原仓库： 1. https://github.com/unlock-music/unlock-music ；2. https://git.unlock-music.dev/um/web 项目地址: https://gi…
ASP与jmail发送邮件：一次实用的回顾
在早期的ASP开发中，发送邮件是一个常见需求。今天回过头来整理一下当年使用jmail组件发送邮件的经验，希望能给还在维护老项目的朋友一点帮助。1. 组件安装（当时折腾了一下）首先需要下载jmail.dll文件（网上搜索就能找到…
从 Prompt 到生产闭环：Spring AI Tool Calling 深度拆解与企业级落地
从 Prompt 到生产闭环：Spring AI Tool Calling 深度拆解与企业级落地 摘要 Tool Calling 是大模型系统从“会回答”走向“会执行”的关键能力。很多文章只停留在 @Tool 注解和 Hello World 级别示例，但一旦进入生产环境，问题很快从“怎么调用”升级为“怎么控延迟、怎么控风…
解耦安防碎片化：基于 Docker 与边缘计算的 AI 视频中台架构设计（支持 GB28181/RTSP 与源码交付）
在智能视频分析（IVA）与产业物联网（IoT）大行其道的今天，政企级安防项目的落地依然面临着严重的碎片化挑战。对于系统集成商和独立软件开发商（ISV）而言，传统的流媒体研发存在两大核心痛…
解耦品牌壁垒：基于 Docker 与边缘计算的高并发视频中台架构（支持 GB28181/RTSP 统一接入与源码交付）
在泛安防与产业物联网（IoT）工程落地中，系统集成商与技术团队往往深陷于底层流媒体对接的碎片化泥潭。一方面，前端摄像机、IPC、NVR 品牌林立（如海康、大华、宇视等），其 GB28181 国标协议的信令交…
Win10/Win11下Realtek 8188GU网卡驱动感叹号？别急着扔，试试这个手动安装的野路子
Realtek 8188GU网卡驱动故障深度修复指南：从原理到实战当设备管理器里那个顽固的黄色感叹号挥之不去，而你已经尝试了所有"标准操作"——Windows自动更新、第三方驱动工具、甚至重启大法——却依然无济于事时，是时候换个思路了。这篇…
AnolisOS 8.8安装源配置踩坑实录：从‘设置基础软件仓库时出错’到成功联网的保姆级指南
AnolisOS 8.8安装源配置实战指南：从诊断到解决方案的全流程解析当你在安装AnolisOS 8.8时遇到"设置基础软件仓库时出错"的提示，这通常意味着系统无法访问或识别安装源。这个问题看似简单，但背后可能涉及网络配置、镜像选择、启动参…
基于树莓派Pico的反应速度测试游戏：从GPIO编程到状态机实战
1. 项目概述与核心思路最近在整理工作室的电子元件，翻出来几个闲置的街机按钮和一块树莓派Pico，灵机一动，决定做个简单又有趣的反应速度测试游戏。这个项目非常适合想入门嵌入式开发的朋友，它不涉及复杂的传感器和通信协议&#x…
Zotero Duplicates Merger：5步彻底清理文献库重复条目
Zotero Duplicates Merger：5步彻底清理文献库重复条目 【免费下载链接】ZoteroDuplicatesMerger A zotero plugin to automatically merge duplicate items 项目地址: https://gitcode.com/gh_mirrors/zo/ZoteroDuplicatesMerger 还在为文献库中堆积如山的重…
利用随机有限集理论对蜂群的ILQR和MPC控制研究附Matlab代码
✅作者简介：热爱科研的Matlab仿真开发者，擅长数据处理、建模仿真、程序设计、完整代码获取、论文复现及科研仿真。🍎 往期回顾关注个人主页：Matlab科研工作室🍊个人信条：格物致知,完整Matlab代码及仿真咨询…
为什么你的Gemini邮件CTE低于行业均值2.8倍？：从Prompt架构到发送时序的深度归因
更多请点击： https://intelliparadigm.com 第一章：为什么你的Gemini邮件CTE低于行业均值2.8倍？：从Prompt架构到发送时序的深度归因 Gemini邮件的客户转化效率（CTE）显著偏低，根本原因常被误判为…