Ubuntu 22.04 安装 Apache IoTDB 2.0.11 指南

在 Ubuntu 22.04 真实服务器上从零到一离线/在线安装 Apache IoTDB 2.0.11（standalone），含 JDK17 配置、JVM 堆限制、启动与 CLI 建库建测点插查全流程实测。

Apache IoTDBApache IoTDB安装部署数据库ApacheUbuntu 22.04时间序列2026/10/11

Ubuntu 22.04 安装 Apache IoTDB 2.0.11 指南

目标：在 Ubuntu 22.04 x86_64 真实服务器上完成 Apache IoTDB（时序数据库）2.0.11 的 0→1 全流程安装与验证，覆盖 JDK 环境、JVM 堆限制、standalone 启动、CLI 建库建测点与插入查询，已在 /opt/iotdb-exp（安装根目录 /opt/iotdb-exp/apache-iotdb-2.0.11-all-bin）实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（NAME="Ubuntu"，VERSION_ID="22.04"）
  • 系统架构：x86_64（uname -m 输出 x86_64）
  • 运行用户：root
  • JDK：OpenJDK 17.0.20.1（IoTDB 2.0.x 要求 Java 17 及以上）
  • 安装目录：/opt/iotdb-exp/apache-iotdb-2.0.11-all-bin
  • 数据目录：/opt/iotdb-exp/apache-iotdb-2.0.11-all-bin/data（含 confignode/、datanode/）
  • 日志目录：/opt/iotdb-exp/apache-iotdb-2.0.11-all-bin/logs
  • 关键端口：6667（DataNode CLI/RPC）、10710（ConfigNode RPC）、10720（ConfigNode 共识）、10730（DataNode 内部 RPC）、10740（MPP 数据交换）、10750/10760（schema/data region 共识）、9091/9092（Prometheus 指标）
  • 版本：Apache IoTDB 2.0.11（Build 7c0de06，SHOW VERSION; 实测）
  • 下载源：https://downloads.apache.org/iotdb/2.0.11/
  • 测试账号：root / 密码 q1w2e3r4（由默认密码修改而来）

二、前置条件

  • 操作系统为 Ubuntu 22.04（PASS 认证、x86_64）。
  • 能够访问外网以便 apt 安装依赖、wget 从 Apache 官方下载（下载源 downloads.apache.org / archive.apache.org）。
  • 至少 4GB 内存用于 standalone 双进程（ConfigNode + DataNode）运行；下方会显式把 JVM 堆限制在 512MB，见「五、配置说明」。
  • 磁盘留有足够空间存放数据与 WAL（测试环境约需要数百 MB 以上）。
  • 拥有 root 权限执行安装与启动。

三、版本选型说明

Apache IoTDB 官方下载目录 https://downloads.apache.org/iotdb/ 实测存在以下版本线（2026 年 10 月）：

版本线目录状态说明
0.13.40.13.4/老旧早期导入(cluster)，脚本与目录结构与 1.x/2.x 差异大，不推荐
1.3.71.3.7/稳定/维护引入 Tree+Table 模型雏形，start-server.sh 形态
2.0.102.0.10/稳定2.0 稳定线，树+表双模型
2.0.112.0.11/最新稳定（推荐）当前 Apache 官方最新稳定版，本指南实测版本

💡 说明：2.0.x 起安装包统一拆分为 all-bin、confignode-bin、datanode-bin、cli-bin、edge-bin、library-udf-bin 等独立压缩包。单机/测试使用 apache-iotdb-<版本>-all-bin.zip 一个包即可包含 ConfigNode、DataNode 与 CLI；集群场景则分别使用 confignode-bin 与 datanode-bin 部署在两台服务器。

建议：内网隔离、无外网或公司离线环境 → 提前用 wget 把 all-bin.zip 与校验和文件下载到本地再上传；可联网环境 → 直接按本指南在线 wget 下载即可。

四、部署步骤

4.1 更新系统源并安装依赖（JDK、wget、unzip）

apt-get update
apt-get install -y openjdk-17-jdk-headless wget unzip net-tools

安装完成后确认 Java 版本（实测输出）：

java -version

回显：

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

⚠️ 注意：IoTDB 2.0.x 的 datanode-env.sh/confignode-env.sh 启动脚本会检查 JDK 大版本，Maj.Api < 17 时直接报 IoTDB requires Java 17 or later. 并退出，因此必须使用 Java 17+，不能再用 JDK 8/11 启动 2.0.x。

4.2 配置 JAVA_HOME 环境变量

JDK 17 安装路径为 /usr/lib/jvm/java-17-openjdk-amd64。写入 /etc/profile.d/java.sh 使其登录即生效：

echo "export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64" > /etc/profile.d/java.sh
echo "export PATH=\$JAVA_HOME/bin:\$PATH" >> /etc/profile.d/java.sh
chmod +x /etc/profile.d/java.sh
source /etc/profile.d/java.sh
echo $JAVA_HOME

验证回显：

/usr/lib/jvm/java-17-openjdk-amd64

💡 说明：sbin/start-cli.sh 等脚本默认从 JAVA_HOME 或 PATH 里找 java；若未设置 JAVA_HOME，脚本报 Unable to find java executable. Check JAVA_HOME and PATH environment variables.。配置好 JAVA_HOME 即可避免。

4.3 从 Apache 官方下载 IoTDB 2.0.11 all-bin

mkdir -p /opt/iotdb-exp
cd /opt/iotdb-exp
wget https://downloads.apache.org/iotdb/2.0.11/apache-iotdb-2.0.11-all-bin.zip

下载完成后核对文件大小与校验和（本指南实测）：

ls -lh apache-iotdb-2.0.11-all-bin.zip
sha512sum apache-iotdb-2.0.11-all-bin.zip

实测回显：

-rw-r--r-- 1 root root 114M Sep 11 02:55 apache-iotdb-2.0.11-all-bin.zip
f569ffc94aed2ad898cb256e693ff85c8a0d9bbf02a7bb920858d152b1f0980a4b2f5e4574ddc5727268f5522d739b7cda7abc3d72eb604fc20ce821ca829ed0  apache-iotdb-2.0.11-all-bin.zip

⚠️ 注意：Apache 每个版本目录下都有 KEYS 与对应 .sha512/.asc 文件，生产环境建议下载校验和文件并比对，防止下载被篡改。

4.4 解压到安装目录

cd /opt/iotdb-exp
unzip -q apache-iotdb-2.0.11-all-bin.zip
ls -la /opt/iotdb-exp/apache-iotdb-2.0.11-all-bin

解压后顶层结构（实测）：

LICENSE  NOTICE  README.md  README_ZH.md  RELEASE_NOTES.md
conf  lib  licenses  sbin  tools

关键目录说明：

目录说明
sbin/启动脚本：start-standalone.sh、start-confignode.sh、start-datanode.sh、start-cli.sh、stop-*.sh
conf/配置文件：iotdb-system.properties、datanode-env.sh、confignode-env.sh 等
lib/依赖 jar 包
tools/运维与工具脚本（导入导出、schema 管理、tsfile 校验等）

4.5 启动 standalone 服务

2.0.x 单机使用 sbin/start-standalone.sh，会同时拉起 ConfigNode 与 DataNode 两个 Java 进程：

cd /opt/iotdb-exp/apache-iotdb-2.0.11-all-bin
sbin/start-standalone.sh

实测回显：

Execute start-standalone.sh finished, you can see more details in the logs of confignode and datanode

4.6 验证进程与端口

进程（jps -l 实测）：

3684 org.apache.iotdb.db.service.DataNode
3592 org.apache.iotdb.confignode.service.ConfigNode
5706 jdk.jcmd/sun.tools.jps.Jps

使用 jps -v 确认 JVM 堆设置生效（实测摘录，可见 -Xms512M -Xmx512M -XX:MaxDirectMemorySize=256M）：

3592 ConfigNode -Xms512M -Xmx512M -XX:MaxDirectMemorySize=256M -Dname=iotdb.ConfigNode
3684 DataNode   -Xms512M -Xmx512M -XX:MaxDirectMemorySize=256M -Dname=iotdb.IoTDB

端口监听（netstat 实测）：

tcp6   0   0 127.0.0.1:6667   :::*   LISTEN   3684/java
tcp6   0   0 127.0.0.1:10710  :::*   LISTEN   3592/java
tcp6   0   0 127.0.0.1:10730  :::*   LISTEN   3684/java

日志就绪信息（logs/log_datanode_all.log 与 logs/log_confignode_all.log 实测摘录）：

Congratulations, IoTDB DataNode is set up successfully. Now, enjoy yourself!
DataNode started
IoTDB-ConfigNode has successfully started and joined the cluster: defaultCluster.
IoTDB started

4.7 用 CLI 连接并做功能验证

先以默认账号 root/root 连接，把密码改为团队公共演示密码 q1w2e3r4：

cd /opt/iotdb-exp/apache-iotdb-2.0.11-all-bin
sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root -e "ALTER USER root SET PASSWORD \"q1w2e3r4\";"

回显：

Msg: The statement is executed successfully.

查看现有数据库：

sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4 -e "SHOW DATABASES;"

回显：

+--------+-----------------------+---------------------+-------------------+---------------------+
|Database|SchemaReplicationFactor|DataReplicationFactor|TimePartitionOrigin|TimePartitionInterval|
+--------+-----------------------+---------------------+-------------------+---------------------+
Empty set.
It costs 0.285s

创建数据库（即数据结构中的 database/schema group）：

sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4 -e "CREATE DATABASE root.iot;"
sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4 -e "SHOW DATABASES;"

回显：

Msg: The statement is executed successfully.
+--------+-----------------------+---------------------+-------------------+---------------------+
|Database|SchemaReplicationFactor|DataReplicationFactor|TimePartitionOrigin|TimePartitionInterval|
+--------+-----------------------+---------------------+-------------------+---------------------+
|root.iot|                      1|                    1|                  0|            604800000|
+--------+-----------------------+---------------------+-------------------+---------------------+
Total line number = 1
It costs 0.123s

创建测点（时间序列 schema）：

sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4 -e "CREATE TIMESERIES root.iot.sensor.temperature WITH DATATYPE=FLOAT, ENCODING=PLAIN, COMPRESSOR=SNAPPY;"
sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4 -e "CREATE TIMESERIES root.iot.sensor.humidity WITH DATATYPE=DOUBLE, ENCODING=PLAIN, COMPRESSOR=SNAPPY;"
sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4 -e "SHOW TIMESERIES;"

回显：

Msg: The statement is executed successfully.
Msg: The statement is executed successfully.
+---------------------------+-----+--------+--------+--------+-----------+----+----------+--------+------------------+--------+
|                 Timeseries|Alias|Database|DataType|Encoding|Compression|Tags|Attributes|Deadband|DeadbandParameters|ViewType|
+---------------------------+-----+--------+--------+--------+-----------+----+----------+--------+------------------+--------+
|root.iot.sensor.temperature| null|root.iot|   FLOAT|   PLAIN|     SNAPPY|null|      null|    null|              null|    BASE|
|   root.iot.sensor.humidity| null|root.iot|  DOUBLE|   PLAIN|     SNAPPY|null|      null|    null|              null|    BASE|
+---------------------------+-----+--------+--------+--------+-----------+----+----------+--------+------------------+--------+
Total line number = 2
It costs 0.963s

插入时序数据：

sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4 -e "INSERT INTO root.iot.sensor(timestamp, temperature, humidity) VALUES (1690000000000, 25.5, 60.0);"
sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4 -e "INSERT INTO root.iot.sensor(timestamp, temperature, humidity) VALUES (1690000001000, 26.2, 58.8), (1690000002000, 27.0, 61.5);"

回显：

Msg: The statement is executed successfully.
Msg: The statement is executed successfully.

查询时序数据：

sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4 -e "SELECT * FROM root.iot.sensor;"

回显：

+------------------------+---------------------------+------------------------+
|                    Time|root.iot.sensor.temperature|root.iot.sensor.humidity|
+------------------------+---------------------------+------------------------+
|2023-07-22T04:26:40.000Z|                       25.5|                    60.0|
|2023-07-22T04:26:41.000Z|                       26.2|                    58.8|
|2023-07-22T04:26:42.000Z|                       27.0|                    61.5|
+------------------------+---------------------------+------------------------+
Total line number = 3
It costs 0.332s

查看版本：

sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4 -e "SHOW VERSION;"

回显：

+-------+---------+
|Version|BuildInfo|
+-------+---------+
| 2.0.11|  7c0de06|
+-------+---------+
Total line number = 1
It costs 0.026s

五、配置说明

5.1 配置文件位置

文件作用
conf/iotdb-system.properties集群/节点/RPC/端口/副本/目录/指标等核心配置
conf/datanode-env.shDataNode 的 JVM 参数（堆、非堆、GC 日志等）
conf/confignode-env.shConfigNode 的 JVM 参数
conf/iotdb-common.sh通用环境脚本
conf/jmx.access / conf/jmx.passwordJMX 认证

5.2 端口配置（conf/iotdb-system.properties）

实测默认值（摘录）：

cn_internal_address=127.0.0.1
cn_internal_port=10710
cn_consensus_port=10720

dn_rpc_address=127.0.0.1
dn_rpc_port=6667
dn_internal_address=127.0.0.1
dn_internal_port=10730
dn_mpp_data_exchange_port=10740
dn_schema_region_consensus_port=10750
dn_data_region_consensus_port=10760

schema_replication_factor=1
data_replication_factor=1
dn_metric_prometheus_reporter_port=9092

5.3 JVM 堆限制（256–512MB）

2.0.x 通过 conf/datanode-env.sh 与 conf/confignode-env.sh 里的 ON_HEAP_MEMORY/OFF_HEAP_MEMORY 控制堆（-Xms/-Xmx）与非堆（-XX:MaxDirectMemorySize）。默认按系统内存 1/2 自动计算，测试/低配服务器建议显式限制在 256–512MB。

编辑 conf/datanode-env.sh，把堆设为 512MB、非堆 256MB（把注释掉的默认行放开并按需改值）：

cd /opt/iotdb-exp/apache-iotdb-2.0.11-all-bin/conf
sed -i "s|#ON_HEAP_MEMORY=\"2G\"|ON_HEAP_MEMORY=\"512M\"|g" datanode-env.sh
sed -i "s|#OFF_HEAP_MEMORY=\"512M\"|OFF_HEAP_MEMORY=\"256M\"|g" datanode-env.sh
sed -i "s|#ON_HEAP_MEMORY=\"2G\"|ON_HEAP_MEMORY=\"512M\"|g" confignode-env.sh
sed -i "s|#OFF_HEAP_MEMORY=\"512M\"|OFF_HEAP_MEMORY=\"256M\"|g" confignode-env.sh

修改后重启服务，并用 jps -v 验证生效（实测看到 -Xms512M -Xmx512M -XX:MaxDirectMemorySize=256M）：

3592 ConfigNode -Xms512M -Xmx512M -XX:MaxDirectMemorySize=256M -Dname=iotdb.ConfigNode
3684 DataNode   -Xms512M -Xmx512M -XX:MaxDirectMemorySize=256M -Dname=iotdb.IoTDB

💡 说明：若需更小堆（256MB），把 ON_HEAP_MEMORY 与 FF_HEAP_MEMORY 均改为 256M 即可。堆过小会触发频繁 GC，适合纯功能验证；生产建议按数据量评估。

六、注意事项

  • IoTDB 2.0.x 要求 Java 17+，JAVA_HOME 未配置会启动失败。
  • 首次连接建议使用默认 root/root，随后用 ALTER USER root SET PASSWORD 修改为强密码 q1w2e3r4。
  • 单机 start-standalone.sh 同时跑 ConfigNode 与 DataNode 两个进程，共同占用约 1GB+ 内存；低配机器务必按 5.3 限制堆。
  • 数据与 WAL 默认落在安装目录 data/ 下，重装/迁移前请先备份该目录。

七、常见问题

Q1：java: command not found 或启动报 Unable to find java executable？ 原因：未安装 JDK 或未配置 JAVA_HOME。执行 apt-get install -y openjdk-17-jdk-headless 并按 4.2 配置 JAVA_HOME 即可。

Q2：启动报 IoTDB requires Java 17 or later.？ 原因：PATH 上的 java 指向旧版本 JDK（如 JDK 8/11）。确保 JAVA_HOME 指向 /usr/lib/jvm/java-17-openjdk-amd64，并让脚本使用 17+。

Q3：ALTER USER 或建库查询报认证失败？ 原因：密码与当前根用户不一致。IoTDB 默认 root 密码为 root，请先用 -pw root 连接，再改密码。

Q4：ss/netstat 查不到 6667 端口？ 原因：系统未安装 net-tools 或进程未完全就绪。apt-get install -y net-tools 后重试；启动后等待数秒让 DataNode 完成 RPC 注册。

八、卸载方式

停止服务：

cd /opt/iotdb-exp/apache-iotdb-2.0.11-all-bin
sbin/stop-standalone.sh

确认进程退出后，删除安装与数据目录即可：

rm -rf /opt/iotdb-exp/apache-iotdb-2.0.11-all-bin /opt/iotdb-exp/apache-iotdb-2.0.11-all-bin.zip
rm -f /etc/profile.d/java.sh

⚠️ 注意：rm -rf 不可逆，确认目录内无需要保留的数据后再执行。

九、参考链接

  • Apache IoTDB 官方下载目录：https://downloads.apache.org/iotdb/
  • Apache IoTDB 官网：https://iotdb.apache.org/
  • Apache IoTDB 文档（中文）：https://iotdb.apache.org/zh/UserGuide/latest/
  • 配置参数详解见《Apache IoTDB 配置参数详解》篇；CLI 命令详见《Apache IoTDB 常用 CLI 命令与工具详解》篇。