📚 课程目录第2章安装Cromwell

安装 Cromwell：本地安装与 Docker 部署

安装 Cromwell 其实比你想的简单。它本质上就是一个 Java JAR 包，或者一个 Docker 镜像。不过，不同的部署方式会影响你后续的 workflow 开发和流程调试效率。我两种方式都用过，今天把经验梳理一下。

本地安装：最直接的开始

本地安装适合开发调试、小规模测试。我个人习惯在笔记本或工作站上先用本地模式跑通一个简单的 WDL，再去上集群。这样排查问题最快。

前提条件

Java Runtime：Cromwell 是 Java 应用，需要 JDK/JRE 11 或更高版本。我曾经因为装了个 Java 8 折腾了半天，记住了：java -version 确认版本。
足够的磁盘空间：workflow 运行会产生大量中间文件和日志，特别是跑 NGS 数据时，分分钟占满 /tmp。

下载与运行

去 Cromwell 的 GitHub Release 页面下载最新的 cromwell-xxx.jar。下载完成后，你就可以直接用命令行启动它：

java -jar cromwell-85.jar server

跑起来之后，默认监听 localhost:8000。你可以用浏览器打开 http://localhost:8000 查看 Swagger API 文档。我个人习惯不用 Swagger，直接用 curl 提交 workflow，更快：

curl -X POST "http://localhost:8000/api/workflows/v1" \
  -F workflowSource=@my_pipeline.wdl \
  -F workflowInputs=@inputs.json

嗯，这里要注意：如果你在 Linux 服务器上运行，记得加上 -Dconfig.file=application.conf 来指定你的配置文件，否则 Cromwell 会使用一堆默认配置，可能会踩到路径和权限的坑。

我的建议：开发阶段用 java -jar cromwell.jar run my_pipeline.wdl --inputs inputs.json 来跑单次 workflow，不需要启动长时间运行的 server 进程。简单又方便。

Docker 部署：生产环境的标配

说实话，在生产环境里，我几乎不用本地安装。Docker 部署才是王道。为什么？你想想看，Java 版本、环境变量、文件系统权限这些乱七八糟的问题，Docker 一次性全隔离了。我曾在客户的 HPC 集群上帮他们部署 Cromwell，因为管理员死活不同意装特定版本的 Java，最后还是用 Docker 搞定的。

拉取镜像

Cromwell 官方 Docker 镜像发布在 broadinstitute/cromwell 仓库下：

docker pull broadinstitute/cromwell:85

注意版本号要和你的 WDL 语法兼容。我一般都会锁定一个具体的版本，而不是用 latest。被 latest 坑过的人应该都懂。

启动容器

最简单的启动方式：

docker run -p 8000:8000 \
  -v /path/to/workflows:/workflows \
  -v /path/to/outputs:/outputs \
  broadinstitute/cromwell:85 server

这里 -v 是关键：把宿主机的 workflow 目录和输出目录挂载到容器里。我曾经忘记挂载输出目录，结果跑完发现所有结果都在容器内部，取不出来，只能重新跑。嗯，这个坑我印象很深。

配置文件挂载

Cromwell 的配置支持多种后端（Local、SLURM、HTCondor、Google Cloud 等）。我建议把 application.conf 放到宿主机上，用 -v 挂载进去：

docker run -p 8000:8000 \
  -v /etc/cromwell/application.conf:/app/application.conf \
  -v /data/workflows:/workflows \
  -v /data/outputs:/outputs \
  broadinstitute/cromwell:85 server \
  -Dconfig.file=/app/application.conf

  注意：配置文件里的路径要写容器内的路径，不是宿主机的路径！我见过很多人反复在这里出错。

两种方式对比

特性	本地安装	Docker 部署
上手难度	简单，一条 java 命令即可	中等，需要熟悉 Docker
环境一致性	依赖宿主机环境	完全隔离，跨平台一致
适合场景	开发调试、单机测试	生产环境、集群部署
文件系统管理	直接存取，权限问题多	需要挂载卷，但更安全
升级维护	手动下载 JAR	docker pull 即可

验证安装是否成功

不管你选哪种方式，跑起来之后，我推荐用下面的方法快速验证：

curl -s "http://localhost:8000/api/workflows/v1/query" | python -m json.tool

如果返回一个包含 results 字段的 JSON 数组（哪怕是个空数组），说明 Cromwell 已经在正常提供服务了。如果没有返回，别慌，看看日志。通常问题出在端口被占用，或者配置文件的语法错误上。

我曾遇到过一个特别隐蔽的问题：Cromwell 启动后，第一次提交 workflow 就报奇怪的 I/O 错误。查了两天才发现是文件系统挂载的权限不对。Docker 容器里的 cromwell 用户和宿主机用户 UID 不匹配。解决方案：在 docker run 时加上 --user $(id -u):$(id -g)，强制容器内的进程以当前用户身份运行。

本章知识体系一览

下面这张图把本地安装和 Docker 部署的主要流程和关键步骤梳理了一下。

两种安装方式，没有绝对的好坏，关键看你的场景。本地安装适合快速上手和调试，特别是 workflow 还处于频繁修改的阶段。Docker 部署则适用于需要稳定运行、多用户共享或生产环境的场景。我个人推荐：你在开发机上用本地安装，服务器上一定用 Docker 部署。