企业官网建设流程全解析

做肿瘤生信分析的研究者，几乎没有绕过TCGA数据库的。但很多新手第一次接触TCGA时，最头疼的往往不是筛选数据，而是“怎么把几百个样本的测序文件高效下载下来”。浏览器一个一个点，点两下手就酸了，还容易断；用一些第三方脚本，又担心数据不完整。今天这篇就来聊聊TCGA官方提供的数据下载工具——GDC-client，从下载安装到批量下载实操，以及我实际使用中踩过的坑。无论你是刚接触生信的学生，还是已经做了几年科研的老人，这篇文章都能帮你把TCGA数据下载这件事彻底理顺。

GDC-client是GDC（Genomic Data Commons）官方推出的命令行数据下载工具，TCGA的数据几乎都托管在GDC上。用这个工具，你可以通过一个manifest清单文件批量下载数据，支持断点续传、并发下载，还能够在下载完成后自动校验文件完整性。对经常和几十GB甚至上TB测序数据打交道的人来说，这是效率和安全性的双重保障。接下来，我会按“为什么用→如何装→怎么用→常见坑”的顺序完整过一遍，保证你看完能直接用起来。

1. 为什么下载TCGA数据必须用到GDC-client

1.1 TCGA数据的存储逻辑：GDC平台和它的分层结构

先搞清楚TCGA的数据在哪儿、怎么组织的，才能理解为什么GDC-client这么重要。TCGA的全称是The Cancer Genome Atlas，一个跨机构的癌症基因组图谱项目，收集了33种癌症类型、超过2万个样本的多组学数据，包括基因表达、甲基化、拷贝数变异、体细胞突变以及临床信息。这些数据经过统一处理后，都存放在GDC平台上，也就是Genomic Data Commons。

GDC并不只是简单地把文件堆在服务器上，它对数据做了“项目→case→file”的层级管理。你进入GDC Data Portal后，会先选择一个项目，比如TCGA-BRCA（乳腺癌）或TCGA-LUAD（肺腺癌），然后根据样本类型、数据类别、实验策略等条件筛选文件，最后把需要的文件加入购物车，生成一个manifest清单文件。这个清单文件记录了你选中的每一个文件的唯一标识、文件名、MD5校验值、文件大小等信息，相当于一张购物清单。GDC-client就是拿着这张清单，去GDC的服务器上把你选中的文件一个个取回来。

我见过不少朋友第一反应是用浏览器从GDC网站上直接下载。对于文件数量少、体积小的情况这没问题，但如果你的研究需要全转录组测序的BAM文件，或者需要批量下载某个癌症类型的全部表达矩阵，浏览器就完全扛不住了。大文件动不动几个GB甚至几十GB，浏览器下载一旦中断就只能从头再来，网速稍微不稳就是几个小时白等。GDC-client就是为这种批量、大容量的下载场景专门设计的命令行工具，说它是生信人的“下载神器”毫不夸张。

1.2 浏览器直下与GDC-client的对比：大文件场景下的取舍

很多刚接触TCGA的人心里都会有个疑问，既然网页上也有下载按钮，我为什么要费力去搞一个命令行工具？我把浏览器下载和GDC-client的差异整理成了表格，看完对比你心里就有数了。

从表里能看到，GDC-client最大的优势在于批量和稳定。对于做下游分析的研究组，一个癌症类型的转录组数据通常就有几十到上百个文件，用GDC-client配合manifest清单，一条命令就能全部搞定，不需要人盯在电脑前面。而且它支持校验MD5，下载完成后本地文件是否完整一目了然，这对于后续分析结果的可靠性至关重要。下载得到坏文件却不知道，分析跑到一半才发现数据有问题，那种感觉我有过，真的不想第二次。

2. GDC-client的下载与安装（Windows / macOS / Linux全覆盖）

2.1 从GDC官网获取对应系统的安装包

GDC-client的安装包可以从GDC官网的下载页面获取，地址是gdc.cancer.gov/access-data/gdc-data-transfer-tool。进入页面后，你会看到当前最新的稳定版本以及对应的安装包列表。官方针对三大主流平台都提供了支持：Windows系统对应的是zip压缩包，macOS对应的是.tar.gz压缩包，Linux同样也是.tar.gz压缩包。

这里要特别提醒一点，下安装包之前先确认操作系统的架构。现在绝大多数人的电脑是64位，对应的安装包一般是x86_64版本。老一些的机器如果是32位系统，就需要找对应的32位版本，但GDC-client新版本基本已经放弃32位支持了，所以如果你的机器还停留在32位，做TCGA数据分析会非常吃力，建议先升级设备或换一台机器。如果不确定系统架构，Linux下可以用uname -m查看输出，macOS下用uname -m也可以，输出x86_64就是64位，arm64则是Apple Silicon的M系列芯片。

另外，macOS用户要特别注意：M系列芯片的Mac虽然可以通过Rosetta转译运行x86_64版本的GDC-client，但官方针对Apple Silicon的版本也在持续更新。我个人的建议是先优先下载官方标注了相应架构的版本，如果实在没有，再考虑转译运行。转译本身通常没什么问题，只是第一次运行可能需要你到“系统设置→隐私与安全性”里允许程序的执行权限。

2.2 安装与验证：三步让gdc-client跑起来

安装过程不复杂，三步走就能完成，以Linux环境为例，整个过程是这样：

第一步，下载安装包并解压。

# 假设安装包已经下载到当前目录 tar -xzf gdc-client_v2.0.tar.gz

解压后你会得到一个可执行文件，文件名就是gdc-client。有的版本会连同一个文本说明和LICENSE文件一起打包，不用管那些，真正有用的就是那个没有扩展名的可执行文件。

第二步，给可执行文件添加运行权限。

chmod +x gdc-client

这一步在Windows下不需要，Windows的zip解压后直接就能运行exe文件。但Linux和macOS下，下载下来的文件默认可能没有可执行权限，直接运行会报Permission denied。我第一回用的时候就是忘了这一步，卡了五分钟才想明白是哪出了问题。

第三步，验证安装是否成功。

./gdc-client --version

正常的话会输出类似GDC-client (v2.0.x)的内容。如果输出版本号，说明工具已经能正常运行了。Windows下就是把命令换成gdc-client.exe --version，或者你直接双击也能测试，但既然是命令行工具，还是建议在PowerShell或cmd里跑一下，确认能出结果。

2.3 跨平台使用的小细节

等工具验证通过之后，建议先把gdc-client放到一个固定目录，比如Linux/macOS下可以放在/usr/local/bin/或者~/bin/，Windows下可以放在C:\tools\。这样做的好处是后续可以在任意目录直接调用Lệnhgdc-client，不用每次敲完整路径。Linux下如果你有sudo权限，甚至可以做一个软链接到/usr/local/bin，用法如下：

sudo ln -s /path/to/gdc-client /usr/local/bin/gdc-client gdc-client --version

这之后你就拥有了一个全局可用的gdc-client命令。Windows用户想达到类似效果，需要把gdc-client所在目录添加到系统环境变量的Path中，方法不复杂，网上教程很多，我就不过多展开了。还有一个经常被忽略的点：Windows下杀毒软件可能会对解压出来的exe文件误报，这属于常见的劝退现场。如果被杀毒软件隔离了，你到隔离区恢复一下，再在杀毒软件里加个信任目录就行，GDC-client是官方工具，安全性方面没有问题。

3. GDC-client核心操作：从数据筛选到批量下载一条龙

3.1 用Data Portal生成manifest文件

安装好工具只算热身，真正有意思的是后面这步。GDC-client本身不会告诉你要下载哪些文件，它只负责执行下载。选择文件的决策，是在GDC Data Portal网页上完成的。这个过程我走过了无数遍，总结下来就是：筛选条件、加入购物车、生成manifest。

先打开portal.gdc.cancer.gov，首页就能看到TCGA、TARGET等多种数据项目的入口。以TCGA-BRCA为例，点击进入后你会进入一个带筛选面板的页面。左侧的筛选器非常丰富，包括primary site（原发部位）、project（项目名）、data category（数据类别，比如Transcriptome Profiling、Copy Number Variation）、data type（数据类型，比如Gene Expression Quantification、Masked Somatic Mutation）、experimental strategy（实验策略，比如RNA-Seq、WXS）、workflow type（分析流程，比如STAR - Counts）等。

我之前下载转录组表达数据时，一般会把data category选成Transcriptome Profiling，experimental strategy选成RNA-Seq，workflow type选成STAR - Counts。这样筛选出来的就是每个样本的基因表达count矩阵文件。如果你需要的是突变数据，就选data type为Masked Somatic Mutation，实验策略选WXS。每点一个筛选条件，右侧的文件列表都会实时刷新，同时会显示当前命中的文件数量和总体积。这一步是规划下载范围的关键环节，筛得越精细，后面下载越省事。

筛选完成后，点击“Add All Files to Cart”把所有文件添加到购物车。然后点击右上角购物车图标进入购物车页面，在这里你可以最后确认一次选中的文件列表、总大小，也可以通过“Remove”按钮剔除个别不需要的文件。确认没问题后，点击“Manifest”按钮，浏览器就会自动下载一个类似manifest.txt的文件。这个文件就是接下来要给GDC-client用的“购物清单”。

3.2 manifest文件是什么：一探下载清单的格式

下载下来的manifest.txt是个纯文本文件，用文本编辑器就能打开。我拆开一个实际的manifest文件示范一下：

id fileName md5 size state 1fa3f5e4-5a61-4c3f-8f10-2e67c9f6b6ab STAR_Counts/8a8f...tsv 7f2d31ea6e98b6e0f56dc770b3c0a1a4 1723637 released 34c1f722-56b3-4abf-b2d7-7b61e29e5dcd STAR_Counts/ce1c...tsv c1e1ace3a9a629cba2dd67c74f958d9f 1872932 released

第一列id是GDC内部的文件UUID，每个文件在GDC中有唯一标识，这就是GDC-client下载文件的核心依据。第二列fileName是文件在对象存储中的完整路径名称，通常包含样本ID和文件类型信息。第三列md5是文件内容的MD5校验值，下载完成后工具会用它来验证文件是否完整。第四列size是文件大小，单位是字节。最后一列state表示文件状态，大多数情况下是released，代表数据已公开且可正常下载。

你不需要手动修改manifest文件的内容，因为GDC-client能直接解析它的格式。唯一要留意的是：manifest文件里尽量不要保留多余的空白行，有些版本的GDC-client对空行比较敏感，解析时可能报错。如果你后续需要微调下载范围，可以用文本编辑器或grep从manifest里筛选出行，再把选中的行保存成另一个manifest文件，这是非常实用的一个技巧。

3.3 下载实操：使用manifest文件批量下载

现在关键的步骤来了。把manifest.txt和gdc-client放在同一个目录（或者记住manifest文件的完整路径），然后执行下面的命令：

./gdc-client download -m manifest.txt

就这么简单。执行之后，工具会逐行读取manifest文件，获取每个文件的UUID，然后从GDC服务器开始下载。下载完成的文件会默认保存在当前目录下，以文件UUID作为子目录名称。

如果你下载的是受控数据（比如原始测序的FASTQ文件、BAM文件），还需要在命令中指定token，这个下一小节会专门讲。这里先放开源数据，比如表达量矩阵、体细胞突变注释文件这类公开数据，一条命令就能搞定。

实际使用中，我更推荐大家加上这几个参数，能显著提升体验：

./gdc-client download -m manifest.txt -d /path/to/output -n 8 --retry-amount 5

-d参数指定输出目录，文件下载后都保存在这里，避免了把一堆UUID目录散落在命令执行目录下。-n参数决定并发下载的进程数，数字越大下载越快，但也越吃网络带宽和CPU，不是越高越好。根据我自己的经验，家用宽带设置成4到8个并发比较合适。--retry-amount参数设置单个文件下载失败后的重试次数，设成5能在网络抖动时省不少事。

下载过程中屏幕上会不断滚动文件的状态信息，你可能会看到download、verify等字样。等命令执行完毕，所有文件都显示已下载，就可以去输出目录检查结果了。如果中间某个文件下载失败，GDC-client不会中断整个任务，它会继续尝试下一个文件，最后用日志告诉你哪些文件失败了，这是它非常贴心的一点。

3.4 token的获取与使用：处理受控数据的关键环节

GDC平台把数据分成开放数据和受控数据两类。表达量矩阵、临床数据、突变注释这类开放数据，任何人都能随意下载。但原始测序数据、BAM文件、FASTQ文件这类受控数据，需要先通过相关项目的授权申请才可以使用。受控数据在下载时必须提供token，token就是你的访问凭证，相当于一把打开受控数据仓库的钥匙。

获取token的路径是：登录GDC Data Portal后，点击页面右上角的用户名，在下拉菜单里选择“GDC Authentication”选项。Token获取页面上会有一个“Generate Token”按钮，点击后会生成一串很长的字符串，然后下载成一个文本文件。这个文本文件就是接下来下载受控数据时要用的token文件。

使用token的命令也很简单，额外加一个-t参数：

./gdc-client download -m manifest.txt -t gdc-user-token.txt -d /path/to/output

token文件的有效期是30天，过期之后需要重新登录GDC页面生成新的token。我吃过一次亏，当时跑着一批BAM的下载任务，跑了两天忽然报出403错误，排查了半天才发现是token过期了。从那以后，我每次下载受控数据前都会先检查一下token文件的生成日期，超过20天就直接在页面上重新生成一个，避免任务跑到一半才掉链子。

4. 实用进阶：下载中断恢复与并发参数调优

4.1 断点续传：Ctrl+C也不怕数据重来

GDC-client内置了断点续传机制。下载过程中如果网络中断或者你主动按了Ctrl+C，已经下载完的文件会保留在本地，下次再执行相同的下载命令时，工具会先对本地已存在的文件做校验，已完整的文件会跳过，不完整的部分则从断点处继续下载。

这个机制的体验非常友好。我曾经下载过一批总大小将近200GB的RNA-Seq BAM文件，中间笔记本睡眠过、网络也断过，每次恢复后重新执行命令，它都会很智能地把剩余的部分继续拉完，不用从头再来。需要注意的一点是“重新执行相同的命令”这个前提，也就是manifest文件的路径和输出目录要和之前保持一致，如果换了输出目录，工具找不到之前的半成品文件，就会老实重新下载。所以下载大文件时，一定要固定一个工作目录，别中途随意切换。

4.2 并发参数：不是越大越好

并发下载数由-n参数控制，这个参数直接影响下载速度，但不是数值越大越好。在往年的实际使用中，我试过把并发数开到32，结果下载速度并没有等比提升，反而因为TCP连接数过多，遇到过Wi-Fi路由器负载过高导致整个局域网都卡顿的情况。后来我听一个搞运维的朋友建议，把并发控制在8到16之间，情况明显好转，下载稳定很多。

如果你是在学校的科研网或实验室服务器上操作，服务器的上行带宽通常比较充裕，可以把并发设到16。家用宽带一般带宽不太稳定，4到8比较稳妥。另外要留意，如果同一台服务器上有多个下载任务同时跑，建议总并发数不要超过20，否则容易出现文件系统打开文件数过多之类的系统限制报错。

4.3 只下载manifest中的部分文件

有时候你不想一次下载manifest里的全部文件，只想先拿几个样本的数据跑一跑流程。这时可以手动编辑manifest.txt，只保留需要的行，再用编辑后的文件作为参数执行下载。举个例子，如果我们只需要manifest中前3个文件，可以执行：

head -n 4 manifest.txt > manifest_sub.txt ./gdc-client download -m manifest_sub.txt -d /path/to/output

用head -n 4是因为manifest文件第一行是表头，所以取前4行正好是表头加上前3个文件。如果文件列表是乱的，也可以先用Excel或文本编辑器按文件名排序，再选择性剪切保留。这个小技巧对“先跑通流程再全量下载”的场景特别有用，我每次拿到一个新的分析流程，都会先下载两三个样本做测试，确认一切正常后，再启动全量下载，这样既省时间又省流量。

5. 常见问题与排查技巧实录

5.1 下载失败和连接超时的排查思路

GDC-client下载过程中出现错误，可以通过日志信息定位问题。我整理了最常见的情况和处理方式：

遇到连接超时的问题，我的习惯是先确认网络本身是否正常，最简单的办法是访问一下GDC官网首页，如果能打开，说明到GDC的链路是通的。接着再跑一次下载命令，很多时候自动重试就能恢复。如果是分时段断连的情况，比如每天固定时间卡住，那可能是网络出口或学校代理在高峰期限制了大文件传输，错峰到凌晨再跑会比较顺利。

5.2 token无效或过期的快速应对

token这个坑我前面提过，这里再单独说一说。GDC的token有效期是30天，从生成时刻开始计算。如果你下载时看到日志里出现UNAUTHORIZED或者403，十有八九是token的问题。最快的处理方式就是打开GDC Data Portal，进入GDC Authentication页面，重新生成token文件，然后替换掉本地的旧token文件重新执行下载。

替换token文件后，并不需要从头开始下载，已经下载完的文件不会重新下载，工具只会对未完成的部分继续工作。如果遇到“token file is invalid”这类错误，先检查token文件路径是不是写对了，以及文件内容是不是完整的一大段字符串。有时候浏览器下载token时会把它存成带.html后缀的文件，这种伪token文件GDC-client也能读，但会直接报Token Not Authorized，最好检查一下下载下来的文件类型。

5.3 下载速度慢怎么办

下载速度慢是一个高频问题。先看manifest里的文件类型，如果全是几千KB的小文件，瓶颈往往不在网络带宽，而是并发数太低。这时可以把-n调到16甚至24，通过更多并行连接来提升整体处理效率。如果文件类型是大BAM或FastQ，单文件就要几GB，那单个连接的速度就是决定性因素，调高并发的作用相对有限。

还有一种情况是学校的网络出口或服务器防火墙做了一定限制，导致到GDC的连接不稳定。这种情况下可以试试更换DNS，或者换一个网络环境，比如从办公室网换成临时用手机热点测试一下。如果手机热点下速度明显更快，说明是本地网络到GDC的路由质量不行，可以考虑通过代理中转，但具体方案大家根据自身网络环境来定，我这里就不展开了。用GDC-client官方工具本身是合规的数据下载方式，请确保下载行为符合你所在机构的学术规范。

5.4 本地磁盘空间不足的处理

大批量下载前，一定要确认磁盘空间足够。GDC文件中，表达矩阵通常几百KB到几MB，BAM文件则以GB计，一个转录组BAM可能在5~15GB之间。我们实验室曾遇到过一次批处理任务跑到一半，因为磁盘满了导致大量文件下载失败的情况，最后只能删掉部分临时数据，释放空间后再重跑。现在我的习惯是，在正式启动下载前先估算一下总量：打开manifest文件统计size列的总和，除以1024的三次方换算成GB，再对比当前磁盘剩余空间。如果空间紧张，就分批下载，用split命令把manifest按行数切成多份，一批下载完再跑下一批。

6. 写在最后：一点个人使用心得

TCGA数据下载这件事，看着简单，实际操作里的小门道并不少。跑了这么多年生信流程，我个人的体会是：GDC-client的正确打开方式，就是“网页筛选数据 + manifest批量下载”，把筛选和传输这两件事彻底分开。筛选交给Data Portal的图形界面，直观方便；传输交给GDC-client的命令行，稳定高效。两者配合，是官方推荐路径，也是真正省心省力的方式。

最后分享一个我自己的习惯：我会在每次下载任务完成后，写一个简单的记录文件，把manifest文件、下载日期、输出目录、下载文件数量都存档。这样做的好处是，当某篇论文需要说明数据来源、版本和下载时间时，这些记录能直接派上用场，不需要再去翻历史命令。生信科研这种工作，数据管理做得好不好，直接决定你后期的产出效率。希望这篇关于GDC-client的分享能帮你少走一些弯路，把时间花在真正重要的分析上。