DataHub Docker 部署实战指南：官方镜像体系、Compose Profiles 与 Nuke 清理机制

DataHub Docker 部署实战指南：官方镜像体系、Compose Profiles 与 Nuke 清理机制

【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub

本指南以 DataHub 仓库的 docker/README.md 为核心，系统讲解 DataHub 的 Docker 部署全貌：从官方镜像清单与 full/slim/locked 变体体系，到基于 Compose Profiles 的 quickstart 与本地调试工作流，再到用于彻底清理环境的 Gradle Nuke 任务。读完本文，你将掌握如何选择正确的镜像 tag 与变体、用一条命令拉起或停掉整套环境，并能在源码层面理解镜像构建与清理的底层机制。

前置条件与环境准备

DataHub 的容器化部署依赖 Docker 与 Docker Compose。在 Linux 上需要单独安装 docker 与 docker-compose；在 Windows 与 macOS 上，Docker Desktop 已内置 Compose。

硬件资源方面，仓库文档给出的已验证配置为2 CPU、8GB RAM、2GB Swap 交换区；docs/quickstart.md 进一步补充了13GB 磁盘空间的建议值。资源不足时，Elasticsearch/OpenSearch、Kafka、MySQL 等依赖组件的启动或健康检查可能失败。

如果不希望使用需要商业授权的 Docker Desktop，官方文档推荐了Podman Desktop与Rancher Desktop这两个免费开源替代品，并给出了可直接写入~/.bashrc的别名配置，将docker/docker-compose命令无缝映射到替代引擎：

# podman alias docker=podman alias docker-compose="podman compose" # Rancher (或 nerdctl) alias docker=nerdctl alias docker-compose="nerdctl compose"

快速开始：一条命令拉起整套 DataHub

DataHub 的官方镜像随仓库每次提交持续构建并发布。最简单的启动方式是通过 DataHub CLI（acryl-datahub）执行：

datahub docker quickstart

该命令会拉取协调一致的镜像集合与 Compose 编排文件，依次启动 MySQL、OpenSearch、Kafka、datahub-gms、datahub-frontend、datahub-actions 等容器。启动成功后（docs/quickstart.md 给出了完整的输出形态），即可通过浏览器访问http://localhost:9002，使用默认凭据登录：

username: datahub password: datahub

常用管理命令一览（详见 docs/quickstart.md 的 "Managing Your Local Instance" 一节）：

datahub docker quickstart --stop # 停止 quickstart 环境 datahub docker nuke # 清除全部状态（容器与数据卷） datahub docker quickstart --version v1.6.0 # 指定发布版本启动 datahub docker quickstart --backup # 备份 MySQL 到 ~/.datahub/quickstart/backup.sql datahub docker quickstart --restore # 从备份恢复主库与索引 datahub docker quickstart --restore-indices # 仅用主库数据重建搜索索引

关于版本选择，官方明确要求不要在生产的 Compose/quickstart 环境使用latest或debugtag（二者仅因历史原因保留，不受支持）；本地部署应使用协调发布的quickstarttag 或v*版本 tag（如v0.8.40），生产与 Kubernetes 部署则应固定发布 tag 或不可变的 commit tag（sha-<short_sha>）。

Compose 布局：基于 Profiles 的编排架构

自新版本起，quickstart 与本地开发统一改用Docker Compose Profiles编排，定义在 docker/profiles/docker-compose.yml。根文件本身只是一个聚合入口，通过include按职责拆分：

• docker-compose.prerequisites.yml：存储层，即 mysql、kafka、elasticsearch（或 OpenSearch）
• docker-compose.actions.yml：datahub-actions 动作执行器
• docker-compose.frontend.yml：前端
• docker-compose.gms.yml：GMS、system-update、消费者等其余组件
• docker-compose.ollama.yml：可选的本地 Ollama 嵌入服务（quickstart-ai / debug-ai profile）

CLI 使用的扁平化 Compose 文件在构建期由 Gradle 任务generateQuickstartComposeConfig（定义于 docker/build.gradle）生成，产物为 docker/quickstart/docker-compose.quickstart-profile.yml。该文件中的版本号、签名密钥、端口等均以${VAR}占位形式保留，运行时由 CLI 注入。

快速开始与开发共用的 Profiles 一览（完整矩阵见 docker/profiles/README.md）：

直接使用 Profiles 需要docker compose >= 2.20（docker/build.gradle中的minDockerCompose2.20任务会在每次 ComposeUp 前做版本校验）。也可以绕过 Gradle 直接运行：

cd docker/profiles docker compose --profile quickstart up

Gradle 侧则提供了./gradlew quickstart、./gradlew quickstartDebug等封装任务。所有 quickstart 配置定义在docker/build.gradle的quickstart_configs字典中，涵盖 quickstart、quickstartCLI、quickstartDebug、quickstartPg、quickstartSlim、quickstartSpark、quickstartStorage 等十余种组合，每种配置都指定了profile（或profiles列表）以及需要参与构建的 Gradle 模块。

官方镜像全家桶

DataHub 以acryldata组织名义发布一组分工明确的镜像，每次 commit 都会持续部署到镜像仓库：

其中datahub-actions请使用acryldata/datahub-actions；文档明确标注acryldata/acryl-datahub-actions已废弃、不再使用。

镜像变体体系：full / slim / locked

datahub-ingestion与datahub-actions两个 Python 类镜像各自提供full、slim、locked三种变体，取舍维度是连接器覆盖度与镜像体积的平衡：

变体通过 tag 后缀区分：

acryldata/datahub-ingestion:v0.x.y # full（默认） acryldata/datahub-ingestion:v0.x.y-slim # slim acryldata/datahub-ingestion:v0.x.y-locked # locked

datahub-ingestion特性矩阵（完整版见 docker/README.md）：

datahub-actions特性矩阵（完整版见 docker/README.md）：

CI 测试覆盖方面：full与slim变体在每个 PR 上都会运行冒烟测试（smoke tests），而locked变体目前仅做构建验证。

从源码看，变体的差异直接体现在 Dockerfile 的构建阶段中。以 docker/datahub-ingestion/Dockerfile 为例：ingestion-base-slim安装 LDAP/SASL/Kerberos、librdkafka、unixODBC 等通用依赖；ingestion-base-full在其上追加openjdk-25-jre-headless（支撑 Spark lineage）、构建工具链、Oracle Instant Client 与 MSSQL ODBC 驱动；locked则复用 slim 底座，但在最终阶段通过UV_DEFAULT_INDEX与PIP_INDEX_URL指向不可达地址（http://127.0.0.1:1/simple）封锁 PyPI 网络访问，实现"构建期装好、运行期不可再装"。datahub-ingestion各变体依赖RELEASE_VERSION构建参数，并要求预先完成 codegen（test -d /metadata-ingestion/src/datahub/metadata）。

docker/datahub-actions/Dockerfile 的 locked 变体更进一步：最终镜像中直接删除 pip/uv（strip_pip_uv_from_venvs.sh），仅保留/opt/datahub/venvs下预构建的 bundled venvs，缩小攻击面。

Java 运行时与镜像构建参数

五个 Java 服务镜像（datahub-gms、datahub-mce-consumer、datahub-mae-consumer、datahub-upgrade、datahub-frontend-react）共享 docker/snippets/setup_java_runtime.sh，该脚本统一负责：

• 通过 apk 安装 OpenJDK JRE，运行时为Java 25 LTS（脚本内JAVA_MAJOR=25是唯一的版本升级触点，datahub-actions构建时也会解析该行）；
• 由于 apk 的 OpenJDK JRE 默认不提供/usr/bin/java，脚本负责建立符号链接，确保各start.sh入口能直接调用java；
• 按架构下载jattach（可通过INSTALL_JATTACH=0跳过），用于后续性能采集；
• 下载 OpenTelemetry Java Agent 与 JMX Prometheus Java Agent（版本由JMX_VERSION控制，默认1.0.1），对应ENABLE_OTEL/ENABLE_PROMETHEUS运行开关；
• 移除unix_chkpwd的 setuid/setgid 位以消除扫描告警。

每个 Java 服务镜像的 Dockerfile 都声明了默认基础镜像，可通过BASE_IMAGE构建参数覆盖；可选APK_REPOSITORY_URL参数可替换构建期使用的 apk 软件源（面向企业内网环境）。使用 Gradle 构建时，对应参数为-PdockerBaseImage=...与-PapkRepositoryUrl=...（取代历史遗留的 mirror 属性）。

以 docker/datahub-gms/Dockerfile 为例，其默认基础镜像为cgr.dev/chainguard/wolfi-base:latest，构建时：

• 将APK_REPOSITORY_URL（默认https://apk.cgr.dev/chainguard）写入/etc/apk/repositories；
• 挂载缓存执行setup_java_runtime.sh；
• 通过ARG WAR_FILE选择启动包：默认war.war，ONNX 变体（datahub-gms-onnx，内置 ONNX/DJL 原生库）则打包war-onnx.war，但目标文件名保持不变以保证start.sh无需改动；
• 使用非 root 用户datahub运行，EXPOSE 8080并配置了基于/health端点的 HEALTHCHECK。

GMS 启动脚本 docker/datahub-gms/start.sh 还实现了 JAR 解压优化：当EXTRACT_JAR_ENABLED=true时，将 WAR 解压到 tmpfs 并基于BOOT-INF/classpath.idx生成确定性 classpath（通过 Java argfile 启动），以加快类加载；解压失败或资源不足时自动回退到传统-jar启动。GMS/upgrade 启动脚本中还能看到datahub_wait_*系列依赖等待逻辑（等待 Elasticsearch、Ebean 数据源、Kafka broker、Neo4j 等就绪后再启动服务）。

datahub-ingestion镜像基于Ubuntu 24.04，Python 默认 3.10，使用uv管理虚拟环境与依赖安装（见 docker/datahub-ingestion/Dockerfile）。

依赖组件与系统更新任务

DataHub 的容器化部署依赖以下后端组件：

• Elasticsearch（或 OpenSearch）—— 搜索、图与时间序列索引
• MySQL（或 PostgreSQL）—— 主数据存储
• （可选）Neo4j —— 图关系存储

SQL 与搜索索引的初始化由system update 任务完成，即datahub-upgrade容器以-u SystemUpdate运行，前提是后端存储服务已健康。换言之，不再需要单独的 setup 容器，这与旧版编排有显著区别。升级任务在 quickstart 与生产环境中会阻塞其他容器的对外就绪（datahub-upgrade的 start.sh 会先行等待依赖并执行升级/重建索引，详见 docker/datahub-upgrade/start.sh 与 docker/datahub-upgrade/README.md）。

加载演示数据

环境启动后，如需快速体验元数据摄入，可依次执行：

datahub init datahub datapack load showcase-ecommerce

showcase-ecommerce数据包包含约 1,050 个实体（覆盖 Snowflake、Looker、PowerBI、Tableau 场景），并附带了血缘、治理、术语表、域与数据产品等元数据，便于在 UI 中直观探索（详见 docs/quickstart.md）。

开发模式：用 Docker 镜像做本地调试

本地开发推荐使用./gradlew quickstartDebug（或面向 Agent 工作流的 scripts/dev/datahub-dev.sh）。该任务定义在 docker/build.gradle，执行三步：

1. 构建全部所需工件（GMS war、前端 distribution zip 等）；
2. 以debugtag 本地构建镜像；
3. 以debugprofile 启动 Compose 栈，将本地文件直接挂载进容器，并开放远程调试端口。

启动后 UI 同样位于http://localhost:9002。调试端口由环境变量控制：DATAHUB_MAPPED_GMS_DEBUG_PORT（默认 5001）与DATAHUB_MAPPED_FRONTEND_DEBUG_PORT（默认 5002），IDE 可通过 Remote Java Debug 连接。

增量开发时，reload与reloadEnv是更高效的选择：

./gradlew :docker:reload # 仅重建发生变化的模块并重启受影响的容器 ./gradlew :docker:reloadEnv # 重建并 recreate 全部相关容器（用于环境变量变更）

两者的前置条件是已通过某个 debug 变体任务（如quickstartDebug）拉起过环境；docker/build.gradle通过记录到build/目录的 profile 文件自动识别当前激活的 profile。通过DATAHUB_LOCAL_COMMON_ENV=my-settings.env ./gradlew quickstartDebug可以为所有容器批量注入自定义环境变量（env 文件需放在docker/profiles目录下）。

暂停与恢复环境可直接使用 Compose 命令：

docker compose --project-directory docker/profiles -p datahub stop docker compose --project-directory docker/profiles -p datahub start

更完整的开发工作流说明见 docs/docker/development.md。

构建与发布 Docker 镜像

官方镜像由 CI（GitHub Actions）在每次 release 成功后自动构建并发布，正常情况下无需手动构建。如需在本地复现发布级镜像，可执行：

COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 docker compose -p datahub build

其中DOCKER_BUILDKIT=1是必需的，因为镜像依赖 BuildKit 的多阶段构建特性；建议同时设置唯一的DATAHUB_VERSION以区分本地构建产物。在 Gradle 一侧，docker/build.gradle提供了buildImages<配置名>任务族，内部调用docker buildx bake（或depot，通过DOCKER_CACHE=DEPOT环境变量切换），并支持-PbuildModules只构建 PR 实际影响的镜像子集。

对于希望扩展官方镜像的社区成员，仓库欢迎在官方镜像之上二次构建的社区 Dockerfile，但并非所有镜像改动都会被上游合并（需权衡构建时长、依赖与安全漏洞风险），此类扩展镜像由社区自行托管维护。

Nuke 任务系统：彻底清理 DataHub 容器与数据卷

Nuke 任务是 Docker 部署配套的清理机制，用于彻底移除指定命名空间下的 DataHub 容器与数据卷，典型场景包括清理测试环境、重置开发环境、隔离不同项目实例以及排障。

可用任务

每种 quickstart 配置都会自动获得对应的 Nuke 任务（均作用于默认项目命名空间datahub）：

• quickstartNuke/quickstartDebugNuke/quickstartDebugMinNuke/quickstartDebugConsumersNuke
• quickstartPgNuke（quickstart-postgres）/quickstartPgConsumersNuke/quickstartPgDebugNuke
• quickstartSlimNuke（backend 配置）/quickstartSparkNuke/quickstartStorageNuke/quickstartBackendDebugNuke

用法

./gradlew quickstartDebugNuke # 清理 debug 配置 ./gradlew quickstartDebugMinNuke # 清理 debug-min 配置 ./gradlew quickstartPgNuke # 清理 quickstart-postgres（slim） ./gradlew quickstartPgConsumersNuke # 清理 postgres + consumers（含 MAE/MCE） # 通用清理：停止所有配置的容器 ./gradlew quickstartDown

选择策略：需要定向清理某个具体配置环境（而不影响其他环境）时用对应 Nuke 任务；需要停止全部容器时用quickstartDown。

工作原理

从 docker/build.gradle 的源码可见，Nuke 任务的生成逻辑是遍历quickstart_configs为每个配置注册${taskName}Nuke任务，其行为要点是：

1. 数据卷管理：任务执行时动态设置removeVolumes = !config.preserveVolumes（quickstartStorage配置显式声明preserveVolumes: true，因此其 Nuke 任务保留数据卷）；
2. 容器清理：以finalizedBy挂接对应的ComposeDownForced操作强制移除容器；
3. 项目隔离：每个任务在其所属 Compose 项目命名空间内操作，命名空间默认来自环境变量COMPOSE_PROJECT_NAME（缺省datahub），也可通过配置中的additionalConfig.projectName覆盖；
4. 状态清理：任务还会删除build/下的 profile 状态文件，避免后续reload误判。

新增 Nuke 任务

Nuke 任务完全由quickstart_configs自动派生。要新增一个配置及其 Nuke 任务，只需在 docker/build.gradle 的quickstart_configs中添加条目，例如：

'quickstartCustom': [ profile: 'debug', modules: [...], // 可选：自定义项目名实现命名空间隔离 additionalConfig: [ projectName: 'dh-custom' ] ]

随后quickstartCustomNuke任务会被自动创建。

排障要点

• 任务找不到：确认配置存在于quickstart_configs，且任务名符合{configName}Nuke命名模式；
• 容器未被移除：核对项目命名空间是否正确、配置的projectName是否匹配，以及是否挂接了正确的ComposeDownForced操作；
• 数据卷残留：检查配置中preserveVolumes是否为true、removeVolumes设置是否生效。

生产环境注意事项

quickstart模式面向本地开发与快速体验，官方明确不建议用于生产，原因包括：内置默认凭据、服务默认绑定所有网卡地址、单机资源受限无法水平扩展、升级通常伴随停机、默认跟随最新构建（unstable）。生产部署请参考 docs/deploy/kubernetes.md 的 Kubernetes/Helm 方案，并严格遵守镜像 tag 规范（固定v*release tag 或sha-<short_sha>，禁止latest、debug与quickstarttag）。

【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub