Apache AsterixDB 0.9.9 配置参数详解

目标：详解 Apache AsterixDB 0.9.9 的核心配置——集群配置文件 cc.conf 的 [cc]、[nc]、[nc/<节点名>]、[common] 四段参数、JVM 堆的两个入口（jvm.args 与 JAVA_OPTS）以及日志参数，并给出可直接套用的生产模板。参数与默认值均基于真实环境实测（Ubuntu 22.04 / OpenJDK 11.0.32.1 / asterixcc -help 与 /admin/cluster 回显）。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（x86_64）
• Java：OpenJDK 11.0.32.1
• Apache AsterixDB：0.9.9（/admin/version 实测 git.build.version=0.9.9）
• 安装目录：/opt/asterixdb
• 配置文件：/opt/asterixdb/conf/cc.conf（部署时手工创建，官方示例见 opt/local/conf/cc.conf）
• 端口：19001（Web 控制台）、19002（HTTP API）、19004（NC API）、19006（查询 Web）、9090（NCService）、1098/1099（CC 内部）、16001（CC console，默认值实测在监听）
• 数据目录：/opt/asterixdb/data/（txnlog、coredump、iodevice 三个子目录）
• JVM 堆：NC 与 CC 均限制在 256-512MB

二、前置条件

• 已按《Apache AsterixDB 0.9.9 安装指南》完成安装并可正常启动（集群 ACTIVE）。
• 配置修改后需重启对应服务生效；重启前先用 asterixhelper shutdown_cluster_all 优雅停集群（进程完全退出约 10-25 秒）。
• 启动/重启后用 bin/asterixhelper get_cluster_state 确认回到 ACTIVE 再做后续验证。

三、参数查看与修改方式

AsterixDB 的运行参数有三个查看入口，改配置前先分清各自的来源：

查看当前部署的 cc.conf（去掉注释行）：

grep -vE '^\s*;|^\s*$' /opt/asterixdb/conf/cc.conf

[nc/nc1]
txn.log.dir=/opt/asterixdb/data/txnlog
core.dump.dir=/opt/asterixdb/data/coredump
iodevices=/opt/asterixdb/data/iodevice
nc.api.port=19004
jvm.args=-Xms256m -Xmx512m -Djava.io.tmpdir=/opt/asterixdb/tmp

[nc]
address=127.0.0.1
command=asterixnc

[cc]
address=127.0.0.1
api.port=19002
web.port=19001
active.port=19003

[common]
log.dir=/opt/asterixdb/logs
log.level=INFO

cc.conf 是 ini 风格：[cc]、[nc]、[common] 是固定段名，[nc/节点名] 每段定义一个 NC 节点；等号两侧空格可有可无（官方示例 opt/local/conf/cc.conf 即写作 address = 127.0.0.1）。cc.conf 中未写的参数全部回落到 asterixcc -help 显示的出厂默认值。

查看运行中集群的生效配置（节选实测）：

curl -s http://localhost:19002/admin/cluster | tr "," "\n" | grep -E "configUri|compiler.framesize|log.level|max.wait.active.cluster"

"configUri":"http://localhost:19002/admin/cluster/cc/config"
"compiler.framesize":32768
"log.level":"INFO"
"max.wait.active.cluster":60

/admin/cluster 返回的 JSON 含 CC 与每个 NC 的 configUri/statsUri/threadDumpUri 子链接与全量生效参数，改完配置重启后到这里核对是最可靠的验证手段。

修改流程统一为：编辑 cc.conf → asterixhelper shutdown_cluster_all 优雅停集群 → 重启服务（systemd 场景 systemctl start asterixdb-nc.service、systemctl start asterixdb-cc.service，每条命令只操作一个单元）→ get_cluster_state 确认 ACTIVE → /admin/cluster 核对参数值。

四、参数总览

下表汇总部署与运维最常触碰的参数（默认值来自 asterixcc -help 与官方 0.9.9 文档，均经实测核对）：

关键解读：日常运维最常改的是「端口、数据目录、JVM 堆、日志」四类；存储内存两项默认取 JVM 最大堆的 1/4，调大堆时会随之放大，小内存机器要么显式限定这两项，要么把堆压在 512MB 以内。

五、核心参数分类详解

5.1 [cc] 集群控制器参数

[cc]
address=127.0.0.1
api.port=19002
web.port=19001
active.port=19003

验证（实测）：改端口后重启，用监听与 HTTP 状态码双重确认：

netstat -tlnp | grep java | grep -E '19001|19002|19006'
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:19001/

tcp6       0      0 :::19006                :::*                    LISTEN      5198/java
tcp6       0      0 :::19001                :::*                    LISTEN      5198/java
tcp6       0      0 :::19002                :::*                    LISTEN      5198/java
200

5.2 [nc] 节点公共参数

[nc]
address=127.0.0.1
command=asterixnc

💡 说明：[nc] 段在单机（伪集群）部署里描述的是「本机 NCService 如何拉起 NC」；多机部署时每台机器的 NCService 配置可经 asterixncservice -port/-address 参数指定，见《Apache AsterixDB 0.9.9 常用 CLI 命令与工具详解》中 asterixncservice 的参数表。

5.3 [nc/节点名] 单节点参数

每个 [nc/名字] 段定义一个 NC 节点，存储三目录是必填项：

[nc/nc1]
txn.log.dir=/opt/asterixdb/data/txnlog
core.dump.dir=/opt/asterixdb/data/coredump
iodevices=/opt/asterixdb/data/iodevice
nc.api.port=19004
jvm.args=-Xms256m -Xmx512m -Djava.io.tmpdir=/opt/asterixdb/tmp

验证（实测）——jps -v 看 NCDriver 的完整参数：

jps -v | grep NCDriver

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

5.4 [common] 公共运行参数

[common]
log.dir=/opt/asterixdb/logs
log.level=INFO

验证（实测）——/admin/cluster 里核对生效值：

curl -s http://localhost:19002/admin/cluster | tr "," "\n" | grep -E "compiler.framesize|log.level"

"compiler.framesize":32768
"log.level":"INFO"

5.5 存储与内存参数

存储内存两项的默认值都与 JVM 堆挂钩（官方语义：默认取 JVM 最大堆的 1/4），这是小内存部署最容易忽略的联动关系：

其他存储行为参数（asterixcc -help 实测默认值）：

💡 技术拓展：存储行为有多个可选维度，横向对比——

维度	选项	特点与取舍
存储格式	row / column	row 写入与点查友好；column 压缩比与分析型扫描更好，0.9.9 默认 row
页压缩	snappy 等	snappy 压缩快、CPU 开销低，属均衡默认
分区方案	dynamic / static	dynamic 按集群自动分布；static 需手工指定 -storage-partitions-count（默认 8），建库后不可切换
数据复制	none（默认）/ 异步复制	replication-enabled=false 单副本；开启后按 replication-factor（默认 2）跨节点容灾，代价是写放大

本文保持出厂默认（row + snappy + dynamic + 不复制），理由：单机 512MB 小堆场景优先保功能稳定，复制与列存属生产扩容后的进阶选项。

5.6 JVM 参数（jvm.args 与 JAVA_OPTS 双入口）

两个常驻 Java 进程的 JVM 参数入口不同，是 AsterixDB 配置最大的特殊点：

jps -v | grep -E 'CCDriver|NCDriver' | grep -oE '\-Xms[0-9]+m -Xmx[0-9]+m'

-Xms256m -Xmx512m
-Xms256m -Xmx512m

要点：

• 改堆后 storage.buffercache.size 与 storage.memorycomponent.globalbudget 若未显式设置，会随新堆按 1/4 联动放大，堆小、预算大会在启动或刷盘时报内存不足；堆调到 512MB 以上时应显式固定这两项。
• -Djava.io.tmpdir 指向可执行目录（如 /opt/asterixdb/tmp）：snappy 本地库要解压到临时目录加载，/tmp 挂 noexec 时 NC 会直接崩溃，两处入口都要加。

5.7 日志参数

ls /opt/asterixdb/logs/

cc.log  nc1-service.log

💡 说明：手工启动时输出经 shell 重定向到 cc.log 与 nc1-service.log；systemd 托管下 journalctl -u asterixdb-cc.service、journalctl -u asterixdb-nc.service 亦可查看，NCService 的 -logdir 参数会把 NC 输出落到指定目录。

六、生产配置模板

适用场景：8 核 32GB 内存、NVMe SSD、单机开发/功能验证向生产过渡的 2 节点（1 CC + 2 NC）起步集群。

[nc/nc1]
txn.log.dir=/data/asterixdb/nc1/txnlog
core.dump.dir=/data/asterixdb/nc1/coredump
iodevices=/data/asterixdb/nc1/iodevice
nc.api.port=19004
jvm.args=-Xms2g -Xmx4g -Djava.io.tmpdir=/opt/asterixdb/tmp
storage.buffercache.size=1073741824
storage.memorycomponent.globalbudget=1073741824

[nc/nc2]
txn.log.dir=/data/asterixdb/nc2/txnlog
core.dump.dir=/data/asterixdb/nc2/coredump
iodevices=/data/asterixdb/nc2/iodevice
nc.api.port=19005
jvm.args=-Xms2g -Xmx4g -Djava.io.tmpdir=/opt/asterixdb/tmp
storage.buffercache.size=1073741824
storage.memorycomponent.globalbudget=1073741824

[nc]
address=127.0.0.1
command=asterixnc

[cc]
address=192.168.1.10
api.port=19002
web.port=19001
max.wait.active.cluster=120

[common]
log.dir=/opt/asterixdb/logs
log.level=INFO

配套 JVM：CC 侧 JAVA_OPTS="-Xms1g -Xmx2g -Djava.io.tmpdir=/opt/asterixdb/tmp"；每个 NC 堆 4GB 时缓冲池与写预算各显式固定 1GB，其余留给查询算子（groupmemory/joinmemory/sortmemory 各 32MB × 并行实例）。

说明：本文 256-512MB 小堆配置已实测可完成建域、建表、写入、查询全流程，适合功能验证；上表模板面向 32GB 内存与真实数据量，address 需换成本机对外 IP，两 NC 的存储目录建议放独立数据盘。上线后用 /admin/cluster 核对生效值并观察 GC 表现微调。

七、常见问题

7.1 修改配置后不生效

现象：改了 cc.conf，行为仍是旧值。

定位：AsterixDB 只在启动时读配置，运行中不热加载；且 [nc/...] 段参数是 CC 启动时下发给 NC 的，只重启 NC 进程而 CC 未重启时，下发的仍是旧值。

解决：NC 类参数改完后整套重启——优雅停集群再依次启动 NCService 与 CC（每条命令只操作一个单元）：

bin/asterixhelper shutdown_cluster_all
systemctl restart asterixdb-nc.service
systemctl restart asterixdb-cc.service

生效验证走 /admin/cluster（实测回显见第三节），不要只看进程活着。

7.2 小内存机器启动或刷盘报内存不足

现象：堆已限 512MB，仍在启动或首次写入时报存储内存分配失败。

定位：storage.buffercache.size 与 storage.memorycomponent.globalbudget 默认取 JVM 最大堆的 1/4，两项合计即堆的一半；若曾调大过堆又调回来，显式设置过的旧值不会自动回落。

解决：在 [nc/节点名] 段显式固定两项，例如 512MB 堆下各 128MB：

storage.buffercache.size=134217728
storage.memorycomponent.globalbudget=134217728

重启后经 /admin/cluster 核对两项数值已变为设定值。

7.3 /admin/config 访问 404

现象：按直觉访问 http://localhost:19002/admin/config 或 /metrics 返回 404（实测）。

定位：0.9.9 的管理端点没有 /admin/config 与 /metrics；生效配置统一在 /admin/cluster（含 CC 与各 NC 的 config 子链接），版本在 /admin/version，Active 运行时状态在 /admin/active（空对象 {} 表示无活动运行时）。

解决：改用以下三个端点（均实测 200）：

curl -s -o /dev/null -w "cluster:%{http_code}\n" http://localhost:19002/admin/cluster
curl -s -o /dev/null -w "version:%{http_code}\n" http://localhost:19002/admin/version
curl -s http://localhost:19002/admin/active

cluster:200
version:200
{ }

7.4 asterixhelper 报 Cluster is DOWN

现象：把 active.port 误当查询端口连，集群明明 ACTIVE 却报 DOWN（实测）：

bin/asterixhelper get_cluster_state -clusterport 19003

INFO: Attempting to determine state of cluster 127.0.0.1:19003...
INFO: Cluster 127.0.0.1:19003 is DOWN.

定位：asterixhelper 要连的是 CC 的 api.port（出厂默认 19002），而不是 19003 的 Active Server 端口（默认未启用不监听）；改过 api.port 的部署也必须在命令上同步指定。

解决：用 -clusterport 显式指向 api.port 实际值：

bin/asterixhelper get_cluster_state -clusterport 19002

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

八、参考链接

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