Apache Ambari 2.7.9 常用 CLI 命令与工具详解

目标：梳理 Apache Ambari 2.7.9 日常运维使用的命令行工具，覆盖 ambari-server 全部子命令与真实回显、ambari-agent 子命令、curl 调用 REST API（主机/集群/用户管理与改密）以及进程、端口、日志三件套诊断。全部命令均在 CentOS 7.9 环境逐条实测。

一、环境信息

操作系统：CentOS Linux release 7.9.2009 (Core)（x86_64）
Apache Ambari：2.7.9.0-0（Server）/ 2.7.9.0（Agent）
Java：OpenJDK 1.8.0_412（jps 可用）
Python：2.7.5（ambari-server 与 ambari-agent 命令本体是 Python 脚本）
元数据库：内嵌 PostgreSQL 9.2.24
服务端口：8080（Web/REST API）、8440/8441（Agent 通信）、5432（PostgreSQL）、8670（Agent 自检 ping）
管理账号：admin / q1w2e3r4（出厂 admin/admin 已改密）
主机名：ambari1.example.com（Server 与 Agent 同机）

二、工具概览

Ambari 2.7.9 的日常运维围绕四类工具展开：

工具/入口	位置	用途
`ambari-server`	`/usr/sbin/ambari-server`	Server 生命周期管理：setup/start/stop/status/restart/backup/restore/reset/check-database 等 26 个子命令
`ambari-agent`	`/usr/sbin/ambari-agent`	节点代理生命周期：start/stop/restart/status/reset
`curl`（REST API）	系统自带	通过 8080 端口的 REST API 查询主机/集群/用户、修改密码、触发服务操作
`jps` / `ss` / `tail`	JDK 与系统自带	进程、监听端口、日志三件套诊断

解读：ambari-server 与 ambari-agent 是本地管理入口，REST API 是唯一官方编程接口（Web 控制台本身也走这套 API）；诊断三件套用于命令失效时的底层取证。

三、前置条件

已按《Apache Ambari 2.7.9 安装指南》完成 Server 与 Agent 安装初始化，服务处于运行状态。
REST API 调用需要账号口令（本文用 admin/q1w2e3r4）与必需请求头 X-Requested-By: ambari（缺失该头 Ambari 拒绝所有写请求，防 CSRF）。
jps 命令来自 JDK，若提示 command not found，确认已安装 java-1.8.0-openjdk-devel 并在 PATH 中。
本文所有 Server 侧命令以 root 在本机执行；REST API 示例中的 127.0.0.1:8080 可替换为任意可达 Server 的地址。

四、工具详解

4.1 ambari-server 服务管理（start / stop / status / restart）

四个子命令覆盖 Server 的日常启停。启动并等待就绪：

ambari-server start

Using python  /usr/bin/python
Starting ambari-server
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.

确认状态与版本：

ambari-server status

Using python  /usr/bin/python
Ambari-server status
Ambari Server running
Found Ambari Server PID: 79677 at: /var/run/ambari-server/ambari-server.pid

ambari-server --version

2.7.9.0-0

status 的判断依据是 pid.dir（默认 /var/run/ambari-server）下的 PID 文件加进程存活校验。停止：

ambari-server stop

Using python  /usr/bin/python
Stopping ambari-server
Ambari Server stopped

重启（等价 stop + start，改完配置后用）：

ambari-server restart

Using python  /usr/bin/python
Stopping ambari-server
Ambari Server stopped
Using python  /usr/bin/python
Starting ambari-server
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.

HTTP 探活验证（任何启停操作后的最直接确认）：

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/

4.2 ambari-server 初始化与重置（setup / reset / check-database）

setup 完成首次初始化（JDK 检查、内嵌 PostgreSQL 建库建表、管理员账号写入），交互顺序与回显全文见《Apache Ambari 2.7.9 安装指南》4.9；重复执行会提示已初始化并询问是否覆盖。常用参数可用 --help 查看：

ambari-server setup --help

Using python  /usr/bin/python
Setup ambari-server
Usage: ambari-server.py action [options]

Options:
  -h, --help            show this help message and exit
  -v, --verbose         Print verbose status messages
  -s, --silent          Silently accepts default prompt values. For db-cleanup
                        command, silent mode will stop ambari server.

  Database options (command need to include all options):
    --database=DBMS     Database to use
                        embedded|oracle|mysql|mssql|postgres|sqlanywhere
    --databasehost=DATABASE_HOST
                        Hostname of database server
    --databaseport=DATABASE_PORT
                        Database port
    --databasename=DATABASE_NAME
                        Database/Service name or ServiceID
    --databaseusername=DATABASE_USERNAME
                        Database user login
    --databasepassword=DATABASE_PASSWORD
                        Database user password

  JDBC options (command need to include all options):
    --jdbc-driver=JDBC_DRIVER
                        Specifies the path to the JDBC driver JAR file or
                        archive with all required files(jdbc jar, libraries
                        and etc), for the database type specified with the
                        --jdbc-db option. Used only with --jdbc-db option.
                        Archive is supported only for sqlanywhere database.
    --jdbc-db=JDBC_DB   Specifies the database type
                        [postgres|mysql|mssql|oracle|hsqldb|sqlanywhere] for
                        the JDBC driver specified with the --jdbc-driver
                        option. Used only with --jdbc-driver option.

  Other options:
    -j JAVA_HOME, --java-home=JAVA_HOME
                        Use specified java_home.  Must be valid on all hosts
（其余选项输出节选，实测首尾）

常用参数	说明
`-j <JAVA_HOME>`	指定本机 JDK，跳过联网下载 Oracle JDK 交互项（推荐，实测可用）
`--database` 系列	切换外部数据库，六个参数需成组给出
`--jdbc-db` + `--jdbc-driver`	安装外部数据库的 JDBC 驱动（如 `--jdbc-db=mysql --jdbc-driver=/usr/share/java/mysql-connector-java.jar`）
`-s`（--silent）	全部交互取默认值，用于脚本化安装

check-database 对元数据库做一致性检查（引用完整性、孤儿记录等）。注意 2.7.9 的已知怪癖——检查完成后会以退出码 1 收尾：

ambari-server check-database

Using python  /usr/bin/python
Checking database
ERROR: Exiting with exit code 1.
REASON: Database check failed to complete: No errors and warnings were found.（日志初始化警告行节选）
（中间为 Guice AssistedInject 警告与检查过程日志，实测节选）
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.
.
Please check /var/log/ambari-server/ambari-server.log and /var/log/ambari-server/ambari-server-check-database.log for more information.

💡 解读：输出中的 No errors and warnings were found. 才是检查结论——数据库健康；随后的 Persistence service was already initialized. 是 2.7.9 检查器自身缺陷（检查完成后重复初始化 JPA 持久化服务导致异常退出）。判断健康状态看结论行与 /var/log/ambari-server/ambari-server-check-database.log，不要被退出码 1 误导。

reset 清空元数据库（删除全部集群定义与主机记录），用于把 Server 还原到「setup 刚完成」状态。运行中的 Server 会拒绝执行，必须先 stop：

ambari-server stop
ambari-server reset

Using python  /usr/bin/python
Stopping ambari-server
Ambari Server stopped
（reset 为交互命令，先提示 WARNING 确认，输入 y 后清空数据库并重新建表）

⚠️ reset 不可逆：集群、服务配置、主机、告警历史全部删除且不备份。生产环境执行前必须先做 4.3 的 backup。执行后需重新 ambari-server setup 才能再次 start。

4.3 ambari-server 备份与恢复（backup / restore）

backup 把 Server 的文件系统状态（配置、证书、资源定义）打包为 zip。实测：

ambari-server backup

Using python  /usr/bin/python
Backing up Ambari File System state... *this will not backup the server database*
Backup requested.
No path specified. Will use /var/lib/ambari-server/Ambari_State_Backup.zip
Backup process initiated.
Creating zip file...
Zip file created at /var/lib/ambari-server/Ambari_State_Backup.zip
Backup complete.
Ambari Server 'backup' completed successfully.

确认产物：

ls -lh /var/lib/ambari-server/Ambari_State_Backup.zip

-rw-r--r-- 1 root root 11K Oct 13 21:14 /var/lib/ambari-server/Ambari_State_Backup.zip

⚠️ 回显明确说明 this will not backup the server database——backup 只覆盖文件系统状态（/etc/ambari-server 配置、/var/lib/ambari-server 下的证书与资源）。元数据库需另用 PostgreSQL 自带工具备份：su postgres -c "pg_dump -Fc ambari > /root/ambari-db.dump"。

restore 是配套恢复命令，从指定 zip 还原（覆盖现有文件）：

ambari-server restore --help

Using python  /usr/bin/python
Restoring Ambari File System state
Usage: ambari-server.py action [options]

Options:
  -h, --help     show this help message and exit
  -v, --verbose  Print verbose status messages
  -s, --silent   Silently accepts default prompt values. For db-cleanup
                 command, silent mode will stop ambari server.

⚠️ restore 会用备份包内容覆盖当前配置文件，且同样不恢复数据库；完整恢复 = restore 文件状态 + pg_restore 数据库备份，且要求 Ambari 版本一致。

4.4 ambari-server 子命令全集速查

ambari-server 不带子命令或带 --help 输出全部 26 个子命令（实测）：

ambari-server --help

Using python  /usr/bin/python
Usage: /usr/sbin/ambari-server
        {start|stop|reset|restart|upgrade|status|upgradestack|setup|setup-jce|setup-ldap|sync-ldap|set-current|setup-security|refresh-stack-hash|backup|restore|update-host-names|check-database|enable-stack|setup-sso|setup-trusted-proxy|db-purge-history|install-mpack|uninstall-mpack|upgrade-mpack|setup-kerberos|setup-pam|migrate-ldap-pam} [options]
        Use /usr/sbin/ambari-server.py <action> --help to get details on options available.
        Or, simply invoke ambari-server.py --help to print the options.

子命令	用途	运行要求
`start` / `stop` / `status` / `restart`	Server 生命周期	任意时刻
`setup`	首次初始化（数据库/JDK/账号）	通常 stop 状态；重复执行询问覆盖
`reset`	清空元数据库	必须 stop
`backup` / `restore`	文件系统状态备份与恢复	backup 建议 stop 后执行更完整
`check-database`	元数据库一致性检查	建议执行时 Server 停止（避免写入竞争）
`upgrade` / `upgradestack` / `set-current`	版本升级、栈版本切换	升级流程专用
`refresh-stack-hash`	重算栈定义哈希	替换 stacks 目录内容后执行
`enable-stack`	启用额外 Stack	需指定栈名
`setup-jce`	安装 JCE 策略包	Kerberos 前置
`setup-ldap` / `sync-ldap` / `migrate-ldap-pam`	LDAP 接入、用户同步、LDAP/PAM 迁移	交互式
`setup-security`	安全选项入口（加密主密钥等）	交互式
`setup-kerberos` / `setup-sso` / `setup-trusted-proxy`	Kerberos、单点登录、可信代理配置	交互式
`setup-pam`	切换 PAM 认证	交互式
`update-host-names`	批量更新主机名记录	集群停机时
`db-purge-history`	清理历史请求/告警记录	大库瘦身
`install-mpack` / `uninstall-mpack` / `upgrade-mpack`	Management Pack 安装管理	交付扩展栈用

4.5 ambari-agent 子命令

ambari-agent 只有 5 个子命令（实测 --help）：

ambari-agent --help

Usage: /usr/sbin/ambari-agent {start|stop|restart|status|reset <server_hostname>}

ambari-agent --version

2.7.9.0

启动与状态确认（Agent 连接 Server 的 hostname 在 /etc/ambari-agent/conf/ambari-agent.ini 的 [server] 段配置）：

ambari-agent start

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...
Agent process is running
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

ambari-agent status

Found ambari-agent PID: 119269
ambari-agent running.
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

改配置后重启生效（实测重启回显，stop 与 start 段一次完成）：

ambari-agent restart

Restarting ambari-agent
Verifying Python version compatibility...
Using python  /usr/bin/python
Found ambari-agent PID: 119269
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

reset <server_hostname> 用于把 [server] hostname 改写为指定 Server 地址；Agent 运行中会拒绝执行（实测）：

ambari-agent reset ambari1.example.com

ambari-agent is running. You must stop it before using reset.

按 ambari-agent stop → ambari-agent reset <server_hostname> → ambari-agent start 的顺序执行即可。

4.6 curl 调用 REST API

REST API 基址为 http://<server>:8080/api/v1，认证用 HTTP Basic（-u user:password），写操作必须带 X-Requested-By 头。查询已注册主机列表：

curl -s -u admin:q1w2e3r4 -H 'X-Requested-By: ambari' http://127.0.0.1:8080/api/v1/hosts

{
  "href" : "http://127.0.0.1:8080/api/v1/hosts",
  "items" : [
    {
      "href" : "http://127.0.0.1:8080/api/v1/hosts/ambari1.example.com",
      "Hosts" : {
        "host_name" : "ambari1.example.com"
      }
    }
  ]
}

查询集群列表（尚未通过向导建集群时为空数组，可确认 API 鉴权与连通性正常）：

curl -s -u admin:q1w2e3r4 -H 'X-Requested-By: ambari' http://127.0.0.1:8080/api/v1/clusters

{
  "href" : "http://127.0.0.1:8080/api/v1/clusters",
  "items" : [ ]
}

查询单个用户详情（含账号状态与权限）：

curl -s -u admin:q1w2e3r4 -H 'X-Requested-By: ambari' http://127.0.0.1:8080/api/v1/users/admin

{
  "href" : "http://127.0.0.1:8080/api/v1/users/admin",
  "Users" : {
    "active" : true,
    "admin" : true,
    "consecutive_failures" : 0,
    "created" : 1791888708000,
    "display_name" : "Administrator",
    "groups" : [ ],
    "ldap_user" : false,
    "local_user_name" : "admin",
    "user_name" : "admin",
    "user_type" : "LOCAL"
  },
  （privileges 段输出节选，实测首尾）
}

修改用户密码（PUT 目标用户资源，body 带 old_password）：

curl -s -o /dev/null -w '%{http_code}\n' -u admin:admin -H 'X-Requested-By: ambari' \
  -X PUT -d '{"Users":{"password":"q1w2e3r4","old_password":"admin"}}' \
  http://127.0.0.1:8080/api/v1/users/admin

验证旧口令已失效、新口令生效：

curl -s -o /dev/null -w '%{http_code}\n' -u admin:admin -H 'X-Requested-By: ambari' \
  http://127.0.0.1:8080/api/v1/users/admin
curl -s -o /dev/null -w '%{http_code}\n' -u admin:q1w2e3r4 -H 'X-Requested-By: ambari' \
  http://127.0.0.1:8080/api/v1/users/admin

403
200

要点	说明
`-u user:password`	Basic 认证；口令错误返回 403
`X-Requested-By: ambari`	所有请求必需（GET 亦建议带上），缺失时写操作被 400 拒绝
常用只读资源	`/api/v1/hosts`、`/api/v1/clusters`、`/api/v1/users`、`/api/v1/services`（集群建好后）
常用写操作	PUT 改用户密码/权限、PUT 改服务配置（`/api/v1/clusters/<名>/configurations`）

4.7 进程、端口与日志诊断

进程形态：ambari-server 是 JVM 进程（主类 org.apache.ambari.server.controller.AmbariServer），ambari-agent 是 Python 进程。确认两者都在：

jps -l
ps -ef | grep [A]mbariAgent | grep -v grep | head -1 | cut -c1-120

79677 org.apache.ambari.server.controller.AmbariServer
root     119269       1  0 11:18 ?        00:00:02 /usr/bin/python /usr/lib/pyth

监听端口：8080（Web/REST）、8440/8441（Agent 通信）、5432（内嵌 PostgreSQL）、8670（Agent ping）应全部 LISTEN：

ss -tlnp | grep -E '8080|8440|8441|5432|8670'

LISTEN     0      50        [::]:8440                  [::]:*                   users:(("java",pid=79677,fd=218))
LISTEN     0      50        [::]:8441                  [::]:*                   users:(("java",pid=79677,fd=223))
LISTEN     0      50        [::]:8080                  [::]:*                   users:(("java",pid=79677,fd=214))
LISTEN     0      208       *:5432                     *:*                   users:(("postgres",pid=75789,fd=3))

解读：8080/8440/8441 由 java 进程（PID 79677 即 AmbariServer）监听，5432 由 postgres 监听——端口与进程对得上说明 Server 全链路正常。8670 只在 Agent 侧本机监听，ss 不加过滤即可看到。

日志：Server 日志在 /var/log/ambari-server/（ambari-server.log 常规日志、ambari-server.out 启动异常输出、ambari-audit.log 审计），Agent 在 /var/log/ambari-agent/。心跳正常的 Agent 日志样例（每 10 秒一次心跳往返）：

tail -4 /var/log/ambari-agent/ambari-agent.log

INFO 2026-10-13 13:11:35,695 security.py:135 - Event to server at /heartbeat (correlation_id=6): {'id': 0}
INFO 2026-10-13 13:11:35,698 __init__.py:82 - Event from server at /user/ (correlation_id=6): {u'status': u'OK', u'id': 1}
INFO 2026-10-13 13:11:45,699 security.py:135 - Event to server at /heartbeat (correlation_id=7): {'id': 1}
INFO 2026-10-13 13:11:45,702 __init__.py:82 - Event from server at /user/ (correlation_id=7): {u'status': u'OK', u'id': 2}

Server 侧的主机注册/重注册日志（排障 Agent 注册问题时 grep 关键字）：

grep -E 'register' /var/log/ambari-server/ambari-server.log | tail -3

2026-10-13 13:11:35,666  INFO [agent-register-processor-3] TopologyManager:665 - TopologyManager.onHostRegistered: Entering
2026-10-13 13:11:35,666  INFO [agent-register-processor-3] TopologyManager:719 - Host ambari1.example.com re-registered, will not be added to the available hosts list
2026-10-13 13:11:35,669  INFO [pool-4-thread-1] StackAdvisorHelper:245 - Clear stack advisor caches, host: ambari1.example.com

五、注意事项

写操作必带 X-Requested-By 头：REST 的所有 PUT/POST/DELETE 缺该头即被拒（防 CSRF 机制），报错不会明确提示缺头，先核对请求头。
reset 与 restore 是高危命令：reset 清库不可逆；restore 覆盖现有配置文件。执行前一律先 backup + pg_dump，并确认 Server 已 stop。
check-database 退出码 1 ≠ 数据库故障：2.7.9 的检查器缺陷，以输出中 No errors and warnings were found. 结论行为准（见 4.2）。
Agent 命令是 Python 2 脚本：不要用 systemd 之外的进程管理器直接拉起 /usr/sbin/ambari-agent，用自带 start/stop 子命令或 SysV 脚本；异常退出后先看 ambari-agent.out 再重启。
改配置一律走 restart：ambari-server 配置（ambari.properties、ambari-env.sh）与 ambari-agent 配置（ambari-agent.ini）都是启动时读取，热改无效。
版本号两套写法：Server 报 2.7.9.0-0（RPM 风格），Agent 报 2.7.9.0，对应同一构建；对版本时按 2.7.9.0 口径沟通。

六、常见问题

6.1 ambari-server start 报 buildNumber: unbound variable

现象：任何子命令执行即报 /usr/sbin/ambari-server: line 34: buildNumber: unbound variable。

原因：从源码 tarball（无 .git 目录）构建的 RPM 中 ${buildNumber} 占位符未被替换，脚本又在 set -u 严格模式运行。

解决：对三个文件执行修复后重试（《Apache Ambari 2.7.9 安装指南》4.8 有完整步骤）：

sed -i 's/\${buildNumber}/source/g' /usr/sbin/ambari-server
sed -i 's/\${buildNumber}/source/g' /etc/init.d/ambari-server
sed -i 's/\${buildNumber}/source/g' /var/lib/ambari-agent/bin/ambari-agent

6.2 status 显示 running 但 curl 8080 无响应

现象：ambari-server status 正常，curl http://127.0.0.1:8080/ 无返回。

排查：

ss -tlnp | grep 8080
tail -20 /var/log/ambari-server/ambari-server.out

常见原因：启动仍在进行（Waiting for server start 的点号阶段），JVM 慢启动等待即可；或启动中途异常退出但 PID 文件残留——ambari-server.out 末行通常给出 Java 异常栈首行，按异常处理。

6.3 REST 调用返回 403

现象：curl -u admin:... 返回 403。

排查顺序：口令是否正确（改过密码用新口令）→ 是否漏了 X-Requested-By 头（缺失时部分场景直接 403）→ 账号是否被禁用（GET /api/v1/users/admin 看 "active" 字段）。

6.4 agent status 显示 running 但 Server 看不到该主机

现象：ambari-agent status 正常，GET /api/v1/hosts 里没有该主机。

排查顺序：

grep hostname /etc/ambari-agent/conf/ambari-agent.ini
ss -tlnp | grep 8440
tail -20 /var/log/ambari-agent/ambari-agent.log

常见原因：[server] hostname 配错（指向了不可解析的名字）；Server 的 8440 未监听；主机名解析冲突（/etc/hosts 里同名记录指向别的 IP）。修正后 ambari-agent restart，十几秒内重新注册。

6.5 jps 命令不存在

现象：执行 jps 提示 command not found。

原因：只装了 JRE。安装开发包后即可用：

yum install -y java-1.8.0-openjdk-devel
jps -l

79677 org.apache.ambari.server.controller.AmbariServer

七、参考链接

Apache Ambari 官网：https://ambari.incubator.apache.org/
Ambari REST API 参考（wiki）：https://cwiki.apache.org/confluence/display/AMBARI/Ambari+REST+API
Ambari 源码仓库：https://github.com/apache/ambari
2.7.9 源码包（官方归档）：https://archive.apache.org/dist/ambari/ambari-2.7.9/
同系列：《Apache Ambari 2.7.9 安装指南》《Apache Ambari 2.7.9 配置参数详解》