企业官网建设流程全解析

1. 为什么1.1.0这个版本值得单独写一份安装方案

Apache Atlas 的版本迭代节奏不算快，但 1.1.0 这个版本在不少存量生产集群里依然是主力。原因很现实：很多公司的数据治理平台是在 2019 到 2021 年间搭建的，当时选型就落在 1.1.0 上，后面因为 HBase、Solr、Kafka 这些依赖组件的版本锁定，一直没敢往上升。所以直到现在，仍然有人需要在新机器上把 1.1.0 重新装一遍——可能是扩容、可能是迁移、也可能是灾备环境重建。

问题在于，Atlas 1.1.0 的官方文档写得比较"理想化"，它假设你的环境是干净的、依赖版本是匹配的、网络是通畅的。而真实的生产环境里，你面对的往往是：一台已经装了 JDK 8 但环境变量乱七八糟的机器、一个已经跑着其他服务的 HBase 集群、一套需要手动建 schema 的关系型数据库。这份方案就是把这些"不理想"的情况全部考虑进去，给出一套能落地、能复现、能排错的安装路径。

这篇文章适合三类人：第一类是从零开始搭 Atlas 的运维或大数据工程师；第二类是从别人手里接手了一套 Atlas、需要重新部署或迁移的开发者；第三类是正在做数据治理选型、想先在本机或测试环境跑通 Atlas 看看效果的技术负责人。不管你属于哪一类，下面的内容都会覆盖到——从依赖组件的版本选择，到配置文件里每一个容易踩坑的参数，再到启动失败时怎么一步步定位。

需要先说明一点：Atlas 1.1.0 对依赖版本相当敏感，尤其是 HBase 和 Solr。版本差一个小号，就可能出现元数据写不进去、索引查不出来的问题。所以整篇方案里，我会反复强调版本对齐这件事，这不是啰嗦，而是血泪教训。

2. 装之前必须想清楚的依赖矩阵与版本锁定

2.1 Atlas 1.1.0 到底依赖哪些外部组件

Atlas 本身不是一个"单机就能跑"的工具，它的架构决定了它必须依赖外部存储和索引。核心依赖有四块：

• 元数据存储：默认用 HBase，也可以用 Cassandra，但生产环境绝大多数选 HBase。Atlas 把实体定义、血缘关系、分类标签这些元数据都写进 HBase。
• 全文索引：用 Solr。Atlas 的搜索功能、按名称模糊查询、按分类过滤，全靠 Solr 的索引。没有 Solr，Atlas 的 UI 基本就是个摆设。
• 消息队列：用 Kafka。Atlas 通过 Kafka 接收来自 Hive、HBase、Storm 等组件的 Hook 消息，异步写入元数据。没有 Kafka，Hook 就发不出消息。
• 关系型数据库：用 MySQL 或 PostgreSQL。Atlas 自己需要一张关系库来存用户、权限、审计日志等管理类数据。

这四块缺一不可。很多人第一次装的时候只关注 Atlas 本身，结果启动到一半报错，才发现是 Kafka 没起或者 Solr 的 collection 没建。

2.2 版本对齐：为什么 HBase 1.1.x 和 Solr 5.5.x 是相对安全的选择

Atlas 1.1.0 官方推荐的组合是 HBase 1.1.x + Solr 5.5.x + Kafka 0.10.x + JDK 8。这个组合不是随便定的，而是因为 Atlas 1.1.0 内部用的 HBase client 和 Solr client 就是按这些版本编译的。

如果你用 HBase 2.x，会遇到NoSuchMethodError或者ClassNotFoundException，因为 HBase 2.x 的 API 有变动。如果你用 Solr 7.x 或 8.x，Atlas 的 Solr 索引创建脚本会直接失败，因为 Solr 的 collection API 在 6.0 之后改了。Kafka 同理，0.10.x 和 2.x 的 producer API 不兼容。

所以我的建议是：不要试图用新版本去"兼容" Atlas 1.1.0，而是老老实实按它的版本要求来。如果生产环境已经有更高版本的 HBase 或 Solr 在跑其他业务，那就给 Atlas 单独部署一套低版本的依赖，或者用容器隔离。混用是灾难的开始。

下面这张表是我实际验证过的版本组合，可以直接参考：

2.3 内存和磁盘：别让 JVM 成为第一个瓶颈

Atlas 本身是个 Java 应用，默认的 JVM 堆是 512MB，这在生产环境肯定不够。Atlas 的元数据量一大，堆内存很快就会被占满，然后就是频繁 Full GC，最后 OOM。

我的经验是：Atlas 服务端至少给 4GB 堆内存，Solr 至少给 2GB，HBase 的 RegionServer 至少给 4GB。如果元数据量特别大（比如超过百万级实体），Atlas 堆内存要加到 8GB。

磁盘方面，HBase 和 Solr 都是写密集型，建议用 SSD。如果只有机械盘，那至少要做 RAID 0 或者 RAID 10，别用单盘。Atlas 本身的日志目录也要留够空间，因为调试阶段日志会刷得很快。

3. 从零开始的安装流程：每一步都解释清楚为什么

3.1 基础环境准备：JDK、主机名、防火墙

第一步永远是 JDK。Atlas 1.1.0 只支持 JDK 8，不支持 JDK 11。安装完 JDK 后，JAVA_HOME必须正确设置，而且要注意：Atlas 的启动脚本会读取JAVA_HOME，如果这个变量指向了 JRE 而不是 JDK，启动会失败。因为 Atlas 需要用到 JDK 里的tools.jar来做一些动态编译。

主机名和 hosts 文件也容易被忽略。Atlas 在启动时会用主机名去注册服务，如果主机名解析不了，会卡在启动阶段。所以要在/etc/hosts里把本机主机名和 IP 对应上。

防火墙方面，Atlas 默认用 21000 端口（HTTP）和 21443 端口（HTTPS）。如果开了防火墙，这两个端口要放行。另外 Atlas 还要连 HBase 的 2181（ZooKeeper）、Solr 的 8983、Kafka 的 9092，这些端口也要通。

提示：如果是在云主机上部署，除了系统防火墙，还要检查安全组规则。我遇到过好几次系统防火墙关了但安全组没放行，排查了半天。

3.2 HBase 的安装与 Atlas 专用表空间

HBase 的安装这里不展开讲，假设你已经有一套可用的 HBase 1.1.x。重点讲 Atlas 对 HBase 的特殊要求。

Atlas 在 HBase 里会创建两张表：ATLAS_ENTITY和ATLAS_JANUS（如果用了 JanusGraph 作为图存储）。这两张表的列族和 TTL 都有讲究。Atlas 的安装包里带了atlas-hbase-schema脚本，但很多人不知道这个脚本在哪、怎么用。

脚本位置在atlas/conf/hbase/下面，有一个create-hbase-schema.sh。执行之前，要确保 HBase 的hbase-site.xml在 classpath 里，或者通过HBASE_CONF_DIR环境变量指定。执行完脚本后，可以用list命令在 HBase shell 里确认表是否创建成功。

还有一个坑：Atlas 默认用的 HBase 表是ATLAS_ENTITY，但如果你之前装过其他版本的 Atlas，表名可能不一样。1.1.0 用的是ATLAS_ENTITY，而 0.8 版本用的是ATLAS_TABLE。如果表名对不上，Atlas 启动时会报TableNotFoundException。

3.3 Solr 的 collection 创建：为什么不能自动建

Atlas 1.1.0 不会自动创建 Solr collection，必须手动建。这是很多人第一次装 Atlas 时最容易卡住的地方——Atlas 启动了，UI 也能打开，但搜索任何东西都报错，因为 Solr 里根本没有 collection。

创建 collection 的命令在atlas/conf/solr/下面，有一个create-solr-collection.sh。执行前要确保 Solr 已经启动，并且SOLR_HOME环境变量指向 Solr 的安装目录。

collection 的名字默认是vertex_index和edge_index。这两个名字对应 Atlas 的图存储模型：顶点索引和边索引。如果只建了一个，Atlas 启动时会报CollectionNotFoundException。

创建命令大概长这样：

# 假设 Solr 在 localhost:8983 curl "http://localhost:8983/solr/admin/collections?action=CREATE&name=vertex_index&numShards=1&replicationFactor=1&maxShardsPerNode=1&collection.configName=vertex_index"

注意collection.configName要和 Atlas 提供的配置集名字一致。Atlas 的安装包里带了vertex_index和edge_index两个配置集，需要先上传到 Solr 的 ZooKeeper 里。上传命令在atlas/conf/solr/下也有脚本。

注意：如果 Solr 是单机模式而不是 Cloud 模式，collection 的创建方式不一样。Atlas 1.1.0 推荐用 Solr Cloud 模式，因为需要 ZooKeeper 来管理配置集。单机模式虽然也能跑，但配置集上传比较麻烦。

3.4 Kafka 的 topic 准备与 Hook 消息格式

Kafka 这边相对简单，只需要确保 Kafka 集群可用，并且 Atlas 能连上。Atlas 默认用的 topic 是ATLAS_HOOK和ATLAS_ENTITIES。ATLAS_HOOK用来接收 Hook 发来的消息，ATLAS_ENTITIES用来接收 Atlas 自己产生的实体变更消息。

这两个 topic 不需要手动创建，Atlas 启动时会自动创建（如果 Kafka 允许自动创建 topic）。但如果 Kafka 关闭了自动创建，就要手动建，并且分区数建议至少 3 个，副本数根据 Kafka 集群规模定。

消息格式方面，Atlas 1.1.0 用的是 JSON 序列化。Hook 端发消息时，消息体是一个 JSON 数组，每个元素是一个实体变更事件。如果消息格式不对，Atlas 的消费者会报DeserializationException，然后消息就被丢弃了。调试的时候可以在 Kafka 消费者端手动消费一下ATLAS_HOOK，看看消息体长什么样。

3.5 Atlas 本体的配置：atlas-application.properties 逐项拆解

Atlas 的核心配置文件是atlas-application.properties，在atlas/conf/目录下。这个文件里的参数非常多，但真正影响启动和运行的就这么几类：

存储配置：atlas.graph.storage.backend默认是hbase，如果要用 Cassandra 就改成cassandra。atlas.graph.storage.hostname填 ZooKeeper 地址，多个用逗号分隔。

索引配置：atlas.graph.index.search.backend默认是solr。atlas.graph.index.search.solr.zookeeper-url填 Solr 的 ZooKeeper 地址。这里要注意，如果 Solr 和 HBase 共用同一个 ZooKeeper，要确保 chroot 路径不一样，否则会冲突。

Kafka 配置：atlas.kafka.bootstrap.servers填 Kafka 地址。atlas.kafka.zookeeper.connect填 Kafka 的 ZooKeeper 地址。这两个别搞混了，Kafka 的 bootstrap 地址是 broker 地址，不是 ZooKeeper 地址。

服务端口：atlas.server.http.port默认 21000。如果这个端口被占了，改成别的。

管理员配置：atlas.admin.user和atlas.admin.password是 Atlas 的管理员账号，默认是admin/admin。生产环境一定要改。

配置改完后，不要急着启动，先用atlas/conf/下的check-config.sh脚本检查一下配置是否有语法错误。这个脚本会读取atlas-application.properties并尝试解析，如果有拼写错误或者格式问题，会提前报出来。

4. 启动之后才是真正的战场：常见故障与排查链路

4.1 Atlas 启动卡在 "Starting Atlas Server" 不动

这是最常见的现象。Atlas 启动脚本会打印 "Starting Atlas Server"，然后就没下文了。这时候不要干等，直接去看日志。日志在atlas/logs/下面，主要是atlas.log和application.log。

如果atlas.log里最后一行是Connecting to ZooKeeper，那说明卡在连 ZooKeeper 了。检查 ZooKeeper 地址是否正确、网络是否通、ZooKeeper 是否真的在跑。

如果最后一行是Initializing graph，那可能是 HBase 连不上，或者 HBase 表没建。这时候要去application.log里找更详细的堆栈。

如果日志里出现了java.lang.OutOfMemoryError，那就是堆内存不够，去atlas-env.sh里把ATLAS_SERVER_HEAP调大。

4.2 Solr 索引查不到数据：从 collection 状态查起

Atlas 启动成功了，UI 也能打开，但搜索框里输入任何关键词都返回空。这种情况八成是 Solr 索引的问题。

第一步，去 Solr 的管理界面（http://solr-host:8983/solr）看vertex_index和edge_index两个 collection 的状态。如果状态是red或者down，说明 collection 有问题。

第二步，如果 collection 状态是green，但文档数是 0，说明 Atlas 没有把数据写进 Solr。这时候要去 Atlas 日志里搜Solr相关的报错。常见的是SolrServerException，原因可能是 Solr 的 ZooKeeper 地址配错了，或者 Solr 的配置集没上传。

第三步，如果文档数不为 0 但搜索还是空，那可能是查询语句的问题。Atlas 的搜索用的是 Solr 的edismax查询解析器，如果字段名对不上，就查不出来。这时候可以用 Solr 的admin界面手动执行一个*:*查询，看看能不能查出文档。如果能查出，说明索引里有数据，问题在 Atlas 的查询逻辑上。

4.3 Hook 消息发不出去：Kafka 生产者端的排查

Hive 或 HBase 的 Hook 配置好了，但 Atlas 里就是看不到元数据。这时候要分两步排查：先确认 Hook 有没有发消息，再确认 Atlas 有没有收到消息。

确认 Hook 发消息：在 Hive 的日志里搜AtlasHook，如果看到Sending message to Kafka，说明 Hook 在尝试发消息。如果看到Failed to send message，那就是 Kafka 连不上，检查atlas-application.properties里的 Kafka 地址。

确认 Atlas 收消息：用 Kafka 的命令行消费者消费ATLAS_HOOKtopic，看看有没有消息。如果有消息但 Atlas 没处理，那就是 Atlas 的消费者有问题，去 Atlas 日志里搜KafkaConsumer。

还有一个隐蔽的坑：Hook 端和 Atlas 端的 Kafka 版本不一致。Hook 端用的是 Hive 自带的 Kafka client，Atlas 端用的是 Atlas 自带的 Kafka client。如果两边版本差太多，消息序列化格式可能不兼容。解决办法是统一 Kafka client 版本，或者用 Atlas 提供的 Hook 库替换 Hive 自带的。

4.4 元数据写入 HBase 失败：RegionServer 的负载问题

Atlas 运行一段时间后，突然写不进元数据了，日志里报RegionServer is busy或者TimeoutException。这通常是 HBase 的 RegionServer 负载太高，或者 Region 分裂导致的。

先看 HBase 的 RegionServer 日志，确认有没有Too many open files或者GC pause过长的记录。如果有，说明 RegionServer 的资源不够，需要加内存或者加 RegionServer 节点。

如果 RegionServer 本身没问题，那可能是 Atlas 的写入批量太大。Atlas 默认的批量写入大小是 1000，如果单次写入的实体太多，会撑爆 RegionServer 的写缓冲。可以在atlas-application.properties里把atlas.graph.storage.hbase.batch.size调小，比如改成 500。

还有一个容易被忽略的点：HBase 的hbase-site.xml里zookeeper.znode.parent配置。如果 HBase 的 ZooKeeper 根路径不是默认的/hbase，Atlas 也要相应配置atlas.graph.storage.hbase.zookeeper.znode.parent。这个配置对不上，Atlas 就连不上 HBase。

5. 生产环境特有的加固与调优经验

5.1 把管理员密码和敏感配置从明文里挪出去

Atlas 1.1.0 默认把数据库密码、Kafka 密码这些敏感信息明文写在atlas-application.properties里。这在生产环境是不可接受的。Atlas 支持通过atlas-application.properties里的atlas.jaas配置来集成 Kerberos，但配置起来比较繁琐。

一个折中方案是：用环境变量替换明文密码。Atlas 的启动脚本支持读取环境变量，可以在atlas-env.sh里定义ATLAS_DB_PASSWORD，然后在atlas-application.properties里用${ATLAS_DB_PASSWORD}引用。这样密码就不在配置文件里了。

另一个方案是用配置管理工具（比如 Ansible Vault 或者 HashiCorp Vault）来管理配置文件，部署时动态生成。这个方案更彻底，但需要额外的运维投入。

5.2 JVM 调优：别让 Full GC 拖垮 Atlas

Atlas 的 JVM 调优主要是堆内存和 GC 策略。堆内存前面说了，至少 4GB。GC 策略建议用 G1，因为 Atlas 的元数据对象生命周期比较长，G1 对大堆的支持更好。

在atlas-env.sh里加上：

export ATLAS_SERVER_OPTS="-XX:+UseG1GC -XX:MaxGCPauseMillis=200 -XX:InitiatingHeapOccupancyPercent=45"

MaxGCPauseMillis设成 200 毫秒，是权衡吞吐量和延迟的结果。如果设得太小，GC 会太频繁；设得太大，单次 GC 停顿会很长。InitiatingHeapOccupancyPercent设成 45，是让 G1 在堆用到 45% 的时候就开始并发标记，避免到最后才触发 Full GC。

还要加上 GC 日志，方便出问题时排查：

export ATLAS_SERVER_OPTS="$ATLAS_SERVER_OPTS -Xloggc:/var/log/atlas/gc.log -XX:+PrintGCDetails -XX:+PrintGCDateStamps"

5.3 备份策略：元数据丢了就全完了

Atlas 的元数据都在 HBase 和 Solr 里。HBase 有自带的快照功能，可以定期对ATLAS_ENTITY表做快照。Solr 的 collection 也可以做备份，但 Solr 的备份不如 HBase 成熟，建议以 HBase 为准，Solr 索引丢了可以重建。

重建 Solr 索引的方法是：停掉 Atlas，清空 Solr 的vertex_index和edge_index，然后重启 Atlas。Atlas 启动时会从 HBase 里读取所有元数据，重新写入 Solr。这个过程可能比较慢，取决于元数据量，但至少数据不会丢。

HBase 快照的命令：

hbase shell snapshot 'ATLAS_ENTITY', 'atlas_entity_backup_20250101'

恢复的时候用clone_snapshot或者restore_snapshot。注意restore_snapshot会覆盖当前表，操作前要确认。

5.4 监控指标：哪些指标必须盯

Atlas 本身暴露了一些 JMX 指标，可以通过 JMX 客户端或者 Prometheus 的 JMX exporter 采集。必须盯的指标有：

• JVM 堆使用率：超过 80% 就要警惕，超过 90% 就要考虑扩容。
• GC 停顿时间：单次超过 1 秒就要查原因。
• Kafka 消费延迟：ATLAS_HOOKtopic 的消费 lag 如果持续增长，说明 Atlas 处理不过来。
• HBase 写入延迟：Atlas 写 HBase 的 P99 延迟超过 100 毫秒就要关注。
• Solr 查询延迟：Atlas 搜索的 P99 延迟超过 500 毫秒，用户体验就会明显下降。

这些指标可以用 Grafana 做面板，配上告警规则。告警阈值根据实际业务量调整，不要照搬网上的默认值。

6. 迁移与扩容时容易忽略的细节

6.1 迁移 Atlas 时 HBase 表怎么搬

迁移 Atlas 最麻烦的是 HBase 表。如果只是换机器但 HBase 集群不变，那简单，改一下 Atlas 的配置指向新的 HBase 就行。但如果 HBase 集群也要换，那就要搬表。

搬表的方法有两种：一是用 HBase 的Export/Import工具，二是用快照。Export/Import适合小表，快照适合大表。快照的步骤是：在原集群做快照，把快照文件复制到新集群，在新集群恢复快照。

注意：Atlas 的 HBase 表在迁移过程中必须停止写入，否则会丢数据。所以迁移前要停掉 Atlas 和所有 Hook，迁移完再启动。

6.2 扩容 Atlas 节点时 Solr 的 shard 怎么分

Atlas 支持多节点部署，多个 Atlas 实例共享同一个 HBase 和 Solr。扩容的时候，新节点加入集群，Solr 的 collection 可能需要重新分片。

Solr 的 collection 在创建时指定了numShards，这个值一旦确定就不能改了。如果要增加分片，只能重建 collection。重建的步骤是：停掉 Atlas，删除旧的 collection，用新的numShards创建新 collection，然后重启 Atlas 让数据重新索引。

所以扩容前要规划好分片数。如果预计元数据量会增长很快，一开始就把numShards设大一点，比如 4 或 8。分片多了查询会慢一点，但扩容方便。

6.3 版本升级的路径：1.1.0 能直接升到 2.x 吗

不能直接升。Atlas 1.1.0 到 2.x 的跨度太大，HBase 表结构和 Solr 索引结构都变了。官方推荐的升级路径是 1.1.0 → 1.2.0 → 2.0.0 → 2.1.0，每一步都要做数据迁移。

如果只是想升到 1.2.0，那相对简单，因为 1.2.0 和 1.1.0 的存储结构基本兼容。升级步骤是：停掉 1.1.0，替换成 1.2.0 的二进制包，启动 1.2.0，它会自动做 schema 升级。但升级前一定要备份 HBase 表，因为 schema 升级是不可逆的。

我在实际迁移中遇到过一个问题：1.1.0 的 HBase 表里有一些废弃的列族，1.2.0 启动时会尝试删除这些列族，但如果 HBase 的权限不够，删除会失败，然后 Atlas 启动就卡住了。解决办法是手动在 HBase shell 里删除这些列族，或者给 Atlas 的 HBase 用户足够的权限。

7. 一些零散但重要的实操心得

装 Atlas 这件事，说难不难，说简单也不简单。难点不在步骤多，而在细节多。下面这几条是我踩过坑之后总结出来的，每条都对应一个真实的问题。

第一条：配置文件里的空格和换行。atlas-application.properties是 Java Properties 格式，对空格和换行很敏感。如果某个参数的值后面多了一个空格，Atlas 可能解析成不同的值。比如atlas.server.http.port=21000后面多一个空格，端口就变成21000，启动时会报端口非法。所以改完配置后，用cat -A看一下有没有多余的空格。

第二条：ZooKeeper 的 chroot。如果 HBase、Solr、Kafka 共用同一个 ZooKeeper 集群，一定要用 chroot 隔离。HBase 默认的 chroot 是/hbase，Solr 是/solr，Kafka 是/kafka。Atlas 连 HBase 的时候，ZooKeeper 地址要写成zk-host:2181/hbase，连 Solr 的时候写成zk-host:2181/solr。如果漏了 chroot，Atlas 会连到 ZooKeeper 的根路径，然后找不到对应的节点。

第三条：Hook 的类路径冲突。Hive 的 Hook 和 Atlas 的 Hook 可能依赖不同版本的同一个库。比如 Hive 自带的commons-lang是 2.6，Atlas 需要 3.x。如果类路径里先加载了 Hive 的版本，Atlas 的 Hook 就会报NoSuchMethodError。解决办法是把 Atlas 的 Hook 库放在类路径的最前面，或者用-Djava.class.path显式指定。

第四条：Solr 的autoSoftCommit配置。Atlas 写入 Solr 后，默认不是立即能搜到的，因为 Solr 有 commit 延迟。如果希望写入后马上能搜到，要在 Solr 的solrconfig.xml里把autoSoftCommit的maxTime调小，比如改成 1000 毫秒。但调太小会影响性能，所以要在实时性和吞吐量之间权衡。

第五条：日志级别别开 DEBUG。Atlas 的 DEBUG 日志量非常大，开一天就能把磁盘写满。调试的时候可以临时开 DEBUG，调完马上改回 INFO。改日志级别在atlas-log4j.xml里，找到对应的 logger，把 level 从INFO改成DEBUG。

第六条：时间同步。Atlas、HBase、Solr、Kafka 这些组件之间的时间必须同步，否则会出现各种诡异的问题，比如 Kerberos 认证失败、消息时间戳乱序。生产环境一定要配 NTP，确保所有节点的时间差在 1 秒以内。

第七条：别在 Atlas 机器上跑其他重负载服务。Atlas 本身对 CPU 和内存的占用就不低，如果再跑一个 Spark 或者 Elasticsearch，资源竞争会很严重。Atlas 的机器最好专用，或者至少保证有足够的资源余量。

这些心得看起来琐碎，但每一条都是实际部署中会遇到的。Atlas 1.1.0 虽然是个老版本，但它的稳定性在存量生产环境里已经得到了验证。只要把依赖版本对齐、配置项填对、启动顺序搞对，它就能稳定运行。真正麻烦的是那些"看起来没问题"的细节，而上面这些内容，就是帮你把这些细节提前想到。