Apache AsterixDB 0.9.9 常用 CLI 命令与工具详解

目标：详解 Apache AsterixDB 0.9.9 的常用命令行工具——bin/ 下 asterixcc、asterixncservice、asterixnc、asterixhelper 四个脚本、官方示例集群启停脚本、curl 调用 HTTP API（查询服务与 admin 端点）、jps/netstat 进程与端口诊断及日志排障。所有命令与回显均为真实环境实测（Ubuntu 22.04 / OpenJDK 11.0.32.1）。

一、环境信息

操作系统：Ubuntu 22.04 LTS
Java：OpenJDK 11.0.32.1（含 jps）
Apache AsterixDB：0.9.9（/admin/version 实测 git.build.version=0.9.9）
安装目录：/opt/asterixdb
集群形态：单 NC（nc1）+ CC，配置文件 /opt/asterixdb/conf/cc.conf
端口：19001（Web 控制台）/ 19002（HTTP API）/ 19004（NC API）/ 19006（查询 Web）/ 9090（NCService）
运行方式：systemd 托管（asterixdb-nc.service、asterixdb-cc.service），演示脚本用法时先停用 systemd 避免互相干扰

二、工具概览

工具	位置	用途
`asterixcc`	`/opt/asterixdb/bin/`	启动 Cluster Controller（CC），全部运行参数可用命令行覆盖
`asterixncservice`	`/opt/asterixdb/bin/`	启动 NCService 看护进程，CC 经它拉起 NC
`asterixnc`	`/opt/asterixdb/bin/`	NC 驱动本体（由 NCService 拉起，不手工执行）
`asterixhelper`	`/opt/asterixdb/bin/`	集群状态查询、等待、优雅停机助手
`start-sample-cluster.sh` / `stop-sample-cluster.sh`	`/opt/asterixdb/opt/local/bin/`	官方示例双 NC 集群一键启停
`curl`	系统命令	调用 19002 的查询服务与 admin 端点
`jps` / `jps -v`	JDK 自带	查看 Java 进程与 JVM 参数生效值
`netstat`	`net-tools` 包	校验端口监听

三、前置条件

已按《Apache AsterixDB 0.9.9 安装指南》完成安装：/opt/asterixdb 就绪，JDK 11 已装（含 jps），net-tools 已装。
本文演示进程管理命令时先停用 systemd 托管（两种托管方式不要混用）：

systemctl stop asterixdb-cc.service
systemctl stop asterixdb-nc.service
sleep 25 && jps -l

7392 jdk.jcmd/sun.tools.jps.Jps

仅剩 Jps 自身，进程已全停，可以开始脚本方式演示。

四、工具详解

4.1 asterixncservice：NC 看护进程

asterixncservice 是每台 NC 机器上常驻的看护进程，监听 9090 等待 CC 指令，收到指令后拉起 NCDriver。查看参数：

bin/asterixncservice -help

org.kohsuke.args4j.CmdLineException: "-help" is not a valid option
 -address VAL     : Address to listen on for connections from CC (default: all addresses)
 -config-file VAL : Local NC configuration file (default: none)
 -logdir VAL      : Directory to log NC output ('-' for stdout of NC service; default: $app.home/logs)
 -port N          : Port to listen on for connections from CC (default: 9090)

参数	默认值	说明
`-address`	全部地址	NCService 监听地址，多机时按需收敛
`-port`	9090	等待 CC 连接的端口
`-logdir`	$app.home/logs	NC 输出落盘目录，`-` 表示直接打到 NCService 自身 stdout
`-config-file`	none	本地 NC 配置文件（一般不用，节点参数由 CC 下发）

启动方式（无参数即可工作，日志经 shell 重定向）：

cd /opt/asterixdb
bin/asterixncservice > /opt/asterixdb/logs/nc1-service.log 2>&1 &

验证监听：

netstat -tlnp | grep 9090

tcp6       0      0 :::9090                 :::*                    LISTEN      5191/java

4.2 asterixcc：启动集群控制器

asterixcc 启动 CC，JVM 参数经 JAVA_OPTS 环境变量注入，集群参数经 -config-file 指向 cc.conf。本文实测启动命令：

JAVA_OPTS="-Xms256m -Xmx512m -Djava.io.tmpdir=/opt/asterixdb/tmp" \
  bin/asterixcc -config-file /opt/asterixdb/conf/cc.conf > /opt/asterixdb/logs/cc.log 2>&1 &

查看全部命令行参数（输出很长，以下为关键节选，均为实测真实默认值）：

bin/asterixcc -help

 -active-memory-global-budget VAL               : The memory budget (in bytes) for the active runtime (default:
                                                  67108864 (64 MB))
 -active-port N                                 : The listen port of the active server (default: 19003)
 -address VAL                                   : Default bind address for all services on this cluster controller
                                                  (default: 127.0.0.1)
 -api-port N                                    : The listen port of the API server (default: 19002)
 -client-listen-port N                          : Sets the port to listen for connections from clients (default: 1098)
 -cluster-listen-port N                         : Sets the port to listen for connections from node controllers
                                                  (default: 1099)
 -compiler-framesize N                          : The page size (in bytes) for computation (default: 32768 (32 kB))
 -compiler-groupmemory VAL                      : The memory budget (in bytes) for a group by operator instance in a
                                                  partition (default: 33554432 (32 MB))
 -compiler-joinmemory VAL                       : The memory budget (in bytes) for a join operator instance in a
                                                  partition (default: 33554432 (32 MB))
 -compiler-parallelism N                        : The degree of parallelism for query execution. Zero means to use the
                                                  storage parallelism as the query execution parallelism, ...
 -compiler-sortmemory VAL                       : The memory budget (in bytes) for a sort operator instance in a
                                                  partition (default: 33554432 (32 MB))
 -config-file VAL                               : Specify path to master configuration file (default: <undefined>)
 -console-listen-port N                         : Sets the http port for the Cluster Controller) (default: 16001)
 -cores-multiplier N                            : the factor to multiply by the number of cores to determine maximum
                                                  query concurrent execution level (default: 3)
 -credential-file VAL                           : Path to HTTP basic credentials (default: -default-dir/passwd)
 -default-dir VAL                               : Directory where files are written to by default (default:
                                                  /tmp/asterixdb)
 -heartbeat-max-misses N                        : Sets the maximum number of missed heartbeats before a node can be
                                                  considered dead (default: 5)
 -heartbeat-period VAL                          : Sets the time duration between two heartbeats from each node
                                                  controller in milliseconds (default: 10000)
 -job-history-size N                            : Limits the number of historical jobs remembered by the system to the
                                                  specified value (default: 10)
 -job-queue-capacity N                          : The maximum number of jobs to queue before rejecting new jobs
                                                  (default: 4096)
 -max-wait-active-cluster N                     : The max pending time (in seconds) for cluster startup. After the
                                                  threshold, if the cluster still is not up and running, it is
                                                  considered unavailable (default: 60)
 -metadata-listen-port N                        : IP port to bind metadata listener (0 = random port) (default: 0)
 -replication-enabled VALUE                     : Whether or not data replication is enabled (default: false)
 -result-ttl VAL                                : Limits the amount of time results for asynchronous jobs should be
                                                  retained by the system in milliseconds (default: 86400000)
 -storage-compression-block VAL                 : The default compression scheme for the storage (default: snappy)
 -storage-format VAL                            : The default storage format (either row or column) (default: row)
 -web-port N                                    : The listen port of the legacy query interface (default: 19001)
 -web-queryinterface-port N                     : The listen port of the query web interface (default: 19006)

说明：命令行参数名与 cc.conf 参数一一对应（点号换连字符，如 api.port ↔ -api-port）；-help 输出的 <undefined> 表示无默认值、必须由 cc.conf 提供。命令行参数优先级高于 cc.conf。

启动完成验证（约 10-20 秒后三进程齐全，实测）：

jps -l

5191 org.apache.hyracks.control.nc.service.NCService
5198 org.apache.hyracks.control.cc.CCDriver
5278 org.apache.hyracks.control.nc.NCDriver

4.3 asterixnc：NC 驱动本体

asterixnc 是 NCDriver 的启动器，正常情况下由 NCService 按 cc.conf 的 command=asterixnc 拉起，不要手工执行（手工拉起的 NC 不受 CC 会话管理，参数拼装也与标准流程不一致）。它与 asterixcc 共享同一套参数体系（bin/asterixnc -help 可查看，含 -cluster-address、-cluster-port 等节点专属项），仅作排障时核对参数用途：

bin/asterixnc -help | grep -E 'cluster-address|cluster-port|command'

 -cluster-address VAL                            : Cluster Controller address (required unless specified in config
                                                   file) (default: <undefined>)
 -cluster-port N                                 : Cluster Controller port (default: 1099)
 -command VAL                                    : Command NCService should invoke to start the NCDriver (default:
                                                   hyracksnc)

运行中 NC 的实际参数用 jps -v 核对（实测，NCService 已自动追加 GC 参数）：

jps -v | grep NCDriver | head -1

5278 NCDriver -Xms256m -Xmx512m -Djava.io.tmpdir=/opt/asterixdb/tmp -XX:MaxGCPauseMillis=25000 -Dapp.name=asterixnc -Dapp.pid=5278 -Dapp.repo=/opt/asterixdb/repo -Dapp.home=/opt/asterixdb -Dbasedir=/opt/asterixdb

4.4 asterixhelper：集群状态与停机助手

asterixhelper 是最常用的集群运维入口，不指定命令时打印用法（实测全文）：

bin/asterixhelper

ERROR: No command specified.
Usage: asterixhelper [options] <command>
Commands:
  get_cluster_state    : Get state of cluster (errorcode 0 = ACTIVE, 1 = DOWN, 2 = UNUSABLE, 3 = OTHER)
  wait_for_cluster     : Wait for cluster to be ready (errorcode 0 = ACTIVE, non-zero = UNKNOWN)
  shutdown_cluster     : Instructs the cluster to shut down, leaving NCService processes intact
  shutdown_cluster_all : Instructs the cluster to shut down, including NCService processes
  sleep                : Sleep for specified -timeout seconds
  add_credential       : Generate passwd file for API endpoints that require authentication. -username and -password must be specified.
Options:
 -clusteraddress <address> : default 127.0.0.1
 -clusterport <port>       : default 19002
 -credentialpath (-cp) VAL : default ./passwd
 -password (-p) VAL
 -quiet (-q)
 -timeout <secs>
 -username (-u) VAL

查询集群状态：

bin/asterixhelper get_cluster_state

INFO: Attempting to determine state of cluster 127.0.0.1:19002...
INFO: Cluster 127.0.0.1:19002 is ACTIVE.

等待集群就绪（部署脚本里轮询用，就绪返回 0）：

bin/asterixhelper wait_for_cluster -timeout 60

INFO: Waiting up to 60 seconds for cluster 127.0.0.1:19002 to be available.
INFO: Cluster started and is ACTIVE.

优雅停机（推荐用含 NCService 的 all 形态，两形态差异见用法表）：

bin/asterixhelper shutdown_cluster_all

INFO: Attempting to shutdown cluster 127.0.0.1:19002...
INFO: Cluster 127.0.0.1:19002 accepted shutdown request.

accepted shutdown request 只是受理回执，进程完全退出需 10-25 秒（NCDriver 先退，CC 与 NCService 随后），之后用 jps -l 复核（见 6.2）。

4.5 示例集群脚本：start/stop-sample-cluster.sh

发行包内置一个双 NC（asterix_nc1、asterix_nc2）的示例集群脚本，配置在 opt/local/conf/（cc.conf 与 blue.conf）。运行前需先停掉现有集群（示例与常规集群同用 19002 等端口）。启动：

cd /opt/asterixdb/opt/local/bin && ./start-sample-cluster.sh

CLUSTERDIR=/opt/asterixdb/opt/local
INSTALLDIR=/opt/asterixdb
LOGSDIR=/opt/asterixdb/opt/local/logs

INFO: Starting sample cluster...
INFO: Waiting up to 90 seconds for cluster 127.0.0.1:19002 to be available.
INFO: Cluster started and is ACTIVE.

进程形态（2 个 NCService、2 个 NCDriver、1 个 CCDriver，实测）：

jps -l

6960 org.apache.hyracks.control.nc.service.NCService
7105 org.apache.hyracks.control.nc.NCDriver
6961 org.apache.hyracks.control.nc.service.NCService
6962 org.apache.hyracks.control.cc.CCDriver
7103 org.apache.hyracks.control.nc.NCDriver

停止：

./stop-sample-cluster.sh

INFO: Attempting to shutdown cluster 127.0.0.1:19002...
INFO: Cluster 127.0.0.1:19002 accepted shutdown request.
INFO: Waiting up to 60s for cluster to shutdown........done.

💡 说明：脚本会打印 CLUSTERDIR/INSTALLDIR/LOGSDIR 三个路径变量（工作目录、安装目录、示例集群日志目录）。示例集群的数据与日志都在 opt/local/ 下，与常规部署的 /opt/asterixdb/data 互不干扰；它也是学习多节点 cc.conf 写法（两个 [nc/...] 段、nc2 的 ncservice.port=9091）的现成样本。

4.6 curl 调用 HTTP API

查询服务统一入口是 POST /query/service，SQL++ 文本放 statement 表单参数。基础查询：

curl -s http://localhost:19002/query/service --data-urlencode "statement=SELECT 1 AS num;"

{
        "requestID": "11485a00-1294-4899-bb84-5d811e6347c3",
        "signature": { "*": "*" },
        "results": [ { "num": 1 } ],
        "plans":{},
        "status": "success",
        "metrics": {
                "elapsedTime": "756.344673ms", "executionTime": "592.254853ms",
                "compileTime": "305.261735ms", "queueWaitTime": "8ms",
                "resultCount": 1, "resultSize": 13, "processedObjects": 0
        }
}

建域、建表、插入、查询的完整链路（注意：shell 双引号内 JSON 的引号需转义）：

curl -s http://localhost:19002/query/service --data-urlencode "statement=CREATE DATAVERSE demo;" | grep -o '"status": "[a-z]*"'
curl -s http://localhost:19002/query/service --data-urlencode "statement=USE demo; CREATE TYPE GreetingType AS { id: int, message: string };" | grep -o '"status": "[a-z]*"'
curl -s http://localhost:19002/query/service --data-urlencode "statement=USE demo; CREATE DATASET Greetings(GreetingType) PRIMARY KEY id;" | grep -o '"status": "[a-z]*"'
curl -s http://localhost:19002/query/service --data-urlencode "statement=USE demo; INSERT INTO Greetings ({\"id\":1,\"message\":\"Hello AsterixDB!\"});" | grep -o '"status": "[a-z]*"'
curl -s http://localhost:19002/query/service --data-urlencode "statement=SELECT * FROM demo.Greetings ORDER BY id;" | grep -o '"Greetings": {[^}]*}'

前四条返回 "status": "success"，查询回显（实测）：

"Greetings": { "id": 1, "message": "Hello AsterixDB!" }

admin 端点速查（均实测）：

端点	方法	返回
`/admin/version`	GET	构建版本 JSON，`git.build.version=0.9.9`
`/admin/cluster`	GET	生效配置与 CC/NC 的 config、stats、threaddump 子链接
`/admin/active`	GET	Active 运行时状态，默认 `{ }`
`/admin/config`、`/admin`、`/metrics`	GET	404（0.9.9 无这些端点）

curl -s http://localhost:19002/admin/version | grep -o '"git.build.version":"[^"]*"'
curl -s http://localhost:19002/admin/cluster | head -c 120
curl -s http://localhost:19002/admin/active

"git.build.version":"0.9.9"
{"cc":{"configUri":"http://localhost:19002/admin/cluster/cc/config"
{ }

0.9.9 的这些接口默认无认证（带不带凭据访问 /admin/version 均 200，实测），暴露面靠网络层收敛；add_credential 在该版本不可用（见 6.1）。

4.7 Web 控制台与查询界面

浏览器访问 http://<服务器IP>:19001/ 为 Web 控制台（旧版查询界面），http://<服务器IP>:19006/ 为新版查询界面，均可在页面直接提交 SQL++、查看作业与集群拓扑。命令行侧等价验证（实测，注意该服务对 HEAD 返回 405，用 GET 探活）：

curl -s -o /dev/null -w "HEAD:%{http_code}\n" -I http://localhost:19001/
curl -s -o /dev/null -w "GET:%{http_code}\n" http://localhost:19001/

HEAD:405
GET:200

4.8 进程、端口与日志诊断

进程与 JVM 参数生效值：

jps -v | grep -E 'CCDriver|NCDriver|NCService'

5191 NCService -Dapp.name=asterixncservice -Dapp.pid=5191 -Dapp.repo=/opt/asterixdb/repo -Dapp.home=/opt/asterixdb -Dbasedir=/opt/asterixdb
5198 CCDriver -Xms256m -Xmx512m -Djava.io.tmpdir=/opt/asterixdb/tmp -Dapp.name=asterixcc -Dapp.pid=5198 -Dapp.repo=/opt/asterixdb/repo -Dapp.home=/opt/asterixdb -Dbasedir=/opt/asterixdb
5278 NCDriver -Xms256m -Xmx512m -Djava.io.tmpdir=/opt/asterixdb/tmp -XX:MaxGCPauseMillis=25000 -Dapp.name=asterixnc -Dapp.pid=5278 -Dapp.repo=/opt/asterixdb/repo -Dapp.home=/opt/asterixdb -Dbasedir=/opt/asterixdb

端口监听全景（netstat -tlnp 节选 java 行，实测）：

tcp6       0      0 :::9090                 :::*                    LISTEN      5191/java
tcp6       0      0 127.0.0.1:1098          :::*                    LISTEN      5198/java
tcp6       0      0 127.0.0.1:1099          :::*                    LISTEN      5198/java
tcp6       0      0 :::19004                :::*                    LISTEN      5278/java
tcp6       0      0 :::19006                :::*                    LISTEN      5198/java
tcp6       0      0 :::19001                :::*                    LISTEN      5198/java
tcp6       0      0 :::19002                :::*                    LISTEN      5198/java

端口	进程	说明
9090	NCService	等待 CC 指令
1098 / 1099	CCDriver	Hyracks 客户端与 NC 注册端口
19001 / 19002 / 19006	CCDriver	Web 控制台 / HTTP API / 查询 Web
19004	NCDriver	NC HTTP API

日志速查（本文部署形态）：

文件/位置	内容
`/opt/asterixdb/logs/cc.log`	CC 主日志（手工启动重定向；systemd 下走 journalctl）
`/opt/asterixdb/logs/nc1-service.log`	NCService 与 NC 输出
`journalctl -u asterixdb-cc.service`	systemd 托管时 CC 日志
`journalctl -u asterixdb-nc.service`	systemd 托管时 NCService 日志
`/opt/asterixdb/opt/local/logs/`	示例集群日志目录

排障顺序建议：get_cluster_state 定状态 → jps -l 看进程在不在 → netstat 看端口监听 → 对应日志文件或 journalctl 看异常栈。

五、注意事项

两种托管方式不要混用：systemd 与手工脚本同时管理会互相拉起/误判状态；切换托管方式前先 asterixhelper shutdown_cluster_all 并确认 jps -l 仅剩 Jps。
停机必须走 asterixhelper shutdown_cluster_all 的优雅路径，强杀（kill -9、超时强停）会导致事务日志尾部未落盘的元数据回滚；进程完全退出需 10-25 秒。
asterixnc 不手工执行；NC 的参数由 CC 从 cc.conf 读取后下发。
CC 的堆经 JAVA_OPTS 环境变量设置，NC 的堆在 cc.conf 的 jvm.args，两处都要限制在 256-512MB 并用 jps -v 复核。
0.9.9 接口默认无认证且 add_credential 存在缺陷，暴露面务必靠防火墙/绑定地址收敛。
查询服务对 SQL++ 文本用 --data-urlencode 的 statement 参数传递，shell 双引号内 JSON 引号需转义。

六、常见问题

6.1 asterixhelper add_credential 报 IOException: No such file or directory

现象：0.9.9 执行凭据生成必现异常（多路径与多参数形态均实测复现）：

bin/asterixhelper add_credential -username admin -password q1w2e3r4 -credentialpath /opt/asterixdb/passwd

Exception in thread "main" java.io.IOException: No such file or directory
        at java.base/java.io.UnixFileSystem.createFileExclusively(Native Method)
        at org.apache.asterix.clienthelper.commands.GenerateCredentialCommand.execute(GenerateCredentialCommand.java:49)

定位：0.9.9 的 GenerateCredentialCommand 实现缺陷，无法产出 passwd 文件，该子命令在当前版本不可用；且 HTTP 接口默认无认证。

解决：放弃 add_credential，用网络层限制访问面（[cc] address 绑 127.0.0.1 或防火墙限网段）；升级到修复版本后再启用接口认证。

6.2 shutdown 后进程未立即退出

现象：asterixhelper shutdown_cluster_all 已返回 accepted，jps -l 仍能看到进程。

定位：优雅停机流程 NCDriver 先退、CC 与 NCService 随后收尾，实测全程约 10-25 秒。

解决：等待后复核：

sleep 25 && jps -l

7392 jdk.jcmd/sun.tools.jps.Jps

仅剩 Jps 即全停。脚本化停机可在 shutdown 后接 bin/asterixhelper wait_for_cluster（未就绪即非 0 返回码）或轮询 jps 判断。

6.3 端口 19003 未监听

现象：netstat -tlnp | grep 19003 无输出。

定位：19003 是 Active Server 端口（-active-port，默认 19003），默认未启用，属正常现象；SQL++ 查询走 19002，与 19003 无关。

解决：无需处理；确需 Active Server 时按官方文档启用相应配置后再验证监听。

6.4 访问 /admin/config 返回 404

现象：curl http://localhost:19002/admin/config 返回 404（/admin、/metrics 同样）。

定位：0.9.9 没有这些管理端点，生效配置在 /admin/cluster，版本在 /admin/version，Active 状态在 /admin/active。

解决：改用上述三个端点（回显见 4.6 的 admin 速查表）。

6.5 jps 命令不存在

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

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

七、参考链接

官方下载页：https://downloads.apache.org/asterixdb/
0.9.9 NCService 部署文档：https://asterixdb.apache.org/docs/0.9.9/ncservice.html
官网首页：https://asterixdb.apache.org/
源码仓库：https://github.com/apache/asterixdb