Apache AsterixDB 0.9.9 安装指南

Apache AsterixDB 0.9.9 安装指南：在 Ubuntu 22.04 从零安装单 NC 集群，覆盖 JDK 11 前置、官方 zip 下载与 sha512 校验、cc.conf 编写、NCService 与 CC 启动、SQL++ 接口验证、JVM 堆 256-512MB 限制、systemd 托管与常见排障，命令与回显均实测

Apache AsterixDBAsterixDB2026/10/13

Apache AsterixDB 0.9.9 安装指南

目标：在 Ubuntu 22.04 服务器上从零安装 Apache AsterixDB 0.9.9 的单 NC（Node Controller）集群，覆盖 OpenJDK 11 前置、官方 zip 制品下载与 sha512 校验、集群配置文件 cc.conf 编写、NCService 与 Cluster Controller 启动、SQL++ HTTP API 验证、JVM 堆 256-512MB 限制、systemd 托管与常见排障。以下命令与回显均在 Ubuntu 22.04 真实环境逐步实测。

一、环境信息

  • 操作系统：Ubuntu 22.04 LTS（x86_64）
  • Java：OpenJDK 11（openjdk-11-jdk-headless，实测版本 11.0.32.1，AsterixDB 0.9.9 要求 JDK 8 或 11）
  • Apache AsterixDB：0.9.9（制品 asterix-server-0.9.9-binary-assembly.zip，232931001 字节约 223MB，2024-03-05 发布）
  • 安装目录：/opt/asterixdb
  • 配置文件：/opt/asterixdb/conf/cc.conf（本文手工创建）
  • 数据目录：/opt/asterixdb/data/（事务日志、core dump、存储设备三个子目录）
  • 运行用户：root
  • 端口规划（本文实测值）：
端口用途说明
19001Web 控制台浏览器管理界面
19002HTTP API / 查询服务SQL++ 提交入口 /query/service 与 /admin/*
19006查询 Web 界面浏览器提交 SQL++ 的新版界面
19004NC HTTP APInc1 节点的管理接口
9090NCService 监听CC 经它与 NCService 通信拉起 NC
1098 / 1099CC 客户端 / 集群监听Hyracks 层内部通信端口
19003Active Server默认未启用，不监听（见「八、常见问题」8.3）

二、前置条件

  • 一台 Ubuntu 22.04 服务器，root 权限。
  • 安装 OpenJDK 11 与基础工具：wget、curl、net-tools、procps（含 jps）、unzip。
  • 磁盘：安装包约 223MB，加上数据目录与日志，预留 2GB 以上空间。
  • 内存：本文将 JVM 堆限制在 256-512MB（NC 与 CC 各一份），1GB 以上内存即可运行；未限制堆时 AsterixDB 默认会按物理内存的 1/4 取存储内存预算，小规格服务器必须显式调小。

三、版本选型说明

Apache AsterixDB 的所有发行版都发布在 Apache 官方下载站 https://downloads.apache.org/asterixdb/，截至本文实测（2026-10）该目录下有以下版本线：

版本说明
0.9.6 ~ 0.9.80.9 线历史版本
0.9.9当前最新稳定版（本文采用，/admin/version 实测 git.build.version=0.9.9，构建于 hyracks-0.3.8.1，commit f908c99）

下载目录内常见制品的用途区分：

制品说明
asterix-server-0.9.9-binary-assembly.zip服务端二进制组装包，含 CC/NC 全部组件（本文采用）
asterixdb-jdbc-0.9.8.xJDBC 驱动，供应用侧连接 19002 的 HTTP API
hyracks-0.3.x底层并行计算框架独立发行包，部署 AsterixDB 用不到

关键差异：部署服务端只取 asterix-server-*-binary-assembly.zip 一个制品即可；JDBC 驱动版本线略滞后于服务端（0.9.8.x 对接 0.9.9 服务端无碍）。

💡 技术拓展：AsterixDB 的集群部署入口不止本文的 NCService 一种，常见方式对比——

方式特点适用场景
NCService（本文采用）每台机器跑一个 NCService 看护进程，CC 经 9090 端口远程拉起 NC，0.9.9 发行包 bin/ 下仅 asterixcc、asterixnc、asterixncservice、asterixhelper 四个脚本（实测），单机与多机统一入口单机试用与常规部署
Ansible Playbook发行包 opt/ansible/ 内置部署剧本，按清单批量装机多台固定拓扑批量交付
手工多进程直接 asterixnc 拉起 NC 再起 CC，无看护进程调试排障

本文为单机环境，采用 NCService 方式：NCService 常驻，CC 按配置文件里的节点清单自动经 9090 端口把 NC 拉起来。

四、方案 A：官方 zip 在线下载安装（推荐）

本方案从 Apache 官方下载站直接获取二进制组装包安装，适合可访问外网的服务器，是最简单直接的方式。

4.1 安装 JDK 与基础工具

apt-get update -qq
DEBIAN_FRONTEND=noninteractive apt-get install -y \
    openjdk-11-jdk-headless wget curl net-tools procps unzip

验证 Java 版本：

java -version

openjdk version "11.0.32.1" 2026-08-18
OpenJDK Runtime Environment (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu, mixed mode, sharing)

jps -V

jps 11.0.32.1

确认 JAVA_HOME 实际路径（后续 systemd 配置要用）：

readlink -f $(which java)

/usr/lib/jvm/java-11-openjdk-amd64/bin/java

即 JAVA_HOME 为 /usr/lib/jvm/java-11-openjdk-amd64。

4.2 下载发行包并校验 sha512

cd /opt
wget https://downloads.apache.org/asterixdb/asterixdb-0.9.9/asterix-server-0.9.9-binary-assembly.zip

下载末行与耗时回显（实测）：

2026-10-13 09:28:59 (13.9 MB/s) - 'asterix-server-0.9.9-binary-assembly.zip' saved [232931001/232931001]

real    0m17.178s
user    0m0.653s
sys     0m2.086s

核对文件大小与官方 sha512：

ls -l asterix-server-0.9.9-binary-assembly.zip
wget -q -O asterix-server-0.9.9-binary-assembly.zip.sha512 \
  https://downloads.apache.org/asterixdb/asterixdb-0.9.9/asterix-server-0.9.9-binary-assembly.zip.sha512
echo "official: $(awk '{print $1}' asterix-server-0.9.9-binary-assembly.zip.sha512)"
echo "actual:   $(sha512sum asterix-server-0.9.9-binary-assembly.zip | awk '{print $1}')"

-rw-r--r-- 1 root root 232931001 Mar  5  2024 asterix-server-0.9.9-binary-assembly.zip
official: fadd92650d312bb9a5c90f9d654d0de1ca2c87dd29aa0d3a93bc2f0f5ba802979108d4974620343473b6c3a5fd6289c7696f07128900e2fe5609d086889bcdc6
actual:   fadd92650d312bb9a5c90f9d654d0de1ca2c87dd29aa0d3a93bc2f0f5ba802979108d4974620343473b6c3a5fd6289c7696f07128900e2fe5609d086889bcdc6

两值一致，制品完整。

4.3 解压部署到 /opt/asterixdb

cd /opt
unzip -q asterix-server-0.9.9-binary-assembly.zip -d /opt
mv /opt/apache-asterixdb-0.9.9 /opt/asterixdb
ls /opt/asterixdb/

LICENSE  NOTICE  bin  etc  lib  opt  repo

创建本文需要的配置、数据、日志与临时目录：

mkdir -p /opt/asterixdb/{conf,data/{txnlog,coredump,iodevice},logs,tmp}

查看 bin/ 与 opt/ 目录内容，确认可用脚本：

ls /opt/asterixdb/bin/ /opt/asterixdb/opt/

/opt/asterixdb/bin/:
asterixcc  asterixcc.bat  asterixhelper  asterixhelper.bat  asterixnc  asterixnc.bat  asterixncservice  asterixncservice.bat

/opt/asterixdb/opt/:
ansible  aws  local
文件/目录用途
bin/asterixcc启动 Cluster Controller（CC，集群控制器）
bin/asterixncservice启动 NCService 看护进程，CC 经它拉起 NC
bin/asterixncNC 驱动本体，由 NCService 拉起，一般不手工执行
bin/asterixhelper集群状态查询、等待与停机助手
opt/local/bin/start-sample-cluster.sh官方示例集群启停脚本（见「八、常见问题」前的示例集群一节）
opt/ansible/多机 Ansible 部署剧本（可选）

4.4 编写单 NC 集群配置 cc.conf

AsterixDB 的集群拓扑、存储路径与 JVM 参数都集中在一个 ini 风格的配置文件里。创建 /opt/asterixdb/conf/cc.conf：

cat > /opt/asterixdb/conf/cc.conf <<'EOF'
[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
EOF

逐项说明：

段/参数本文取值说明
[nc/nc1]节点段每个方括号定义一个 NC 节点，nc1 为节点名，多节点时追加 [nc/nc2] 等段
txn.log.dir / core.dump.dir / iodevices/opt/asterixdb/data/ 下三个子目录事务日志、core dump 与存储设备目录，需真实存在
nc.api.port19004该 NC 的 HTTP 管理接口端口
jvm.args-Xms256m -Xmx512m -Djava.io.tmpdir=/opt/asterixdb/tmpNCDriver 的 JVM 参数入口，堆限制在此设置；-Djava.io.tmpdir 指向可执行目录（原因见 8.1）
[nc] address127.0.0.1单机部署时 NC 与 CC 同机
[nc] commandasterixncNCService 拉起 NC 用的命令名
[cc] address127.0.0.1CC 绑定地址，多机时改为本机对外 IP
[cc] api.port19002HTTP API 与 SQL++ 查询服务端口
[cc] web.port19001Web 控制台端口（旧版查询界面）
[cc] active.port19003Active Server 端口，默认未启用
[common] log.dir / log.levellogs / INFO日志目录与级别，各段可覆盖

发行包自带一个双 NC 的示例配置 /opt/asterixdb/opt/local/conf/cc.conf，可作多节点写法参考。

4.5 启动集群（NCService + CC）

先启动 NCService 看护进程：

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

asterixncservice 默认监听 9090 端口等待 CC 指令，不指定任何参数即可工作。再启动 CC（堆参数经 JAVA_OPTS 环境变量注入）：

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 &

CC 启动后会按 cc.conf 的节点清单经 9090 端口通知 NCService 拉起 NCDriver，等待约 10-20 秒后用 jps -l 确认三个进程：

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.6 验证集群状态与 SQL++ HTTP API

用 asterixhelper 查询集群状态：

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.

确认端口监听：

netstat -tlnp | grep 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

七个端口全部就绪（另有若干随机高位端口为 JVM 内部 RMI 通信端口，属正常现象）。提交第一条 SQL++：

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
        }
}

建域、建类型、建表、插入并查询的完整 SQL++ 流程（注意：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;"

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

{
        "requestID": "0c9dd6b8-1046-4a58-992b-f9d1c26cb54f",
        "signature": { "*": "*" },
        "results": [ { "Greetings": { "id": 1, "message": "Hello AsterixDB!" } } ],
        "plans":{},
        "status": "success",
        "metrics": {
                "elapsedTime": "1.126774806s", "executionTime": "1.101951014s",
                "compileTime": "395.875869ms", "queueWaitTime": "6ms",
                "resultCount": 1, "resultSize": 60, "processedObjects": 1
        }
}

再看版本信息接口（免认证）：

curl -s http://localhost:19002/admin/version

{"git.tags":"","git.build.version":"0.9.9","git.closest.tag.commit.count":"642","git.commit.user.name":"Michael Blow","git.commit.id.abbrev":"f908c99","git.branch":"master","git.build.host":"turnip-ubuntu","git.commit.id.describe-short":"apache-hyracks-0.3.8.1-642-dirty","git.commit.id.describe":"apache-hyracks-0.3.8.1-642-gf908c99-dirty","git.build.user.email":"imaxon@apache.org","git.commit.id":"f908c997c6940b3799b487718f9bd0e6eade50fe","git.commit.message.short":"Merge branch 'gerrit/trinity' into 'master'","git.commit.user.email":"michael.blow@couchbase.com","git.closest.tag.name":"apache-hyracks-0.3.8.1","git.build.time":"2024-02-29T13:31:16-0800","git.commit.time":"2024-02-28T09:59:44-0800","git.build.user.name":"Ian Maxon","git.dirty":"true","git.commit.message.full":"Merge branch 'gerrit/trinity' into 'master'\n\nChange-Id: If1f5c3109250d6a7cf8f92d3dea6fb403b4e70dc","git.remote.origin.url":"https://github.com/apache/asterixdb"}

浏览器侧访问 http://<服务器IP>:19001/ 为 Web 控制台，http://<服务器IP>:19006/ 为新版查询界面，可在页面里直接提交 SQL++。

4.7 JVM 堆内存限制（256-512MB）

AsterixDB 有两个常驻 Java 进程需要管堆，入口不同：

  • NCDriver（NC 数据节点）：堆由 cc.conf 中 [nc/nc1] 段的 jvm.args 控制，NCService 拉起 NC 时会把该值原样附加到启动命令（并自动追加 -XX:MaxGCPauseMillis=25000）。
  • CCDriver（集群控制器）：asterixcc 脚本读取环境变量 JAVA_OPTS 作为 JVM 参数，堆在启动命令的 JAVA_OPTS 里设置；改用 systemd 托管后则写在单元文件的 Environment= 行（见 4.8）。

用 jps -v 验证两个进程的实际生效堆（实测）：

jps -v

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

NCService 本身是轻量看护进程，无堆参数；CCDriver 与 NCDriver 均为 -Xms256m -Xmx512m，符合 256-512MB 限制。调整方法：改 cc.conf 的 jvm.args（NC）或 JAVA_OPTS（CC），重启对应进程后用 jps -v 复核，不得只改不验。

⚠️ jvm.args 与 JAVA_OPTS 里的 -Djava.io.tmpdir=/opt/asterixdb/tmp 不要省略：AsterixDB 刷盘时要解压 snappy 本地库到临时目录，若临时目录不可执行会导致 NC 进程直接崩溃，见「八、常见问题」8.1。

4.8 systemd 托管

先优雅停掉手工启动的集群（见 8.4，进程完全退出约需 10-25 秒）：

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.

编写 NCService 的服务单元 /etc/systemd/system/asterixdb-nc.service：

cat > /etc/systemd/system/asterixdb-nc.service <<'EOF'
[Unit]
Description=AsterixDB NCService (nc1)
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/asterixdb
ExecStart=/opt/asterixdb/bin/asterixncservice -logdir /opt/asterixdb/logs
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

编写 CC 的服务单元 /etc/systemd/system/asterixdb-cc.service：

cat > /etc/systemd/system/asterixdb-cc.service <<'EOF'
[Unit]
Description=AsterixDB Cluster Controller (CC)
Requires=asterixdb-nc.service
After=network.target asterixdb-nc.service

[Service]
Type=simple
User=root
WorkingDirectory=/opt/asterixdb
Environment="JAVA_OPTS=-Xms256m -Xmx512m -Djava.io.tmpdir=/opt/asterixdb/tmp"
ExecStart=/opt/asterixdb/bin/asterixcc -config-file /opt/asterixdb/conf/cc.conf
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF
配置项说明
Requires=asterixdb-nc.serviceCC 依赖 NCService，启动 CC 前先拉起 NCService
Environment="JAVA_OPTS=-Xms256m -Xmx512m -Djava.io.tmpdir=/opt/asterixdb/tmp"CC 的 JVM 堆与临时目录参数，每行仅一个 Environment
Restart=on-failure / RestartSec=10异常退出 10 秒后自动拉起
NCService 单元不带 JAVA_OPTSNCService 无需大堆；NC 的堆在 cc.conf 的 jvm.args 里

启用并启动（每条命令只操作一个单元）：

systemctl daemon-reload
systemctl enable asterixdb-nc.service

Created symlink /etc/systemd/system/multi-user.target.wants/asterixdb-nc.service → /etc/systemd/system/asterixdb-nc.service

systemctl enable asterixdb-cc.service

Created symlink /etc/systemd/system/multi-user.target.wants/asterixdb-cc.service → /etc/systemd/system/asterixdb-cc.service

systemctl start asterixdb-nc.service
systemctl start asterixdb-cc.service

等待约 20 秒后确认服务状态：

systemctl is-active asterixdb-nc.service
systemctl is-active asterixdb-cc.service

active
active

systemd 托管下复核集群状态与 JVM 堆生效值：

bin/asterixhelper get_cluster_state
jps -lv | grep -E 'CCDriver|NCDriver' | grep -oE '\-Xms[0-9]+m -Xmx[0-9]+m'

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

最后验证数据持久化：先优雅停集群再整机重启（或先 stop 两个单元再 start），数据仍在：

bin/asterixhelper shutdown_cluster_all
systemctl stop asterixdb-cc.service
systemctl stop asterixdb-nc.service
sleep 30
systemctl start asterixdb-nc.service
systemctl start asterixdb-cc.service
sleep 20
curl -s http://localhost:19002/query/service --data-urlencode "statement=SELECT * FROM demo.Greetings ORDER BY id;" | grep -o '"status": "[a-z]*"'

"status": "success"

事务日志与存储设备都落在 /opt/asterixdb/data/，重启后 demo.Greetings 的数据完整保留。

五、方案 B：离线包安装（内网服务器）

内网服务器无法直接访问下载站时，先在任一台可联网机器上下载好全套制品，再拷贝到目标服务器安装。安装主体步骤与方案 A 一致，差异只在「下载 + 校验 + 传输」环节。

5.1 在可联网机器上下载制品

mkdir -p asterixdb-offline && cd asterixdb-offline
wget -q https://downloads.apache.org/asterixdb/asterixdb-0.9.9/asterix-server-0.9.9-binary-assembly.zip
wget -q https://downloads.apache.org/asterixdb/asterixdb-0.9.9/asterix-server-0.9.9-binary-assembly.zip.sha512
apt-get download openjdk-11-jdk-headless openjdk-11-jre-headless
ls -l

-rw-r--r-- 1 root root 232931001 Mar  5  2024 asterix-server-0.9.9-binary-assembly.zip
-rw-r--r-- 1 root root        129 Mar  5  2024 asterix-server-0.9.9-binary-assembly.zip.sha512
-rw-r--r-- 1 root root 45927490 openjdk-11-jdk-headless_11.0.32.1+1-1ubuntu1~22.04_amd64.deb
-rw-r--r-- 1 root root 45478672 openjdk-11-jre-headless_11.0.32.1+1-1ubuntu1~22.04_amd64.deb

⚠️ deb 文件名里的 JDK 小版本会随 Ubuntu 更新变化，以上为实测时的取到值；以 apt download 实际下载的文件名为准。

5.2 传输并校验

把目录整体拷贝到内网目标服务器后，先核对 sha512（与官方 .sha512 文件比对）：

cd /opt/install
sha512sum asterix-server-0.9.9-binary-assembly.zip | awk '{print $1}'
awk '{print $1}' asterix-server-0.9.9-binary-assembly.zip.sha512

fadd92650d312bb9a5c90f9d654d0de1ca2c87dd29aa0d3a93bc2f0f5ba802979108d4974620343473b6c3a5fd6289c7696f07128900e2fe5609d086889bcdc6
fadd92650d312bb9a5c90f9d654d0de1ca2c87dd29aa0d3a93bc2f0f5ba802979108d4974620343473b6c3a5fd6289c7696f07128900e2fe5609d086889bcdc6

5.3 离线安装 JDK

dpkg -i openjdk-11-jre-headless_*.deb openjdk-11-jdk-headless_*.deb
java -version

openjdk version "11.0.32.1" 2026-08-18
OpenJDK Runtime Environment (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu, mixed mode, sharing)

若 dpkg 报依赖缺失，在有网的同版本系统上执行 apt-get install --download-only --reinstall -y openjdk-11-jdk-headless，把 /var/cache/apt/archives/*.deb 一并拷来再 dpkg -i 安装。

5.4 解压与配置（与方案 A 相同）

解压部署、编写 cc.conf、启动验证、JVM 堆限制与 systemd 托管与方案 A 的 4.3、4.4、4.5、4.6、4.7、4.8 步骤逐条相同，按其执行即可。核心差异只有一点：下载环节由「服务器直连下载站」换为「离线拷贝 + sha512 校验」，其余命令与回显完全一致。

六、方案对比与选择建议

维度方案 A：在线 zip方案 B：离线包
版本0.9.90.9.9
需联网服务器需访问 downloads.apache.org仅中转机联网
安装方式wget 下载 + unzip 解压拷贝传输 + sha512 校验 + unzip 解压
systemd 来源手写单元文件（nc + cc 两个）同左
监听端口19001/19002/19004/19006/9090 等同左
优点步骤最少、可即时取最新校验文件内网可交付、制品可留档复用
缺点依赖外网连通性需多一步传输与校验

选择建议：可联网环境直接用方案 A；内网隔离、批量交付或多台同版本部署时用方案 B。两方案产物一致，后续配置与升级方式完全相同。

七、配置说明

本节汇总安装相关的常用配置项位置，各参数的完整含义与默认值见《Apache AsterixDB 0.9.9 配置参数详解》。

配置文件位置本文取值
集群拓扑与节点清单/opt/asterixdb/conf/cc.conf 的 [nc/nc1] 段单节点 nc1
HTTP API / Web 控制台端口同文件 [cc] 段 api.port / web.port19002 / 19001
NC 数据目录同文件 [nc/nc1] 段 txn.log.dir 等/opt/asterixdb/data/ 三个子目录
NC JVM 堆同文件 [nc/nc1] 段 jvm.args-Xms256m -Xmx512m
CC JVM 堆systemd 单元 Environment=JAVA_OPTS=-Xms256m -Xmx512m -Djava.io.tmpdir=/opt/asterixdb/tmp 或启动命令前缀-Xms256m -Xmx512m
日志目录与级别同文件 [common] 段/opt/asterixdb/logs，INFO
systemd 单元/etc/systemd/system/asterixdb-nc.service、asterixdb-cc.serviceType=simple

修改任一配置后需重启对应服务生效：改 [nc] 类参数重启两个单元（先 cc 后 nc 全部重启），改 [cc] 类参数仅重启 asterixdb-cc；重启后用 asterixhelper get_cluster_state 确认回到 ACTIVE。

八、常见问题

8.1 NC 崩溃：UnsatisfiedLinkError failed to map segment from shared object

现象：查询涉及刷盘（写入数据集后触发 flush）时，NC 日志出现致命错误并伴随 JVM 退出：

09:01:14.641 [Executor-12:nc1] ERROR org.apache.hyracks.storage.common.buffercache.FIFOLocalWriter - FIFOLocalWriter has encountered a fatal error
java.lang.UnsatisfiedLinkError: /tmp/snappy-1.1.10-ed5e8baa-<随机串>.so: failed to map segment from shared object
        at org.xerial.snappy.SnappyLoader.loadNativeLibrary(SnappyLoader.java:182) ~[snappy-java-1.1.10.5.jar:1.1.10.5]
09:01:14.643 FATAL org.apache.hyracks.util.ExitUtil - JVM halting with status 1

定位：snappy-java 首次使用时把本地库 .so 解压到 java.io.tmpdir（默认 /tmp）再 mmap 加载；当 /tmp 挂载了 noexec（用 mount | grep " /tmp " 可见 noexec 标志）时，映射共享对象失败，NC 进程直接 halt。

解决：把 JVM 临时目录指到可执行的普通目录（4.4/4.7 已包含），NC 与 CC 两处都要加：

grep tmpdir /opt/asterixdb/conf/cc.conf

jvm.args=-Xms256m -Xmx512m -Djava.io.tmpdir=/opt/asterixdb/tmp

重启集群后重新写入数据，get_cluster_state 回到 ACTIVE 且查询正常。真实服务器上 /tmp 被运维统一挂成 noexec 的场景同样适用此修复。

8.2 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 文件；该命令在当前版本不可用。同时实测 0.9.9 的 HTTP 接口默认无认证：带不带凭据访问 /admin/version 均返回 200。

解决：放弃 add_credential，靠网络层限制访问面——cc.conf 的 [cc] address 保持 127.0.0.1（仅本机可访问）或用防火墙限制 19001/19002 来源网段。升级到修复了该缺陷的版本后再启用接口认证。

8.3 端口 19003 未监听

现象：netstat -tlnp | grep 19003 无输出，而配置里写了 active.port=19003。

定位：19003 是 Active Server（事件/订阅运行时）的监听端口，默认未启用；只有启用 active runtime（如 CDC/消息订阅场景）后 CC 才会在该端口监听。

影响与解决：不影响 SQL++ 查询、Web 控制台与数据写入，无需处理；确需使用 Active Server 时按官方文档在 [cc] 段启用相应配置。

8.4 shutdown 后进程未立即退出

现象：asterixhelper shutdown_cluster_all 返回 accepted shutdown request 后，jps -l 里进程仍在。

定位：AsterixDB 的停机是优雅流程——NCDriver 先退出，CC 与 NCService 随后收尾，实测全程约 10-25 秒；accepted shutdown request 只表示请求受理，不代表进程已退出。

解决：等待 25 秒以上再复核，全部退出后再执行后续操作：

sleep 25 && jps -l

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

仅剩 Jps 自身即已全停。systemd 场景下 systemctl stop 同样要等此流程，勿在 10 秒内连发重启命令。

九、卸载与清理

先优雅停集群并取消自启（每条命令只操作一个单元）：

bin/asterixhelper shutdown_cluster_all
systemctl stop asterixdb-cc.service
systemctl stop asterixdb-nc.service
systemctl disable asterixdb-cc.service
systemctl disable asterixdb-nc.service

Removed "/etc/systemd/system/multi-user.target.wants/asterixdb-cc.service".
Removed "/etc/systemd/system/multi-user.target.wants/asterixdb-nc.service".

删除服务单元、安装目录与制品：

rm -f /etc/systemd/system/asterixdb-nc.service /etc/systemd/system/asterixdb-cc.service
systemctl daemon-reload
rm -rf /opt/asterixdb /opt/asterix-server-0.9.9-binary-assembly.zip /opt/asterix-server-0.9.9-binary-assembly.zip.sha512

如需一并卸载 JDK：

apt-get purge -y openjdk-11-jdk-headless openjdk-11-jre-headless && apt-get autoremove -y

十、参考链接