去年帮一个临床团队搭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.jarbin目录下是启动脚本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.hostlocalhost exomiser.postgresql.port5432 exomiser.postgresql.databaseexomiser exomiser.postgresql.userexomiser exomiser.postgresql.passwordexomiserpass如果使用文件模式而不使用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 21 启动后日志会逐步打印数据加载、样本命中、分析进度等信息。第一次跑通常会慢一些因为程序需要加载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默认只监听了localhostTCP连接自然进不来。改回去或者修改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验证打分和报告。这两个都过了才敢正式上分析。这个习惯帮我过滤掉了很多“当时没报错但结果全空”的隐患。祝大家都能顺利跑出自己的候选基因报告。