企业官网建设流程全解析

去年帮一个临床团队搭WES数据线下分析环境，头一件事就是装Exomiser。本来以为一个jar包几分钟就能搞定，结果从Java版本到PostgreSQL再到数据包，陆陆续续折腾了一周。现在回头看，真正的坑不在Exomiser本身，而在于很多人（包括我）把它当成一个“下载即用”的普通软件，忽略了它背后的运行条件和数据依赖。这篇文章我把自己的安装过程和排障经验完整记录下来，给准备做遗传病变异注释预测工具安装的同行一个参考，特别是那些卡在启动报错和运行不出结果的朋友，省得再走一遍弯路。

1. 遗传病分析为什么要用Exomiser：从变异列表到基因排序

1.1 一个真实场景

我拿到过一个三人核心家系的外显子组测序VCF，样本包含患儿和父母。经过常规的变异过滤之后，剩余需要人工关注的位点还有两三千个。如果按照“频率低、预测有害、符合遗传模式、表型相关”的思路去逐个排查，一个样本至少需要两到三天。而Exomiser的做法是把这些规则全部工程化：输入VCF、家系信息和患儿表型（HPO术语），输出一份候选基因排序列表。它把“从变异到基因”的优先级计算过程压缩到一个晚上跑完，第二天直接看报告，实验效率完全不一样。

1.2 Exomiser解决的核心问题

Exomiser是一款开源的Java程序，最初由Sanger研究院等机构推动，主要面向遗传病方向的候选基因筛选。它并不是单纯做“变异注释”的工具，而是把注释和基因优先排序黏合在一起。它读取VCF/BCF文件，结合已知变异频率数据（比如gnomAD、1000 Genomes）、致病性预测数据（SIFT、PolyPhen、MutationTaster、CADD等）、数据库（ClinVar、OMIM、Orphanet）以及HPO表型本体，最后给每个基因打一个综合分数。这个分数反映的是“该基因导致患儿表型的可能性”。

它和普通注释工具最大的区别在于表型驱动。比如两个基因都出现了一个罕见的错义突变，如果没有表型信息，你很难判断哪个更可能与患者症状相关。Exomiser会计算HPO项与已知疾病基因之间的相似度，表型匹配度高的基因会获得更高的权重，这一步是人工短时间难以完成的。

1.3 安装前先想清楚用哪种模式

正式开始安装前，我建议你先确定自己的分析场景，因为不同模式对输入文件的要求差别很大。Exomiser支持单样本外显子组或基因组、家系共分离、以及自定义基因白名单等模式。单样本模式只需要一个VCF和一个样本HPO列表；家系模式还需要PED文件，并且要指明先证者和遗传模式；白名单模式则适合你已经有若干个候选基因，想快速验证哪些基因有可解释的变异。

另一个要提前定下来的是参考基因组版本，GRCh37还是GRCh38。这个选择直接影响后续下载的数据包类型和配置文件里的genomeAssembly字段。版本混用是我见过最常见的问题，比如VCF是GRCh38，而Exomiser的数据目录只准备了GRCh37，结果分析时一个变异都跑不出来，甚至启动时就报contig缺失。先把这些前提理清楚，再往下走会顺利很多。

2. 环境准备的三座大山：Java版本、PostgreSQL和参考数据

2.1 Java 17是硬门槛，别用8和11将就

Exomiser是基于Spring Boot的Java应用，对JDK版本非常敏感。以Exomiser 13.x和14.x为例，官方明确要求Java 17，你用Java 8或Java 11启动，很大概率会直接抛UnsupportedClassVersionError。如果只是做测试，也可以先装一个OpenJDK 17再说。

sudo apt install openjdk-17-jdk java -version

安装完务必确认java -version显示的确实是17。我遇到过一台服务器上同时装了系统自带JDK 11、conda环境里的JDK 8、以及手动解压的JDK 17，结果which java指向了conda环境，折腾了很久。如果发现版本不对，可以用绝对路径调用Java，或者在启动脚本里显式写上JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64，再导出PATH。

2.2 PostgreSQL不一定是必需，但生产环境建议上

Exomiser有两种变异数据存储方式：一种是直接用压缩的VCF/TSV文件作为数据源，适合小规模验证；另一种是把变异数据导入PostgreSQL，适合正式的生产分析。如果你只是先跑通流程，文件模式完全够用；但样本量大、查询频繁的场景，PostgreSQL的优势就很明显，也方便后续做增量更新。

如果决定用PostgreSQL，安装后要做三件事：创建数据库用户、创建数据库、导入建表脚本。我的做法是在PostgreSQL里单独建一个exomiser用户和exomiser库，不要图省事直接用postgres超级用户。原因很简单，Exomiser的配置中需要明文写数据库密码，用一个权限被限制的专有账号更安全。

CREATE USER exomiser WITH PASSWORD 'exomiserpass'; CREATE DATABASE exomiser OWNER exomiser;

后续从Exomiser安装包的sql目录下找到建表脚本，用psql导入到exomiser数据库里。这一步必须放在第一次运行前，否则程序启动检测不到表结构，会报数据库相关错误。导入完成后可以用\dt检查一下表是否生成成功。

2.3 参考数据包：大小、版本和下载方式

Exomiser程序本身很小，真正占空间的是参考数据。官方releases页面会同时提供程序zip和数据包zip，数据包解压后经常是几十GB，里面包括参考基因序列、HPO本体、疾病表型关联数据、人群频率数据、致病性预测数据等。下载的时候建议用wget -c加断点续传，不要用浏览器下载到一半失败又重新来，太浪费时间。

下载完成后强烈建议核对一下文件的SHA256，再解压。数据包损坏的表现很隐蔽，解压时不一定会报错，但Exomiser启动时读取某个文件可能异常或者直接找不到某个目录。我踩过一次数据文件不完整导致HPO本体解析失败的坑，最后重新下载才解决。版本方面，数据包的大版本要和程序版本匹配，不要拿Exomiser 13的程序搭配Exomiser 14的数据，字段格式和读取逻辑可能有变化。

2.4 磁盘和路径规划

安装前先规划好路径，会少很多麻烦。我的习惯是在根目录下建一个/data/exomiser，程序放在/data/exomiser/app，数据放在/data/exomiser/data，输出目录放在/data/exomiser/output。路径中不要出现中文、空格和奇怪的特殊字符，否则YAML配置和shell脚本容易出问题。

磁盘类型也要考虑。Exomiser在分析过程中需要频繁读取参考数据，机械硬盘虽然能跑，但速度会拖后腿。如果条件允许，把数据目录放在SSD上，或者使用带缓存的阵列。另外，PostgreSQL如果也部署在同一台机器，要给数据库和Exomiser分别预留足够的空间，两者加起来可能要占用相当多的磁盘。

3. 正式安装：目录分析、启动脚本和配置文件逐行解读

3.1 解压后的目录结构

拿到exomiser-cli-13.2.0.zip后，直接unzip解压到指定目录。解压后的目录结构大致如下：

exomiser-cli-13.2.0/ ├── bin/ ├── lib/ ├── sql/ ├── test_data/ ├── application.properties └── exomiser-cli-13.2.0.jar

bin目录下是启动脚本，lib目录里是各种依赖jar包，sql目录里是数据库建表脚本，test_data是官方自带的测试数据，这个非常重要，后续验证安装是否成功全靠它。主程序就是那个exomiser-cli-*.jar，但日常使用建议通过bin/exomiser脚本启动，因为脚本里已经处理了classpath和环境变量，直接用java命令反而容易漏掉依赖。

3.2 application.properties配置说明

Exomiser的全局配置通常在application.properties里，不同版本文件名可能略有差异，但核心字段大同小异。我最关心的几个配置项是数据目录、数据库连接和临时目录：

exomiser.data-directory=/data/exomiser/data exomiser.postgresql.host=localhost exomiser.postgresql.port=5432 exomiser.postgresql.database=exomiser exomiser.postgresql.user=exomiser exomiser.postgresql.password=exomiserpass

如果使用文件模式而不使用PostgreSQL，数据库连接相关配置可以暂时不填。但>analysis: genomeAssembly: GRCh37 vcf: /data/exomiser/input/patient.vcf.gz pedigree: /data/exomiser/input/family.ped proband: PATIENT_ID modeOfInheritance: AD hpoIds: - HP:0001156 - HP:0001363 analysisMode: PASS_ONLY frequencySources: - GNOMAD_E - THOUSAND_GENOMES pathogenicitySources: - SIFT - POLYPHEN - MUTATION_TASTER - CADD outputOptions: outputContributingVariantsOnly: true

这里有几个容易忽略的细节。genomeAssembly必须写成GRCh37或GRCh38，大小写别错；proband这个ID必须与PED文件里的样本ID完全一致，否则Exomiser无法判断哪个样本是先证者；modeOfInheritance的值也是有固定枚举的，比如AD对应常染色体显性，AR对应常染色体隐性。

3.4 启动命令与常见启动参数

配置好之后，在解压目录下运行以下命令：

./bin/exomiser --analysis analysis.yml

如果是在服务器后台长时间跑，建议加上nohup把日志写到文件里：

nohup ./bin/exomiser --analysis analysis.yml > exomiser.log 2>&1 &

启动后日志会逐步打印数据加载、样本命中、分析进度等信息。第一次跑通常会慢一些，因为程序需要加载HPO本体和变异数据索引。看到日志里出现类似“Analysis complete”这样的信息，就说明流程跑完了。如果启动时报错，不要急着改配置，先看日志文件，日志里通常会给出具体原因。

4. bug处理实录：我踩过的6个典型问题复盘

4.1 UnsupportedClassVersionError：一看就让人怀疑人生的报错

第一次启动时，我遇到的是下面这个报错：

Exception in thread "main" java.lang.UnsupportedClassVersionError: org/exomiser/cli/Exomiser has been compiled by a more recent version of the Java Runtime (class file version 61.0)

class file version 61.0对应Java 17，而当前运行环境只支持到55.0，也就是Java 11。排查链路并不复杂：先运行java -version看当前Java版本，再用which java确认它来自哪里。我发现是conda base环境里注册了一个旧JDK，导致即使sudo apt install openjdk-17-jdk成功了，shell里的java仍然指向旧版本。解决办法是修改用户.bashrc，将JAVA_HOME指向JDK 17的绝对路径，并重新登录终端。

这个报错的隐蔽之处在于，它不是一启动就崩溃，而是可能在加载某个类的时候才抛出来，容易让人误以为jar包损坏。如果你反复解压重下还是同样错误，请先确认Java版本。

4.2 PostgreSQL连接失败：一半以上安装问题都出在这里

数据库相关的报错花样最多。我遇到过连接被拒绝、密码认证失败、数据库不存在三种情况。连接拒绝时日志里会有Connection refused，我第一反应是PostgreSQL没启动，结果systemctl status postgresql显示服务正常。后来发现是我把配置里的host写成了服务器内网IP，而PostgreSQL默认只监听了localhost，TCP连接自然进不来。改回去或者修改postgresql.conf里的listen_addresses就能解决。

密码认证失败则多半是pg_hba.conf的认证方式和配置不匹配。默认配置下，本地peer认证可能不允许通过TCP加密码登录，需要改成md5或scram-sha-256，改完重启PostgreSQL。数据库不存在这个错误更常见，通常是你手滑在配置里写了exomiser_db，但实际建的库叫exomiser。排查数据库问题时，先别急着看Exomiser日志，先用psql命令行手动连一次：

psql -h 127.0.0.1 -U exomiser -d exomiser -W

如果psql能连上，Exomiser连不上，那问题一定在配置细节上。

4.3 数据目录找不到或数据文件损坏

启动时报Unable to access exomiser data directory是最直接的提示，一般是配置里的>cd exomiser-cli-13.2.0 ./bin/exomiser --analysis test_data/test_analysis.yml

测试数据通常体积很小，加载数据可能比实际分析还费时间。运行成功后，日志会显示输出文件的路径。我的习惯是加time命令记录总耗时，判断后续真实样本分析的参考用时。如果测试配置能正常生成结果文件，说明Java、数据目录、配置解析这几个核心环节没有问题。

5.3 读懂输出文件

Exomiser会输出多种格式的结果，常见的包括HTML报告、JSON数据和带注释的VCF。HTML报告适合直接打开看，里面会有候选基因列表、贡献变异列表和相关疾病信息。JSON文件适合程序化读取，里面每个基因都有geneScore、pValue、phenotypeScore和variantScore这些关键字段。带注释的VCF则是在原VCF基础上增加了Exomiser的注释信息，可以和下游工具无缝衔接。

看报告时不要只盯着排名第一的基因。Exomiser的分数只是一个优先排序依据，真正下结论还得看变异的人群频率、致病性预测和家系共分离情况。软件只是把人工筛选工作量缩小了一个数量级，而不是替代临床判断。

5.4 用自测结果判断“装没装成功”

怎么判断安装是否成功？我的标准很简单：测试运行能正常结束，生成的HTML里有基因列表，JSON里能读到分数，带注释的VCF里有变异条目。如果任何一步不对，哪怕程序没报错“正常退出”，也必须排查清楚再进入正式分析。

6. 上线前自检：性能调优和数据更新的几点建议

6.1 内存与并发参数

正式跑之前，建议根据样本量大小调整内存参数。全外显子组单样本建议至少8G堆内存，家系样本或全基因组数据建议16G以上。如果数据索引放在PostgreSQL里，Java进程和数据库进程会争抢内存，所以不要盲目把-Xmx调成物理内存的大头，给数据库留一定余量。分析过程中可以同时观察top和数据库连接数，确认没有内存颠簸。

6.2 数据版本更新

Exomiser的参考数据不是一劳永逸的。HPO本体、ClinVar、gnomAD等数据源都在持续更新，导致旧版数据可能漏掉新发现的疾病关联或者使用过期的HPO ID。建议每隔三到六个月关注一次官方发布，按说明更新数据包。更新后，如果使用PostgreSQL模式，记得重新导入变异数据，并对表执行ANALYZE更新统计信息，否则查询性能会明显下降。

6.3 联调生产环境时的注意事项

正式环境里，我建议把输入、输出和数据目录分开管理，分析任务通过脚本进行封装，每个样本一个子目录，保留完整的日志和配置文件副本。这样排错时能快速还原当时的运行环境。另外，Exomiser运行时会产生一些中间临时文件，确认临时目录有足够空间，并且定期清理，避免撑爆磁盘。

6.4 最后再聊一个容易踩的细节：文件命名和路径

VCF文件、PED文件、HPO列表这些输入文件的命名，尽量只用字母、数字、下划线和中划线。文件名里的空格会导致YAML解析出错，中文路径可能导致字符编码问题。配置文件里每一层的缩进也必须一致，不要混用Tab和空格，否则报错会让人摸不着头脑。

最后说一个我自己的习惯：每次装完Exomiser，我先跑一遍自带测试数据，再拿一个已知阳性位点的VCF验证打分和报告。这两个都过了，才敢正式上分析。这个习惯帮我过滤掉了很多“当时没报错但结果全空”的隐患。祝大家都能顺利跑出自己的候选基因报告。