DataHub Quickstart 故障排查完全指南从 CLI 启动失败到 Docker 容器异常的实战处理【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub本文围绕 DataHub 官方 Quickstart 调试指南 展开系统梳理datahub docker quickstart本地部署过程中最常见的故障场景CLI 命令找不到、端口冲突、Apple Silicon 镜像拉取失败、容器启动报错、后台服务异常等并结合当前仓库的 CLI 源码与 docker-compose 配置给出可验证的根因分析与修复步骤。读完本文你将能够独立诊断本地 DataHub 快速启动中的绝大多数问题并掌握datahub docker check、docker logs、kafkacat、curl等健康检查手段。DataHub 的 Quickstart 模式通过datahub docker quickstart命令一键拉起前端datahub-frontend、元数据服务datahub-gms、消息队列Kafka、搜索引擎Elasticsearch/OpenSearch与存储MySQL等十余个容器。由于涉及组件众多部署过程中容易踩坑。本指南正是为「Quickstart 没有顺利跑起来」的场景而写先看官方完整入门文档 Quickstart Guide再回到本文逐条排查。一、CLI 启动失败command not found: datahub在终端执行datahub相关命令时如果提示command not found通常有两个原因1. 系统默认了旧版本 PythonDataHub CLI 不支持 Python 2.x如果你的系统默认python指向的是旧版本CLI 安装的入口脚本可能没有被正确解析。此时最简单的方式是用python3 -m显式调用模块python3 -m datahub docker quickstart这等价于调用datahub可执行文件但绕开了 PATH 中可能存在的旧入口。CLI 内部通过 Click 注册了datahub命令组见 docker_cli.py 中的click.group()定义因此python3 -m datahub与datahub两种调用方式等价。2. PATH 中缺少 pip 的$HOME/.local/bin以 pip 方式安装的 CLI 默认把可执行脚本放入用户级 bin 目录。在 Linux 上可以把它加入~/.bashrcif [ -d $HOME/.local/bin ] ; then PATH$HOME/.local/bin:$PATH fi修改后重新打开终端或执行source ~/.bashrc再验证datahub version。安装 CLI 的完整步骤Homebrew / pip 两种方式见 Quickstart Guide 的 Install the DataHub CLI 章节。二、端口冲突默认端口被占用Quickstart 部署默认要求本机以下端口空闲端口用途对应服务3306MySQL元数据主存储9200Elasticsearch搜索与图索引9092Kafka broker元数据事件总线8081Schema RegistryAvro Schema 注册2181ZooKeeperKafka 协调9002DataHub Web 前端datahub-frontend8080DataHub 元数据服务datahub-gms通过 CLI 参数覆盖端口datahub docker quickstart提供端口覆盖参数例如把 MySQL 端口改为 53306datahub docker quickstart --mysql-port 53306从源码看这些参数最终会被映射为 compose 模板中的环境变量见 docker_cli.py 的_set_environment_variables--mysql-port→DATAHUB_MAPPED_MYSQL_PORT--kafka-broker-port→DATAHUB_MAPPED_KAFKA_BROKER_PORT--elastic-port→DATAHUB_MAPPED_ELASTIC_PORT这些变量在 docker-compose.quickstart-profile.yml 中通过${DATAHUB_MAPPED_GMS_PORT:-8080}、${DATAHUB_MAPPED_FRONTEND_PORT:-9002}这类「变量默认值」语法生效。元数据服务端口用环境变量覆盖与其他服务不同gms元数据服务的端口需要直接用环境变量指定DATAHUB_MAPPED_GMS_PORT58080 datahub docker quickstart查看完整参数列表datahub docker quickstart --help三、Apple Silicon 镜像拉取失败no matching manifest for linux/arm64/v8在 M1、M2 等 Apple Silicon Mac 上如果出现类似no matching manifest for linux/arm64/v8 in the manifest list entries的错误说明 CLI 没有正确识别你的机器架构导致拉取了错误的镜像平台。解决办法是显式指定架构datahub docker quickstart --arch m1从源码看CLI 定义了x86、arm64、m1、m2四种架构枚举见 docker_cli.py 的Architectures并通过is_apple_silicon()判断platform.uname().machine arm64且系统为 Darwin做自动检测--arch参数可强制覆盖检测结果detect_quickstart_arch。如果在非 Apple Silicon 机器上误传了--arch m1CLI 也会输出「Failed to match arch ...」告警并继续尝试。四、通用 Docker 问题清理残留状态容器残留、悬空卷等杂项 Docker 问题通常可以通过清理 Docker 状态解决docker system prune注意该命令会删除所有未使用的容器、网络、镜像包括悬空和未被引用的以及带-a或按提示确认后卷。执行前请确认没有需要保留的本地数据。五、如何确认 Quickstart 后所有容器正常运行1. 使用内置检查命令安装好 DataHub CLI 后参见 metadata-ingestion/README.md可直接运行datahub docker check该命令调用 docker_check.py 的check_docker_quickstart它按com.docker.compose.projectdatahub标签过滤出 Quickstart 项目下的容器逐一对容器状态分类为OK / DIED / MISSING / STARTING / UNHEALTHY / EXITED_WITH_FAILURE等并比对 compose 文件里声明的服务报告缺失容器。一切正常时输出✔ No issues detected。2. 列出所有容器docker container ls正常情况下应能看到类似下面的容器列表旧版示例仅供参考容器构成CONTAINER ID IMAGE ... NAMES 979830a342ce acryldata/datahub-mce-consumer:latest ... datahub-mce-consumer 3abfc72e205d acryldata/datahub-frontend-react:latest ... datahub-frontend 50b2308a8efd acryldata/datahub-mae-consumer:latest ... datahub-mae-consumer 4d6b03d77113 acryldata/datahub-gms:latest ... datahub-gms c267c287a235 landoop/schema-registry-ui:latest ... schema-registry-ui 4b38899cc29a confluentinc/cp-schema-registry:5.2.1 ... schema-registry 37c29781a263 confluentinc/cp-kafka:5.2.1 ... broker 15440d99a510 docker.elastic.co/kibana/kibana:5.6.8 ... kibana 943e60f9b4d0 neo4j:4.0.6 ... neo4j 6d79b6f02735 confluentinc/cp-zookeeper:5.2.1 ... zookeeper 491d9f2b2e9e docker.elastic.co/elasticsearch/...:5.6.8 ... elasticsearch注意当前仓库的 Quickstart 已迁移到 OpenSearch profiles 方案见 docker-compose.quickstart-profile.yml新版容器命名形如datahub-datahub-gms-quickstart-1、datahub-frontend-quickstart-1并包含system-update-quickstart初始化任务容器健康检查输出见 docs/quickstart.md。3. 查看单个容器日志docker logs container_name对于datahub-gms初始化完成时日志末尾应出现 Jetty 启动成功信息2020-02-06 09:20:54.870:INFO:oejs.Server:main: Started 18807ms对于datahub-frontend-react应看到 Play 框架的 HTTP 监听日志09:20:22 [main] INFO play.core.server.AkkaHttpServer - Listening for HTTP on /0.0.0.0:9002六、Elasticsearch 或 Broker 容器退出 / 卡死资源不足如果日志中持续出现类似下面的错误多半是 Docker 分配的硬件资源不够datahub-gms | 2020/04/03 14:34:26 Problem with request: Get http://elasticsearch:9200: dial tcp 172.19.0.5:9200: connect: connection refused. Sleeping 1s broker | [2020-04-03 14:34:42,398] INFO Client session timed out, have not heard from server in 6874ms ... schema-registry | [2020-04-03 14:34:48,518] WARN Client session timed out, have not heard from server in 20459ms ...解决办法给 Docker 至少分配 8GB 内存 2GB swap。官方 Quickstart 文档给出的测试配置为 2 CPU、8GB RAM、2GB Swap 与 13GB 磁盘空间见 docs/quickstart.md 的 Prerequisites 章节。更有力的证据来自源码CLI 在启动前会执行预检run_quickstart_preflight_checks其中MIN_MEMORY_NEEDED 4.3GB、MIN_DISK_SPACE_NEEDED 13GB见 docker_check.py。内存低于阈值会直接抛出DockerLowMemoryError磁盘低于阈值会抛出DockerLowDiskSpaceError提示你到 Docker 设置里扩容或清理磁盘空间。也就是说资源不足时 CLI 会在启动之前就拦截避免容器起来后连环超时。七、如何检查 Kafka 上的 MXE 主题是否已创建DataHub 的元数据事件MXEMetadata eXchange Events通过 Kafka 传递概念详见 docs/what/mxe.md。可以用kafkacat列出 broker 上的所有主题kafkacat -L -b localhost:9092确认除默认主题外以下主题已存在MetadataChangeEventMetadataAuditEventMetadataChangeProposal_v1MetadataChangeLog_v1八、如何检查 Elasticsearch 中的搜索索引是否创建执行curl http://localhost:9200/_cat/indices确认datasetindex_v2与corpuserindex_v2等索引已存在。典型响应节选yellow open dataset_datasetprofileaspect_v1 HnfYZgyvS9uPebEQDjA1jg 1 1 0 0 208b 208b yellow open datajobindex_v2 A561PfNsSFmSg1SiR0Y0qQ 1 1 2 9 34.1kb 34.1kb yellow open mlmodelindex_v2 WRJpdj2zT4ePLSAuEvFlyQ 1 1 1 12 24.2kb 24.2kb yellow open dataflowindex_v2 FusYIc1VQE-5NaF12uS8dA 1 1 1 3 23.3kb 23.3kb yellow open corpuserindex_v2 gbNXtnIJTzqh3vHSZS0Fwg 1 1 2 2 18.4kb 18.4kb yellow open datasetindex_v2 bWE3mN7IRy2Uj0QzeCt1KQ 1 1 7 47 93.7kb 93.7kb yellow open dataplatformindex_v2 GihumZfvRo27vt9yRpoE_w 1 1 0 0 208b 208b ...索引命名遵循entityindex_v2的规律不同的实体dataset、datajob、corpuser、chart、dashboard、tag、glossary 等各有独立索引此外还有graph_service_v1、system_metadata_service_v1等系统索引。索引由datahub-gms启动时的索引构建流程自动创建若缺失可参考 docs/how/restore-indices.md 重新索引。九、如何确认 MySQL 中的数据已正确加载MySQL 容器启动后可以直接在localhost:3306用 MySQL Workbench 等工具连接也可以进入容器调用 MySQL 命令行客户端docker exec -it mysql /usr/bin/mysql datahub --userdatahub --passworddatahub重点检查metadata_aspect_v2表它保存了所有实体的已摄取 aspect 数据。metadata_aspect_v2的实体类为EbeanAspectV2对应源码位于 metadata-io 的 Ebean 存储实现中。十、容器启动报错常见错误分类与处理容器初始化失败的原因五花八门以下是最高频的几类1.bind: address already in use端口被本机其他进程占用。需要先找到并结束占用进程或为容器更换端口。示例macOS ERROR: for mysql Cannot start service mysql: driver failed programming external connectivity on endpoint mysql (...): Error starting userland proxy: listen tcp 0.0.0.0:3306: bind: address already in use 1) sudo lsof -i :3306 2) kill -15 PID found in step1如果不想杀进程更优雅的方案是改端口优先用datahub docker quickstart --mysql-port 新端口等 CLI 参数见本文第二节若使用自定义 compose 文件部署则需修改对应服务的ports配置后重新部署。2.OCI runtime create failed出现如下错误时通常意味着本地镜像与当前仓库代码不匹配请先把本地仓库 git 更新到最新提交ERROR: for datahub-mae-consumer Cannot start service datahub-mae-consumer: OCI runtime create failed: container_linux.go:349: starting container process caused exec: \bash\: executable file not found in $PATH: unknown3.failed to register layer: devmapper: Unknown device磁盘空间不足导致镜像层写入失败请清理磁盘可参考docker system prune见第四节。4.ERROR: for kafka-rest-proxy Get https://registry-1.docker.io/v2/...: EOF这是 Docker Registry 的瞬时网络问题稍后重试即可。十一、Docker Hub 限流toomanyrequests: too many failed login attempts如果拉取镜像时提示登录失败次数过多可以清除 Docker 的登录凭据缓存后重新登录rm ~/.docker/config.json docker login注意rm命令会删除本机保存的所有 Docker Hub 登录凭据执行后需要重新docker login。十二、登录时报Table datahub.metadata_aspect doesnt exist这说明 Quickstart 过程中数据库没有被正确初始化。可以手动执行初始化 SQL该命令会读取 Quickstart 使用的 MySQL 初始化脚本并导入docker exec -i mysql sh -c exec mysql datahub -udatahub -pdatahub docker/mysql/init.sql命令中的docker/mysql/init.sql指向 Quickstart 部署目录~/.datahub/quickstart/下随 compose 一起使用的初始化脚本路径。若该文件不存在可换用 docker/mysql 相关部署配置 中的初始化方式或直接通过datahub docker nukedatahub docker quickstart重建一个干净的实例。十三、彻底重来清空整个 Quickstart 环境如果本地 Docker 环境已经被折腾乱可以一键移除 Quickstart 创建的所有容器、网络与卷datahub docker nuke从源码看docker_cli.py 的nuke该命令会删除datahubcompose 项目下的全部容器container.remove(vTrue, forceTrue)、数据卷包括datahub_neo4jdata、datahub_mysqldata、datahub_esdata等历史卷见 docker_check.py 的卷过滤列表以及项目网络。注意数据会全部丢失。需要保留数据时请先执行datahub docker quickstart --backup备份逻辑为对 MySQL 执行mysqldump见 docker_cli.py 的_backup。提示从 CLI v1.2 开始docker-compose文件与旧版不兼容升级前必须执行datahub docker quickstart --backup→datahub docker nuke→datahub docker quickstart→可选datahub docker quickstart --restore的迁移流程完整说明见 docs/quickstart.md 的 Managing Your Local Instance 章节。十四、GMS 抛Duplicate key EbeanAspectV2异常字符集排序规则问题datahub-gms容器日志中出现类似Caused by: java.lang.IllegalStateException: Duplicate key com.linkedin.metadata.entity.ebean.EbeanAspectV2dd26e011时通常是 SQL 列的 collation排序规则问题2021 年 10 月 26 日之前的部署URN 字段默认使用大小写不敏感的utf8mb4_unicode_ci此后默认切换为大小写敏感的utf8mb4_bin。如果是从 v0.8.16 及以下版本升级上来的老部署需要直接对数据库执行ALTER TABLE metadata_aspect_v2 CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;这会把metadata_aspect_v2表的字符集与排序规则统一为大小写敏感的utf8mb4_bin与新版部署保持一致。十五、修改了user.props但 UI 里看不到新用户user.props仅被 JAAS 的PropertyFileLoginModule用于认证校验密码并不会自动向 DataHub 摄取用户的元数据。要让新用户出现在 Users Groups 页面需要额外通过 Rest.li API 或 Metadata File 摄取源 摄取用户信息。参考 single_mce.json该示例向 DataHub 摄取单个用户对象注意其中urn字段必须与user.props中的用户名对齐。例如user.props中包含my-custom-user:my-custom-password则需要摄取的 MCE 大致如下{ auditHeader: null, proposedSnapshot: { com.linkedin.pegasus2avro.metadata.snapshot.CorpUserSnapshot: { urn: urn:li:corpuser:my-custom-user, aspects: [ { com.linkedin.pegasus2avro.identity.CorpUserInfo: { active: true, displayName: { string: The name of the custom user }, email: my-custom-user-emailexample.io, title: { string: Engineer }, managerUrn: null, departmentId: null, departmentName: null, firstName: null, lastName: null, fullName: { string: My Custom User }, countryCode: null } } ] } }, proposedDelta: null }摄取完成后新用户即可在 UI 的 Users Groups 中看到。十六、OIDC 登录后持续重定向Cookie 过大配置了 OIDC 却无法登录、页面被不断重定向常见根因是 DataHub 用于认证的 Cookie 过大超过 4096 字节。Cookie 内嵌了 OIDC Identity Provider 返回信息的编码版本IdP 返回信息越多Cookie 越大最终突破浏览器限制导致重定向循环。解决方案改用 Play Cache 保存会话。将用户属性与会话信息从浏览器端 Cookie 迁移到datahub-frontend服务的进程内缓存中为前端容器设置环境变量PAC4J_SESSIONSTORE_PROVIDERPlayCacheSessionStore注意权衡Play Cache 会让datahub-frontend变成有状态服务。如果部署了多个前端实例必须保证同一用户被确定性地路由到同一个容器会话存储在内存中单实例部署默认情况则无需额外处理。十七、附Quickstart 健康检查命令速查表检查项命令预期结果整体健康datahub docker check✔ No issues detected容器列表docker container ls所有服务容器Up/Healthy单容器日志docker logs container_namegms 出现Started ...ms前端出现Listening for HTTP on /0.0.0.0:9002Kafka 主题kafkacat -L -b localhost:9092存在 4 个 MXE 主题ES 索引curl http://localhost:9200/_cat/indices存在datasetindex_v2、corpuserindex_v2等MySQL 数据docker exec -it mysql /usr/bin/mysql datahub --userdatahub --passworddatahubmetadata_aspect_v2有数据如果上述排查均无法解决请先保存docker compose logs输出CLI 失败时也会自动把日志写到临时文件并提示路径再向项目提交 issue 或寻求社区支持。需要了解 Quickstart 之外的备份恢复--backup/--restore/--restore-indices与生产部署建议请继续阅读 docs/quickstart.md 与 docs/troubleshooting/general.md。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考