DataHub Quickstart：用 datahub CLI 一条命令拉起本地 DataHub 全栈实例
【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub
本文基于 DataHub 仓库的官方快速入门文档 docs/quickstart.md，完整覆盖从安装 CLI、一条命令启动全栈 DataHub 环境、加载示例数据，到停止、重置、升级、备份与恢复实例的全流程操作，并结合 docker_cli.py 与 quickstart_version_mapping.yaml 等源码，讲清每个命令背后的实际行为。读完本文，你可以在本机 5～10 分钟内搭建出可交互的 DataHub 实例，并具备对本地实例进行版本管理、数据备份与索引重建的运维能力。
环境准备（Prerequisites）
quickstart 依赖 Docker 完成全部部署，本地环境需满足以下前提：
安装 Docker 与 Docker Compose v2（当前平台对应版本）：
平台 推荐应用 Windows Docker Desktop Mac Docker Desktop Linux Docker Engine + 独立安装的 Docker Compose v2 确保 Docker 引擎已启动（通过命令行或桌面应用）。
Python 3.10+已安装并配置到 PATH，可用
python3 --version检查。
CLI 侧对 Compose 版本有硬性校验：_docker_compose_v2() 会依次探测docker compose version与docker-compose version，若检测到的是 1.x 版本会抛出DockerComposeVersionError，提示必须升级到 Compose v2。
:::note Docker 资源分配
请为 Docker 引擎分配足够的硬件资源。仓库文档给出的已验证配置为：2 CPU、8GB 内存、2GB Swap、13GB 磁盘空间。
从 docker-compose.quickstart-profile.yml 的内存设置看，GMS 容器配置为-Xms1g -Xmx1g，Kafka 与前端各约 512MB，OpenSearch 约 1GB（OPENSEARCH_JAVA_OPTS: -Xms768m -Xmx1024m），上述资源配置与此相符。 :::
安装 DataHub CLI
DataHub CLI 提供了两条安装路径：
方式一：Homebrew
brew install datahub-project/tap/datahub datahub versionHomebrew 会为datahub维护一个隔离的 Python 环境，无需手动创建/激活 venv。该 formula 仅安装CLI 核心，如需使用元数据采集连接器，需额外安装到 brew 管理的环境中：
"$(brew --prefix datahub)/libexec/bin/pip" install 'acryl-datahub[snowflake,bigquery]'方式二：pip
python3 -m pip install --upgrade pip wheel setuptools python3 -m pip install --upgrade acryl-datahub datahub version:::note 提示command not found时
若安装后执行datahub报command not found，可尝试用python3 -m datahub version形式调用。注意 DataHub CLI 不支持 Python 2.x。 :::
启动 DataHub：datahub docker quickstart
在终端执行：
datahub docker quickstart该命令通过 docker-compose 部署一个完整的 DataHub 实例。如果你好奇，docker-compose.yml会被下载到用户主目录的~/.datahub/quickstart目录下。
命令背后发生了什么
从 docker_cli.py 的 quickstart 命令实现 可以还原出完整的执行链路：
- 拉取 compose 配置：默认从仓库中定义的
QUICKSTART_COMPOSE_FILE = "docker/quickstart/docker-compose.quickstart-profile.yml"（docker_cli.py#L51）对应的 GitHub 原始文件下载，写入本地~/.datahub/quickstart/docker-compose.yml（见 download_compose_files）； - 预检（preflight checks）：通过 Docker client 检查本机环境；
- 升级兼容性检查：_check_upgrade_and_show_instructions 会检测现有实例是否可用当前 CLI 直接升级，不兼容时打印迁移/修复指引并退出；
- 解析版本执行计划：依据
--version参数与版本映射文件生成执行计划（详见下节）； - 拉取镜像：
docker compose pull（可用--no-pull-images跳过）； - 循环启动与健康检查：执行
docker compose up -d --remove-orphans，每2 秒（_QUICKSTART_STATUS_CHECK_INTERVAL）检查一次容器健康状态，单次 up 超时 100 秒（_QUICKSTART_UP_TIMEOUT），最长等待15 分钟（_QUICKSTART_MAX_WAIT_TIME）；失败时可加--dump-logs-on-failure把 compose 日志直接打印到控制台。
一切顺利时，你会看到类似输出：
Fetching docker-compose file ... from GitHub Pulling docker images... Finished pulling docker images! Starting up DataHub... [+] Running 14/14 ✔ Network datahub_network Created ✔ Volume "datahub_broker" Created ✔ Volume "datahub_mysqldata" Created ✔ Volume "datahub_osdata" Created ✔ Container datahub-mysql-1 Healthy ✔ Container datahub-opensearch-1 Healthy ✔ Container datahub-kafka-broker-1 Healthy ✔ Container datahub-system-update-quickstart-1 Exited ✔ Container datahub-datahub-gms-quickstart-1 Healthy ✔ Container datahub-frontend-quickstart-1 Started ✔ Container datahub-datahub-actions-quickstart-1 Started ✔ DataHub is now running Load sample data: run `datahub init` then `datahub datapack load showcase-ecommerce`, or head to http://localhost:9002 (username: datahub, password: datahub) to play around with the frontend.容器栈里到底跑了什么
从 docker/quickstart/docker-compose.quickstart-profile.yml 可以确认，quickstart profile 启动以下服务（项目名固定为datahub，网络为datahub_network）：
| 服务 | 镜像 | 宿主机端口 | 说明 |
|---|---|---|---|
datahub-gms-quickstart | acryldata/datahub-gms:${DATAHUB_VERSION} | 8080（可用DATAHUB_MAPPED_GMS_PORT覆盖） | 元数据服务主后端（GMS），健康检查探活http://datahub-gms:8080/health |
frontend-quickstart | acryldata/datahub-frontend-react:${DATAHUB_VERSION} | 9002（DATAHUB_MAPPED_FRONTEND_PORT） | React 前端 UI |
kafka-broker | confluentinc/cp-kafka:8.2.2 | 9092 | KRaft 单节点 broker（已移除 Zookeeper 依赖），外部监听EXTERNAL://localhost:9092 |
mysql | mysql:8.2 | 3306 | 主存储数据库，库名datahub |
opensearch | opensearchproject/opensearch:2.19.3 | 9200 | 搜索/图索引存储（GMS 侧GRAPH_SERVICE_IMPL=elasticsearch兼容协议访问） |
system-update-quickstart | acryldata/datahub-upgrade:${DATAHUB_VERSION} | 无 | 一次性初始化任务（-u SystemUpdate），负责建库建索引、预建 Kafka topic 等，成功后才放行 GMS/前端启动 |
datahub-actions-quickstart | acryldata/datahub-actions:${DATAHUB_VERSION}-slim | 无 | 元数据 Actions 执行器，依赖 GMS 健康后启动 |
依赖顺序由 compose 的depends_on显式声明：存储三件套（Kafka、MySQL、OpenSearch）健康 →system-update成功退出 → GMS 健康 → Actions 启动；前端在system-update完成后启动。
数据持久化依赖三个命名卷：datahub_broker（Kafka 数据）、datahub_mysqldata（MySQL 数据）、datahub_osdata（OpenSearch 数据）。
版本选择：quickstart_version_mapping.yaml 的映射机制
--version参数不是简单透传镜像 tag，而是经过 QuickstartVersionMappingConfig 解析。映射配置来自仓库中的 docker/quickstart/quickstart_version_mapping.yaml（运行时从远端拉取并缓存到本地，网络不通时回退本地文件，再不通则用内置默认计划）。
当前仓库中的关键映射：
| 请求版本 | compose 文件来源（git ref） | 镜像 tag | 说明 |
|---|---|---|---|
不传--version（default） | master | v1.7.0.1 | 默认：master 分支的 compose + 已发布修复版镜像 |
head/quickstart | master | quickstart | 使用 master 的协同开发构建（compose 来自 master，镜像打quickstart浮标 tag） |
v1.7.0 | v1.7.0.1 | v1.7.0.1 | 小版本别名自动重映射到最新 patch |
v1.6.0 | v1.6.0.2 | v1.6.0.2 | 同上 |
stable | 查询 GitHub 最新 release | 最新 release tag | 映射文件中未显式定义stable时，CLI 会查询 GitHub releases API 动态解析 |
其他行为规则（来自映射文件头注与 quickstart_versioning.py 源码）：
- 未映射的版本号（如
v1.2.0这类发布 tag）会被当作 docker tag 与 compose git ref原样使用； - 四段式热修复 tag（如
v1.5.0.6）中，镜像用该四段 tag，而 compose 文件及其他非镜像设置回退到对应的三段短版本（v1.5.0）； - 传入无法识别的
--version（比如拼写错误）时，CLI 会提示确认后再回退到默认 quickstart 配置；省略--version则直接使用默认配置、不提示。脚本化场景可传--accept-version-default跳过交互提示； - 低于最低支持版本会直接报错退出（
is_minimum_supported_version校验）。
常用启动示例：
# 默认版本启动 datahub docker quickstart # 指定某个发布版本 datahub docker quickstart --version v1.6.0 # 指定特定 commit 构建（仅镜像仓库中存在，不是 git tag） datahub docker quickstart --version sha-<short_sha>（可选）固定签名密钥
DataHub 首次启动时会为认证 token 生成随机签名密钥与 salt，并在后续启动中复用，值保存在~/.datahub/quickstart/.local-secrets.env。多数用户无需改动。
从源码看，_resolve_token_service_secrets 采用三级优先级解析DATAHUB_TOKEN_SERVICE_SIGNING_KEY与DATAHUB_TOKEN_SERVICE_SALT：
- shell 环境变量（最高优先级，便于 CI/生产覆盖）；
~/.datahub/quickstart/.local-secrets.env中已持久化的生成值；- 均无则用
secrets.token_bytes(32)的 base64 随机值，并写入上述文件供下次复用。
若希望 token 在多个环境间保持稳定，请在首次运行datahub docker quickstart之前自行设定：
export DATAHUB_TOKEN_SERVICE_SIGNING_KEY=<value> export DATAHUB_TOKEN_SERVICE_SALT=<value>可用openssl rand -base64 32生成值。
从 v1.5 之前的旧版 CLI 升级注意：签名密钥由硬编码默认值改为随机生成，升级前创建的 PAT（个人访问令牌）会失效，需要重新生成。
登录与加载示例数据
登录（Sign In）
启动完成后，浏览器访问http://localhost:9002，使用默认凭据登录：
username: datahub password: datahub如需修改该默认凭据，参见 修改 quickstart 中的默认用户 datahub。
加载示例数据（Load Sample Data）
先配置 CLI 连接本地 DataHub 实例：
datahub init --username datahub --password datahub然后加载showcase-ecommerce数据包——一组横跨 Snowflake、Looker、PowerBI、Tableau 的约 1,050 个实体，包含血缘、治理、业务术语表（glossary）、域（domains）与数据产品（data products）：
datahub datapack load showcase-ecommerce:::note
datahub datapack命令目前仍属实验性质——其命令接口与行为可能在后续版本中变化。 :::
从 CLI 内置的数据包注册表 registry.json 可确认，showcase-ecommerce包描述为 “Rich e-commerce demo with 1049 entities across Snowflake, Looker, PowerBI, Tableau...”，体积约 2.7MB，最低要求服务端版本 0.14.0；另有默认bootstrap包（约 100KB 的演示数据集、仪表板、用户与标签）。
到此，你就可以在 UI 中自由体验 DataHub 了！
管理本地实例（Managing Your Local Instance）
以下命令仅适用于本地 quickstart 部署；生产运维请参见 docs/deploy/kubernetes.md。
datahub docker quickstart完整参数表
以下参数整理自 docker_cli.py 中 quickstart 命令的 click 选项定义：
| 参数 | 默认值 | 说明 |
|---|---|---|
--version | default | 要部署的 DataHub 版本；不指定时使用 quickstart compose 的默认值 |
--pull-images/--no-pull-images | True | 启动前是否从镜像仓库拉取容器镜像 |
-f/--quickstart-compose-file | 空（远端下载） | 使用本地 docker-compose 文件替代从 GitHub 拉取（可多次指定） |
--dump-logs-on-failure | False | 启动失败时把 compose 日志打印到控制台 |
--mysql-port | None（映射 3306） | 本机已有 MySQL 占用 3306 时，指定一个空闲端口避开冲突 |
--kafka-broker-port | None（映射 9092） | 本机已有 Kafka 占用 9092 时，指定空闲端口 |
--elastic-port | None（映射 9200） | 本机已有 Elasticsearch 占用 9200 时，指定空闲端口 |
--stop | False | 停止运行中的容器 |
--backup | False | 备份运行中的 quickstart 实例 |
--backup-file | ~/.datahub/quickstart/backup.sql | 备份 SQL 文件输出路径 |
--restore | False | 从备份恢复实例（配合--backup使用） |
--restore-file | ~/.datahub/quickstart/backup.sql | 指定自定义恢复文件 |
--restore-indices | False | 恢复索引；注意--restore默认会自动恢复索引，除非显式传--no-restore-indices |
--no-restore-indices | False | 与--restore联用，跳过索引重建 |
--arch | 自动检测 | 指定 quickstart 镜像架构（x86、arm64 等），默认自动识别 Apple Silicon |
--accept-version-default | False | 未识别的--version直接采用建议配置，不交互提示 |
停止 DataHub（Stop）
datahub docker quickstart --stop源码中 _attempt_stop 通过docker compose --profile quickstart -p datahub stop实现；若未显式指定 compose 文件，会回落到默认位置~/.datahub/quickstart/docker-compose.yml。
重置 DataHub（Reset / Nuke）
需要清除 DataHub 全部状态（例如在导入自有数据前）时，使用nuke命令：
datahub docker nuke从 nuke 命令实现 看，它会按 compose 项目过滤器（项目名datahub）依次移除所有容器（连带匿名卷）、数据卷（含旧版本遗留卷的过滤器）与网络；若加--keep-data则仅保留数据卷。
升级 DataHub（Upgrade）
如果本地一直在测试 DataHub、想体验新版本，直接再次执行 quickstart 命令即可——它会拉取更新的镜像并重启实例，且不丢失数据：
datahub docker quickstart默认安装最新发布版本；也可以显式指定版本：
datahub docker quickstart --version v1.6.0可用版本即仓库的 releases（见 quickstart_version_mapping.yaml 中已维护的映射）。另外可指定head或quickstart作为版本值，以获取来自master分支的最新协同开发镜像（compose 来自master，镜像 tag 为quickstart）。特定 commit 构建可用sha-<short_sha>（仅存在于镜像仓库，不是 git tag）。
自定义安装（Customize installation）
如需进一步定制，可下载 CLI 实际使用的 docker-compose 文件，按需修改后传入：
datahub docker quickstart --quickstart-compose-file <compose文件路径>该选项在源码中支持多次-f传入多个 compose 文件，并校验文件存在且可读。
备份 DataHub（Back up）
quickstart 镜像不建议作为生产实例使用。但如果你需要为当前 quickstart 状态做备份（例如公司演示前想留一份可日后恢复的数据副本），可加--backup标志：
datahub docker quickstart --backup默认在~/.datahub/quickstart/目录生成backup.sql文件。可用--backup-file自定义路径：
datahub docker quickstart --backup --backup-file <备份文件路径>从源码看，备份实现是 _backup 中对 MySQL 容器执行mysqldump -u root -pdatahub datahub并重定向输出，因此它本质是一份主数据库（MySQL）的全量 SQL 转储。
:::caution
Quickstart 备份不包含任何时序数据（数据集统计、数据画像等）。若你删除全部索引后仅用该备份恢复，这些信息将丢失。 :::
恢复 DataHub（Restore）
备份是可恢复的，共有三种恢复模式：
1. 通用恢复（General Restoring）
恢复主数据库与搜索索引：
datahub docker quickstart --restore该命令读取~/.datahub/quickstart下的backup.sql，恢复主数据库并连带重建索引。指定自定义备份文件：
datahub docker quickstart --restore --restore-file /home/my_user/datahub_backups/quickstart_backup_2002_22_01.sql源码层面（_restore），恢复分两步：先把 SQL 文件通过docker exec -i管道进 MySQL 容器执行；再拉取acryldata/datahub-upgrade镜像、以-u RestoreIndices -a clean参数运行，从主存储全量重建搜索/图索引。执行前 CLI 会用click.confirm展示将要进行的操作并要求确认。
2. 仅恢复索引（Restore Only Index）
索引损坏或缺少部分更新时，可仅从主存储重新引导索引，不同步主库：
datahub docker quickstart --restore-indices3. 仅恢复主库（Restore Only Primary）
有时只想恢复 MySQL 主库状态而不重建索引，需显式禁用索引恢复：
datahub docker quickstart --restore --no-restore-indices参数组合有校验（valid_restore_options）：单独使用--no-restore-indices（不带--restore）是未定义用法，会报错退出；--restore与--restore-indices同时给出则提示前者已隐含后者并继续。
从旧版本 CLI 升级（Upgrading from an older CLI）
从 v1.2 之前的 CLI 升级：v1.2 起datahub docker quickstart使用的 docker-compose 文件与更早 CLI 安装的 DataHub不兼容。若你已用旧 CLI 装过 DataHub，请按以下步骤升级：
- 备份数据（推荐）：
datahub docker quickstart --backup（若无需保留数据可跳过）； - 移除旧安装：
datahub docker nuke； - 重新全新安装：
datahub docker quickstart。
⚠️ 不做备份将丢失全部已有数据。
跨版本的完整破坏性变更清单见 docs/how/updating-datahub.md。
CLI 中这一检查是自动执行的：docker_cli.py 内置了MIGRATION_REQUIRED_INSTRUCTIONS（可迁移路径：备份 → nuke → 重装 → restore）与REPAIR_REQUIRED_INSTRUCTIONS（不可修复的旧安装：回退 CLI 到 1.1 修复后再迁移，或放弃数据直接 nuke 重装）两套指引，启动前检测到不兼容实例时会自动打印。
为什么 Quickstart 不适合生产环境
官方文档明确：Quickstart 并非为生产环境设计，推荐生产部署采用 Kubernetes（配套 Helm Charts 可快速拉起，见 docs/deploy/kubernetes.md）。不建议用于生产的理由有三点：
- 默认凭据：quickstart 的 compose 配置中内置了 DataHub 自身及其底层存储（如 MySQL）的默认凭据，且部分组件开箱即无认证。这是为降低开发门槛的设计取舍，不是生产最佳实践。例如 compose 文件中
MYSQL_ROOT_PASSWORD: datahub、GMS 的METADATA_SERVICE_AUTH_ENABLED: 'false'均可在 docker-compose.quickstart-profile.yml 中直接看到。 - 端口全部暴露：DataHub 各服务与后端存储使用 Docker 默认行为绑定所有网络接口地址，便于开发调试，但不适合生产网络环境。
- 性能与运维能力受限：quickstart 受限于单机资源，无法水平扩展；新版本发布往往需要停机窗口；配置大体预置、难以灵活管理；且默认跟随最新构建，会强制更新到最新（含未发布的）构建。
下一步（Next Steps）
- Quickstart 故障排查指南
- 通过 UI 摄入元数据
- 通过 CLI 摄入元数据
- 向 DataHub 添加用户
- 配置 OIDC 认证
- 配置 JaaS 认证
- 配置 DataHub 后端的元数据服务认证
- 修改 quickstart 中的默认用户 datahub
- 重建搜索索引（restore-indices 相关文档）
【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
