如果你所在的团队已经开始搭数据平台一定对“元数据管理”不陌生。数据表越来越多字段口径越铺越开哪个表是谁产生的、又被哪个任务消费这些问题单靠人肉记录根本撑不住。Atlas 就是用来承接这类需求的开源元数据治理组件但它的安装方式比较特别不是解压以后点个启动脚本就完事。很多人栽在起步阶段其实不是因为 Atlas 本身难装而是没搞明白它运行时要依赖哪些东西。这篇文章从零开始给你完整过一遍 Atlas 的安装过程。我会把环境准备、组件搭建、配置文件修改、启动验证、常见故障排查全链路讲清楚适合刚接手数据平台、需要自己在测试环境部署 Atlas 的开发或运维同学参考。1. 安装Atlas前必须先想明白的三件事1.1 Atlas到底解决什么问题装它需要装什么Atlas 本质上是一个元数据管理平台。你可以把“元数据”简单理解为“关于数据的数据”一张 Hive 表有哪些字段、字段是什么类型、这张表是哪个任务生成的、下游又用在了哪里这些信息都是元数据。Atlas 把这些信息组织成图并且能解析 SQL 任务来追数据血缘帮你在数据问题排查、数据资产盘点、合规审计时把来龙去脉理清楚。但它本身不是一个“软件全家桶”。官方文档里描述 Atlas 的架构时你很快会看到几个高频名字HBase、Solr、Kafka。它们的分工大概是这样的HBase 负责持久化图数据。Atlas 把元数据实体、关系、分类都写进底层的图存储默认元数据表的存储压在 HBase 上。Solr 负责索引和搜索。你在 Atlas 界面里按名称搜表、按标签筛实体背后是 Solr 在做全文检索和条件过滤。Kafka 负责异步消息。Atlas 和各组件 Hook比如 Hive Hook之间通过 Kafka 传递元数据变更事件做到旁路采集而不阻塞业务查询。打个比方Atlas 像一套图书馆管理程序HBase 是书架Solr 是检索卡片柜Kafka 是图书变动通知管道。程序本身是核心逻辑但没了书架和卡片柜光有程序干不了活。1.2 三种安装模式怎么选嵌入式、独立伪分布式、真分布式安装 Atlas 前先确定你的目标环境不同模式对应完全不同的准备工作。第一种是“快速体验模式”。这种模式会把 Atlas 依赖的组件尽量简化或本地化适合只想知道 Atlas 长什么样、能在界面点一点的同学不适合任何意义上的生产使用。网上很多演示视频用的就是这种方式好处是快坏处是和你真正要面对的生产环境差距大容易产生误导。第二种是“单机伪分布式”也是我下面会重点展开的方式。在一台 Linux 服务器上分别装好 HBase、Solr、Kafka再安装 Atlas让 Atlas 连接这三个组件。研发自测、测试环境、中小团队验证功能用这种方式最贴近生产架构隔离问题上也最方便。第三种是“完全分布式”也就是 Atlas 本体、HBase、Solr、Kafka 实际分布在多台机器或集群上。这时 Atlas 的安装动作反而更简单你只需要把配置文件里的连接地址指向远端集群即可。真正复杂的是那些集群本身的安装维护不在本文讨论范围。我的建议是第一次安装不要跳过第二种模式直接上生产集群。先在一台机器上把整条链路跑通你会对 Atlas 启动时到底要连哪些端口、建哪些表、注册哪些索引有直观认识这些经验迁移到分布式环境时特别管用。1.3 版本匹配比安装本身更容易踩坑Atlas 的版本兼容问题非常容易踩而且报错往往不直观。比如 Atlas 2.2.0 配 JDK 11启动时可能一切正常但跑一段 Hive Hook 后出现莫名其妙的序列化异常又比如 Atlas 2.x 配 HBase 3.x某些 RPC 协议不一致会导致图数据写入失败。这里给出一套我多次验证过的参考组合组件参考版本备注JDK8Atlas 2.x 对 JDK 8 支持最好不要图新鲜用 11/17HBase2.2.x配置存储后端时选 hbase2Solr7.7.x必须以 Cloud 模式运行Kafka2.8.x单机测试选自带 ZooKeeper 模式即可ZooKeeper3.5.xHBase、Solr、Kafka 共用同一套 ZK 最省事Atlas2.2.0这是目前社区使用面较广的稳定版本如果你的环境里用的是某个商业发行版的大数据套件组件路径、jar 版本可能和我下面写的略有出入。建议先看发行版自带的兼容矩阵再动手装。2. 环境准备把HBase、Solr、Kafka这三尊“靠山”先摆平2.1 JDK与目录规划Atlas 是 Java 服务第一步确认 JDK。上面已经说过用 JDK 8最好同时把JAVA_HOME写到全局环境变量里否则后面 HBase 脚本和 Atlas 脚本各自找不到 Java 会很难受。我习惯把组件集中放到一个目录下统一管理比如mkdir -p /opt/bigdata软件分别解压到/opt/bigdata/hbase、/opt/bigdata/solr、/opt/bigdata/kafka、/opt/bigdata/atlas同时建一个/data目录存 HBase 的本地数据、Kafka 的日志。这里要注意Solr 的默认数据目录和 Kafka 的默认日志目录都可能在/tmp下测试环境重启后会被系统清理到时候 Atlas 再启动会报索引或日志目录缺失很容易让人误判成组件损坏。规规矩矩在安装阶段就把数据目录改到独立位置后面省很多事。2.2 HBase的快速搭建与启动参数HBase 的安装其实就是解压后改两个文件。编辑conf/hbase-site.xml先把关键项写成这样configuration property namehbase.rootdir/name valuefile:///data/hbase/value /property property namehbase.zookeeper.property.clientPort/name value2181/value /property property namehbase.cluster.distributed/name valuefalse/value /property /configuration单机伪分布式把hbase.cluster.distributed设为 false让 HBase 自己管理 ZooKeeper 客户端。如果你已经有了一个独立的 ZooKeeper 集群也可以把 HBase 指向它不过首次安装没必要增加变量。启动方式用脚本最省事/opt/bigdata/hbase/bin/start-hbase.sh启动后不要急着往下走至少确认两件事jps能看到HMaster和HRegionServer两个进程。hbase shell里执行status返回正常。如果HRegionServer没起来多半是/tmp/hbase-xxx目录权限或磁盘空间问题先处理了再去装 Atlas否则 Atlas 启动时能连上 HMaster 但写数据会超时。2.3 Solr云模式的集群配置Atlas 要求 Solr 以 Cloud 模式启动。Cloud 模式意味着 Solr 会把集合配置和分片状态放到 ZooKeeper 里Atlas 查询索引时通过 ZooKeeper 找到对应分片。启动命令很简单/opt/bigdata/solr/bin/solr start -c -z localhost:2181如果你已经有独立 ZooKeeper就把localhost:2181换成你的 ZK 地址列表。如果 Solo 模式已经启动过先停掉再切 Cloud不然会报端口占用或模式冲突。Solr 启动之后Atlas 正常运行需要三类集合默认名称是vertex_index、edge_index、fulltext_index。集合名可以改但配置要能对上。用命令行创建集合curl -X POST http://localhost:8983/solr/admin/collections?actionCREATEnamevertex_indexnumShards1replicationFactor1 curl -X POST http://localhost:8983/solr/admin/collections?actionCREATEnameedge_indexnumShards1replicationFactor1 curl -X POST http://localhost:8983/solr/admin/collections?actionCREATEnamefulltext_indexnumShards1replicationFactor1生产环境里 numShards 和 replicationFactor 要根据 Solr 集群规模调整但测试环境一个分片、一个副本就够了。需要注意的是Atlas 发行包里其实带了这些集合的 Solr 配置模板在conf/solr目录下正规做法是把配置模板上传到 ZooKeeper 后再建集合。你要是想图省事直接用上面的命令建空集合Atlas 启动后也可能会帮你把 schema 补上但只要 Atlas 没有触发索引初始化就会出现“服务起来了但一搜索就报错”的情况。我更推荐按官方文档来过一遍配置集至少把conf/solr里的vertex_index配置目录对应到集合上。2.4 Kafka的本地启动与Topic检查Kafka 在 Atlas 里承担事件管道。下载 Kafka 后改一下config/server.properties里的几个路径log.dirs/data/kafka-logs zookeeper.connectlocalhost:2181启动 Kafka/opt/bigdata/kafka/bin/kafka-server-start.sh -daemon /opt/bigdata/kafka/config/server.propertiesKafka 启动成功与否看日志不如直接查端口和 broker/opt/bigdata/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server localhost:9092能正常列出 API 版本列表说明 broker 已经注册到 ZooKeeper 并在 9092 端口监听。我这里额外建议手动预创建 Atlas 会用到的两个 Topic/opt/bigdata/kafka/bin/kafka-topics.sh --create --bootstrap-server localhost:9092 --replication-factor 1 --partitions 1 --topic ATLAS_HOOK /opt/bigdata/kafka/bin/kafka-topics.sh --create --bootstrap-server localhost:9092 --replication-factor 1 --partitions 1 --topic ATLAS_ENTITIES测试环境里 Kafka 的auto.create.topics.enable默认是 trueAtlas 起不来时可以自动创建但手动创建能提前发现权限、磁盘、网络这些问题排查起来更可控。3. 下载、解压和改配置这一步决定能不能起来3.1 获取安装包并确认目录结构Atlas 安装包可以从项目的 GitHub Release 页面或你们公司内部的制品库下载文件名一般是atlas-2.2.0-bin.tar.gz之类的发行包。下载后解压cd /opt/bigdata tar -zxvf atlas-2.2.0-bin.tar.gz mv atlas-2.2.0 atlas解压后先看一眼结构几个关键目录的含义要清楚目录作用bin启动、停止脚本conf核心配置、Solr 配置模板、日志配置libext扩展 jar 目录接入外部组件时经常要往这里放 jarserver/webappAtlas 自带的 Web UIlogs运行日志目录3.2 atlas-application.properties 关键项逐条拆解Atlas 有一个配置模板文件conf/atlas-application.properties.example第一次装要把这个模板复制成正式配置再改cp /opt/bigdata/atlas/conf/atlas-application.properties.example /opt/bigdata/atlas/conf/atlas-application.properties这个文件默认项非常多挑最关键的先改清楚。# 图存储后端HBase 2.x 用 hbase2HBase 1.x 用 hbase atlas.graph.storage.backendhbase2 atlas.graph.storage.hostnamelocalhost:2181 atlas.graph.storage.hbase.tableatlas # 索引后端 atlas.graph.index.search.backendsolr atlas.graph.index.search.solr.zookeeper-urllocalhost:2181 atlas.graph.index.search.solr.collection.vertexindexvertex_index atlas.graph.index.search.solr.collection.edgeindexedge_index atlas.graph.index.search.solr.collection.fulltextindexfulltext_index # 消息后端 atlas.kafka.bootstrap.serverslocalhost:9092 atlas.kafka.zookeeper.connectlocalhost:2181 # REST 服务地址 atlas.rest.addresshttp://localhost:21000几个容易看走眼的地方我单独拎出来说atlas.graph.storage.hostname填的不是 HBase 的 RPC 地址HBase 对外不直接暴露给 AtlasAtlas 通过 ZooKeeper 找到 HBase 的 RegionServer所以这里填 ZooKeeper 地址。Solr 的集合名必须和 2.3 节创建的名称完全一致大小写敏感。你写Vertex_Index就和vertex_index对不上服务起来后搜索会找不着集合。Kafka 地址是 broker 地址不是 ZK 地址而atlas.kafka.zookeeper.connect又单独填 ZK。3.3 配置 Hive Hook 与元数据导入 jarAtlas 安装的很多时候不只是装 Atlas 本身还要接 Hive。Hive 通过一个叫 Hive Hook 的插件把元数据事件发送到 KafkaAtlas 消费后才会有数据。你在 Atlas 发行包的hook/hive目录下能看到对应的 jar比如atlas-hive-plugin-2.2.0.jar。若要让 Atlas 能采集 Hive 元数据需要把这个 jar 放进 Hive 的辅助 jar 路径并在 Hive 配置里追加 Hook 类property namehive.exec.post.hooks/name valueorg.apache.atlas.hive.hook.HiveHook/value /property这一步不是基础安装必须的但如果你装 Atlas 就是为了给 Hive 做血缘就要在 Atlas 起来之后同步处理。我一般在第一次启动 Atlas 之前先把 jar 准备好其他组件都确认好了再统一重启 Hive 加载 Hook避免中间反复重启 Hive。3.4 环境变量与JVM参数调整Atlas 启动脚本通过conf/atlas-env.sh读取 Java 环境打开这个文件确认里面有正确的JAVA_HOMEexport JAVA_HOME/usr/local/java/jdk1.8.0_xxx内存参数是 Atlas 安装里一个很容易被忽略的坑。默认配置在小型机器上可能不够内存不够的表现不是启动报错而是 Atlas 启动很慢或者在导入大量类型定义时直接 OOM。参考设置export ATLAS_SERVER_OPTS-Xmx4g -Xms1g -XX:UseConcMarkSweepGC测试机如果只有 8G 内存4G 给 Atlas 已经很极限HBase、Solr、Kafka 也要分内存这时候可以适当降到 2G但你要有心理准备后面导入 Hive 元数据时 Full GC 会明显变多。生产环境建议单独给 Atlas 分配足够内存避免和其他服务挤在一起。4. 启动Atlas并完成首次初始化的完整流程4.1 启动顺序为什么必须是HBase→Solr→Kafka→AtlasAtlas 虽然是一个独立进程但它启动时要做三件依赖外部的事情通过 ZooKeeper 找 HBase连接元数据表。通过 ZooKeeper 找 Solr验证索引集合。连接 Kafka初始化消费者和生产者。所以第一次安装时推荐的启动顺序是/opt/bigdata/hbase/bin/start-hbase.sh /opt/bigdata/solr/bin/solr start -c -z localhost:2181 /opt/bigdata/kafka/bin/kafka-server-start.sh -daemon /opt/bigdata/kafka/config/server.properties /opt/bigdata/atlas/bin/atlas_start.py从底层到上层一层层把依赖准备好。Atlas 启动时有重试机制某些组件没起来它不会立刻挂掉而是卡在连接等待上这时候你几乎看不出它在等什么加上日志刷得又慢特别容易让人以为程序没起来。按顺序启动至少能缩小排查面。4.2 atlas_start.py 执行过程会做哪些事运行启动脚本后你以为它就是一个“java -jar”实际它在后台做了不少初始化动作检查atlas-application.properties是否能正常解析。尝试连接 ZooKeeper读取 HBase 的根表。检查 Solr 集合是否可用必要时做初始化。启动 Atlas Server开始加载内置的类型定义比如 hive_table、hive_column、hdfs_path 等一大堆内置实体类型。启动 Kafka 消费者线程接收来自 Hook 的通知事件。整个初始化过程在低配机器上可能需要 2 到 5 分钟。你看到进程起来了不代表服务已经可访问正确的做法是持续看日志tail -f /opt/bigdata/atlas/logs/application.log当日志里出现类似“Atlas Server started”的日志并且 21000 端口已经有 Java 进程监听才算真正起来。期间如果看到一些 WARN 级别的连接超时先别急着打断等一等但如果是 ERROR 并伴有异常堆栈就要停下来排查。4.3 通过REST API验证安装结果UI 能打开只是第一步。我更推荐直接通过 REST API 验证因为返回结果更明确方便脚本化监控。试一下获取类型定义curl -u admin:admin http://localhost:21000/api/atlas/v2/types/typedefs | head -c 500正常情况下你会看到一大段 JSON里面包含一系列类型定义。如果返回的不是 JSON 而是错误页或者提示无权限说明认证配置或服务状态有问题。Atlas 默认管理员账号是admin/admin。如果你改了认证配置这里的密码也要对应用户名密码。4.4 停机与重启的正确方式Atlas 的停止脚本是/opt/bigdata/atlas/bin/atlas_stop.py不要动不动就kill -9。Atlas 进程里有一些 Kafka 消费者会提交消费位点HBase 写入也需要时间刷新硬杀可能导致重启后消费重复或索引状态不一致。当然测试环境无所谓但养成优雅停机的习惯对生产环境很重要。重启 Atlas 时不需要重启 HBase、Solr、Kafka直接再跑atlas_start.py即可。但如果这三个组件有过重启我习惯先确认它们的端口和 ZooKeeper 状态正常再启动 Atlas否则又会陷入等连接超时的漩涡。5. 安装中的常见坑按定位链路一个个说清楚5.1 21000端口起不来先查日志而不是查进程这个现象我见到太多次jps里能看到 Atlas 进程但浏览器访问 21000 就是打不开。很多人第一反应是杀进程重启反复几次都没用。正确思路是先看日志最后 200 行tail -200 /opt/bigdata/atlas/logs/application.log | grep -A 20 Exception常见情况是Caused by: java.net.ConnectException: Connection refused指向 HBase 的 ZooKeeper 地址。这时候先确认 HBase 是否已经注册到 ZK/opt/bigdata/hbase/bin/hbase zkcli ls /hbase能列出 HBase 节点说明 HBase 这边没问题。如果ls /hbase报节点不存在回到 2.2 节检查 HBase 是否真正启动完成而不是只看到进程存在。还有一种很隐蔽的情况HBase 2.x 的某些 jar 在 Atlas 发行包里没有直接带上日志会报ClassNotFoundException: org.apache.hadoop.hbase.HBaseConfiguration。解决方法是把 HBase 安装目录lib下的相关 jar 复制到 Atlas 的libext下。注意先复制缺失的不要把所有 jar 一把梭拷进去容易和 Atlas 自带的版本冲突。5.2 Solr集合状态不对导致查询失败Atlas 服务起来了UI 也能打开但你在搜索栏里敲表名返回结果一直转圈或报 500 错误这类问题大概率出在 Solr 集合上。先查集合列表curl http://localhost:8983/solr/admin/collections?actionLISTwtjson返回的集合列表和配置里的atlas.graph.index.search.solr.collection.*对比少哪个补哪个。这里有一个非常容易踩的坑生产环境有人会把集合名写成atlas_vertex_index配置里却是vertex_index两边差一个前缀Atlas 启动时不报错但搜索时总找不到索引。如果集合都在再看集合健康状态curl http://localhost:8983/solr/admin/collections?actionCLUSTERSTATUSwtjson重点关注shard.state是否为active。如果显示recovering或down说明副本存在异常需要等 Solr 自动恢复或者检查磁盘、ZK 连接。我处理这类问题时最麻烦的一次是 Solr 集合全部正常但 Atlas 查询还是报错最后发现是 Solr 的数据目录快满了索引写不进去导致搜索节点直接返回异常。这个方向容易忽略排查时顺手看一眼磁盘占用。5.3 Kafka consumer线程报错的定位方法Atlas 正常启动后日志里偶尔有 Kafka consumer 的报错是常见的但有一种情况特别让人抓狂Atlas 界面里看不到 Hive 表的数据日志反复出现类似“Subscription(s) X not initialized due to timeout”的提示。这通常是 Kafka Topic 没建好或者消费者组配置有问题。手动建 Topic 是性价比最高的解决办法。上面 2.4 节已经给过命令如果 Topic 已存在可以查一下消费者组消费位点/opt/bigdata/kafka/bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --list看到 group 存在后进一步查看是否有 lag/opt/bigdata/kafka/bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group group名如果 groups 列表为空说明 Atlas 的消费者线程始终没有加入 group。这时候回过去查 Atlas 日志里的atlas.kafka.bootstrap.servers是否指向正确以及 Kafka 的advertised.listeners是否配置成了别的 IP。测试环境里最常见的原因其实是/tmp下的 Kafka 日志被系统清理broker 起是新起的但 Atlas 还在按老的 offset 提交消费卡住。清理 Atlas 本地 Kafka 数据目录或重置消费者组能解决这个问题。Atlas 本地 Kafka 数据目录不可能存在因为 Atlas 不存储 Kafka data消费者 offset 默认存在 Kafka 内部 topic__consumer_offsets。 所以这里准确的说法是如果你确认是 Kafka 数据问题需要清理 Kafka 的 log.dirs 或重置消费组。我在文中可以这么写。别提到似乎就不存在“Atlas 本地 Kafka 数据目录”。我会将措辞调整为“如果 Kafka 日志目录被清理过消费者组状态对不上就重置一下消费组。” 好。5.4 HBase2后端额外JAR处理Atlas 2.2.0 的发行包里自带的 HBase 依赖和你自己装的 HBase 2.2.x 客户端可能出现版本差异。症状是 Atlas 启动到了图存储初始化那一步突然报NoSuchMethodError或ClassNotFoundException堆栈里能看到 HBase 客户端方法调用。不要急着重装 Atlas。先把 HBase 安装目录里的客户端 jar 找出来ls /opt/bigdata/hbase/lib/ | grep -E hbase|hadoop | head -50找出和 Atlaslibext下重复但版本不同的 jar优先把 HBase 侧的 jar 复制到libext。复制后重启 Atlas如果报新的冲突再把明显重复的旧版本从libext移出。这个动作说白了就是“用真实环境的 jar 覆盖发行包里的 jar”。做的时候注意两点一是先备份二是不要动 Solr 和 Kafka 相关的 jar它们一般不需要这样处理。6. 安装只是开始连接Hive与日常维护6.1 开启身份认证的注意点默认安装是 auth 关闭的Web UI 虽然会弹登录框但输入admin/admin就能进去。如果你们的 Atlas 要开放给多个团队用建议从文件认证开始而不是一上来就上 Kerberos。在配置里加上atlas.auth.enabledtrue atlas.auth.method.filetrue然后维护conf/users-credentials.json这个文件里面定义了用户名、密码和角色。这是相对轻量的方案至少能解决“谁都能改元数据”的问题。Kerberos 方案不是不行但它要求 Atlas、HBase、Solr、Kafka 这些组件全部完成 Kerberos 认证涉及的关键步骤和排错点会多出很多不建议放在首次安装时处理。先把 Atlas 本身跑稳定再加入安全层可能更符合多数团队的节奏。6.2 让Hive元数据和血缘真正进入AtlasAtlas 起来了UI 也开了但如果 Hive 的元数据还没进来它对你实际业务的价值就是零。让 Hive 元数据进入 Atlas需要确保两件事已经就位Hive 所在节点上有 Atlas 的 Hive Hook jar 并加入到 Hive 的辅助 jar 路径。Hive 的hive-site.xml里配置了hive.exec.post.hooksorg.apache.atlas.hive.hook.HiveHook。配置完成后重启 HiveServer2。接着在 Hive 里执行建表语句再回到 Atlas 的 UI 搜索这个表名应该能看到表和列信息。如果还是看不到按 5.3 节的链路查 Kafka 消费。SQL 的血缘关系不是建表后立刻完美的它需要结合 Hive 的执行计划解析所以测试时建议先用几条简单的create table ... as select语句再逐步验证复杂 SQL。6.3 定期维护备份、日志清理、Solr集合重建Atlas 安装完成只是起点日常维护比安装更重要。三个高频维护动作备份 HBase 里的 atlas 表。最简单的办法是官方自带命令。测试环境可以接受 HBase 导出生产环境则要做全链路备份规划。至少你要清楚Atlas 的实体数据在 HBase 里索引在 Solr 里两者不是一回事。日志清理。Atlas 的logs/application.log涨得非常快不加限制的话一个测试环境一年能吃掉几十 GB。配置好 logrotate 或运维平台日志采集及时归档。Solr 集合异常时重建。如果索引损坏最直接的办法是删除对应的 Solr 集合再重建然后重启 Atlas让它基于 HBase 里的实体数据重新建索引。HBase 在索引就能重建HBase 没备份才是真正的灾难。最后分享一个我自己的习惯正式安装前我会先写一个小检查脚本把 HBase 状态、Solr 集合列表、Kafka broker 列表一次性打出来确认都在了再启动 Atlas。这样能筛掉八成“看起来是 Atlas 问题其实是组件环境没就绪”的坑。你照着本文装完一遍后也会慢慢找到适合自己的检查节奏这套流程自然就成了你上手数据治理的第一步。 
长河君 · 2026/10/13 23:37:57 · 阅读 1.2k Atlas元数据管理平台安装实战：从环境搭建到故障排查
如果你所在的团队已经开始搭数据平台一定对“元数据管理”不陌生。数据表越来越多字段口径越铺越开哪个表是谁产生的、又被哪个任务消费这些问题单靠人肉记录根本撑不住。Atlas 就是用来承接这类需求的开源元数据治理组件但它的安装方式比较特别不是解压以后点个启动脚本就完事。很多人栽在起步阶段其实不是因为 Atlas 本身难装而是没搞明白它运行时要依赖哪些东西。这篇文章从零开始给你完整过一遍 Atlas 的安装过程。我会把环境准备、组件搭建、配置文件修改、启动验证、常见故障排查全链路讲清楚适合刚接手数据平台、需要自己在测试环境部署 Atlas 的开发或运维同学参考。1. 安装Atlas前必须先想明白的三件事1.1 Atlas到底解决什么问题装它需要装什么Atlas 本质上是一个元数据管理平台。你可以把“元数据”简单理解为“关于数据的数据”一张 Hive 表有哪些字段、字段是什么类型、这张表是哪个任务生成的、下游又用在了哪里这些信息都是元数据。Atlas 把这些信息组织成图并且能解析 SQL 任务来追数据血缘帮你在数据问题排查、数据资产盘点、合规审计时把来龙去脉理清楚。但它本身不是一个“软件全家桶”。官方文档里描述 Atlas 的架构时你很快会看到几个高频名字HBase、Solr、Kafka。它们的分工大概是这样的HBase 负责持久化图数据。Atlas 把元数据实体、关系、分类都写进底层的图存储默认元数据表的存储压在 HBase 上。Solr 负责索引和搜索。你在 Atlas 界面里按名称搜表、按标签筛实体背后是 Solr 在做全文检索和条件过滤。Kafka 负责异步消息。Atlas 和各组件 Hook比如 Hive Hook之间通过 Kafka 传递元数据变更事件做到旁路采集而不阻塞业务查询。打个比方Atlas 像一套图书馆管理程序HBase 是书架Solr 是检索卡片柜Kafka 是图书变动通知管道。程序本身是核心逻辑但没了书架和卡片柜光有程序干不了活。1.2 三种安装模式怎么选嵌入式、独立伪分布式、真分布式安装 Atlas 前先确定你的目标环境不同模式对应完全不同的准备工作。第一种是“快速体验模式”。这种模式会把 Atlas 依赖的组件尽量简化或本地化适合只想知道 Atlas 长什么样、能在界面点一点的同学不适合任何意义上的生产使用。网上很多演示视频用的就是这种方式好处是快坏处是和你真正要面对的生产环境差距大容易产生误导。第二种是“单机伪分布式”也是我下面会重点展开的方式。在一台 Linux 服务器上分别装好 HBase、Solr、Kafka再安装 Atlas让 Atlas 连接这三个组件。研发自测、测试环境、中小团队验证功能用这种方式最贴近生产架构隔离问题上也最方便。第三种是“完全分布式”也就是 Atlas 本体、HBase、Solr、Kafka 实际分布在多台机器或集群上。这时 Atlas 的安装动作反而更简单你只需要把配置文件里的连接地址指向远端集群即可。真正复杂的是那些集群本身的安装维护不在本文讨论范围。我的建议是第一次安装不要跳过第二种模式直接上生产集群。先在一台机器上把整条链路跑通你会对 Atlas 启动时到底要连哪些端口、建哪些表、注册哪些索引有直观认识这些经验迁移到分布式环境时特别管用。1.3 版本匹配比安装本身更容易踩坑Atlas 的版本兼容问题非常容易踩而且报错往往不直观。比如 Atlas 2.2.0 配 JDK 11启动时可能一切正常但跑一段 Hive Hook 后出现莫名其妙的序列化异常又比如 Atlas 2.x 配 HBase 3.x某些 RPC 协议不一致会导致图数据写入失败。这里给出一套我多次验证过的参考组合组件参考版本备注JDK8Atlas 2.x 对 JDK 8 支持最好不要图新鲜用 11/17HBase2.2.x配置存储后端时选 hbase2Solr7.7.x必须以 Cloud 模式运行Kafka2.8.x单机测试选自带 ZooKeeper 模式即可ZooKeeper3.5.xHBase、Solr、Kafka 共用同一套 ZK 最省事Atlas2.2.0这是目前社区使用面较广的稳定版本如果你的环境里用的是某个商业发行版的大数据套件组件路径、jar 版本可能和我下面写的略有出入。建议先看发行版自带的兼容矩阵再动手装。2. 环境准备把HBase、Solr、Kafka这三尊“靠山”先摆平2.1 JDK与目录规划Atlas 是 Java 服务第一步确认 JDK。上面已经说过用 JDK 8最好同时把JAVA_HOME写到全局环境变量里否则后面 HBase 脚本和 Atlas 脚本各自找不到 Java 会很难受。我习惯把组件集中放到一个目录下统一管理比如mkdir -p /opt/bigdata软件分别解压到/opt/bigdata/hbase、/opt/bigdata/solr、/opt/bigdata/kafka、/opt/bigdata/atlas同时建一个/data目录存 HBase 的本地数据、Kafka 的日志。这里要注意Solr 的默认数据目录和 Kafka 的默认日志目录都可能在/tmp下测试环境重启后会被系统清理到时候 Atlas 再启动会报索引或日志目录缺失很容易让人误判成组件损坏。规规矩矩在安装阶段就把数据目录改到独立位置后面省很多事。2.2 HBase的快速搭建与启动参数HBase 的安装其实就是解压后改两个文件。编辑conf/hbase-site.xml先把关键项写成这样configuration property namehbase.rootdir/name valuefile:///data/hbase/value /property property namehbase.zookeeper.property.clientPort/name value2181/value /property property namehbase.cluster.distributed/name valuefalse/value /property /configuration单机伪分布式把hbase.cluster.distributed设为 false让 HBase 自己管理 ZooKeeper 客户端。如果你已经有了一个独立的 ZooKeeper 集群也可以把 HBase 指向它不过首次安装没必要增加变量。启动方式用脚本最省事/opt/bigdata/hbase/bin/start-hbase.sh启动后不要急着往下走至少确认两件事jps能看到HMaster和HRegionServer两个进程。hbase shell里执行status返回正常。如果HRegionServer没起来多半是/tmp/hbase-xxx目录权限或磁盘空间问题先处理了再去装 Atlas否则 Atlas 启动时能连上 HMaster 但写数据会超时。2.3 Solr云模式的集群配置Atlas 要求 Solr 以 Cloud 模式启动。Cloud 模式意味着 Solr 会把集合配置和分片状态放到 ZooKeeper 里Atlas 查询索引时通过 ZooKeeper 找到对应分片。启动命令很简单/opt/bigdata/solr/bin/solr start -c -z localhost:2181如果你已经有独立 ZooKeeper就把localhost:2181换成你的 ZK 地址列表。如果 Solo 模式已经启动过先停掉再切 Cloud不然会报端口占用或模式冲突。Solr 启动之后Atlas 正常运行需要三类集合默认名称是vertex_index、edge_index、fulltext_index。集合名可以改但配置要能对上。用命令行创建集合curl -X POST http://localhost:8983/solr/admin/collections?actionCREATEnamevertex_indexnumShards1replicationFactor1 curl -X POST http://localhost:8983/solr/admin/collections?actionCREATEnameedge_indexnumShards1replicationFactor1 curl -X POST http://localhost:8983/solr/admin/collections?actionCREATEnamefulltext_indexnumShards1replicationFactor1生产环境里 numShards 和 replicationFactor 要根据 Solr 集群规模调整但测试环境一个分片、一个副本就够了。需要注意的是Atlas 发行包里其实带了这些集合的 Solr 配置模板在conf/solr目录下正规做法是把配置模板上传到 ZooKeeper 后再建集合。你要是想图省事直接用上面的命令建空集合Atlas 启动后也可能会帮你把 schema 补上但只要 Atlas 没有触发索引初始化就会出现“服务起来了但一搜索就报错”的情况。我更推荐按官方文档来过一遍配置集至少把conf/solr里的vertex_index配置目录对应到集合上。2.4 Kafka的本地启动与Topic检查Kafka 在 Atlas 里承担事件管道。下载 Kafka 后改一下config/server.properties里的几个路径log.dirs/data/kafka-logs zookeeper.connectlocalhost:2181启动 Kafka/opt/bigdata/kafka/bin/kafka-server-start.sh -daemon /opt/bigdata/kafka/config/server.propertiesKafka 启动成功与否看日志不如直接查端口和 broker/opt/bigdata/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server localhost:9092能正常列出 API 版本列表说明 broker 已经注册到 ZooKeeper 并在 9092 端口监听。我这里额外建议手动预创建 Atlas 会用到的两个 Topic/opt/bigdata/kafka/bin/kafka-topics.sh --create --bootstrap-server localhost:9092 --replication-factor 1 --partitions 1 --topic ATLAS_HOOK /opt/bigdata/kafka/bin/kafka-topics.sh --create --bootstrap-server localhost:9092 --replication-factor 1 --partitions 1 --topic ATLAS_ENTITIES测试环境里 Kafka 的auto.create.topics.enable默认是 trueAtlas 起不来时可以自动创建但手动创建能提前发现权限、磁盘、网络这些问题排查起来更可控。3. 下载、解压和改配置这一步决定能不能起来3.1 获取安装包并确认目录结构Atlas 安装包可以从项目的 GitHub Release 页面或你们公司内部的制品库下载文件名一般是atlas-2.2.0-bin.tar.gz之类的发行包。下载后解压cd /opt/bigdata tar -zxvf atlas-2.2.0-bin.tar.gz mv atlas-2.2.0 atlas解压后先看一眼结构几个关键目录的含义要清楚目录作用bin启动、停止脚本conf核心配置、Solr 配置模板、日志配置libext扩展 jar 目录接入外部组件时经常要往这里放 jarserver/webappAtlas 自带的 Web UIlogs运行日志目录3.2 atlas-application.properties 关键项逐条拆解Atlas 有一个配置模板文件conf/atlas-application.properties.example第一次装要把这个模板复制成正式配置再改cp /opt/bigdata/atlas/conf/atlas-application.properties.example /opt/bigdata/atlas/conf/atlas-application.properties这个文件默认项非常多挑最关键的先改清楚。# 图存储后端HBase 2.x 用 hbase2HBase 1.x 用 hbase atlas.graph.storage.backendhbase2 atlas.graph.storage.hostnamelocalhost:2181 atlas.graph.storage.hbase.tableatlas # 索引后端 atlas.graph.index.search.backendsolr atlas.graph.index.search.solr.zookeeper-urllocalhost:2181 atlas.graph.index.search.solr.collection.vertexindexvertex_index atlas.graph.index.search.solr.collection.edgeindexedge_index atlas.graph.index.search.solr.collection.fulltextindexfulltext_index # 消息后端 atlas.kafka.bootstrap.serverslocalhost:9092 atlas.kafka.zookeeper.connectlocalhost:2181 # REST 服务地址 atlas.rest.addresshttp://localhost:21000几个容易看走眼的地方我单独拎出来说atlas.graph.storage.hostname填的不是 HBase 的 RPC 地址HBase 对外不直接暴露给 AtlasAtlas 通过 ZooKeeper 找到 HBase 的 RegionServer所以这里填 ZooKeeper 地址。Solr 的集合名必须和 2.3 节创建的名称完全一致大小写敏感。你写Vertex_Index就和vertex_index对不上服务起来后搜索会找不着集合。Kafka 地址是 broker 地址不是 ZK 地址而atlas.kafka.zookeeper.connect又单独填 ZK。3.3 配置 Hive Hook 与元数据导入 jarAtlas 安装的很多时候不只是装 Atlas 本身还要接 Hive。Hive 通过一个叫 Hive Hook 的插件把元数据事件发送到 KafkaAtlas 消费后才会有数据。你在 Atlas 发行包的hook/hive目录下能看到对应的 jar比如atlas-hive-plugin-2.2.0.jar。若要让 Atlas 能采集 Hive 元数据需要把这个 jar 放进 Hive 的辅助 jar 路径并在 Hive 配置里追加 Hook 类property namehive.exec.post.hooks/name valueorg.apache.atlas.hive.hook.HiveHook/value /property这一步不是基础安装必须的但如果你装 Atlas 就是为了给 Hive 做血缘就要在 Atlas 起来之后同步处理。我一般在第一次启动 Atlas 之前先把 jar 准备好其他组件都确认好了再统一重启 Hive 加载 Hook避免中间反复重启 Hive。3.4 环境变量与JVM参数调整Atlas 启动脚本通过conf/atlas-env.sh读取 Java 环境打开这个文件确认里面有正确的JAVA_HOMEexport JAVA_HOME/usr/local/java/jdk1.8.0_xxx内存参数是 Atlas 安装里一个很容易被忽略的坑。默认配置在小型机器上可能不够内存不够的表现不是启动报错而是 Atlas 启动很慢或者在导入大量类型定义时直接 OOM。参考设置export ATLAS_SERVER_OPTS-Xmx4g -Xms1g -XX:UseConcMarkSweepGC测试机如果只有 8G 内存4G 给 Atlas 已经很极限HBase、Solr、Kafka 也要分内存这时候可以适当降到 2G但你要有心理准备后面导入 Hive 元数据时 Full GC 会明显变多。生产环境建议单独给 Atlas 分配足够内存避免和其他服务挤在一起。4. 启动Atlas并完成首次初始化的完整流程4.1 启动顺序为什么必须是HBase→Solr→Kafka→AtlasAtlas 虽然是一个独立进程但它启动时要做三件依赖外部的事情通过 ZooKeeper 找 HBase连接元数据表。通过 ZooKeeper 找 Solr验证索引集合。连接 Kafka初始化消费者和生产者。所以第一次安装时推荐的启动顺序是/opt/bigdata/hbase/bin/start-hbase.sh /opt/bigdata/solr/bin/solr start -c -z localhost:2181 /opt/bigdata/kafka/bin/kafka-server-start.sh -daemon /opt/bigdata/kafka/config/server.properties /opt/bigdata/atlas/bin/atlas_start.py从底层到上层一层层把依赖准备好。Atlas 启动时有重试机制某些组件没起来它不会立刻挂掉而是卡在连接等待上这时候你几乎看不出它在等什么加上日志刷得又慢特别容易让人以为程序没起来。按顺序启动至少能缩小排查面。4.2 atlas_start.py 执行过程会做哪些事运行启动脚本后你以为它就是一个“java -jar”实际它在后台做了不少初始化动作检查atlas-application.properties是否能正常解析。尝试连接 ZooKeeper读取 HBase 的根表。检查 Solr 集合是否可用必要时做初始化。启动 Atlas Server开始加载内置的类型定义比如 hive_table、hive_column、hdfs_path 等一大堆内置实体类型。启动 Kafka 消费者线程接收来自 Hook 的通知事件。整个初始化过程在低配机器上可能需要 2 到 5 分钟。你看到进程起来了不代表服务已经可访问正确的做法是持续看日志tail -f /opt/bigdata/atlas/logs/application.log当日志里出现类似“Atlas Server started”的日志并且 21000 端口已经有 Java 进程监听才算真正起来。期间如果看到一些 WARN 级别的连接超时先别急着打断等一等但如果是 ERROR 并伴有异常堆栈就要停下来排查。4.3 通过REST API验证安装结果UI 能打开只是第一步。我更推荐直接通过 REST API 验证因为返回结果更明确方便脚本化监控。试一下获取类型定义curl -u admin:admin http://localhost:21000/api/atlas/v2/types/typedefs | head -c 500正常情况下你会看到一大段 JSON里面包含一系列类型定义。如果返回的不是 JSON 而是错误页或者提示无权限说明认证配置或服务状态有问题。Atlas 默认管理员账号是admin/admin。如果你改了认证配置这里的密码也要对应用户名密码。4.4 停机与重启的正确方式Atlas 的停止脚本是/opt/bigdata/atlas/bin/atlas_stop.py不要动不动就kill -9。Atlas 进程里有一些 Kafka 消费者会提交消费位点HBase 写入也需要时间刷新硬杀可能导致重启后消费重复或索引状态不一致。当然测试环境无所谓但养成优雅停机的习惯对生产环境很重要。重启 Atlas 时不需要重启 HBase、Solr、Kafka直接再跑atlas_start.py即可。但如果这三个组件有过重启我习惯先确认它们的端口和 ZooKeeper 状态正常再启动 Atlas否则又会陷入等连接超时的漩涡。5. 安装中的常见坑按定位链路一个个说清楚5.1 21000端口起不来先查日志而不是查进程这个现象我见到太多次jps里能看到 Atlas 进程但浏览器访问 21000 就是打不开。很多人第一反应是杀进程重启反复几次都没用。正确思路是先看日志最后 200 行tail -200 /opt/bigdata/atlas/logs/application.log | grep -A 20 Exception常见情况是Caused by: java.net.ConnectException: Connection refused指向 HBase 的 ZooKeeper 地址。这时候先确认 HBase 是否已经注册到 ZK/opt/bigdata/hbase/bin/hbase zkcli ls /hbase能列出 HBase 节点说明 HBase 这边没问题。如果ls /hbase报节点不存在回到 2.2 节检查 HBase 是否真正启动完成而不是只看到进程存在。还有一种很隐蔽的情况HBase 2.x 的某些 jar 在 Atlas 发行包里没有直接带上日志会报ClassNotFoundException: org.apache.hadoop.hbase.HBaseConfiguration。解决方法是把 HBase 安装目录lib下的相关 jar 复制到 Atlas 的libext下。注意先复制缺失的不要把所有 jar 一把梭拷进去容易和 Atlas 自带的版本冲突。5.2 Solr集合状态不对导致查询失败Atlas 服务起来了UI 也能打开但你在搜索栏里敲表名返回结果一直转圈或报 500 错误这类问题大概率出在 Solr 集合上。先查集合列表curl http://localhost:8983/solr/admin/collections?actionLISTwtjson返回的集合列表和配置里的atlas.graph.index.search.solr.collection.*对比少哪个补哪个。这里有一个非常容易踩的坑生产环境有人会把集合名写成atlas_vertex_index配置里却是vertex_index两边差一个前缀Atlas 启动时不报错但搜索时总找不到索引。如果集合都在再看集合健康状态curl http://localhost:8983/solr/admin/collections?actionCLUSTERSTATUSwtjson重点关注shard.state是否为active。如果显示recovering或down说明副本存在异常需要等 Solr 自动恢复或者检查磁盘、ZK 连接。我处理这类问题时最麻烦的一次是 Solr 集合全部正常但 Atlas 查询还是报错最后发现是 Solr 的数据目录快满了索引写不进去导致搜索节点直接返回异常。这个方向容易忽略排查时顺手看一眼磁盘占用。5.3 Kafka consumer线程报错的定位方法Atlas 正常启动后日志里偶尔有 Kafka consumer 的报错是常见的但有一种情况特别让人抓狂Atlas 界面里看不到 Hive 表的数据日志反复出现类似“Subscription(s) X not initialized due to timeout”的提示。这通常是 Kafka Topic 没建好或者消费者组配置有问题。手动建 Topic 是性价比最高的解决办法。上面 2.4 节已经给过命令如果 Topic 已存在可以查一下消费者组消费位点/opt/bigdata/kafka/bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --list看到 group 存在后进一步查看是否有 lag/opt/bigdata/kafka/bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group group名如果 groups 列表为空说明 Atlas 的消费者线程始终没有加入 group。这时候回过去查 Atlas 日志里的atlas.kafka.bootstrap.servers是否指向正确以及 Kafka 的advertised.listeners是否配置成了别的 IP。测试环境里最常见的原因其实是/tmp下的 Kafka 日志被系统清理broker 起是新起的但 Atlas 还在按老的 offset 提交消费卡住。清理 Atlas 本地 Kafka 数据目录或重置消费者组能解决这个问题。Atlas 本地 Kafka 数据目录不可能存在因为 Atlas 不存储 Kafka data消费者 offset 默认存在 Kafka 内部 topic__consumer_offsets。 所以这里准确的说法是如果你确认是 Kafka 数据问题需要清理 Kafka 的 log.dirs 或重置消费组。我在文中可以这么写。别提到似乎就不存在“Atlas 本地 Kafka 数据目录”。我会将措辞调整为“如果 Kafka 日志目录被清理过消费者组状态对不上就重置一下消费组。” 好。5.4 HBase2后端额外JAR处理Atlas 2.2.0 的发行包里自带的 HBase 依赖和你自己装的 HBase 2.2.x 客户端可能出现版本差异。症状是 Atlas 启动到了图存储初始化那一步突然报NoSuchMethodError或ClassNotFoundException堆栈里能看到 HBase 客户端方法调用。不要急着重装 Atlas。先把 HBase 安装目录里的客户端 jar 找出来ls /opt/bigdata/hbase/lib/ | grep -E hbase|hadoop | head -50找出和 Atlaslibext下重复但版本不同的 jar优先把 HBase 侧的 jar 复制到libext。复制后重启 Atlas如果报新的冲突再把明显重复的旧版本从libext移出。这个动作说白了就是“用真实环境的 jar 覆盖发行包里的 jar”。做的时候注意两点一是先备份二是不要动 Solr 和 Kafka 相关的 jar它们一般不需要这样处理。6. 安装只是开始连接Hive与日常维护6.1 开启身份认证的注意点默认安装是 auth 关闭的Web UI 虽然会弹登录框但输入admin/admin就能进去。如果你们的 Atlas 要开放给多个团队用建议从文件认证开始而不是一上来就上 Kerberos。在配置里加上atlas.auth.enabledtrue atlas.auth.method.filetrue然后维护conf/users-credentials.json这个文件里面定义了用户名、密码和角色。这是相对轻量的方案至少能解决“谁都能改元数据”的问题。Kerberos 方案不是不行但它要求 Atlas、HBase、Solr、Kafka 这些组件全部完成 Kerberos 认证涉及的关键步骤和排错点会多出很多不建议放在首次安装时处理。先把 Atlas 本身跑稳定再加入安全层可能更符合多数团队的节奏。6.2 让Hive元数据和血缘真正进入AtlasAtlas 起来了UI 也开了但如果 Hive 的元数据还没进来它对你实际业务的价值就是零。让 Hive 元数据进入 Atlas需要确保两件事已经就位Hive 所在节点上有 Atlas 的 Hive Hook jar 并加入到 Hive 的辅助 jar 路径。Hive 的hive-site.xml里配置了hive.exec.post.hooksorg.apache.atlas.hive.hook.HiveHook。配置完成后重启 HiveServer2。接着在 Hive 里执行建表语句再回到 Atlas 的 UI 搜索这个表名应该能看到表和列信息。如果还是看不到按 5.3 节的链路查 Kafka 消费。SQL 的血缘关系不是建表后立刻完美的它需要结合 Hive 的执行计划解析所以测试时建议先用几条简单的create table ... as select语句再逐步验证复杂 SQL。6.3 定期维护备份、日志清理、Solr集合重建Atlas 安装完成只是起点日常维护比安装更重要。三个高频维护动作备份 HBase 里的 atlas 表。最简单的办法是官方自带命令。测试环境可以接受 HBase 导出生产环境则要做全链路备份规划。至少你要清楚Atlas 的实体数据在 HBase 里索引在 Solr 里两者不是一回事。日志清理。Atlas 的logs/application.log涨得非常快不加限制的话一个测试环境一年能吃掉几十 GB。配置好 logrotate 或运维平台日志采集及时归档。Solr 集合异常时重建。如果索引损坏最直接的办法是删除对应的 Solr 集合再重建然后重启 Atlas让它基于 HBase 里的实体数据重新建索引。HBase 在索引就能重建HBase 没备份才是真正的灾难。最后分享一个我自己的习惯正式安装前我会先写一个小检查脚本把 HBase 状态、Solr 集合列表、Kafka broker 列表一次性打出来确认都在了再启动 Atlas。这样能筛掉八成“看起来是 Atlas 问题其实是组件环境没就绪”的坑。你照着本文装完一遍后也会慢慢找到适合自己的检查节奏这套流程自然就成了你上手数据治理的第一步。