简介apache-atlas-2.3.0-bin.tar.gz 是 Apache Atlas 2.3.0 的官方二进制发行包面向 Hadoop 生态下的大数据治理场景适合数据平台工程师、数据治理架构师及运维人员使用旨在解决元数据分散、血缘关系难以追踪、合规审计困难等核心问题为数据资产提供统一管理入口并减少信息孤岛。压缩包为 gz 格式目录内共 199 个文件其中 jar 运行组件约 100 个json 配置与元数据定义约 59 个python 辅助脚本、xml 配置、properties 配置、shell 脚本及 1 个 war 包等构成其余部分整体大小约 486.99MBjar 包构成 Atlas 核心服务及与 Hive、HDFS、Kafka 等的集成模块json 用于业务分类和实体定义python 脚本便于数据源接入与自动化处理war 包用于 Web 控制台部署。基于该发行包可快速搭建数据分类、血缘追踪、操作审计和安全管理的统一元数据治理平台利用规范与取证模型、丰富的沿袭能力提供 Hadoop 数据资产全景可见性同时结合 Apache Ranger 实现基于角色与属性的细粒度访问控制防止非授权访问并通过通用元数据存储降低组件间的互操作门槛使各类工具无需定制接口即可共享元数据且提供技术审计与操作审计的双重保障。包内已内置 hive-exec、hadoop-hdfs-client、kafka 客户端等常见依赖并包含许可声明与说明文档能够显著降低部署和二次开发中的环境配置成本适合测试环境验证、生产基线搭建或作为二次开发起点。目前已有 360 人学习或下载适合正在规划数据治理体系的团队作为初始版本调研也有助于快速评估 Atlas 的核心功能与周边集成方式。1. apache-atlas-2.3.0-bin.tar.gz 是什么一个能让你看清全链路血缘的元数据服务拿到 apache-atlas-2.3.0-bin.tar.gz 这个安装包你其实拿到的是 Hadoop 生态里最容易被低估的一环——元数据治理与血缘追踪。很多团队数仓跑了大半年业务问“这张报表到底从哪张源表来的”没人答得上来就是因为缺了统一的数据字典和血缘关系。Atlas 干的就是这件事把 Hive、HBase、Kafka 这些组件里的表和主题注册成元数据模型再把它们之间的加工关系记录成血缘图。这篇笔记就围绕这个二进制包从解压、起服务、验证 API 到踩坑排错完整过一遍让新手能照着重现熟手能直接对参数。如果你正准备给现有平台补一套元数据中心先别急着写代码把 Atlas 2.3.0 跑起来再决定怎么接。2. 解压与选型先搞清楚依赖栈再动手别再白白跑五遍安装2.1 为什么 Atlas 2.3.0 把 HBase、Solr、Kafka 焊死在三件套上Atlas 2.3.0 在架构上把元数据拆成三种不同诉求来存储实体属性要支持高频读写和事务能力全文索引要扛住模糊搜索和关联查询事件通道要承接组件侧 Hook 推送的异步打点。对应下来的默认组合就是 HBase 存实体、Solr 存索引、Kafka 传事件。这个组合不是拍脑袋定的而是要跟 Atlas 自带的存储适配器对上号底层图存储用的 Atlas graph 持久化层在 HBase 上有现成实现索引模型只对 Solr 的 schema 做了完整封装。选型时最容易踩的第一个坑是版本错配。我在搭验证环境时一般直接用这套组合JDK 1.8、HBase 2.2.x、Solr 7.7.x、Kafka 2.x。JDK 11 也能启动但 Atlas 2.3.0 的 class 文件按 Java 8 编译没必要给自己添乱。HBase 1.4 更省内存适合笔记本单机验证但如果后续要接生产建议直接上 2.2避免小版本升级时存储适配器行为变化。Solr 8.x 能用但官方 schema 是按 7.x 维护的能用 7.7 就尽量锁版本。组件常见选型选型理由JDK1.8推荐与 2.3.0 编译目标一致GC 参数好控制HBase2.2.x 或 1.4.x2.2 接近生产默认1.4 适合低配机器Solr7.7.xAtlas 自带 conf/solr 的 schema 按 7.x 维护Kafka2.xHook 事件推送和通知消费的默认通道有人会问能不能用 Elasticsearch 替换 SolrAtlas 2.3.0 的配置里确实保留了 ES 选项但社区和我实际见过的生产案例里Solr 是绝对主流ES 方案在版本适配和字段映射上总有零碎问题。除非你团队已经有强运维能力的 ES 集群否则别在验证阶段引入第二个变量。这里还要提醒一句Atlas 启动时对 Solr 的要求是必须运行在 cloud 模式单机 Solr 模式会直接拒绝建索引后面第三章会专门讲怎么启动。2.2 解压、改环境变量、确认目录结构三分钟拿到可配置根目录先把安装包放到固定目录再解压不建议解压到 /tmp因为 Atlas 的日志和数据会写在安装目录附近重启机器后就没了。我习惯统一放 /opttar -zxvf apache-atlas-2.3.0-bin.tar.gz -C /opt cd /opt/apache-atlas-2.3.0 export JAVA_HOME/usr/local/jdk1.8.0_202 export PATH$JAVA_HOME/bin:$PATH java -version解压这步的逻辑很简单tar 的 -C 参数指定落盘目录export 是临时会话变量只对当前 shell 生效。如果你后面要用 atlas_start.py 启动脚本建议把 JAVA_HOME 写进 /etc/profile 或 conf/atlas-env.sh否则新开的 SSH 会话里 Java 环境会丢。java -version 输出 1.8 开头的版本号才说明环境对齐了。解压之后你会看到 bin、conf、webapp、hook 四个核心目录。bin 下是启动和停止脚本conf 下是 atlas-application.properties 与 atlas-env.shwebapp 里是 Atlas UI 和 REST 服务本身hook 里放着各类组件桥接包。最需要先改的是 conf/atlas-env.sh 里的 JVM 参数默认的 -Xms1024m -Xmx1024m 在加载元数据模型时经常不够用vim conf/atlas-env.sh # 找到 ATLAS_OPTS 这一行改成至少 2g # ATLAS_OPTS-Xms2048m -Xmx4096m -XX:UseConcMarkSweepGC参数说明-Xms 是堆初始值-Xmx 是堆上限。单机验证建议初始 2g、最大 4g生产按元数据量给到 8g 以上。这里有个血泪经验不要只调 -Xmx 不调 -Xms否则服务启动后会因为堆反复扩容导致 GC 频繁Atlas UI 看起来活着实际查询慢得离谱。接着改 conf/atlas-application.properties这是 Atlas 能认出依赖组件地址的关键。最小配置如下先存下来再逐个解释# 图存储与实体存储 atlas.storage.backendhbase2 atlas.graph.storage.backendhbase2 atlas.graph.db.hbase.tableatlas_graph # 索引存储 atlas.graph.index.search.backendsolr atlas.graph.index.search.solr.modecloud atlas.graph.index.search.solr.zookeeper-urllocalhost:2181 # 通知与事件通道 atlas.notification.embeddedfalse atlas.kafka.bootstrap.serverslocalhost:9092 atlas.kafka.zookeeper.connectlocalhost:2181逻辑说明storage.backend 决定实体和关系图落到 HBasesolr.zookeeper-url 告诉 Atlas 去哪找 Solr 的协调节点kafka 的 bootstrap 地址是 Hook 事件和通知的收发通道。注意这里有两处 zookeeper 地址一个是 HBase 的一个是 Solr 的如果你的 Solr 是独立集群且自带 ZooKeeper两处地址会不一样别统一写成一个。改完配置后先别急着启动 Atlas因为它的三件套依赖要先跑起来否则启动日志里会全是连接异常。3. 启动整套后端HBase/Solr/Kafka 初始化命令与必调参数3.1 HBase 和 Kafka 初始化建表、启进程、建 Topic 一条龙HBase 这步比较简单因为 Atlas 首次启动时会自动创建 atlas_graph 等表不需要手工建。但你需要先确认 HBase 集群在线否则 Atlas 会一直重试连接$HBASE_HOME/bin/hbase shell status simple如果返回里有 1 个 active master 和对应 region server说明集群正常。注意单机伪分布式下 region server 数量显示为 1 就行。这里不要手动去建 atlas 开头的表Atlas 建表时会带自己的表属性手建容易少预分区配置后面数据一多就会遇到 region 热点。Kafka 相对麻烦一点。如果你的 broker 配置了 auto.create.topics.enabletrueAtlas 启动时能自动建 topic但生产环境一般关掉这个开关所以手动补建是稳妥做法$KAFKA_HOME/bin/kafka-topics.sh --bootstrap-server localhost:9092 --create \ --topic ATLAS_HOOK --partitions 3 --replication-factor 1 $KAFKA_HOME/bin/kafka-topics.sh --bootstrap-server localhost:9092 --create \ --topic ATLAS_ENTITIES --partitions 3 --replication-factor 1参数说明Atlas 2.3.0 的事件通道至少需要两个 topicATLAS_HOOK 是各组件 Hook 上报实体变更的入口ATLAS_ENTITIES 是 Atlas 内部消费后产生的通知流出。partitions 在单机验证时给 1 就够生产按事件量给 3 到 6replication-factor 在单机给 1多 broker 集群给 2 或 3。建完之后用 kafka-topics.sh --list 确认 topic 都在再去启动 Atlas否则日志里会反复出现 “no such topic” 的告警但进程不会退出很多人会忽略。3.2 Solr 云模式集合初始化端口、副本、内存的强行指定Solr 是这三个依赖里启动参数最讲究的。Atlas 2.3.0 虽然内置了接口能连 Solr但不会替你创建 collection必须手动初始化。先以 SolrCloud 模式启动/path/to/solr/bin/solr start -c -z localhost:2181 -p 8983 -m 2g参数说明-c 表示 cloud 模式-z 指向 ZooKeeper 地址-p 是 Solr 的 HTTP 端口-m 2g 限制堆内存。这里有个容易翻车的点如果本机同时有 HBase 的 ZooKeeper 和 Solr 自带的 ZooKeeper你会启动两个 2181 冲突常见做法是把 Solr 的 -z 指向一个独立端口比如 2182然后在 atlas-application.properties 里把 solr.zookeeper-url 改成对应的 2182。Solr 起来后需要把 Atlas 自带的索引配置上传到 ZooKeeper。Atlas 2.3.0 的 conf/solr 目录下就是现成 schema/path/to/solr/bin/solr zk upconfig \ -n atlas \ -d /opt/apache-atlas-2.3.0/conf/solr \ -z localhost:2181这步是把本地配置集推给 SolrCloud-n atlas 是配置集名称后面创建 collection 时必须用同一个名字。上传成功后再创建 Atlas 需要的三个核心索引集合for idx in vertex_index edge_index fulltext_index; do curl -X POST http://localhost:8983/solr/admin/collections?actionCREATEname${idx}replicationFactor1numShards1collection.configNameatlas done三个集合分别对应顶点、边和全文索引缺哪一个 Atlas 启动时都会报 “Missing index collection” 的错。mo 参数里 replicationFactor 单机写 1多节点集群可以写 2numShards 决定分片数一般一个集合一个分片起步数据量大再按 pre-split 拆。创建完成后验证一下curl http://localhost:8983/solr/vertex_index/select?q*:*rows0返回 JSON 里 numFound 字段是 0 就说明集合可用。注意这里验证的是索引能响应查询不是数据有没有Atlas 写入数据要等实体注册之后才有后面第四章会演示。4. 用 REST API 打通元数据与血缘验证 Atlas 真正可用4.1 登录、查看类型定义最小可跑 API 链路后端依赖都就绪后执行 bin/atlas_start.py 启动 Atlas。启动日志在 logs/atlas.log看到 “Started AtlasServer” 之类的记录说明 REST 服务起来了。第一次验证别急着打开 UI 页面直接用命令行走一遍 REST 链路更可靠毕竟 UI 白屏不一定代表接口正常。Atlas 默认账号是 admin/admin先创建会话拿到 Cookiecurl -s -c /tmp/atlas.cookie -X POST \ -H Content-Type: application/json \ -d {username:admin,password:admin} \ http://localhost:21000/api/atlas/admin/sessions参数说明-c 是把服务端返回的 Cookie 写入本地文件后续请求带同一个 Cookie 才能保持登录态。如果执行后遇到 401先确认是不是改过默认密码如果是第一次启动直接 401检查 Kafka 是否消费积压导致登录鉴权组件超时。登录成功后下面这个请求能列出所有已注册的元数据模型类型curl -s -b /tmp/atlas.cookie \ http://localhost:21000/api/atlas/v2/types/typedefs/headers | head -c 500注意这次请求用的是 /api/atlas/v2这是 2.x 的标准前缀。返回的 JSON 数组里能看到 hive_db、hive_table、hive_process 等类型名表示 Atlas 自带的 Hive 桥接模型已经加载。如果这里只返回很少几个类型别急着继续先翻 atlas.log 里有没有模型初始化失败的堆栈。4.2 用 DSL 搜索实体并追一条血缘返回字段解析与常见误读类型定义只是元数据的骨架真正有价值的是实体和血缘关系。用 Atlas 的 DSL 语法搜一下现有的表实体curl -s -b /tmp/atlas.cookie -X POST \ -H Content-Type: application/json \ -d {query:from hive_table limit 5} \ http://localhost:21000/api/atlas/v2/search/dsl返回内容里有一个 entities 数组每个元素里有 guid、typeName、attributes 等字段。其中 guid 是实体在 Atlas 里的全局唯一 ID后面查血缘全靠它。这里有个常见误读DSL 返回的 attributes 里 name 是表的逻辑名qualifiedName 才是全路径限定名比如 default.sales_order两个字段别搞混接 API 做同步时要用 qualifiedName 做去重键。拿到 guid 后就可以查这个实体的血缘关系curl -s -b /tmp/atlas.cookie \ http://localhost:21000/api/atlas/v2/lineage/${guid}这个接口返回的是血缘图结构里面有 nodes 和 edges 数组每条 edge 带有 typeName 字段比如 hive_process表示一次 Hive SQL 的加工过程。解析时最容易犯的错是把血缘方向搞反edges 里的 sourceId 代表上游表targetId 代表下游结果。我第一次接这个接口时把方向写反导致整个血缘图反向排查了很久才发现是这里的问题。如果你现在没有现成实体可查可以用第四章登录后先访问 Atlas UI在 Hive 表列表里随便点开一张表能看到 “Lineage” 页签拿页面里显示的 guid 再回来调接口依然能验证。5. Atlas 2.3.0 装不起来高频踩坑记录与排查思路5.1 Solr collection 一直 ERROR索引读不了现象用上一章命令创建完三个 collection 后访问 Solr Admin UI 看到集合状态是 ERROR点击查询直接报 500。原因绝大部分情况是配置集名称对不上创建 collection 时 collection.configName 写的名字和 zk upconfig 里的 -n 不一致其次是 Solr 的 ZooKeeper 连接串里包含了多段地址但 Atlas 配置里只写了一段导致 leader 选举无法完成。解决先用命令行确认配置集真实存在于 ZooKeepersolr zk ls /configs/atlas -z localhost:2181。如果列表为空重新执行 upconfig如果存在但 collection 仍然 ERROR删除集合重建一次curl -X POST http://localhost:8983/solr/admin/collections?actionDELETEnamevertex_index然后再走创建命令。重建后等待十几秒让 Solr 完成 leader 选举再查状态。这个操作可以在不重启 Atlas 的前提下完成但删除期间 Atlas 写入索引会失败尽量选低峰期做。5.2 Hook 接入后不产生血缘先怀疑 Kafka现象Hive 里执行了一条 create table as selectAtlas UI 里能看到新表实体但血缘图是空的。原因Atlas 的实体写入和血缘写入走了两条链路实体由 Atlas 直接抓取或 Hook 上报血缘依赖 Hook 把 process 事件推到 Kafka再被 Atlas 消费解析。血缘为空十有八九是 Hook 事件根本没进 Kafka。解决先确认 Kafka 里有没有消息进来$KAFKA_HOME/bin/kafka-console-consumer.sh \ --bootstrap-server localhost:9092 \ --topic ATLAS_HOOK --from-beginning \ --timeout-ms 10000如果消费者保持静默去查 Hive 这边的 Atlas Hook 配置是否指向了正确的 Kafka 和集群名如果消息里有内容但 Atlas 不消费再查 atlas-application.properties 里的消费者 group 配置。常见的坑是 atlas.cluster.name 配置值没对齐Hook 事件带了 cluster 名Atlas 端配置的是默认值双方匹配不上消息被直接丢弃。5.3 /api/atlas/admin/status 永远 ACTIVE 但不工作现象访问 http://localhost:21000/api/atlas/admin/status 返回 {Status:ACTIVE}UI 也能打开但搜索表或查看类型定义时一直转圈。原因status 接口检查的是 Atlas 进程是否活着不检查底层依赖是否健康。最常见的场景是 Solr 的某个 collection 因为磁盘写满或 leader 丢失进入不健康状态Atlas 索引读写全部超时但主进程还在。解决先不要重启 Atlas去 Solr Admin 里逐个点击三个 collection 的 “Query” 页签手动执行 q:rows1看哪个集合响应超过 5 秒。定位到问题集合后按 5.1 的删除重建流程处理。重建完回到 Atlas UI 强制刷新一般不用重启 Atlas。这里有一个习惯值得养成排查 Atlas 前先问自己“是 Atlas 本身挂了还是它依赖的索引挂了”能用 curl 验证的就别先动进程。5.4 heap 被默认配置撑爆服务自己退出现象atlas_start.py 执行后进程存活不到 5 分钟或者日志里出现 OutOfMemoryError伴随 GC overhead limit exceeded。原因conf/atlas-env.sh 默认的 1g 堆内存在加载完整类型系统时会频繁触发 Full GC尤其是同时开启 Hive、HBase、Kafka 多个 Hook 时类型定义数量直接翻倍。解决调大堆内存并开启 GC 日志下次翻车时能直接看到堆使用曲线ATLAS_OPTS-Xms4096m -Xmx8192m -XX:UseG1GC -XX:PrintGCDetails -XX:PrintGCDateStamps -Xloggc:/opt/apache-atlas-2.3.0/logs/gc.log参数说明-Xms 和 -Xmx 建议设置成一样的值避免堆扩容抖动UseG1GC 比 CMS 更适合大堆。同时注意别把机器所有内存都给了 AtlasSolr 和 HBase 本身也要占用小内存机器上先砍掉不需要的 Hook 模块比调参更有效。5.5 重装或升级后启动报错数据残留现象同一台机器上重装 Atlas 或者从 2.2 升到 2.3启动时报 schema 冲突或索引字段类型不匹配。原因上一次安装已经把 HBase 表和 Solr collection 建好了重装时 Atlas 检测到已有存储结构但版本升级后 schema 里的字段定义变了旧索引和新代码对不上。这种情况跟普通配置文件覆盖不一样它藏在第三方依赖里所以很多人会以为是安装包有问题。解决卸载时除了删二进制目录还要把 HBase 里 atlas_ 开头的表和 Solr 里三个 collection 一起清理掉。HBase 清理走 hbase shelldisable atlas_graph drop atlas_graphSolr 清理用 DELETE API。做完之后重新走第三章的初始化流程。这里是最接近“后悔药”的操作元数据中心如果还没有历史数据沉淀清掉重来比重试修复快得多如果已经接入了生产环境千万别用这个方式要按官方升级路径走双集群迁移。6. 把血缘做成日常巡检一个能用的健康检查脚本和 REST 细节6.1 健康检查脚本状态、类型数、索引命中一个脚本看全服务跑起来只是开始日常运维里最容易忽略的是“服务活着但链路已断”。我一般会在每台 Atlas 节点上放一个巡检脚本把前面几章验证过的 REST 接口串起来#!/bin/bash BASE_URLhttp://localhost:21000 COOKIE/tmp/atlas.cookie curl -s -c $COOKIE -X POST -H Content-Type: application/json \ -d {username:admin,password:admin} \ $BASE_URL/api/atlas/admin/sessions /dev/null status$(curl -s -b $COOKIE $BASE_URL/api/atlas/admin/status \ | python -c import sys,json;print(json.load(sys.stdin)[Status])) type_count$(curl -s -b $COOKIE $BASE_URL/api/atlas/v2/types/typedefs/headers \ | python -c import sys,json;print(len(json.load(sys.stdin)))) echo Atlas Status: $status echo Type Count: $type_count脚本逻辑分三步先登录拿 Cookie再查服务状态最后统计类型定义数量。如果 status 不是 ACTIVE 或 type_count 低于正常基线就需要进入手动排查。可以配合 crontab 每 5 分钟跑一次把输出重定向到日志文件血泪经验告诉我一个只检查进程存活的监控没有任何意义必须把 REST API 的返回也加进去因为 Atlas 的 ACTIVE 状态几乎不会自己变 false。6.2 一次巡检抓出 Solr 假活之后我才把监控维度补全之前有次值班监控显示 Atlas 所有进程正常但运营反馈数据目录看不到新表。跑了一遍上面的脚本status 是 ACTIVEtype_count 也没变化可血缘图死活不更新。最后发现 Solr 的 fulltext_index 已经处于只读状态索引写入全部失败但 Atlas 本身不感知这个错误因为它的搜索读路径还在走缓存。从那以后我把巡检脚本加了一道 Solr 探针直接请求三个 collection 的 select 接口响应超过 3 秒就告警。这件事给我留下的习惯是凡是用 Atlas 承接了正式数据资产的团队至少要让巡检覆盖 Atlas、Solr、Kafka 消费组三个层面才能算真正心中有数。希望这篇笔记能帮你把这套链路一次跑通少走我当初连续折腾两天的弯路。本文还有配套的精品资源点击获取