DataHub Docker 部署：3 条命令跑起来，踩坑全在这

DataHub Docker 部署：3 条命令跑起来，踩坑全在这

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

上周有人装 DataHub 卡住了：clone 仓库花了 40 分钟，又手改 docker-compose 改了半小时，最后容器一直重启，日志只冒一行。DataHub 是数据栈的元数据目录平台，负责收集中台各数据平台的表、血缘和负责人信息。他卡住的原因其实很简单——MySQL 还在后台初始化，后端服务却在等数据库就绪。用官方 CLI 就能绕开这一切，这篇文章带你 3 条命令跑起来，再讲清楚组件、端口配置和踩坑解法。

先跑起来：3 条命令启动 DataHub

前提只有一个：装好 Docker 并启动，给 Docker 至少分配 2 核 CPU、8GB 内存。因为 quickstart 会一次拉起十几个容器，内存给少了 Java 服务会直接崩。

第一条命令安装 CLI（只做一次），顺带确认版本：

python3 -m pip install --upgrade acryl-datahub datahub version

第二条是主角，一键部署 DataHub：

datahub docker quickstart

它干了 3 件事：把 compose 文件下载到~/.datahub/quickstart/、拉镜像、按依赖顺序起服务。首次运行要拉 7 个镜像并初始化数据库，需要几分钟，别中途打断。

✅ 终端出现DataHub is now running后，打开http://localhost:9002，用datahub/datahub登录就进界面了。

界面此时还比较空。这两条命令让 CLI 连上本地实例，并加载一份官方样例数据：

datahub init --username datahub --password datahub datahub datapack load showcase-ecommerce

样例数据包含 Snowflake 表、血缘、业务术语等约一千个实体，回到浏览器就能看到内容。

看懂你刚跑起来的东西

quickstart 档案主要拉起这几个服务：

服务	干什么的
mysql	主数据库，存实体元数据
opensearch	搜索索引，页面搜索靠它
kafka-broker	消息队列，承载元数据事件流
datahub-upgrade	一次性初始化容器：建表、建索引，跑完自动退出
datahub-gms + frontend	后端 API 服务 + Web 界面

启动顺序是严格的：mysql、opensearch、kafka-broker 全部变 healthy → datahub-upgrade 初始化容器跑完 → GMS 才起 → 前端最后。所以刚启动看不到页面，是 GMS 在等初始化容器（它又依赖数据库就绪），不是卡死了。

镜像统一是acryldata/datahub-*加quickstart标签，生产环境应固定到具体发布版本，详见官方 Docker 文档。

按需微调

改端口只要改一个变量

9002 或 8080 被占了？别动 compose 文件，启动前导出环境变量就行：

export DATAHUB_MAPPED_FRONTEND_PORT=8080 DATAHUB_MAPPED_GMS_PORT=8081

每个服务都有对应的DATAHUB_MAPPED_*_PORT变量，改完重新启动即可。

主存储换成 Postgres

默认是 MySQL + Kafka。如果你的团队全在用 Postgres，可以换 postgres 档案：主库换成 Postgres，Kafka 同时被 pgqueue 替换，少一个 broker：

docker compose -f docker/quickstart/docker-compose.quickstart-profile.yml --profile quickstart-postgres up -d

手动方式需要先把仓库 clone 到本地（仓库地址https://gitcode.com/GitHub_Trending/da/datahub），各档案组合都在docker/profiles/目录里。想要 Cassandra + Neo4j 也有quickstart-cassandra可选，按你的存储栈挑。

Apple 芯片适配

M1/M2 直接用最新版 Docker Desktop 即可，镜像本身已适配 arm64。偶尔报no matching manifest的话，在 Docker Desktop 设置里打开 Rosetta 翻译开关，重启引擎就行。

⚡ 日常三板斧

想暂停就用停止命令，数据留在卷里，下次启动很快：

datahub docker quickstart --stop datahub docker nuke

第二行是彻底清理：容器、卷、数据全删，换版本或环境搞乱了再用它。

查状态和日志：docker ps看哪个容器不 healthy，然后docker logs -f datahub-datahub-gms-quickstart-1跟日志，重点盯 GMS 和 mysql 两个容器。

🔧 踩坑速查

症状	一条命令定位	解法
GMS 容器反复重启	docker logs -f datahub-datahub-gms-quickstart-1	多半是内存不足或数据库没就绪：看 mysql 是否 healthy，给 Docker 加内存
9002 端口被占用	docker ps看容器是否已起	改DATAHUB_MAPPED_FRONTEND_PORT到空闲端口即可
启动一直卡在等待	docker ps找不 healthy 的容器	首次要拉镜像并初始化库，等 5-10 分钟；mysql 长时间 unhealthy 就重启 Docker

什么时候该换 Kubernetes

单机试用和小团队环境，Docker Compose 足够。出现这 3 个信号就该上 Kubernetes 了：需要多副本高可用、想用托管数据库和托管 Kafka、或者不能再接受数据只存在本地磁盘上。届时看Kubernetes 部署文档即可，记得镜像固定发布版本——quickstart 标签别带上生产。

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