在 CDH 6.3.x 上跑数据治理最初我图省事直接用 CDH 自带组件里的 Atlas结果发现版本和 Apache Atlas 2.0.0 差了挺远很多 REST API 和 UI 功能都跟不上做元数据血缘分析时明显吃力。后来折腾了两三天把 Apache Atlas 2.0.0 在 CDH 6.2.x/6.3.x 环境上编译并独立部署成功。这里说的“独立部署”就是标题里的 not-embedded 模式Atlas 作为独立 Java 进程启动元数据存到外部 HBase索引走外部 Solr通知走 Kafka而不是让 Atlas 自己拉起一套内嵌的 HBase/Solr。这篇文章就是把我的编译过程、部署参数、以及排查过的坑完整记录下来给同样在 CDH 环境里折腾 Atlas 的同学做个参考。1. 为什么 2.0.0 必须自己编译一份再上 CDH1.1 先搞清楚 embedded 和 not-embedded 这两条路Apache Atlas 的安装包默认支持两种部署形态。embedded 模式下Atlas 自己管理一套内嵌的 HBase 和 Solr看起来开箱即用但问题是它跟同一个节点上的其他组件容易抢资源而且内嵌组件不好监控也不适合多节点水平扩展基本只能拿来体验功能。not-embedded 模式则完全不同Atlas 不再启动任何内嵌存储服务它只是一个纯 Java 进程通过客户端连接外部已有的 HBase、Solr、Kafka 和 Zookeeper。生产环境或者真实 CDH 集群里我们肯定要选 not-embedded因为你已经有一整套经过 CDH 管理的组件服务没必要再搞一套私有的存储。数据表、索引分片、消息队列都放在集群公共组件里后面维护、监控、扩容都比较顺。CDH 环境下还有一个很容易混淆的点CDH 本身也可能带了一个 Atlas 服务那个通常是 CDH 针对内部组件集成做的裁剪版本和 Apache 官方源码构建的 2.0.0 并不完全等价。一个明显的差异是 CDH 自带版本不会主动跟随 Apache 社区的新接口和 bugfix所以当你需要更强的 Hook 能力或更新的 API 时自己编译一份 Apache Atlas 2.0.0 就成了最直接的办法。1.2 CDH 自带组件版本给编译提了哪些要求先说编译本身。Apache Atlas 2.0.0 是 2019 年左右发布的版本源码构建默认依赖 Apache 生态的一套版本组合比如 Hadoop 2.x、HBase 1.x、Solr 6.x 这类。但 CDH 6.2.x/6.3.x 内部有自己统一管理的组件版本HBase、Solr、Kafka、Zookeeper 都是 CDH 自己打过的分支。这就带来两个层面的问题编译期Atlas 源码里的 Maven 依赖坐标是 Apache 官方仓库的版本不一定能从默认仓库拉到 CDH 的私有构件。如果公司内网有统一的 Maven 私服需要先把 Apache 第三方依赖缓存好否则编译过程中会频繁卡在下载依赖这一步。运行期Atlas 进程启动后会通过 HBase client 连 CDH 的 HBase通过 SolrJ 连 CDH 的 Solr。如果 Atlas 自带的 hadoop/hbase 客户端 jar 和 CDH 集群的 RPC 协议不匹配就会出现连得上 Zookeeper 但连不上 HBase 服务或者启动到一半报 RPC 序列化异常。我自己是先在一台与 CDH 集群网络互通的独立节点上编译编译阶段不依赖 CDH 的 parcel运行阶段再让 Atlas 跟 CDH 组件做连接。这样把编译环境和运行环境隔开出问题时定位范围会小很多。1.3 我的选型结论独立进程加外部存储在动手之前我列了一个很简单的选型清单。部署方式存储位置适用场景我的结论embeddedAtlas 节点内嵌 HBase/Solr快速验证、Demo不采用资源开销大not-embedded外部 HBase/Solr/KafkaCDH 集群生产接入采用跟集群共用组件直接用 CDH 自带 AtlasCDH 托管不想折腾、功能要求低不采用版本不满足需求最终决定是在 CDH 6.3.x 集群旁边部署一台 Atlas 2.0.0 独立节点HBase 用 CDH 管理的已有 HBase 服务Solr 用 CDH 的 Solr CloudKafka 用 CDH 的 Kafka 服务三者都通过 Zookeeper 进行协调。这种做法就是标准的 not-embedded 接入方式后面所有配置也都是围绕这个前提来做的。2. 从零编译 Apache Atlas 2.0.0 的完整操作2.1 环境依赖清单JDK、Maven、Node.js、Python编译 Atlas 2.0.0 不是只装一个 Maven 就能跑前端 UI 部分也要一起构建。我用的编译节点环境如下JDK1.8.0_202一定要用 8不要用 11 或更高版本Atlas 2.0.0 的构建脚本没有充分适配高版本 JDK。Maven3.6.3理论上 3.5 以上都能用但 3.6.x 最稳。Node.jsv10.16.3Atlas 2.0.0 的 UI 模块依赖这个版本范围太高会报 node-sass 或 webpack 相关错误。Python2.7Atlas 构建脚本里有些工具类脚本依赖 Python 2虽然现在看老掉牙但当时版本就是这样的。环境变量要提前排好export JAVA_HOME/usr/local/jdk1.8.0_202 export PATH$JAVA_HOME/bin:$PATH export MAVEN_HOME/opt/apache-maven-3.6.3 export PATH$MAVEN_HOME/bin:$PATH export NODE_HOME/opt/node-v10.16.3 export PATH$NODE_HOME/bin:$PATH这些版本不是随便配的。Atlas 的构建过程中会执行 npm install并调用 node 来编译前端资源如果 node 版本太高npm 依赖安装阶段很容易卡死。我当时第一次用 Node 14 构建报了一堆 node-gyp 相关错误换成 v10 之后一次通过。2.2 修改 settings.xml 与源码解压源码包不建议用 Git 直接 clone因为 Apache 官方归档包里的子模块版本更固定我下载的是 apache-atlas-2.0.0-sources.tar.gz。解压后源码目录长这样tar -zxvf apache-atlas-2.0.0-sources.tar.gz cd apache-atlas-2.0.0 ls目录里有很多模块比如 atlas-docs、atlas-web、atlas-repository、atlas-notification 等最终构建出来的是一个可发布的 tar.gz 包。这里有一个非常关键的预处理修改 Maven 的 settings.xml把中央仓库和 Apache 快照仓库的请求都指向公司内部的私服。如果直接访问外网仓库几百个依赖下载会非常慢而且还可能遇到仓库 DNS 被限流的问题。我配置了一个 mirrormirror idcentral/id nameinternal mirror/name urlhttp://你的内网私服地址/repository/maven-public//url mirrorOf*/mirrorOf /mirror配好之后可以先执行一次简单的依赖解析确认私服能拉通mvn help:effective-settings -DskipTests这一步不是必须的但可以有效避免编译到一半才发现仓库不可用的情况。2.3 执行编译命令重点说明 -Pdist 与 RAT 检查编译命令我试了两种第一次直接用普通的 package结果发现打出来的包里缺少发布目录结构后来才意识到必须加-Pdistprofile这个选项会触发发布包组装逻辑生成带完整 conf、bin、libext 目录的安装包。合格命令如下mvn clean package -DskipTests -Pdist如果编译过程中报 license 或 header 相关错误也就是 Apache RAT 检查未通过可以直接跳过mvn clean package -DskipTests -Pdist -Drat.skiptrue我实际编译时确实遇到了 RAT 问题。原因是某些文件没有 Apache License 头严格检查就失败。对于内部编译来说这个检查其实不影响使用所以我直接加-Drat.skiptrue绕过去了。编译耗时取决于机器性能我在一个 8 核 16G 的节点上跑大概花了一个多小时。建议放到后台执行nohup mvn clean package -DskipTests -Pdist -Drat.skiptrue build.log 21 tail -f build.log有些同学会加-T 1C做并行编译但 Atlas 2.0.0 的模块依赖比较复杂并行度太高会偶尔出现模块间顺序问题我自己试过-T 4出现过一次 webapp 模块先于后端的 build 失败。稳妥起见单线程跑虽然慢但结果最可预期。2.4 编译产物校验与常见失败处理编译完成后发布包在 atlas-dist 模块下面ls -lh atlas-dist/target/apache-atlas-2.0.0-bin.tar.gz解压之后是一个完整安装目录mkdir -p /opt/atlas tar -zxvf atlas-dist/target/apache-atlas-2.0.0-bin.tar.gz -C /opt/atlas cd /opt/atlas/apache-atlas-2.0.0目录里至少有 conf、bin、libext、webui 这些关键结构。开始部署前我先核对了 bin 下是否有 atlas_start.py、atlas_stop.py以及 conf 下是否有 atlas-application.properties这些存在说明发布包组装完整。再分享一下编译期容易遇到的几个失败Node 模块安装失败检查 Node 版本切到 v10 系列。RAT 检查失败加-Drat.skiptrue。某个依赖在私服里没有用 mvn dependency:get 手动上传缺失构件或者去 Apache 仓库先把对应 jar 下下来装到私服。内存不足Maven 构建前端时比较吃内存至少给 Maven 分配 2G 以上堆内存设置 MAVEN_OPTSexport MAVEN_OPTS-Xms2048m -Xmx4096m这些失败大多数不是代码问题而是环境和仓库问题耐着性子看日志一般都能解决。3. 部署前必须完成的外围依赖配置3.1 HBase 的 namespace 与权限设置Atlas 2.0.0 使用 HBase 作为图数据库的存储后端它会把点、边、索引元数据都存在 HBase 表里。not-embedded 模式下Atlas 启动时会尝试连接 HBase 并自动建表因此在动手启动 Atlas 之前必须确认 HBase 服务正常而且 Atlas 进程使用的账号有建表的权限。我先用 HBase Shell 检查集群状态hbase shell status summary如果 HBase 有 Kerberos 认证还要确保 Atlas 节点上有合法的 principal 和 keytab。我的环境是非 Kerberos 的所以这一步相对简单。为了保险起见我先手工创建了一个 namespace避免 Atlas 自动创建时因为权限不足失败hbase shell create_namespace atlasAtlas 默认会在 HBase 中建一张 atlas 表这张表的数据模型由 JanusGraph 体系负责管理。如果你的集群之前用其他工具建过同名表最好先确认表结构是否兼容不兼容就把旧表删掉再启动。我遇到过一次 Atlas 启动后报 table already exists但表结构又不是 Atlas 想要的最后清理掉旧表才正常。另外CDH 的 HBase 在做写入时会依赖 HDFS 上的目录权限。如果 Atlas 以某个 Linux 用户启动而这个用户在 HDFS 上没有对应目录的写权限会在写入时抛 AccessControlException。最简单的处理方式是在 HDFS 上给 Atlas 运行用户授权或者直接使用一个有权限的专用账号来启动 Atlas 进程。3.2 Solr collection 初始化方法Solr 是整个 Atlas 部署里最容易出错的一环。Atlas 2.0.0 需要三个 Solr collectionvertex_index、edge_index、fulltext_index分别处理图顶点、边和全文检索。如果这三个 collection 不存在Atlas 进程虽然能起来但只要触发查询就会报索引找不到的错误。安装包里已经带了对应的 Solr 配置位于/opt/atlas/apache-atlas-2.0.0/conf/solr里面分别有 vertex_index、edge_index、fulltext_index 三个目录。CDH 的 Solr 是 SolrCloud 模式collection 和 configset 都注册在 Zookeeper 上。我的初始化方式是先上传 configset再创建 collection。用 CDH 的 solrctl 命令时上传 configsetsolrctl zk cp conf/solr/vertex_index/conf zk://zk1:2181/solr/configs/vertex_index solrctl zk cp conf/solr/edge_index/conf zk://zk1:2181/solr/configs/edge_index solrctl zk cp conf/solr/fulltext_index/conf zk://zk1:2181/solr/configs/fulltext_index然后创建 collectionsolrctl collection --create vertex_index -s 1 -r 1 solrctl collection --create edge_index -s 1 -r 1 solrctl collection --create fulltext_index -s 1 -r 1参数-s是分片数-r是副本数。如果只是测试环境1 个分片 1 个副本完全够用。生产环境可以根据数据量调大 edge_index 的分片数因为边数据往往是点数据的几倍。如果你的 CDH 环境里 solrctl 不可用也可以直接用 Solr 的 HTTP API。先确认 configset 已上传到 Zookeeper然后调用 Collections API 创建。核心思路一样把 Atlas 自带的 schema 和 solrconfig 传上去再建 collection。还有一个细节Zookeeper 上 Solr 的 chroot 路径要跟 atlas-application.properties 里的配置一致否则 Atlas 找不到 collection。CDH 默认默认 chroot 是/solr所以配置里写zk1:2181/solr,zk2:2181/solr是对的。3.3 Kafka 与 Zookeeper 必要检查Atlas 的 Hook 通知和实体变更事件都通过 Kafka 消息传递。not-embedded 模式下Atlas 不内嵌 Kafka而是作为一个生产者消费者连接外部 Kafka。需要确认两件事Kafka 服务可连以及 topic 是否允许自动创建。Atlas 2.0.0 主要使用两个 topic一个是 ATLAS_ENTITY_NOTIFICATION一个是 ATLAS_HOOK。CDH 的 Kafka 默认允许自动创建 topic但如果集群关闭了自动创建就需要手工创建kafka-topics.sh --create \ --zookeeper zk1:2181 \ --replication-factor 1 \ --partitions 3 \ --topic ATLAS_ENTITY_NOTIFICATION kafka-topics.sh --create \ --zookeeper zk1:2181 \ --replication-factor 1 \ --partitions 3 \ --topic ATLAS_HOOK分区数可以根据业务量调大。在 CDH 环境里Kafka 的 bootstrap.servers 地址通常配置为 broker 主机名加 9092 端口Atlas 所在节点必须能解析这些主机名。我遇到过一个非常隐蔽的问题是 Atlas 节点和 Kafka broker 之间的主机名解析不一致导致连接超时最后在 /etc/hosts 里手动补了 broker 映射才解决。Zookeeper 方面HBase、Solr 和 Kafka 都在用 ZKAtlas 自己也要连 ZK。这里不需要给 Atlas 单独搭 ZK直接用 CDH 管理的 ZK 集群即可。需要核对的是 Atlas 配置里的 ZK 地址和 CDH 集群实际使用的 ZK 地址一致如果 CDH 的 ZK 是 2181 端口就不要写成 2188。端口错误是最低级的坑但我在第一次部署时确实栽在这上面。4. atlas-application.properties 里真正决定成败的配置项4.1 从 embedded 切到 not-embedded 的几个开关Atlas 默认配置其实是 embedded 模式第一次部署时如果不改配置直接启动Atlas 会在本地拉起一套内嵌 HBase 和 Solr这样既慢又容易出问题。not-embedded 模式需要显式关闭内嵌服务并指定外部组件地址。我的 atlas-application.properties 核心配置如下# 关闭内嵌模式 atlas.server.embeddedfalse # 图数据存储到外部 HBase atlas.graph.storage.backendhbase atlas.graph.storage.hostnamezk1:2181,zk2:2181,zk3:2181 atlas.graph.storage.hbase.tableatlas # 索引存储到外部 SolrCloud atlas.graph.index.search.backendsolr atlas.graph.index.search.solr.modecloud atlas.graph.index.search.solr.zookeeper-urlzk1:2181/solr,zk2:2181/solr,zk3:2181/solr atlas.graph.index.search.solr.wait-searcherfalse # 通知消息走外部 Kafka atlas.notification.embeddedfalse atlas.kafka.zookeeper.connectzk1:2181,zk2:2181,zk3:2181 atlas.kafka.bootstrap.serversbroker1:9092,broker2:9092,broker3:9092 # REST 服务地址 atlas.rest.addresshttp://atlas-host:21000atlas.server.embeddedfalse是整个配置里最重要的开关。如果这里还保持 true即使后面写了外部 HBase 地址Atlas 也会优先走内嵌逻辑。atlas.graph.storage.hostname填的是 HBase 对应的 Zookeeper 地址不是 HBase Master 所在地址。很多人第一次配的时候容易把 HBase Master 的 RPC 地址填进来结果 Atlas 一直连不上。这个参数底层是 JanusGraph 的 HBase 后端配置JanusGraph 通过 ZK 来发现 HBase RegionServer。关于 Solr 的wait-searcher参数我建议调试阶段设成 false这样 Atlas 启动时不会因为等待所有 Solr collection 变为 ready 状态而卡住。等确认所有 collection 都正常了再按需改成 true。4.2 与 CDH 网络环境相关的参数CDH 集群内部节点往往配置了多网卡或者多 IP服务监听地址可能和内网业务地址不一致。Atlas 节点作为客户端时必须确保跟 CDH 组件之间能通过主机名正常通信推荐的做法是直接在 Atlas 节点的 /etc/hosts 里写上 CDH 各组件的 IP 和主机名映射。另外Atlas 的 REST 地址要配成 Atlas 节点自身的对外地址atlas.rest.addresshttp://atlas-host:21000如果这里配成了 localhostUI 登录后会出现在浏览器里能打开页面但 Atlas 进程内部回调 API 时却访问不到自己的情况典型表现是 UI 加载正常但搜索功能一直转圈报错。因为前端和后端之间的所有 AJAX 请求都是基于这个 REST 地址发起的。还要设置 Atlas 的直接内存和堆内存。Atlas 需要加载不少图数据和校验逻辑给太少会出现查询时 OOM。我建议在conf/atlas-env.sh中设置export ATLAS_SERVER_HEAP-Xms4096m -Xmx8192m export ATLAS_SERVER_OPTS-XX:HeapDumpOnOutOfMemoryError -XX:HeapDumpPath/var/log/atlas/dump内存要根据节点资源来定至少给 4G 以上。Atlas 默认配置有时候只有 1G处理真实数据时完全不够。4.3 启动失败时先看这几个报错规律我附带总结一下启动过程中的典型报错。Atlas 启动不像普通 Spring Boot 应用那么快它会经历 HBase 表检查、Solr collection 检查、Kafka topic 检查、图数据库初始化等多个阶段整个过程可能持续好几分钟。配置有任何一个环节不通日志里都会暴露线索。常见的三类报错和排查方向HBase 相关报PermissionDeniedException或RegionServer is not online优先检查 Atlas 节点到 ZK 的连通性以及启动账号在 HBase/HDFS 的权限。Solr 相关报Collection not found或No registered leader说明 collection 确实没建好或者 chroot 路径写错了。Kafka 相关报Connection refused通常是 bootstrap.servers 里的 broker 地址解析不了。日志位置在logs/application.log启动过程中如果长时间卡在某一步直接去看日志尾部线索非常明确。我一般习惯把日志界面和配置界面分开改一处配置就重启一次然后观察日志变化比一次改完全部配置再启动更容易定位问题。5. 启动、验证与日常排障记录5.1 第一次启动时的顺序和确认点所有外围组件就绪后启动 Atlas 之前再按顺序检查一遍# 检查 ZK echo ruok | nc zk1 2181 # 检查 HBase hbase shell -e list_namespace # 检查 Solr collection curl -s http://solr1:8983/solr/admin/collections?actionLIST | grep -E vertex_index|edge_index|fulltext_index # 检查 Kafka topic kafka-topics.sh --list --zookeeper zk1:2181确认没问题再启动 Atlasexport JAVA_HOME/usr/local/jdk1.8.0_202 export ATLAS_HOME/opt/atlas/apache-atlas-2.0.0 cd $ATLAS_HOME bin/atlas_start.py启动命令需要以 root 或专门的 atlas 用户执行。之前我用普通用户启动结果部分脚本在写日志目录时没有权限进程起来又立刻退掉报错还不太明显。为了避免这种问题可以把整个 atlas 目录 chown 给启动用户chown -R atlas:atlas /opt/atlas/apache-atlas-2.0.0启动后等待几分钟看日志输出是否出现启动完成的标志。Atlas 的 application.log 里如果出现类似AtlasServerApplication已启动的信息基本就成功了。随后用浏览器访问 Atlas UIhttp://atlas-host:21000如果不能访问先确认 21000 端口是否已经有 Java 进程监听ss -ltnp | grep 210005.2 UI 验证与元数据导入检查UI 能打开还不代表所有功能正常。我习惯先做几个基础动作验证登录后进入 Search 页面尝试搜一个不存在的类型看看是全报错还是返回空结果。打开 Administrator 页面确认 Atlas 能识别配置的 Kafka topic。用命令行工具导入一份模拟元数据模型验证实体创建、血缘关系写入是否成功。Atlas 2.0.0 自带了一个命令行工具bin/atlas_import.py -f /tmp/sample_model.json导入完成后到 UI 里查询对应实体如果能看到数据再简单创建一个 lineage 数据测试血缘关系。这样一套下来基本能确认存储、索引、消息链路都通了。我比较推荐在实际接入 CDH 的 Hive、HDFS 元数据之前先用模拟数据跑一遍完整链路因为 Atlas 真正麻烦的是 Hook 接入如果基础存储链路都不通后面排查 Hook 问题时会非常痛苦。5.3 我记录的三个高频问题第一个高频问题是atlas.graph.storage.hostname配成了 HBase Master 地址而不是 ZK 地址。这个问题在日志里的表现是 Atlas 反复重试连接最后超时。后来我在配置注释里看到“hostname”其实要填 HBase 的 ZooKeeper 地址才意识到被字面意思误导了。第二个是 Solr 的 chroot 路径不一致。CDH 的 Solr 在 ZK 上默认带/solr路径但 Atlas 配置里如果写zk1:2181没有带/solrAtlas 会在根路径下面找 collection自然找不到。这个问题报错不是特别明显有时候要开着 debug 日志才看得到 collection 查找路径。我把 zookeeper-url 改成带/solr之后问题立刻消失。第三个是 Atlas 启动后自动创建 HBase 表失败。排查下来是 HBase 的 namespace 权限问题。我当时直接手工创建了 namespace又在 HDFS 上确认了 atlas 用户的目录权限重启之后才正常。这个坑在 CDH 环境尤其常见因为 CDH 的 HBase 默认不是全开放权限。6. 一点收尾经验版本替换和后续维护如果你在 CDH 6.3.x 上用的 HBase、Solr 版本和 Atlas 2.0.0 默认客户端版本差异较大运行一段时间后可能会遇到底层客户端序列化或 RPC 方法签名不一致的报错。这个时候不要急着把 Atlas 自带的 jar 全部替换成 CDH 的 jar那会让依赖关系变得非常复杂。我自己的做法是先在libext目录下把 CDH 的 hbase-client、hbase-common、solr-solrj 等几个关键 jar 放进去让它们排前加载然后逐个测试。如果换了之后启动报别的类找不到再用jar tf去比对具体类是否存在只有确认是同一个类的冲突才做替换。Atlas 部署完成之后日常维护还有两件事比较重要。一件是定期看logs/application.log里的 ZooKeeper 连接失联和 Solr 超时记录避免集群网络抖动导致 Atlas 索引状态异常。另一件是给 Atlas 进程加监控因为它是独立 Java 进程很容易被基础设施监控遗漏。我在某次机房网络调整后确认过 Atlas 进程虽在但连接已经断开UI 打开超时的现象这类问题需要靠端口连通性检查和进程状态检查结合起来才能第一时间发现。后面如果要接入 CDH 的 Hive还需要在 Hive 服务里配置 Atlas Hook并确保 Kafka 的 topic 能正常接收事件这一步和这里的部署是前后依赖的关系。先把 Atlas 的基础存储链路弄稳后面的 Hook 接入才有意义。希望这份记录能帮你少走几天弯路。