第3章 安装Cromwell：下载与配置运行环境

好了，到了真刀真枪动手的时候。这一章我们就搞定Cromwell的安装和基础配置。别担心，这东西不像某些生物信息学工具那么折腾，几步就能跑起来。

我个人习惯把Cromwell装在专用的服务器或者开发机上，Windows下也可以跑，但生产环境还是建议Linux。嗯，这里假设你用的是Ubuntu 20.04+或者CentOS 7+。

3.1 下载 Cromwell JAR 包

Cromwell本身就是一个可执行的JAR文件。你想想看，人家设计得挺清爽的——没有复杂的依赖安装，拿下来就能用。

去GitHub Releases页面找最新版。我写这个课程时稳定版是85，你可以替换成你需要的版本。

# 创建一个专用目录
mkdir -p ~/cromwell
cd ~/cromwell

# 下载 Cromwell JAR（替换版本号为你需要的）
wget https://github.com/broadinstitute/cromwell/releases/download/85/cromwell-85.jar

# 同时下载 womtool（可选，但很有用）
wget https://github.com/broadinstitute/cromwell/releases/download/85/womtool-85.jar

# 验证文件完整性
ls -lh *.jar

alias cromwell='java -jar ~/cromwell/cromwell-85.jar'

3.2 安装 Java 运行环境

Cromwell 是基于 JVM 的，所以必须先装 Java。我建议用 Java 11 或 Java 17，别用 Java 8 了——我在项目中踩过坑，Java 8 下某些 WDL 特性会报奇怪错误。

# Ubuntu / Debian
sudo apt update
sudo apt install -y openjdk-11-jre

# CentOS / RHEL
sudo yum install -y java-11-openjdk

# 验证
java -version

3.3 快速验证：运行 Hello World

Cromwell 装没装好，跑个最简单的 WDL 脚本就知道了。我每次装新环境都会用这个测试。

创建一个 hello.wdl：

version 1.0

workflow hello_workflow {
    call hello
}

task hello {
    command {
        echo "Hello, Cromwell!"
    }
    output {
        String greeting = read_string(stdout())
    }
}

再创建一个 hello_inputs.json（虽然这个例子不需要输入，但 Cromwell 习惯要一个）：

{}

然后运行：

java -jar ~/cromwell/cromwell-85.jar run hello.wdl -i hello_inputs.json

如果看到类似下面的输出，说明安装成功了：

...
[info] SingleWorkflowRunnerActor Workflow completion status: Succeeded
{
  "hello_workflow.hello.greeting": "Hello, Cromwell!"
}

3.4 配置 Cromwell 运行模式

Cromwell 有两种运行方式：

我建议初学者先用单次运行摸清流程。等你需要管理多个工作流时，再切到服务器模式。

3.5 服务器模式配置详解

服务器模式需要一个配置文件 cromwell.conf。这货用的是 HOCON 格式，说白了就是带缩进的 JSON，更人性化一点。

下面是一个最小可用的配置：

include required("application.conf")

webservice {
  port = 8000
  interface = "0.0.0.0"
}

call-caching {
  enabled = true
  invalidate-bad-cache-results = true
}

database {
  profile = "slick.jdbc.HsqldbProfile$"
  db {
    driver = "org.hsqldb.jdbcDriver"
    url = "jdbc:hsqldb:file:./cromwell-executions/cromwell-db;shutdown=false"
    connectionTimeout = 30000
    numConnections = 5
  }
}

然后启动：

java -jar ~/cromwell/cromwell-85.jar server --config cromwell.conf

启动后访问 http://localhost:8000 就能看到 Cromwell 的 Web 界面了。

3.6 环境变量与 PATH 配置（可选）

为了方便，我习惯把 Cromwell 加到 PATH 里。创建一个启动脚本 ~/bin/cromwell-run：

#!/bin/bash
JAVA_OPTS="-Xmx4g -Xms1g"
exec java $JAVA_OPTS -jar ~/cromwell/cromwell-85.jar "$@"

然后：

chmod +x ~/bin/cromwell-run
export PATH="$HOME/bin:$PATH"

之后直接 cromwell-run run workflow.wdl 就行了。嗯，这样省心。

3.7 验证服务器模式

启动服务器后，用 curl 测试一下 API 是否正常：

# 查询版本
curl http://localhost:8000/api/v1/version

# 查询后端状态
curl http://localhost:8000/api/v1/backends

# 提交一个工作流（假设有 workflow.wdl 和 inputs.json）
curl -X POST \
  http://localhost:8000/api/v1/workflows/v1 \
  -F workflowSource=@workflow.wdl \
  -F workflowInputs=@inputs.json

返回的 JSON 里会有 id 字段，那是你的工作流唯一标识。后面查状态、取消任务都用这个 ID。

这张图把整个安装决策路径串起来了。你下载 JAR → 装 Java → 验证 → 根据场景选模式。我个人推荐先在单次运行模式下摸熟 WDL 语法，然后再搭服务器。

3.8 常见问题排错

安装过程中你可能会遇到下面这些问题，我把经验列出来：