纯离线环境基于Ansible自动化部署Ambari与HDP集群实战

1. 为什么纯离线场景下还要用 Ansible 部署 Ambari

很多团队第一次接触 Ambari 部署，都是在有外网的环境里，yum install一把梭，脚本跑通就完事。可一旦进了内网机房、专线隔离区或者客户现场，外网访问被彻底切断，之前那套在线安装的流程立刻全部失效。这时候你会发现，Ambari 本身依赖的组件链条长得吓人：JDK、PostgreSQL、Ambari Server、Ambari Agent、HDP 仓库、各种 Python 依赖、甚至yum的元数据缓存，任何一环缺失都会让安装卡在半路。

纯离线部署的核心矛盾在于：所有依赖必须提前准备好，并且要在目标机器上以完全一致的方式落地。手工一台台拷贝 RPM 包、手动改配置文件、手动启动服务，在 3 台机器上还能忍，到了 30 台、50 台就是灾难。Ansible 在这里的价值就体现出来了——它不需要在目标机器上装 Agent（走 SSH 就行），用 YAML 描述状态，天然适合把"离线包分发 + 配置渲染 + 服务编排"这套流程固化下来。

我这次要分享的，就是一套完整的、经过实际验证的纯离线 Ambari 自动化部署方案。整套流程覆盖从本地仓库搭建、Ansible 角色设计、变量分层管理，到最终集群初始化的全过程。适合正在做大数据平台私有化交付的运维、实施工程师，也适合想理解 Ansible 在复杂中间件部署中如何落地的朋友。哪怕你之前只用过 Ansible 跑几个简单命令，跟着这套思路也能把离线部署这件事做扎实。

需要先说明一点：Ambari 这套东西版本迭代比较乱，2.7.x 和 3.x 的目录结构、依赖包差异不小。下面我以 2.7.5 + HDP 3.1.5 这个组合为例展开，其他版本思路一致，只是包名和路径要对应调整。

2. 离线部署前必须想清楚的三个前置问题

2.1 离线仓库到底放在哪台机器上

这是整套方案的地基。常见做法有三种：放在 Ansible 控制节点本地、放在目标集群的某一台机器上、或者单独搞一台内网 HTTP 服务器。我实测下来最稳的是在集群内选一台机器做本地仓库，原因很直接——Ansible 控制节点往往在办公网，和目标集群之间带宽有限，几十 GB 的 RPM 包通过 SSH 分发一次就够呛，如果每次部署都从控制节点推，效率极低。

具体做法是：先把所有离线包通过移动介质或者一次性传输放到目标集群的某台机器（比如repo-node），在这台机器上用httpd或nginx起一个静态文件服务，其他节点通过内网 HTTP 访问。这样 Ansible 只需要负责"配置 yum 源指向这台机器"，而不是"分发几十 GB 的包"。

注意：仓库机器的磁盘要留足空间。HDP 3.1.5 的完整仓库加上 Ambari 自身的包，压缩后大约 15-20 GB，解压后接近 40 GB。我见过有人只留了 20 GB，解压到一半磁盘满了，排查了半天才发现是空间问题。

2.2 目标机器的操作系统基线要不要统一

要，而且必须统一。Ambari 对操作系统的要求非常挑剔，ambari-server setup那一步会检查 OS 版本、Python 版本、JDK 版本。如果集群里混着 CentOS 7.6 和 7.9，或者有的机器 Python 是 2.7.5、有的是 2.7.18，安装过程中会出现各种诡异的报错。

我的建议是在 Ansible 里加一个前置检查角色，用assert模块强制校验：

- name: 校验操作系统版本 assert: that: - ansible_distribution == "CentOS" - ansible_distribution_version is version('7.6', '>=') - ansible_distribution_version is version('7.9', '<=') fail_msg: "操作系统版本不符合基线要求，当前为 {{ ansible_distribution }} {{ ansible_distribution_version }}"

这个检查看起来简单，但能帮你挡掉至少一半的"莫名其妙"的失败。基线不统一，后面所有自动化都是空中楼阁。

2.3 是用 Ambari 自带仓库还是自建 yum 源

Ambari 安装时可以通过ambari-server setup指定本地仓库，也可以让它走系统 yum 源。纯离线场景下，我强烈建议自建 yum 源，把所有 RPM 包（包括 JDK、PostgreSQL、Ambari、HDP）统一管理。原因是 Ambari 自带的仓库配置在离线环境下经常找不到依赖，尤其是 PostgreSQL 的驱动包和 JDK，自建源可以一次性把所有依赖补齐。

自建源还有个好处：后续升级或者打补丁时，只需要更新仓库里的包，所有节点yum update就能同步，不用重新跑一遍 Ansible 全流程。

3. Ansible 角色拆分与目录结构设计

3.1 为什么不能把所有任务塞进一个 playbook

我见过不少人的做法是写一个几百行的deploy.yml，从头到尾顺序执行。这种写法在调试阶段还行，一旦要复用或者改某个环节，就非常痛苦。Ambari 部署天然可以拆成几个独立阶段：仓库准备、基础环境、Ambari Server 安装、Ambari Agent 安装、集群初始化。每个阶段职责清晰，出问题也容易定位。

我的角色拆分是这样的：

这种拆法的好处是，每个角色可以单独跑、单独测。比如你只想重新配置 yum 源，就--tags repo单独执行，不用把整个流程重跑一遍。

3.2 目录结构长什么样

ambari-offline-deploy/ ├── ansible.cfg ├── inventory/ │ ├── hosts.ini │ └── group_vars/ │ ├── all.yml │ ├── repo_nodes.yml │ └── ambari_server.yml ├── roles/ │ ├── common/ │ ├── repo/ │ ├── jdk/ │ ├── ambari-server/ │ ├── ambari-agent/ │ └── cluster-init/ ├── files/ │ ├── jdk-8u281-linux-x64.tar.gz │ ├── ambari-2.7.5.0-centos7.tar.gz │ └── hdp-3.1.5-repo.tar.gz └── site.yml

files目录里放的是核心离线包。这里有个经验：不要把几十 GB 的包放进 Git 仓库，用.gitignore排除掉，只保留目录结构和说明文档。包通过其他方式同步到控制节点。

3.3 变量分层怎么设计才不混乱

Ansible 的变量优先级是个大坑，group_vars、host_vars、角色默认值、命令行-e传参，优先级从低到高。我的原则是：环境相关的放group_vars/all.yml，主机相关的放host_vars，角色内部的默认值只放兜底值。

比如all.yml里定义：

# 仓库节点地址 repo_server_ip: "192.168.1.100" repo_server_port: 8080 # 版本信息 ambari_version: "2.7.5.0" hdp_version: "3.1.5" jdk_version: "1.8.0_281" # 数据库配置 ambari_db_name: "ambari" ambari_db_user: "ambari" ambari_db_password: "Ambari123!"

这些变量在角色里通过{{ ambari_version }}引用，改版本只需要改一处。我踩过的坑是：早期把版本号硬编码在任务里，后来升级 HDP 版本时，满项目搜索替换，漏了一处导致安装的还是旧版本，排查了很久。

4. 本地仓库搭建与 yum 源配置的实操细节

4.1 离线包怎么组织才方便维护

拿到 Ambari 和 HDP 的离线包后，不要直接解压成一堆散文件。我的做法是按仓库类型分目录：

/var/www/html/repo/ ├── ambari/ │ └── centos7/ │ └── 2.7.5.0-72/ ├── hdp/ │ └── centos7/ │ └── 3.1.5-1/ ├── hdp-utils/ │ └── centos7/ │ └── 1.1.0.22/ ├── hdp-gpl/ │ └── centos7/ │ └── 3.1.5-1/ └── extras/ ├── jdk/ └── postgresql/

每个目录下放对应的 RPM 包，然后用createrepo生成元数据。这里有个关键点：每次新增或删除 RPM 包后，必须重新执行createrepo --update，否则 yum 客户端拿到的还是旧索引，会出现"包明明在目录里但 yum 找不到"的情况。

4.2 createrepo 的正确用法

# 安装 createrepo（如果仓库节点本身也没网，需要提前准备好 rpm） yum install -y createrepo # 对每个仓库目录生成元数据 for repo_dir in /var/www/html/repo/*/centos7/*/; do createrepo "$repo_dir" done # 后续更新时用 --update 增量更新 createrepo --update /var/www/html/repo/hdp/centos7/3.1.5-1/

createrepo执行时间跟包数量有关，HDP 主仓库有上千个包，第一次生成大概要几分钟。生成完成后目录下会多一个repodata文件夹，这就是元数据。

4.3 yum 源文件怎么通过 Ansible 下发

在repo角色里，我用template模块渲染 yum 源文件：

- name: 下发 Ambari yum 源 template: src: ambari.repo.j2 dest: /etc/yum.repos.d/ambari.repo mode: '0644' when: inventory_hostname != repo_server_ip

对应的模板ambari.repo.j2：

[ambari-{{ ambari_version }}] name=Ambari {{ ambari_version }} baseurl=http://{{ repo_server_ip }}:{{ repo_server_port }}/repo/ambari/centos7/{{ ambari_version }}-72 enabled=1 gpgcheck=0 priority=1

注意gpgcheck=0，离线环境下没有 GPG 密钥，开启校验会直接失败。priority=1是为了确保多个源冲突时优先用这个。

提示：仓库节点自己不需要配置指向自己的 yum 源，用when条件排除掉，避免自己访问自己产生奇怪的问题。

4.4 验证 yum 源是否生效

配置完源之后，一定要在每台机器上验证：

yum clean all yum repolist yum list available | grep ambari

如果repolist里看不到你配置的源，或者yum list报错，八成是baseurl路径写错了，或者 HTTP 服务没起来。我遇到过httpd默认监听 80 端口被占用，改成 8080 后忘了同步改 yum 源文件，结果所有节点都连不上仓库。

5. Ambari Server 与 Agent 的离线安装编排

5.1 JDK 安装为什么不能直接用 yum

理论上yum install java-1.8.0-openjdk也能装，但 Ambari 对 JDK 版本和路径有明确要求，用系统自带的 OpenJDK 经常出现JAVA_HOME识别不到的问题。我的做法是用 Oracle JDK 的 tar 包手动解压，路径固定为/usr/java/jdk1.8.0_281，然后在/etc/profile.d/下配置环境变量。

- name: 解压 JDK unarchive: src: "{{ playbook_dir }}/files/jdk-8u281-linux-x64.tar.gz" dest: /usr/java/ remote_src: no creates: /usr/java/jdk1.8.0_281 - name: 配置 JAVA_HOME copy: content: | export JAVA_HOME=/usr/java/jdk1.8.0_281 export PATH=$JAVA_HOME/bin:$PATH dest: /etc/profile.d/java.sh mode: '0644'

creates参数很关键，它保证重复执行时不会重复解压，实现幂等。

5.2 Ambari Server 安装的静默配置

ambari-server setup是交互式的，自动化场景下必须用-s静默模式，配合--database、--java-home等参数。核心命令：

ambari-server setup -s \ --java-home=/usr/java/jdk1.8.0_281 \ --database=postgresql \ --databasehost=localhost \ --databaseport=5432 \ --databasename=ambari \ --databaseusername=ambari \ --databasepassword=Ambari123!

这里有个大坑：PostgreSQL 必须先建好库和用户，并且要配置好pg_hba.conf允许本地连接，否则ambari-server setup会在初始化数据库那一步失败。我在ambari-server角色里加了一个前置任务专门处理 PostgreSQL：

- name: 初始化 PostgreSQL 数据库 become_user: postgres shell: | psql -c "CREATE USER ambari WITH PASSWORD 'Ambari123!';" psql -c "CREATE DATABASE ambari OWNER ambari;" args: creates: /var/lib/pgsql/data/.ambari_initialized

用creates标记文件来保证只执行一次，避免重复建库报错。

5.3 Agent 安装与 Server 的关联

Agent 安装相对简单，yum install ambari-agent之后，关键是修改/etc/ambari-agent/conf/ambari-agent.ini里的hostname指向 Server：

- name: 配置 Agent 指向 Server lineinfile: path: /etc/ambari-agent/conf/ambari-agent.ini regexp: '^hostname=' line: "hostname={{ ambari_server_hostname }}" notify: restart ambari-agent

notify触发 handler 重启 Agent，保证配置生效。这里要注意：Agent 启动前 Server 必须已经在运行，否则 Agent 连不上会不断重试。我在 playbook 里用wait_for确保 Server 的 8080 端口就绪后再启动 Agent。

5.4 服务启动顺序与健康检查

整个启动顺序是：PostgreSQL → Ambari Server → Ambari Agent。每一步都要做健康检查：

- name: 等待 Ambari Server 就绪 uri: url: "http://{{ ambari_server_hostname }}:8080/api/v1/status" status_code: 200 register: result until: result.status == 200 retries: 30 delay: 10

这个uri检查会轮询 30 次，每次间隔 10 秒，最多等 5 分钟。Ambari Server 首次启动要初始化数据库，比较慢，给足时间很重要。我见过有人只等 30 秒就判定失败，其实 Server 还在初始化。

6. 集群初始化的 API 编排与踩坑记录

6.1 为什么用 API 而不是 Web 界面

Ambari 的 Web 界面点点点确实直观，但纯离线环境下，集群初始化涉及创建集群、添加主机、分配角色、安装服务等几十步操作，手工点一遍至少半小时，而且容易漏配。用 REST API 编排，整个过程可以固化成脚本，重复执行、批量交付都不在话下。

核心 API 调用顺序：

1. POST /api/v1/clusters/{cluster_name}创建集群
2. POST /api/v1/clusters/{cluster_name}/hosts/{hostname}添加主机
3. POST /api/v1/clusters/{cluster_name}/services/{service}添加服务
4. PUT /api/v1/clusters/{cluster_name}应用配置并安装

6.2 创建集群的请求体怎么写

{ "Clusters": { "cluster_name": "offline-cluster", "version": "HDP-3.1.5" } }

看起来简单，但version字段必须和仓库里实际安装的版本完全一致，否则会报"版本不匹配"。这个版本号来自ambari-server的version定义文件，可以在/var/lib/ambari-server/resources/stacks/HDP/3.1/下找到。

6.3 添加主机时的常见报错

添加主机时最容易遇到的是 Agent 心跳没上报。API 返回成功不代表主机真的注册上了，需要轮询主机状态：

- name: 等待主机注册 uri: url: "http://{{ ambari_server_hostname }}:8080/api/v1/clusters/{{ cluster_name }}/hosts/{{ item }}" status_code: 200 register: host_status until: host_status.json.Hosts.host_state == "HEALTHY" retries: 60 delay: 10 loop: "{{ groups['all'] }}"

如果主机一直处于INIT状态，通常是 Agent 和 Server 之间的时间不同步，或者/etc/hosts解析有问题。我在common角色里强制配置了 NTP 时间同步和 hosts 文件，基本杜绝了这类问题。

6.4 服务安装的依赖顺序

HDP 的服务之间有依赖关系，比如 HDFS 必须在 YARN 之前，ZooKeeper 必须在 HBase 之前。API 添加服务时如果不按顺序，会报依赖错误。我的做法是在变量里定义服务列表和顺序：

hdp_services: - ZOOKEEPER - HDFS - YARN - MAPREDUCE2 - HIVE - HBASE - SPARK

然后按顺序循环调用 API。这里有个细节：每个服务添加后要等它进入INSTALLED状态再添加下一个，否则会乱套。

6.5 我踩过的三个真实坑

第一个坑是仓库元数据没更新。有次往 HDP 仓库里补了几个包，忘了跑createrepo --update，结果安装时报"找不到包"，查了半天才发现是索引问题。

第二个坑是PostgreSQL 的pg_hba.conf没配。默认配置只允许本地 socket 连接，Ambari 走 TCP 连接被拒。改成host all all 127.0.0.1/32 md5后解决。

第三个坑是Agent 的hostname配置用了 IP 但 Server 用主机名注册。Ambari 内部用主机名做唯一标识，如果 Agent 上报的是 IP，Server 会认为是两台不同的机器。统一用主机名，并且在所有节点的/etc/hosts里做好解析，这个问题就消失了。

7. 整套流程的幂等性与重复执行保障

7.1 幂等性为什么是自动化的生命线

Ansible 的核心优势就是幂等——同一个 playbook 跑一次和跑十次，结果应该一样。但 Ambari 部署里有很多"一次性"操作，比如建库、初始化 Server、创建集群，这些操作重复执行会报错。解决办法是用creates、when条件、状态检查来包裹。

比如创建集群的 API 调用，如果集群已存在会返回 409 冲突。我在任务里先查询集群是否存在：

- name: 检查集群是否已存在 uri: url: "http://{{ ambari_server_hostname }}:8080/api/v1/clusters/{{ cluster_name }}" status_code: [200, 404] register: cluster_check - name: 创建集群 uri: url: "http://{{ ambari_server_hostname }}:8080/api/v1/clusters/{{ cluster_name }}" method: POST body_format: json body: "{{ cluster_definition }}" status_code: [201, 409] when: cluster_check.status == 404

这样即使集群已经存在，playbook 也不会报错，而是跳过创建步骤。

7.2 失败重试与断点续跑

大规模部署时，网络抖动、磁盘 IO 慢都可能导致某个任务失败。Ansible 的retries和until可以处理临时性失败，但如果是永久性失败，就需要断点续跑。我的做法是把每个阶段的完成状态记录到本地文件：

- name: 记录阶段完成状态 copy: content: "completed" dest: "/tmp/ambari_deploy_{{ stage_name }}.done"

下次执行时先检查这个文件，存在就跳过对应阶段。这在客户现场反复调试时特别有用，不用每次都从头跑。

7.3 日志收集与问题定位

Ansible 默认输出比较简洁，出问题时信息不够。我在ansible.cfg里开启了详细日志：

[defaults] log_path = /var/log/ansible/ambari-deploy.log stdout_callback = yaml display_skipped_hosts = false

同时把 Ambari Server 和 Agent 的日志路径也纳入收集范围，出问题时直接看/var/log/ambari-server/ambari-server.log和/var/log/ambari-agent/ambari-agent.log，比在 Ansible 输出里猜要快得多。

8. 交付前的验收清单与经验沉淀

8.1 一套可复用的验收检查项

部署完成后，不要急着交付，先跑一遍验收。我整理了一份检查清单，每次交付前逐项确认：

这份清单看起来繁琐，但能帮你挡掉 90% 的"交付后才发现"的问题。我吃过亏，有次交付后客户反馈某个服务起不来，一查是 Agent 没注册上，如果当时做了主机数核对，当场就能发现。

8.2 版本升级时怎么复用这套流程

这套 Ansible 流程设计时就考虑了升级场景。升级 HDP 版本时，只需要：更新files目录里的离线包、修改group_vars/all.yml里的版本号、重新跑repo角色生成新仓库、然后通过 Ambari 的升级 API 执行滚动升级。核心的 Ansible 角色逻辑完全不用动。

8.3 给后来者的几点实在建议

第一，先在虚拟机上把整套流程跑通再上生产。我见过直接在生产环境调试的，一个参数写错导致集群起不来，回滚都费劲。

第二，离线包一定要做校验。传输过程中文件损坏是常有的事，用sha256sum对比一下，能省掉很多"包明明在但装不上"的困惑。

第三，把踩过的坑写进 README。这套流程我维护了两年多，每次遇到新问题就补一条，现在这份 README 已经成了团队内部的部署手册，新人照着做基本不会翻车。

第四，Ansible 的--check模式要善用。正式执行前先 dry-run 一遍，看看哪些任务会变更，心里有数再动手。虽然 Ambari 的 API 调用在 check 模式下不一定准确，但至少能发现明显的配置错误。

这套纯离线 Ambari 自动化部署方案，从最初的脚本拼凑到现在的角色化编排，前后迭代了十几个版本。核心体会就一句话：离线部署的难点不在技术，而在把所有依赖和顺序都提前想清楚，然后用代码固化下来。Ansible 只是工具，真正值钱的是你对 Ambari 这套系统运行机制的理解，以及踩坑之后沉淀下来的那份检查清单。