Apache Amoro 0.8.1-incubating 常用 CLI 命令与工具详解

目标：详解 Apache Amoro 0.8.1-incubating AMS 的常用命令行工具——bin/ams.sh 服务生命周期管理、bin/optimizer.sh 独立优化器管理、curl 调用 REST API（Web 会话与 Basic 两种鉴权）、jps/netstat 进程与端口诊断。所有命令与回显均为真实环境实测。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS
• Java：OpenJDK 11.0.32.1
• Apache Amoro：0.8.1-incubating（bin-hadoop3，版本号实测 0.8.1-incubating(bc906c0)）
• 安装目录：/opt/amoro
• 服务脚本：/opt/amoro/bin/ams.sh、/opt/amoro/bin/optimizer.sh
• 服务端口：1630（HTTP）/ 1260（表服务）/ 1261（优化服务）
• 管理账号：admin / q1w2e3r4
• 运行方式：本文演示在 systemd 停止状态下直接用 ams.sh 管理进程（两种托管方式的命令差异见 4.1 末尾）

二、工具概览

三、前置条件

• 已按《Apache Amoro 0.8.1-incubating 安装指南》完成安装：/opt/amoro 就绪，JDK 8/11 已装（含 jps），net-tools 已装。
• 已完成首启前的关键配置（管理员密码、derby 路径、JVM 堆 256-512MB）。
• 若 AMS 由 systemd 托管，演示 ams.sh 前先停止服务避免二者互相干扰：

systemctl stop amoro-ams
systemctl is-active amoro-ams

inactive

四、工具详解

4.1 ams.sh 服务管理

bin/ams.sh 是 AMS 的主管理脚本，用 help 查看用法：

/opt/amoro/bin/ams.sh help

Usage /opt/amoro/bin/ams.sh start|start-foreground|stop|restart|status|pid

启动服务：

export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
/opt/amoro/bin/ams.sh start

starting app server.
process start success.

查看状态与进程号（启动完成约需 10-20 秒）：

/opt/amoro/bin/ams.sh status
/opt/amoro/bin/ams.sh pid
jps -l | grep -v Jps

running.
2037
2037 org.apache.amoro.server.AmoroServiceContainer

ams.sh pid 输出与 jps 看到的 AmoroServiceContainer 进程号一致，说明记录无误。重启与停止：

/opt/amoro/bin/ams.sh restart

stop success.
process start success.

/opt/amoro/bin/ams.sh pid

2251

重启后进程号从 2037 变为 2251，服务继续 running.。停止：

/opt/amoro/bin/ams.sh stop
/opt/amoro/bin/ams.sh status

stopping app server.
stop success.
not running.

💡 说明：start-foreground 用于调试，输出可见 derby 初始化建表 SQL 与 Http server start at 1630.；生产托管二选一——systemd 场景（systemctl start/stop/restart amoro-ams，单元文件见《安装指南》4.8 节）与脚本场景不要混用，混用会出现 6.1 的状态错乱。

4.2 optimizer.sh 独立优化器管理

bin/optimizer.sh 管理内置的独立 optimizer（StandaloneOptimizer，可选高级功能；对接 Flink/Spark 集群时才需要启用，普通 AMS 使用可跳过本节）。用 help 查看用法：

bash /opt/amoro/bin/optimizer.sh help

Usage: /opt/amoro/bin/optimizer.sh {start|start-foreground|stop|status|pid} <memory_limit_in_MB> [additional_args]

日志写到 /opt/amoro/logs/optimizer-<时间戳>/optimizer.log.err。检查 optimizer 进程用 jps 最可靠：

jps -l | grep -v Jps

（无 optimizer 运行时仅显示 AMS 进程；启动后会出现 org.apache.amoro.optimizer.standalone.StandaloneOptimizer 行。）

⚠️ 注意：0.8.1 的 optimizer.sh status/pid 存在脚本缺陷，未运行 optimizer 时会报 error: process ID list syntax error（见 6.3），以 jps -l 的输出为准。

4.3 curl 调用 REST API

AMS REST 接口前缀为 /api/ams/v1/。免登录白名单接口可直接访问：

curl -s http://127.0.0.1:1630/api/ams/v1/versionInfo
curl -s http://127.0.0.1:1630/api/ams/v1/health/status

{"message":"success","code":200,"result":{"version":"0.8.1-incubating(bc906c0)","commitTime":"2025-08-28T08:55:33+0800"}}
{"message":"success","code":200,"result":null}

业务接口需要登录。方式一：Web 会话（与控制台登录同款），先登录拿会话 Cookie：

curl -s -c /tmp/amoro-cookie.txt -X POST http://127.0.0.1:1630/api/ams/v1/login \
  -H "Content-Type: application/json" -H "X-Request-Source: Web" \
  -d '{"user":"admin","password":"q1w2e3r4"}'

{"message":"success","code":200,"result":"success"}

随后带 Cookie 与 X-Request-Source: Web 头访问业务接口（目录列表、概览汇总、当前登录用户）：

curl -s -b /tmp/amoro-cookie.txt -H "X-Request-Source: Web" http://127.0.0.1:1630/api/ams/v1/catalogs
curl -s -b /tmp/amoro-cookie.txt -H "X-Request-Source: Web" http://127.0.0.1:1630/api/ams/v1/login/current
curl -s -b /tmp/amoro-cookie.txt -H "X-Request-Source: Web" http://127.0.0.1:1630/api/ams/v1/overview/summary

{"message":"success","code":200,"result":[]}
{"message":"success","code":200,"result":{"userName":"admin","loginTime":"1791861673624"}}
{"message":"success","code":200,"result":{"catalogCnt":0,"tableCnt":0,"tableTotalSize":0,"totalCpu":0,"totalMemory":0}}

方式二：HTTP Basic（需将 config.yaml 的 ams.http-server.rest-auth-type 改为 basic 并重启，实测）：

curl -s -u admin:q1w2e3r4 http://127.0.0.1:1630/api/ams/v1/catalogs

{"message":"success","code":200,"result":[]}

未登录/密码错误时的实测回显（token 模式）：

{"message":"Please login first","code":403,"requestId":""}
{"message":"Signature check failed","code":403,"requestId":""}

常用业务接口速查（均需登录会话或 Basic）：

4.4 Web 控制台访问

浏览器打开 http://<服务器IP>:1630/，即 Apache Amoro 控制台（页面标题实测为 Apache Amoro™ Dashboard），用 admin / q1w2e3r4 登录后可进行目录管理、表优化状态查看、SQL 终端等操作。控制台的登录走的就是 4.3 的 /api/ams/v1/login 会话机制，脚本登录拿到的 Cookie 与浏览器会话等价。

curl -s http://127.0.0.1:1630/ | grep -oE '<title>[^<]*</title>'

<title>Apache Amoro™ Dashboard</title>

4.5 进程、端口与日志诊断

确认 JVM 参数实际生效（本文堆限制 256-512MB）：

jps -lv | grep AmoroServiceContainer | grep -oE '\-Xms[0-9]+m -Xmx[0-9]+m'

-Xms256m -Xmx512m

确认端口监听：

netstat -tlnp | grep -E '1630|1260|1261'

tcp6       0      0 :::1630                 :::*                    LISTEN      2037/java
tcp6       0      0 :::1260                 :::*                    LISTEN      2037/java
tcp6       0      0 :::1261                 :::*                    LISTEN      2037/java

日志文件速查（/opt/amoro/logs/）：

服务不监听时优先看 ams-error.log 末尾：

tail -20 /opt/amoro/logs/ams-error.log

五、注意事项

• ams.sh 依赖 pid 文件 /opt/amoro/run/app.pid 判断状态；与 systemd 混用会造成状态错乱（见 6.1），一种环境只用一种托管方式。
• start-foreground 前台运行时终端 Ctrl+C 会直接终止服务，仅用于调试。
• REST 鉴权默认 token 模式，脚本直调业务接口必须先走会话登录或切换 basic 模式；白名单接口只有 versionInfo、health/status、login、login/current 等少数几个。
• optimizer.sh 的 start 需要显式传内存参数（如 optimizer.sh start 512），缺省会启动失败。
• 修改任何配置后需重启 AMS 才生效，重启后用 jps -v 与端口检查双重复核。

六、常见问题

6.1 ams.sh stop 报 stop failed 但进程已停止

现象：ams.sh stop 输出：

stopping app server.
stop failed. process is still running.

但 jps -l 里 AmoroServiceContainer 已消失。

定位：stop 后脚本立刻检查进程存活，进程尚在退出过程中即被误判；若同时由 systemd 托管（Restart=on-failure），systemd 还会立刻把进程拉起来，进一步造成 start 报 alreadly running. start app failed.（该拼写为脚本原文）。

解决：systemd 场景一律用 systemctl stop/start/restart amoro-ams；纯脚本场景先 ams.sh stop，等 3 秒再用 ams.sh status 确认 not running. 后再做后续操作。

6.2 optimizer.sh status 报 process ID list syntax error

现象：

error: process ID list syntax error

Usage:

定位：0.8.1 的 optimizer.sh status/pid 未运行 optimizer 时脚本内部命令参数拼接有缺陷，属发行包已知小问题。

解决：以 jps -l 为准（出现 org.apache.amoro.optimizer.standalone.StandaloneOptimizer 即在运行）；需要更详细的 JVM 信息用 jps -lv。

6.3 调用接口返回 Signature check failed 或 Please login first

定位：Signature check failed 是请求未带合法鉴权（token 模式缺 apiKey/signature，或 Basic 密码错误）；Please login first 是 Web 会话缺失或过期（session-timeout 默认 7d）。

解决：按 4.3 先登录拿 Cookie 再访问，或切换 rest-auth-type: basic 用 curl -u admin:q1w2e3r4 直调。

6.4 端口已监听但 curl 无响应

定位：AMS 启动分两阶段——Thrift（1260/1261）先起、HTTP（1630）后起，ams.sh status 显示 running. 不代表 1630 已就绪；极端情况下 1630 绑定失败（地址被占用）。

解决：看 ams-info.log 是否出现 Http server start at 1630.，再用 curl -s http://127.0.0.1:1630/api/ams/v1/versionInfo 确认返回 200。

6.5 jps 命令不存在

定位：jps 属 JDK 工具，只装 JRE 时没有。

解决：安装 openjdk-11-jdk-headless（含 jps），或用 ps -ef | grep AmoroServiceContainer 替代查看进程。

七、参考链接

• 官方文档首页：https://amoro.apache.org/
• AMS 部署文档：https://amoro.apache.org/docs/latest/deployment/
• 下载页：https://downloads.apache.org/incubator/amoro/
• 源码仓库：https://github.com/apache/amoro