Apache Ambari 2.7.9 配置参数详解
Apache Ambari 2.7.9 配置参数详解：解读 ambari.properties、ambari-agent.ini 与 ambari-env.sh 关键参数，JVM 堆出厂 2048m 调至 512m 实测验证。
Apache Ambari 2.7.9 配置参数详解
目标：以一台已完成安装并运行的 CentOS 7.9 服务器为基准，逐项解读 Ambari Server 核心配置
ambari.properties、代理配置ambari-agent.ini与 JVM 启动脚本ambari-env.sh的全部实测参数，给出小规模生产模板与常见排障结论。文中文件内容与命令回显均来自实机逐字采集。
一、环境信息
- 操作系统：CentOS Linux release 7.9.2009 (Core)（x86_64）
- Apache Ambari：2.7.9（
ambari-server --version回显2.7.9.0-0，2.7 系列最终版本） - Java：OpenJDK 1.8.0_412（
java-1.8.0-openjdk-devel，JAVA_HOME 为/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.412.b08-1.el7_9.x86_64） - Python：2.7.5（Ambari Server 命令行与 Agent 均基于 Python 2 运行）
- 元数据库：内嵌 PostgreSQL 9.2.24-9.el7_9（
server.persistence.type=local） - 主机名：
ambari1.example.com（Server 与 Agent 同机部署，/etc/hosts自解析） - 服务端口：8080（Web 与 REST）、8440（Agent 注册心跳）、8441（Agent 加密通信）
- 演示账号：admin（密码已由出厂 admin 改为 q1w2e3r4）
- 运行用户：root
二、前置条件
- 已按《Apache Ambari 2.7.9 安装指南》完成 ambari-server 的安装、setup 初始化，并确认服务处于运行状态：
ambari-server status
Using python /usr/bin/python
Ambari-server status
Ambari Server running
Found Ambari Server PID: 156747 at: /var/run/ambari-server/ambari-server.pid
- 具备 root 权限；修改任何配置前先备份原文件（本文 3.3 给出备份命令）。
- 三份配置文件分布与职责：
| 文件 | 职责 | 修改后生效方式 |
|---|---|---|
/etc/ambari-server/conf/ambari.properties | Server 核心配置：数据库、路径、端口、超时、线程池 | ambari-server restart |
/var/lib/ambari-server/ambari-env.sh | Server JVM 启动参数（堆内存、GC、系统属性） | ambari-server restart |
/etc/ambari-agent/conf/ambari-agent.ini | Agent 连接 Server 的地址、端口、心跳与本地目录 | ambari-agent restart |
三、参数查看与修改方式
3.1 查看参数
Server 参数集中在 /etc/ambari-server/conf/ambari.properties，直接查看全文：
cat /etc/ambari-server/conf/ambari.properties
文件首部有一行由 setup 写入的时间戳注释（每次 setup 会重写整个文件并刷新该时间戳）：
#Tue Oct 13 11:18:23 UTC 2026
只关心某类参数时用 grep 过滤，例如查看全部数据库相关参数：
grep '^server.jdbc' /etc/ambari-server/conf/ambari.properties
server.jdbc.connection-pool=internal
server.jdbc.database=postgres
server.jdbc.database_name=ambari
server.jdbc.postgres.schema=ambari
server.jdbc.user.name=ambari
server.jdbc.user.passwd=/etc/ambari-server/conf/password.dat
3.2 修改参数与生效方式
ambari.properties与ambari-env.sh的修改均在ambari-server restart后生效；Agent 的ambari-agent.ini修改后在ambari-agent restart后生效。- ⚠️ 重新执行
ambari-server setup会按交互应答重写ambari.properties（文件首部时间戳即每次重写的痕迹），手工调整过的参数若无特殊说明会被还原，因此生产变更应直接编辑文件而非重复 setup。 - 参数均为
key=value一行一条，#开头为注释；同键重复时后一行覆盖前一行，修改时注意不要留下重复键。
3.3 修改前备份
cp /etc/ambari-server/conf/ambari.properties /etc/ambari-server/conf/ambari.properties.bak.$(date +%F)
cp /var/lib/ambari-server/ambari-env.sh /var/lib/ambari-server/ambari-env.sh.bak.$(date +%F)
cp /etc/ambari-agent/conf/ambari-agent.ini /etc/ambari-agent/conf/ambari-agent.ini.bak.$(date +%F)
ls /etc/ambari-server/conf/
ambari.properties
ambari.properties.bak.2026-10-13
krb5JAASLogin.conf
log4j.properties
metrics.properties
password.dat
四、参数总览
下表汇总实机 /etc/ambari-server/conf/ambari.properties 的全部参数（去除注释与空行后逐条采集），按前缀分组：
路径与目录类
| 参数 | 实测值 | 说明 |
|---|---|---|
metadata.path | /var/lib/ambari-server/resources/stacks | Stack 定义目录（HDP 服务编排元数据） |
common.services.path | /var/lib/ambari-server/resources/common-services | 通用服务定义目录 |
extensions.path | /var/lib/ambari-server/resources/extensions | Stack 扩展目录 |
resources.dir | /var/lib/ambari-server/resources | 资源总目录（含 views、mpacks 等） |
webapp.dir | /usr/lib/ambari-server/web | Web 控制台前端文件目录 |
pid.dir | /var/run/ambari-server | Server PID 文件目录 |
bootstrap.dir | /var/run/ambari-server/bootstrap | 向导装 Agent 时的引导工作目录 |
server.tmp.dir | /var/lib/ambari-server/data/tmp | 服务端临时目录 |
recommendations.dir | /var/run/ambari-server/stack-recommendations | Stack 推荐结果输出目录 |
mpacks.staging.path | /var/lib/ambari-server/resources/mpacks | Management Pack 安装暂存目录 |
shared.resources.dir | /usr/lib/ambari-server/lib/ambari_commons/resources | Server 与 Agent 共享资源目录 |
server.version.file | /var/lib/ambari-server/resources/version | 版本文件位置 |
stackadvisor.script | /var/lib/ambari-server/resources/scripts/stack_advisor.py | Stack 配置推荐脚本 |
bootstrap.script | /usr/lib/ambari-server/lib/ambari_server/bootstrap.py | 引导安装 Agent 的执行脚本 |
bootstrap.setup_agent.script | /usr/lib/ambari-server/lib/ambari_server/setupAgent.py | 节点上安装 Agent 的脚本 |
custom.action.definitions | /var/lib/ambari-server/resources/custom_action_definitions | 自定义动作定义目录 |
kerberos.keytab.cache.dir | /var/lib/ambari-server/data/cache | Kerberos keytab 缓存目录 |
security.server.keys_dir | /var/lib/ambari-server/keys | Server 与 Agent 通信的 CA 证书与密钥目录 |
数据库类（server.jdbc.* 与 local.database.user）
| 参数 | 实测值 | 说明 |
|---|---|---|
server.persistence.type | local | 持久化类型，local 为内嵌数据库 |
server.jdbc.database | postgres | 数据库类型 |
server.jdbc.database_name | ambari | 数据库名 |
server.jdbc.postgres.schema | ambari | PostgreSQL schema 名 |
server.jdbc.user.name | ambari | 数据库用户名 |
server.jdbc.user.passwd | /etc/ambari-server/conf/password.dat | 数据库密码所在文件（非明文写在配置里） |
local.database.user | postgres | 本机 PostgreSQL 管理超级用户 |
server.jdbc.connection-pool | internal | 连接池实现（详见 5.2 拓展） |
Server 运行行为类
| 参数 | 实测值 | 说明 |
|---|---|---|
ambari-server.user | root | Server 运行账号 |
ambari.python.wrap | ambari-python-wrap | Python 包装器名（兼容 python2/python3 环境） |
server.os_family | redhat7 | 目标节点 OS 家族（决定 Agent 安装与仓库选择） |
server.os_type | centos7 | 目标节点 OS 类型 |
server.task.timeout | 1200 | Server 侧任务超时（秒） |
agent.task.timeout | 900 | Agent 执行命令超时（秒） |
agent.package.install.task.timeout | 1800 | Agent 安装软件包任务超时（秒） |
server.stages.parallel | true | 多阶段请求并行执行 |
server.execution.scheduler.isClustered | false | 定时任务调度是否集群化（多 Server 时开启） |
server.execution.scheduler.maxThreads | 5 | 执行调度线程数 |
server.execution.scheduler.maxDbConnections | 5 | 调度器数据库连接上限 |
server.execution.scheduler.misfire.toleration.minutes | 480 | 错过触发容忍窗口（分钟） |
client.threadpool.size.max | 25 | 客户端请求线程池上限 |
agent.threadpool.size.max | 25 | Agent 通信线程池上限 |
server.connection.max.idle.millis | 900000 | 连接最大空闲时间（毫秒，15 分钟） |
server.http.session.inactive_timeout | 1800 | Web 会话不活动超时（秒，30 分钟） |
agent.stack.retry.on_repo_unavailability | false | 仓库不可用时是否重试 |
agent.stack.retry.tries | 5 | 仓库重试次数 |
check_database_skipped | false | 启动时是否跳过数据库一致性检查 |
skip.service.checks | false | 部署时是否跳过服务检查 |
rolling.upgrade.skip.packages.prefixes | （空） | 滚动升级时跳过的包名前缀 |
recommendations.artifacts.lifetime | 1w | 推荐产物保留时长（1 周） |
ulimit.open.files | 65536 | Server 进程打开文件数上限 |
server.fqdn.service.url | http://169.254.169.254/latest/meta-data/public-hostname | 云元数据服务取主机名的地址（云上部署用） |
server.python.log.level | INFO | Server 命令行脚本日志级别 |
server.python.log.name | ambari-server-command.log | 命令行脚本日志文件名 |
JDK 类
| 参数 | 实测值 | 说明 |
|---|---|---|
java.home | /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.412.b08-1.el7_9.x86_64 | setup -j 写入的本机 JDK 路径 |
stack.java.home | 同上 | 部署集群服务时下发到节点的 JDK 路径 |
java.releases | jdk1.8 | 支持的 JDK 大版本列表 |
java.releases.ppc64le | （空） | PowerPC 架构 JDK 列表（未启用） |
jdk1.8.desc | Oracle JDK 1.8 + Java Cryptography Extension (JCE) Policy Files 8 | JDK 选项描述（setup 交互展示用） |
jdk1.8.url | http://public-repo-1.hortonworks.com/ARTIFACTS/jdk-8u112-linux-x64.tar.gz | 联网下载 JDK 的地址（当前不可达，见 7.1） |
jdk1.8.dest-file | jdk-8u112-linux-x64.tar.gz | 下载保存的文件名 |
jdk1.8.home | /usr/jdk64/ | 联网安装时 JDK 解压目标目录 |
jdk1.8.re | (jdk.*)/jre | 从解压目录识别 JAVA_HOME 的正则 |
jdk1.8.jcpol-url | http://public-repo-1.hortonworks.com/ARTIFACTS/jce_policy-8.zip | JCE 策略文件下载地址（当前不可达） |
jdk1.8.jcpol-file | jce_policy-8.zip | JCE 策略文件名 |
jdk.download.supported | true | 是否支持联网下载 JDK |
jce.download.supported | true | 是否支持联网下载 JCE |
HTTP 响应头与 View 类
| 参数 | 实测值 | 说明 |
|---|---|---|
http.cache-control / views.http.cache-control | no-store | 控制台与 View 的缓存策略响应头 |
http.charset / views.http.charset | utf-8 | 默认字符集响应头 |
http.pragma / views.http.pragma | no-cache | Pragma 响应头 |
http.strict-transport-security / views.http.strict-transport-security | max-age=31536000 | HSTS 响应头 |
http.x-content-type-options / views.http.x-content-type-options | nosniff | 禁止 MIME 嗅探 |
http.x-frame-options | DENY | 控制台禁止被嵌入 iframe |
views.http.x-frame-options | SAMEORIGIN | View 页面仅允许同源嵌入 |
http.x-xss-protection / views.http.x-xss-protection | 1; mode=block | 浏览器 XSS 过滤 |
views.request.connect.timeout.millis | 5000 | View 请求连接超时 |
views.request.read.timeout.millis | 10000 | View 请求读取超时 |
views.ambari.request.connect.timeout.millis | 30000 | Ambari View 连接超时 |
views.ambari.request.read.timeout.millis | 45000 | Ambari View 读取超时 |
views.skip.home-directory-check.file-system.list | wasb,adls,adl | 跳过家目录检查的文件系统类型 |
安全与 Kerberos 类
| 参数 | 实测值 | 说明 |
|---|---|---|
gpl.license.accepted | false | 未接受 GPL（LZO 组件随 setup 交互写入） |
jce.download.supported | true | 同上 JDK 类 |
security.server.disabled.ciphers | （TLS 套件长列表） | Server 与 Agent 通道禁用的弱加密套件 |
kerberos.operation.verify.kdc.trust | true | Kerberos 操作时校验 KDC 可信 |
user.inactivity.timeout.default | 0 | 用户不活动强制登出（0 为不启用） |
user.inactivity.timeout.role.readonly.default | 0 | 只读角色不活动超时（0 为不启用） |
Agent 侧参数位于 /etc/ambari-agent/conf/ambari-agent.ini，总览见 5.4。
五、核心参数分类详解
5.1 Server 核心参数
server.persistence.type=local：持久化类型。local 表示使用本机内嵌 PostgreSQL；采用外部数据库时该值变为 remote，同时 ambari.properties 会新增 server.jdbc.url、server.jdbc.driver 等参数（见 5.2）。
server.os_family / server.os_type：向导安装 Agent 时在目标节点上选择软件仓库与包名的依据。本机实测为 redhat7 / centos7；混合操作系统集群（如混有 Ubuntu 节点）时，Ambari 会按节点实际的 os_family 匹配 stack 仓库定义，该值与节点系统不符会导致 Agent 安装或服务包下载失败（见 7.5）。
metadata.path=/var/lib/ambari-server/resources/stacks：Stack 元数据根目录。Ambari 2.7.9 默认携带 HDP 系列定义，实机目录内容：
ls /var/lib/ambari-server/resources/stacks
HDP hooks repo_templates repo_install_scripts
自定义服务（Custom Service）即以新增 HDP/<版本>/services/<服务名> 目录的方式接入，改错此参数会直接导致 Web 控制台读不到任何 Stack。
webapp.dir=/usr/lib/ambari-server/web：Web 控制台静态资源目录（Ember.js 前端产物）。浏览器看到的登录页与全部界面均来自这里，升级 ambari-web RPM 时由包管理器更新。
pid.dir=/var/run/ambari-server：PID 文件目录，ambari-server status 就是通过读取该目录下 ambari-server.pid 判断进程存活（见「一」中 status 回显的 Found Ambari Server PID 行）。目录被清理会导致 status 误判 not running，重启服务即可重建。
ulimit.open.files=65536：Server 启动时自动设置的打开文件数。管理大规模集群（数千文件句柄）时按需调大，改后 restart 生效：
grep '^ulimit' /etc/ambari-server/conf/ambari.properties
ulimit.open.files=65536
超时三件套 server.task.timeout / agent.task.timeout / agent.package.install.task.timeout：分别为 Server 等待任务完成、Agent 执行单条命令、Agent 安装软件包的超时秒数（实测 1200 / 900 / 1800）。大规模集群首次部署装包慢，报 Task timed out 时优先调大第三个。
client.threadpool.size.max / agent.threadpool.size.max（均 25）：REST 请求处理与 Agent 通信两条线程池的上限，20 节点规模无需调整；数百节点并发心跳时同步调大，并确认数据库连接数（server.execution.scheduler.maxDbConnections）跟得上。
bootstrap.dir 与 recommendations.dir：均位于 /var/run 之下，属运行时可清理数据（引导过程记录与 Stack 推荐产物）；recommendations.artifacts.lifetime=1w 控制推荐产物自动清理周期。
5.2 数据库相关参数（server.jdbc.*）
内嵌 PostgreSQL 模式下的全部实测参数：
grep -E '^(server.jdbc|local.database)' /etc/ambari-server/conf/ambari.properties
local.database.user=postgres
server.jdbc.connection-pool=internal
server.jdbc.database=postgres
server.jdbc.database_name=ambari
server.jdbc.postgres.schema=ambari
server.jdbc.user.name=ambari
server.jdbc.user.passwd=/etc/ambari-server/conf/password.dat
| 参数 | 解读 |
|---|---|
server.persistence.type=local | 内嵌模式总开关；外部数据库时为 remote |
server.jdbc.database=postgres | 数据库引擎类型（postgres 或 mysql） |
server.jdbc.database_name=ambari | 库名，setup 建库时使用 |
server.jdbc.postgres.schema=ambari | schema 名，表全部建在其下 |
server.jdbc.user.name=ambari | 应用连接账号 |
server.jdbc.user.passwd=/etc/ambari-server/conf/password.dat | 密码不落明文，存于该文件（权限 600，属主 root） |
local.database.user=postgres | 内嵌模式下本机 PostgreSQL 超级用户，setup/initdb 使用 |
server.jdbc.connection-pool=internal | 连接池实现（见下方拓展） |
💡 技术拓展：连接池与数据库选型。
server.jdbc.connection-pool支持internal（Ambari 内置 c3p0 封装，内嵌库默认）、c3p0与hikari（外部库可显式指定，hikari 性能更好）。数据库侧：内嵌 PostgreSQL 由 RPM 依赖自动安装、零额外运维，适合管理与小规模集群；节点数百规模或需要高可用时应改为外部 PostgreSQL / MySQL——setup 时对Enter advanced database configuration回答y即进入外部库配置流程，完成后ambari.properties会从server.persistence.type=local变为remote，并新增server.jdbc.url（如jdbc:postgresql://<db主机>:5432/ambari）、server.jdbc.driver（如org.postgresql.Driver）与server.jdbc.properties等参数，JDBC 驱动 jar 放在/usr/share/java/下（内嵌模式实测已有postgresql-jdbc.jar由 RPM 自动装入）。
实机验证数据库密码文件权限（防止被普通用户读取）：
ls -l /etc/ambari-server/conf/password.dat
-rw------- 1 root root 10 Oct 13 11:18 /etc/ambari-server/conf/password.dat
5.3 安全认证相关参数
实机默认采用 Ambari 本地账号认证（用户与密码哈希存于元数据库 users 表），因此 ambari.properties 中没有出现认证方式参数；与安全直接相关的实测参数如下：
| 参数 | 实测值 | 解读 |
|---|---|---|
security.server.keys_dir=/var/lib/ambari-server/keys | CA 根证书、Server 密钥与各 Agent 签发证书所在目录，8440/8441 双向认证的基础 | |
security.server.disabled.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384|... | 通道禁用的弱套件长列表（3DES、匿名 DH、EXPORT 级等），无需修改 | |
kerberos.keytab.cache.dir=/var/lib/ambari-server/data/cache | 启用 Kerberos 后 keytab 的服务端缓存目录 | |
kerberos.operation.verify.kdc.trust=true | 执行 Kerberos 化操作前校验 KDC 连通可信 | |
gpl.license.accepted=false | GPL（LZO）许可未接受；接受后 setup 写入 true 并允许装 LZO | |
http.x-frame-options=DENY 等响应头族 | 见「四、参数总览」HTTP 组，控制台默认安全响应头 |
当需要接入企业认证时，通过对应子命令初始化并写入参数：ambari-server setup-ldap（写入 client.security=ldap 及 authentication.ldap.* 一族）、ambari-server setup-pam（写入 client.security=pam）、ambari-server setup-kerberos、ambari-server setup-sso / setup-trusted-proxy（SSO 场景）。执行后同样以 ambari-server restart 生效，命令详解见《Apache Ambari 2.7.9 常用 CLI 命令与工具详解》。
💡 技术拓展：Ambari 认证方式对比。
client.security取值决定登录链路：db（默认，本地 users 表，本文演示账号 admin 即此类）、ldap（对接 Active Directory/OpenLDAP，authentication.ldap.primaryUrl等参数控制）、pam（操作系统账号）。Web 与 REST 层面另有 Kerberos SPNEGO 免密与 trusted proxy 两种 SSO 形态。多方式不并存——client.security单值生效，切换认证方式务必先备份ambari.properties并确认本地 admin 账号可用，避免锁死管理入口。
5.4 Agent 侧参数（ambari-agent.ini）
Agent 配置采用 ini 分节格式，实机全文如下（; 为注释）：
cat /etc/ambari-agent/conf/ambari-agent.ini
[server]
hostname=ambari1.example.com
url_port=8440
secured_url_port=8441
connect_retry_delay=10
max_reconnect_retry_delay=30
[agent]
logdir=/var/log/ambari-agent
piddir=/var/run/ambari-agent
prefix=/var/lib/ambari-agent/data
;loglevel=(DEBUG/INFO)
loglevel=INFO
data_cleanup_interval=86400
data_cleanup_max_age=2592000
data_cleanup_max_size_MB = 100
ping_port=8670
cache_dir=/var/lib/ambari-agent/cache
tolerate_download_failures=true
run_as_user=root
parallel_execution=0
; 0 - don't report commands output periodically. Reduces bandwidth on big cluster
command_update_output=1
alert_reports_interval=5
command_reports_interval=5
status_commands_run_interval=20
alert_grace_period=5
status_command_timeout=5
; (send_alert_changes_only) - enabling this is necessary to deploy big perf clusters
send_alert_changes_only=0
alert_kinit_timeout=14400000
system_resource_overrides=/etc/resource_overrides
; memory_threshold_soft_mb=400
; memory_threshold_hard_mb=1000
; ignore_mount_points=/mnt/custom1,/mnt/custom2
[security]
keysdir=/var/lib/ambari-agent/keys
server_crt=ca.crt
passphrase_env_var_name=AMBARI_PASSPHRASE
ssl_verify_cert=0
credential_lib_dir=/var/lib/ambari-agent/cred/lib
credential_conf_dir=/var/lib/ambari-agent/cred/conf
credential_shell_cmd=org.apache.hadoop.security.alias.CredentialShell
[network]
; this option apply only for Agent communication
use_system_proxy_settings=true
[services]
pidLookupPath=/var/run/
[heartbeat]
state_interval_seconds=60
dirs=/etc/hadoop,/etc/hadoop/conf,/etc/hbase,/etc/hcatalog,/etc/hive,/etc/oozie,
/etc/sqoop,
/var/run/hadoop,/var/run/zookeeper,/var/run/hbase,/var/run/templeton,/var/run/oozie,
/var/log/hadoop,/var/log/zookeeper,/var/log/hbase,/var/run/templeton,/var/log/hive
; 0 - unlimited
log_max_symbols_size=900000
idle_interval_min=1
idle_interval_max=10
[logging]
syslog_enabled=0
逐段解读：
[server] 段（Agent 与 Server 的连接）
| 参数 | 实测值 | 解读 |
|---|---|---|
hostname | ambari1.example.com | Server 主机名，跨机部署改为 Server 的 IP 或主机名 |
url_port | 8440 | 注册与心跳端口（明文 TLS 协商通道） |
secured_url_port | 8441 | 双向认证后的加密通信端口 |
connect_retry_delay | 10 | 断线重连起始间隔（秒） |
max_reconnect_retry_delay | 30 | 重连间隔上限（秒） |
💡 技术拓展：8440 与 8441 的分工。Agent 首次启动走 8440 完成注册（向 Server 请求证书签名，
[security] keysdir存放 CA 与证书），随后切换到 8441 双向认证通道收发命令与心跳。防火墙策略需同时放行两个端口；仅通 8440 时 Agent 能注册但无法执行任务。
[agent] 段（本地运行行为）
| 参数 | 实测值 | 解读 |
|---|---|---|
logdir / piddir | /var/log/ambari-agent、/var/run/ambari-agent | 日志与 PID 目录 |
prefix | /var/lib/ambari-agent/data | Agent 数据目录（已执行命令记录等） |
loglevel | INFO | 日志级别，排障时改 DEBUG |
data_cleanup_interval / data_cleanup_max_age / data_cleanup_max_size_MB | 86400 / 2592000 / 100 | 数据目录清理周期（天/秒）、最大保留 30 天、单文件上限 100MB |
ping_port | 8670 | Agent 进程本地探活端口 |
cache_dir | /var/lib/ambari-agent/cache | Server 下发命令的缓存目录 |
tolerate_download_failures | true | 资源下载失败时容忍并继续上报 |
run_as_user | root | Agent 执行命令的身份 |
parallel_execution | 0 | 命令串行执行（1 为并行） |
command_update_output | 1 | 周期性上报命令输出（0 可降低大集群带宽） |
alert_reports_interval / command_reports_interval / status_commands_run_interval | 5 / 5 / 20 | 告警上报、命令结果上报、状态命令执行周期（秒） |
alert_grace_period / status_command_timeout | 5 / 5 | 告警宽限与状态命令超时（秒） |
send_alert_changes_only | 0 | 仅上报变化告警（大集群置 1 省带宽） |
alert_kinit_timeout | 14400000 | Kerberos 化告警 kinit 凭据有效期（毫秒，4 小时） |
system_resource_overrides | /etc/resource_overrides | 系统资源覆写文件路径 |
memory_threshold_soft_mb / memory_threshold_hard_mb（注释态） | 400 / 1000 | Agent 自身内存软/硬阈值，默认注释不生效 |
ignore_mount_points（注释态） | （空） | 排除不需要监控的挂载点 |
[security] / [network] / [services] / [heartbeat] / [logging] 段
| 参数 | 实测值 | 解读 |
|---|---|---|
keysdir | /var/lib/ambari-agent/keys | 本机证书与 CA 存放目录 |
server_crt | ca.crt | 服务端 CA 证书文件名 |
passphrase_env_var_name | AMBARI_PASSPHRASE | 通信口令的环境变量名（与 Server 侧 ambari-env.sh 中同名变量配对） |
ssl_verify_cert | 0 | 不校验 CA 证书链（1 为严格校验） |
credential_lib_dir / credential_conf_dir / credential_shell_cmd | /var/lib/ambari-agent/cred/lib、/var/lib/ambari-agent/cred/conf、org.apache.hadoop.security.alias.CredentialShell | 凭据仓库（credential store）支持组件 |
use_system_proxy_settings | true | Agent 通信沿用系统代理配置 |
pidLookupPath | /var/run/ | Agent 查找所管服务 PID 文件的根路径 |
state_interval_seconds | 60 | 组件状态快照上报周期（秒） |
dirs | /etc/hadoop,...（多行） | 心跳时采集配置变更的目录清单（含换行续行） |
log_max_symbols_size | 900000 | 日志回传截断上限（0 为不限） |
idle_interval_min / idle_interval_max | 1 / 10 | 空闲期心跳随机间隔（秒） |
syslog_enabled | 0 | 不转发日志到 syslog |
修改示例：把心跳状态上报收紧到 30 秒（两端排障时常用）：
sed -i 's/^state_interval_seconds=60/state_interval_seconds=30/' /etc/ambari-agent/conf/ambari-agent.ini
grep '^state_interval_seconds' /etc/ambari-agent/conf/ambari-agent.ini
state_interval_seconds=30
ambari-agent restart
Restarting ambari-agent
Verifying Python version compatibility...
Using python /usr/bin/python
Found ambari-agent PID: 154637
Stopping ambari-agent
Removing PID file at /run/ambari-agent/ambari-agent.pid
ambari-agent successfully stopped
Verifying Python version compatibility...
Using python /usr/bin/python
Checking for previously running Ambari Agent...
Checking ambari-common dir...
Starting ambari-agent
Verifying ambari-agent process status...
Ambari Agent successfully started
Agent PID at: /run/ambari-agent/ambari-agent.pid
Agent out at: /var/log/ambari-agent/ambari-agent.out
Agent log at: /var/log/ambari-agent/ambari-agent.log
5.5 JVM 内存参数（ambari-env.sh）
ambari-server 本体是一个 JVM 进程（org.apache.ambari.server.controller.AmbariServer），其启动参数集中在 /var/lib/ambari-server/ambari-env.sh。实机文件全文：
cat /var/lib/ambari-server/ambari-env.sh
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
AMBARI_PASSPHRASE="DEV"
export AMBARI_JVM_ARGS="$AMBARI_JVM_ARGS -Xms256m -Xmx512m -XX:MaxPermSize=128m -Djava.security.auth.login.config=$ROOT/etc/ambari-server/conf/krb5JAASLogin.conf -Djava.security.krb5.conf=/etc/krb5.conf -Djavax.security.auth.useSubjectCredsOnly=false -Dcom.sun.jndi.ldap.connect.pool.protocol=\"plain ssl\" -Dcom.sun.jndi.ldap.connect.pool.maxsize=20 -Dcom.sun.jndi.ldap.connect.pool.timeout=300000"
export PATH=$PATH:$ROOT/var/lib/ambari-server
export PYTHONPATH=$ROOT/usr/lib/ambari-server/lib:$PYTHONPATH
# customize python binary for ambari
# export PYTHON=/usr/bin/python2
# to add additional directory or jar to server classpath use SERVER_CLASSPATH variable
# export SERVER_CLASSPATH=/etc/hadoop/conf/secure
逐项解读：
| 变量 | 解读 |
|---|---|
AMBARI_PASSPHRASE="DEV" | Server 与 Agent 通信口令，出厂值 DEV；Agent 侧 [security] passphrase_env_var_name 与之配对。改值需同步到所有 Agent 并重启两端 |
AMBARI_JVM_ARGS | JVM 全部启动参数；RPM 出厂堆为 -Xms512m -Xmx2048m -XX:MaxPermSize=128m -XX:+UseConcMarkSweepGC ...，实机已改为 -Xms256m -Xmx512m（过程见下） |
-Dcom.sun.jndi.ldap.connect.pool.* | LDAP 连接池属性（协议、上限 20、超时 300 秒），LDAP 认证场景使用 |
-Djava.security.auth.login.config / -Djava.security.krb5.conf | JAAS 与 Kerberos 配置入口 |
PATH / PYTHONPATH 追加 | Server 命令行脚本运行环境 |
SERVER_CLASSPATH（注释态） | 追加第三方 jar 到 Server classpath（如外部数据库驱动） |
JVM 堆从出厂 2048m 调整为 512m 的实测闭环。 Ambari 是管理平面，自身负载有限，出厂 -Xmx2048m 在中小规模环境偏大，实测调整为 256-512MB 区间并验证生效。
第一步，确认出厂值（grep 定位，jps -v 看运行中进程的实际参数）：
grep -n 'AMBARI_JVM_ARGS' /var/lib/ambari-server/ambari-env.sh
18:export AMBARI_JVM_ARGS="$AMBARI_JVM_ARGS -Xms512m -Xmx2048m -XX:MaxPermSize=128m -Djava.security.auth.login.config=$ROOT/etc/ambari-server/conf/krb5JAASLogin.conf -Djava.security.krb5.conf=/etc/krb5.conf -Djavax.security.auth.useSubjectCredsOnly=false -Dcom.sun.jndi.ldap.connect.pool.protocol=\"plain ssl\" -Dcom.sun.jndi.ldap.connect.pool.maxsize=20 -Dcom.sun.jndi.ldap.connect.pool.timeout=300000"
jps -v | grep AmbariServer
156268 AmbariServer -XX:NewRatio=3 -XX:+UseConcMarkSweepGC -XX:-UseGCOverheadLimit -XX:CMSInitiatingOccupancyFraction=60 -XX:+CMSClassUnloadingEnabled -Dsun.zip.disableMemoryMapping=true -Xms512m -Xmx2048m -XX:MaxPermSize=128m -Djava.security.auth.login.config=/etc/ambari-server/conf/krb5JAASLogin.conf -Djava.security.krb5.conf=/etc/krb5.conf -Djavax.security.auth.useSubjectCredsOnly=false -Dcom.sun.jndi.ldap.connect.pool.protocol=plain ssl -Dcom.sun.jndi.ldap.connect.pool.maxsize=20 -Dcom.sun.jndi.ldap.connect.pool.timeout=300000
第二步，sed 修改堆参数：
sed -i 's/-Xms512m -Xmx2048m/-Xms256m -Xmx512m/' /var/lib/ambari-server/ambari-env.sh
grep -o '\-Xms[0-9]*m -Xmx[0-9]*m' /var/lib/ambari-server/ambari-env.sh
-Xms256m -Xmx512m
第三步，重启使参数生效（restart = stop + start 全程回显）：
ambari-server restart
Using python /usr/bin/python
Restarting ambari-server
Waiting for server stop...
Ambari-server failed to stop gracefully. Sending SIGKILL to it
Ambari Server stopped
Ambari Server running with administrator privileges.
Organizing resource files at /var/lib/ambari-server/resources...
Ambari database consistency check started...
Server PID at: /var/run/ambari-server/ambari-server.pid
Server out at: /var/log/ambari-server/ambari-server.out
Server log at: /var/log/ambari-server/ambari-server.log
Waiting for server start...............
Server started listening on 8080
DB configs consistency check: no errors and warnings were found.
Ambari Server 'start' completed successfully.
注：
Sending SIGKILL一行是否出现取决于 JVM 在优雅停机等待窗口内能否自行退出，超时则强制结束，属正常现象；等待窗口长短随环境略有差异。
第四步，ps 确认新参数已在进程命令行中（输出节选运行中的 AmbariServer 进程行）：
ps -ef | grep [j]ava
root 156747 1 99 13:22 ? 00:00:33 /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.412.b08-1.el7_9.x86_64/bin/java -server -XX:NewRatio=3 -XX:+UseConcMarkSweepGC -XX:-UseGCOverheadLimit -XX:CMSInitiatingOccupancyFraction=60 -XX:+CMSClassUnloadingEnabled -Dsun.zip.disableMemoryMapping=true -Xms256m -Xmx512m -XX:MaxPermSize=128m -Djava.security.auth.login.config=/etc/ambari-server/conf/krb5JAASLogin.conf -Djava.security.krb5.conf=/etc/krb5.conf -Djavax.security.auth.useSubjectCredsOnly=false -Dcom.sun.jndi.ldap.connect.pool.protocol=plain ssl -Dcom.sun.jndi.ldap.connect.pool.maxsize=20 -Dcom.sun.jndi.ldap.connect.pool.timeout=300000 -cp /etc/ambari-server/conf:/usr/lib/ambari-server/*:/usr/share/java/postgresql-jdbc.jar org.apache.ambari.server.controller.AmbariServer
-Xms256m -Xmx512m 生效确认。注意命令行中同时可见 classpath 含 /usr/share/java/postgresql-jdbc.jar——这就是 5.2 提到的 JDBC 驱动实际加载位置。
💡 技术拓展：
-XX:MaxPermSize=128m是 JDK 8 的永久代（PermGen）上限，JDK 8 中仍有效；升级到 JDK 11+ 后该参数会被移除（改为 Metaspace 的-XX:MaxMetaspaceSize）。Ambari 2.7.x 官方仅支持 JDK 8，因此保持该参数不动即可。
六、生产配置模板
适用场景：8GB 内存的管理节点、管理规模 ≤20 节点、内嵌 PostgreSQL、JDK 8。以下仅列出与出厂默认不同的建议项（其余参数保持安装后的 ambari.properties 原样即可）：
# /etc/ambari-server/conf/ambari.properties 追加或修改项
ulimit.open.files=65536
client.threadpool.size.max=25
agent.threadpool.size.max=25
server.execution.scheduler.maxThreads=5
server.execution.scheduler.maxDbConnections=5
agent.package.install.task.timeout=1800
check_database_skipped=false
# /var/lib/ambari-server/ambari-env.sh：堆限制在 256~512MB
sed -i 's/-Xms512m -Xmx2048m/-Xms256m -Xmx512m/' /var/lib/ambari-server/ambari-env.sh
| 调整项 | 理由 |
|---|---|
JVM 堆 -Xms256m -Xmx512m | 管理平面实测负载低，512MB 堆足够；省出的内存留给节点上的大数据服务 |
ulimit.open.files=65536 | 与出厂一致，显式固化，避免被系统默认 1024 覆盖 |
| 线程池 25 / 调度 5 | 20 节点规模实测默认值即可，显式写出便于扩容时对照调整 |
| 安装超时 1800 秒 | 大规模首次部署装包慢，预防 Task timed out |
check_database_skipped=false | 保持启动时数据库自检，尽早暴露元数据库异常 |
扩展场景备注：
- 管理 100+ 节点：
agent.threadpool.size.max与client.threadpool.size.max提至 50-100，堆提至 1024-2048MB，数据库改外部 PostgreSQL 并将server.jdbc.connection-pool设为hikari； - 管理节点与集群混部、内存紧张：堆取下限 256MB 起步，观察
/var/log/ambari-server/ambari-server.out无 FullGC/OOM 后再定； - 启用 LDAP/SSO：参数由
setup-ldap/setup-sso子命令写入，不要手抄参数（详见 5.3 拓展）。
七、常见问题
7.1 setup 交互中 JDK 下载卡住（jdk1.8.url 不可达）
现象：setup 未用 -j 指定 JDK 时会尝试从 jdk1.8.url（实测指向 public-repo-1.hortonworks.com，该源已返回 403）下载 Oracle JDK，长时间无响应。
解决：setup 时用 -j 直接指定本机已装 JDK，跳过联网下载：
ambari-server setup -j /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.412.b08-1.el7_9.x86_64
完成后 ambari.properties 中 java.home 与 stack.java.home 即为该路径（见「四、参数总览」JDK 组实测值）。
7.2 手工修改 ambari.properties 不生效
原因：配置在 Server 进程启动时一次性加载。
解决：ambari-server restart 后生效。同时注意：重新执行 ambari-server setup 会重写该文件（首部时间戳即重写痕迹），手工参数会被还原，变更管理上应把 ambari.properties 纳入备份（3.3）。
7.3 外部数据库连接失败
排查顺序：
grep '^server.jdbc' /etc/ambari-server/conf/ambari.properties确认server.persistence.type=remote且server.jdbc.url的主机、端口、库名正确；- 确认 JDBC 驱动 jar 在
/usr/share/java/（内嵌模式驱动包名postgresql-jdbc.jar，见 5.5 ps 回显中的 classpath）；MySQL 场景需手工放置mysql-connector-java.jar； - 远端库需允许管理节点 IP 访问（PostgreSQL 的
pg_hba.conf、MySQL 的授权语句）； - 连接池改
hikari时确认参数拼写为server.jdbc.connection-pool=hikari。
7.4 password.dat 权限错误
现象：Server 启动报数据库密码读取失败。
解决：该文件由 setup 生成，权限应为 600 且属主 root（实测见 5.2 末尾回显）。被误改后修复：
chown root:root /etc/ambari-server/conf/password.dat
chmod 600 /etc/ambari-server/conf/password.dat
ambari-server restart
7.5 server.os_family 与节点系统不符导致 Agent 安装失败
现象：向导安装 Agent 时报找不到可用仓库或包名。
原因：server.os_family / server.os_type（实测 redhat7 / centos7）与目标节点实际系统不匹配，Stack 仓库定义按 OS 家族选择 repo。
解决：集群内统一操作系统版本；确有混合 OS 需求时确认所用 Stack 定义包含对应 os_family 的仓库配置。
7.6 check-database 报 Persistence service was already initialized
现象：ambari-server check-database 末尾抛出异常退出：
Exception in thread "main" java.lang.Exception: Unexpected error, database check failed
at org.apache.ambari.server.checks.DatabaseConsistencyChecker.main(DatabaseConsistencyChecker.java:122)
Caused by: java.lang.IllegalStateException: Persistence service was already initialized.
说明：这是 2.7.9 检查器自身的缺陷——数据库一致性检查实际已完成（检查结论出现在 /var/log/ambari-server/ambari-server.out 中，实测为 Database consistency check result: DB_CHECK_SUCCESS），随后检查器内部重复初始化 JPA 持久化服务导致异常退出。判断数据库健康以该结论行为准，完整检查过程见 /var/log/ambari-server/ambari-server-check-database.log。
7.7 Agent 心跳丢失
现象：Web 控制台主机变红或 REST 查询心跳超时。
排查顺序：
grep -A3 '^\[server\]' /etc/ambari-agent/conf/ambari-agent.ini
[server]
hostname=ambari1.example.com
url_port=8440
secured_url_port=8441
connect_retry_delay=10
max_reconnect_retry_delay=30
hostname是否可达（ping <hostname>与/etc/hosts检查）；- 8440/8441 双端口是否放行（仅通 8440 会出现"能注册不能执行"）；
tail -f /var/log/ambari-agent/ambari-agent.log观察心跳（正常为周期性Event to server at /heartbeat行）；- 两端口令一致性：Server 侧
AMBARI_PASSPHRASE与 Agent 侧[security]段配对（见 5.4、5.5）。
八、参考链接
- Apache Ambari 官网：https://ambari.incubator.apache.org/
- Ambari 源码仓库（配置默认值见 ambari-server/src/main/python/ambari_server 与 conf 目录）：https://github.com/apache/ambari
- 2.7.9 源码包（官方归档）：https://archive.apache.org/dist/ambari/ambari-2.7.9/
- 官方文档（Ambari Reference）：https://ambari.incubator.apache.org/docs.html