简介：这是一份面向生物信息学与基因组数据研究者的Python工具资源，提供基于EGA Data API的pyEGA3下载客户端，用于查看并下载授权EGA数据集中的文件，适合具备Python 3.6以上环境、需要批量获取受控基因组数据的科研人员与生信工程师。压缩包共19个文件，约31KB，以5个py源码与5个sh安装脚本为核心，辅以json配置、md说明文档、cfg与yml构建配置等，覆盖依赖安装、测试与运行全流程。客户端通过https安全传输未加密文件，下载后无需解密，支持断点续传、分段并行下载与校验和完整性验证，并实现GA4GH兼容的htsget协议，可下载带索引文件的基因组范围数据。目前已有1178人学习下载，读者可据此快速搭建EGA数据下载环境，理解分段并行与校验机制，并借助测试脚本与多平台依赖脚本完成部署与排错。
1. 一个 Python 写的 EGA 下载客户端，到底能省掉哪些手工活
如果你从公共组学数据库下载过原始测序数据，大概率经历过这样的流程：先在网页端找到研究编号，再一层层点进样本列表，手动复制每个 run 的下载地址，然后回到命令行用 wget 或 curl 一条条拉。样本量少还能忍，一旦碰上几十上百个 run，光是整理地址就能耗掉半天，中间还容易漏掉某个文件。ega-download-client 这个基于 Python 的客户端，解决的正是这类重复劳动——它把「查清单、拼地址、断点续传、校验完整性」这几件事收进了一套命令行工具里，用脚本驱动而不是靠手点。
它适合三类人：一是经常从公共数据库批量取测序数据的生信分析人员；二是需要把下载环节嵌进自动化流程的工程师；三是刚接触命令行下载、想找一个比裸 wget 更省心方案的新手。需要说明的是，这个客户端面向的是有权限访问的数据集，你得先拿到对应的访问凭证，它本身不提供数据，只负责把你有权拿的东西稳定地搬回来。下面从安装配置讲到批量脚本，再到几个我实际踩过的坑，尽量把参数和边界说清楚。
2. 环境准备与客户端安装：把依赖和凭证先理顺
2.1 为什么用客户端而不是裸 wget
裸 wget 能下载，但它不知道数据集的目录结构，也不管文件校验。你得自己维护一份地址清单，自己判断哪些文件已经下完、哪些下了一半。ega-download-client 的价值在于它内置了会话管理和清单解析：你给它一个研究编号或样本清单，它自己去查有哪些文件、各自多大、校验值是什么，然后按顺序拉取。断点续传也是内建的，网络抖一下不用从头再来。对于动辄几十 GB 的测序数据，这个差别很实在。
另一个理由是凭证管理。公共数据库的下载通常需要一套认证信息，裸 wget 要把凭证拼进 URL 或配置文件里，容易泄露也难维护。客户端一般提供独立的配置命令，把凭证存到本地受保护的路径，后续调用不用反复输入。这一点在多人共用的服务器上尤其重要。
2.2 安装步骤与依赖检查
这个客户端是 Python 写的，常见做法是用 pip 装进一个独立虚拟环境，避免和系统里的其他包打架。先确认 Python 版本，一般要求 3.7 以上。
# 确认 Python 版本，低于 3.7 需要先升级 python3 --version # 建一个独立虚拟环境，名字随意，这里叫 ega_env python3 -m venv ega_env # 激活环境，后续所有操作都在这个环境里 source ega_env/bin/activate # 安装客户端，包名以实际发布为准 pip install ega-download-client装完之后验证一下命令是否可用：
# 查看客户端版本和可用子命令 ega-download-client --version ega-download-client --help如果提示找不到命令，多半是虚拟环境没激活，或者 pip 装到了用户目录但该目录不在 PATH 里。前者重新 source 一次，后者检查~/.local/bin是否在环境变量中。依赖方面，客户端通常会用到 requests 做网络请求、tqdm 显示进度条，pip 会自动带上，不用手动装。
提示：生产环境里建议把虚拟环境固定在某个绝对路径，比如
/opt/ega_env，这样定时任务调用时不会因为当前目录不同而找不到解释器。
2.3 配置访问凭证
拿到凭证文件后，不要直接塞进脚本里。客户端一般提供配置子命令，把凭证写到用户主目录下的隐藏配置文件中。
# 交互式录入凭证，按提示粘贴即可 ega-download-client config --set-credentials # 查看当前配置了哪些字段（不会回显敏感值） ega-download-client config --list配置完成后，凭证会存在类似~/.ega/config的位置。这个文件权限建议设成 600，只有本人可读：
chmod 600 ~/.ega/config参数说明：--set-credentials是写入模式，--list是只读查看。有些版本还支持--config-file指定自定义路径，适合多套凭证切换的场景。如果团队共用一台机器，每个人用自己的系统账号，凭证互不干扰，不要图省事共用一个配置文件。
3. 单文件下载与清单解析：先把一个 run 跑通
3.1 查询数据集里有哪些文件
在批量下载之前，先搞清楚目标数据集包含什么。客户端通常有一个查询或列表子命令，输入研究编号，返回文件清单。
# 查询某个研究编号下的文件列表，输出到终端 ega-download-client list --study-id EGAS00000000001 # 把清单存成文件，方便后续比对 ega-download-client list --study-id EGAS00000000001 --output manifest.txt清单里一般包含文件标识、文件名、大小、校验值几列。拿到清单后先扫一眼总大小，估算下载时间和磁盘占用。如果清单是空的，先确认凭证有没有配对、该研究编号是否在你的授权范围内，而不是急着怀疑网络。
3.2 下载单个文件并验证完整性
先用一个文件试水，确认整条链路通畅，再上批量。
# 下载指定文件到当前目录 ega-download-client download --file-id EGAF00000000001 --output-dir ./data # 下载完成后校验，比对清单里的校验值 ega-download-client verify --file-id EGAF00000000001 --path ./data/参数说明：--file-id是清单里的文件唯一标识，--output-dir指定落盘目录，目录不存在时客户端一般会自动创建。verify子命令会重新计算本地文件的校验值，和远端记录比对，一致才算下载成功。这一步别省，测序数据动辄几个 GB，传输出错但文件大小看着正常的情况并不罕见，校验是唯一的后悔药。
如果下载中断，重新执行同一条 download 命令即可，客户端会检测到本地已有部分文件，从断点继续，不会覆盖重来。这也是它比裸 wget 省心的地方之一。
3.3 用清单文件驱动批量下载
单个文件跑通后，批量就是把它循环起来。最稳的做法是让客户端直接读清单文件，而不是自己写循环拼命令。
# 从清单文件批量下载，并发数设为 4 ega-download-client download --manifest manifest.txt \ --output-dir ./data \ --concurrency 4 \ --retry 3参数说明：--manifest指向之前导出的清单；--concurrency控制同时下载的文件数，默认一般是 1，调大能提速但会吃带宽和磁盘 IO，内网环境可以设 4 到 8，公网建议 2 到 4；--retry是单个文件失败后的重试次数，网络不稳时设 3 比较稳妥。并发不是越大越好，磁盘写入跟不上时反而会拖慢整体，我一般先设 4 跑一批看实际吞吐再调。
注意：批量下载前先确认目标磁盘剩余空间大于清单总大小，留出至少 20% 余量。测序数据解压后可能比压缩包大好几倍，别等下到一半才发现盘满了。
4. 批量脚本与自动化：把下载嵌进流程里
4.1 用 Python 调用客户端做条件筛选
命令行能覆盖大部分场景，但如果你只想下载清单里大于某个体积的文件，或者按文件名前缀过滤，用 Python 包一层更灵活。
import subprocess import csv # 读取清单，按大小过滤出目标文件 targets = [] with open("manifest.txt", newline="") as f: reader = csv.DictReader(f, delimiter="\t") for row in reader: # 只挑大于 1GB 的文件，小文件单独处理 if int(row["size"]) > 1024 ** 3: targets.append(row["file_id"]) # 逐个调用客户端下载，失败记录到日志 failed = [] for fid in targets: result = subprocess.run( ["ega-download-client", "download", "--file-id", fid, "--output-dir", "./data", "--retry", "3"], capture_output=True, text=True ) if result.returncode != 0: failed.append(fid) print(f"下载失败: {fid}") print(f"完成 {len(targets) - len(failed)} 个，失败 {len(failed)} 个")逻辑说明：先解析清单，用size字段做阈值过滤，避免把大量小文件也塞进批量任务拖慢节奏。然后逐个调用客户端，捕获返回码，失败的收集起来统一重试。参数上，capture_output=True把客户端的输出收进变量，方便写日志；如果你希望进度条直接显示在终端，改成capture_output=False。
4.2 定时任务与断点续传的组合
长时间下载最怕中途断掉。把客户端放进定时任务，配合它的断点续传，可以做到无人值守。
# 编辑 crontab crontab -e # 每小时检查一次，把没下完的补上 0 * * * * /opt/ega_env/bin/ega-download-client download \ --manifest /data/manifest.txt \ --output-dir /data/raw \ --retry 5 >> /var/log/ega_download.log 2>&1这里用虚拟环境里的绝对路径调用，避免 cron 环境找不到命令。日志重定向到文件，方便事后排查。客户端每次运行会跳过已完成的文件，只补缺失的部分，所以重复执行是安全的。参数--retry 5比交互式场景设得高一些，因为无人值守时多试几次比直接失败更划算。
4.3 下载完成后的校验与归档
批量任务跑完后，统一做一次校验，再决定是否归档。
# 对整个目录做校验，输出结果到文件 ega-download-client verify --manifest manifest.txt \ --path ./data \ --report verify_report.txt校验报告里会列出通过和失败的文件。失败的文件不要直接删，先看是传输问题还是磁盘问题，重新下载一次通常能解决。全部通过后再把数据移到归档目录，原始下载目录留空给下一批任务用。归档时建议保留清单文件和校验报告，将来数据出问题时能快速定位是下载环节还是后续分析环节的锅。
5. 避坑与排查：几个我实际翻过车的地方
5.1 凭证过期导致清单为空
现象：执行 list 命令返回空列表，或者提示无权限，但确认自己有授权。
原因：凭证有有效期，过期后客户端不会报「凭证过期」这么直白的错，而是返回空结果，容易误判成数据集本身没文件。
解决：重新执行config --set-credentials更新凭证，再跑一次 list。如果还是空，检查系统时间是否准确，时间偏差过大会导致认证失败。
5.2 并发过高把磁盘写满
现象：批量下载跑到一半报写入错误，检查发现磁盘满了，但清单总大小明明小于剩余空间。
原因：并发下载时，多个文件同时写入，临时文件和分片会额外占用空间，实际峰值占用可能接近清单总大小的两倍。
解决：把--concurrency降到 2，或者分批下载，每批完成后清理临时文件。长期方案是给下载目录单独挂一块盘，别和系统盘混用。
5.3 断点续传后文件校验失败
现象：中断后重新下载，文件大小和清单一致，但 verify 报校验不通过。
原因：部分客户端在续传时如果远端文件发生过更新，本地已下载的部分和新数据对不上，拼接出来的文件是坏的。
解决：删掉该文件的本地残留，从头下载一次。如果频繁出现，检查是不是有别人在同时修改数据集，或者客户端版本太旧有续传 bug，升级到最新版。
5.4 定时任务里命令找不到
现象：手动执行正常，放进 crontab 后日志里报 command not found。
原因：cron 的环境变量和登录 shell 不同，虚拟环境的路径没被加载。
解决：在 crontab 里用解释器的绝对路径，比如/opt/ega_env/bin/ega-download-client，而不是裸命令名。必要时在脚本开头显式 source 虚拟环境的 activate。
5.5 校验值算法不匹配
现象：本地用 md5 算出来的值和清单里的对不上，但文件其实没问题。
原因：清单里的校验值可能是 sha256 或其他算法，客户端 verify 默认用的算法和清单不一致。
解决：查看清单表头确认算法类型，verify 时用--checksum-algo指定对应算法。不确定就先拿一个小文件手动算一遍比对。
6. 进阶技巧：把下载日志变成可追溯的记录
跑通批量下载只是第一步，真正省心的是让每次下载都留下可追溯的记录。我现在的习惯是给每个数据集建一个独立目录，里面放三样东西：清单文件、校验报告、下载日志。日志不用自己写，客户端输出重定向过去就行，但要在脚本里加上时间戳。
# 带时间戳的日志，方便按批次排查 LOG="/data/logs/ega_$(date +%Y%m%d_%H%M%S).log" ega-download-client download --manifest manifest.txt \ --output-dir ./data \ --concurrency 4 \ --retry 3 2>&1 | tee "$LOG"tee同时输出到终端和文件，跑的时候能看进度，跑完有记录。参数上没什么特别的，关键是养成习惯：每次下载都留日志，别等出了问题才后悔没记。
再进一步，可以把校验报告解析成结构化数据，统计每个数据集的下载耗时和失败率。下面这个小脚本读校验报告，算出通过率：
# 解析校验报告，统计通过率 total, passed = 0, 0 with open("verify_report.txt") as f: for line in f: if line.startswith("PASS"): total += 1 passed += 1 elif line.startswith("FAIL"): total += 1 rate = passed / total * 100 if total else 0 print(f"通过 {passed}/{total}，通过率 {rate:.1f}%")逻辑很直白，就是数 PASS 和 FAIL 的行数。参数上，报告格式以实际客户端输出为准，如果字段位置不同，调整 startswith 的判断即可。这个统计跑久了能看出哪些数据集容易出问题，下次下载时提前把并发调低或者多留重试次数。
从那以后我每次批量下载前，都强制走一遍「先 list 存清单、再单文件试水、最后批量加日志」的流程，看着多花几分钟，但省掉了后面反复排查的麻烦。希望帮到你。
本文还有配套的精品资源，点击获取
