Apache IoTDB 配置参数详解
详解 Apache IoTDB 2.0.11 各配置文件与关键参数含义、真实默认值、查看与修改方法，含 JVM 堆限制与生产配置模板。
Apache IoTDB 配置参数详解
目标：系统讲解 Apache IoTDB 2.0.11 的配置文件位置、关键参数真实默认值与修改方法（含 JVM 堆限制），并给出适合不同内存/磁盘/场景的生产配置模板。文中默认值与范例均取自
/opt/iotdb-exp/apache-iotdb-2.0.11-all-bin/conf实测。
一、环境信息
- 版本：Apache IoTDB 2.0.11（安装根目录
/opt/iotdb-exp/apache-iotdb-2.0.11-all-bin） - 配置文件目录：
conf/ - 关键配置文件：
conf/iotdb-system.properties、conf/datanode-env.sh、conf/confignode-env.sh、conf/iotdb-common.sh - 运行模式：standalone（ConfigNode + DataNode 同机）
- JDK：OpenJDK 17.0.20.1
二、前置条件
- 已按《Ubuntu 22.04 安装 Apache IoTDB 2.0.11 指南》完成安装并用
start-standalone.sh跑通，具备修改配置后重启服务的能力。 - 修改
conf/*后需重启生效：先sbin/stop-standalone.sh，再sbin/start-standalone.sh。
三、参数查看与修改方式
3.1 查看当前生效值
- 端口、集群、副本参数在
conf/iotdb-system.properties中查看。 - JVM 参数通过
jps -v查看实际启动参数（堆与非堆）。
cat /opt/iotdb-exp/apache-iotdb-2.0.11-all-bin/conf/iotdb-system.properties
/usr/lib/jvm/java-17-openjdk-amd64/bin/jps -v
3.2 修改方式
cd /opt/iotdb-exp/apache-iotdb-2.0.11-all-bin/conf
sbin/../sbin/stop-standalone.sh # 或 cd 到安装根目录后执行 sbin/stop-standalone.sh
- 端口/副本/目录等 → 编辑
iotdb-system.properties。 - JVM 堆/非堆 → 编辑
datanode-env.sh与confignode-env.sh中的ON_HEAP_MEMORY=/OFF_HEAP_MEMORY=（或注入IOTDB_JMX_OPTS）。 - 改完重启：
cd /opt/iotdb-exp/apache-iotdb-2.0.11-all-bin && sbin/start-standalone.sh。
⚠️ 注意：修改端口/地址参数时，若与既有集群其他节点不一致会导致节点无法互相发现；单机改动后应同时核对
cn_seed_config_node。
四、参数总览
| 文件 | 类型 | 主要作用 |
|---|---|---|
iotdb-system.properties | 集群与节点配置 | 集群名、种子节点、RPC/共识端口、副本、复制因子、数据目录、指标 |
datanode-env.sh | DataNode JVM | -Xms/-Xmx、-XX:MaxDirectMemorySize、GC、JMX、句柄数 |
confignode-env.sh | ConfigNode JVM | 同上（针对 ConfigNode 进程） |
iotdb-common.sh | 通用 | 两进程共享的环境与内存计算辅助 |
五、核心参数分类详解
5.1 集群与种子节点段（Cluster / Seed ConfigNode）
conf/iotdb-system.properties 实测默认：
cluster_name=defaultCluster
cn_seed_config_node=127.0.0.1:10710
dn_seed_config_node=127.0.0.1:10710
| 参数 | 默认值 | 说明 |
|---|---|---|
cluster_name | defaultCluster | 集群名称，属于同一集群的节点必须一致 |
cn_seed_config_node | 127.0.0.1:10710 | ConfigNode 种子地址，新节点据此加入集群 |
dn_seed_config_node | 127.0.0.1:10710 | DataNode 注册时使用的 ConfigNode 地址 |
💡 说明：单机挖掘时保持
127.0.0.1即可；真实集群把此处改为 ConfigNode 所在服务器的内网 IP。
5.2 节点 RPC 与共识端口段（Node RPC Configuration）
实测默认：
cn_internal_address=127.0.0.1 # ConfigNode 内部通信地址
cn_internal_port=10710 # ConfigNode RPC 端口
cn_consensus_port=10720 # ConfigNode 共识协议(Ratis)端口
dn_rpc_address=127.0.0.1 # DataNode 对外(CLI/SDK)地址
dn_rpc_port=6667 # CLI/SDK 连接端口
dn_internal_address=127.0.0.1 # DataNode 内部通信地址
dn_internal_port=10730 # DataNode 内部 RPC 端口
dn_mpp_data_exchange_port=10740 # 数据交换(MPP)端口
dn_schema_region_consensus_port=10750 # 元数据区共识端口
dn_data_region_consensus_port=10760 # 数据区共识端口
⚠️ 注意：
6667（dn_rpc_port）是应用接入最重要端口，CLI、JDBC 客户端均连它。对外联通常把dn_rpc_address改为对外网卡地址并放通防火墙6667。
5.3 复制因子段（Replication Configuration）
实测默认：
schema_replication_factor=1
data_replication_factor=1
| 参数 | 默认(单机) | 说明 |
|---|---|---|
schema_replication_factor | 1 | 元数据区副本数，≥3 才具备元数据故障容错 |
data_replication_factor | 1 | 数据区副本数，≥3 才具备数据容错 |
💡 说明：单机/测试保持
1；生产多节点集群按节点数建议设为3。
5.4 目录路径段（Directory Configuration）
实测默认（注释态即内置相对安装目录）：
# dn_data_dirs=data/datanode/data
# dn_wal_dirs=data/datanode/wal
| 参数 | 默认值 | 说明 |
|---|---|---|
dn_data_dirs | data/datanode/data | DataNode 数据(TsFile)目录，可多块盘以分号分隔 |
dn_wal_dirs | data/datanode/wal | 预写日志(WAL)目录，建议放独立/高速盘 |
💡 说明：生产建议把数据与 WAL 指向不同高性能磁盘目录以提升写入吞吐与降低局部故障影响。
5.5 指标段（Metric Configuration）
实测默认：
# cn_metric_reporter_list=
cn_metric_prometheus_reporter_port=9091
# dn_metric_reporter_list=
dn_metric_prometheus_reporter_port=9092
| 参数 | 默认值 | 说明 |
|---|---|---|
cn_metric_prometheus_reporter_port | 9091 | ConfigNode Prometheus 指标端口 |
dn_metric_prometheus_reporter_port | 9092 | DataNode Prometheus 指标端口 |
💡 说明：打开
cn_metric_reporter_list/dn_metric_reporter_list并设为prometheus才会真正向该端口暴露指标，供 Prometheus 抓取。
5.6 JVM / 内存段（datanode-env.sh、confignode-env.sh）
两脚本推荐将堆限制在 256–512MB。把堆设为 512MB、非堆 256MB：
ON_HEAP_MEMORY="512M"
OFF_HEAP_MEMORY="256M"
| 变量 | 作用 | 本指南建议 |
|---|---|---|
ON_HEAP_MEMORY | -Xms/-Xmx 堆内存 | 512M（功能验证可 256M） |
OFF_HEAP_MEMORY | -XX:MaxDirectMemorySize 非堆 | 256M |
IOTDB_JMX_OPTS | 直接注入额外 JVM 参数（优先级最高） | 含 -Xmx 时覆盖上两项 |
修改后 jps -v 实测生效（可见 -Xms512M -Xmx512M -XX:MaxDirectMemorySize=256M）。
⚠️ 注意：
-Xmn（新生代）未显式设置时由 JVM 自适应；低配机器避免把堆开到默认的 1/2 系统内存，防止 OOM。
5.7 时间精度与分区段（iotdb-system.properties 补充）
由 GetSystemConfiguration 返回的全局实测值（写入文件前的内置默认）：
| 参数 | 默认值 | 说明 |
|---|---|---|
timestamp_precision | ms | 时间戳精度：ms/us/ns |
time_partition_interval | 604800000 | 数据分区间隔（毫秒，即 7 天） |
series_partition_slot_num | 1000 | 序列分区槽位数 |
schema_engine_mode | Memory | 元数据引擎模式 |
⚠️ 注意：
timestamp_precision在写入首批数据后不可修改，务必在初始化前确定。
六、生产配置模板
6.1 低配功能验证服务器（4GB 内存，HDD，测试）
# conf/iotdb-system.properties
schema_replication_factor=1
data_replication_factor=1
# conf/datanode-env.sh / confignode-env.sh
ON_HEAP_MEMORY="256M"
OFF_HEAP_MEMORY="256M"
适用场景：功能验证、本地演示、开发联调。内存占用低，吞吐有限。
6.2 标准生产节点（16GB 内存，NVMe SSD，OLTP）
# conf/iotdb-system.properties
cn_internal_address=<内网IP>
dn_rpc_address=<对外IP>
dn_rpc_port=6667
dn_internal_address=<内网IP>
schema_replication_factor=3 # 集群≥3节点
data_replication_factor=3
dn_data_dirs=/data/iotdb/tsfile;/disk2/iotdb/tsfile # 多盘
dn_wal_dirs=/disk_fast/iotdb/wal # 高速盘
# conf/datanode-env.sh / confignode-env.sh
ON_HEAP_MEMORY="4G"
OFF_HEAP_MEMORY="2G"
适用场景：OLTP 时序写入+查询、高并发设备接入。注意按节点数≥3 时把副本因子设为 3，保证容错。
💡 说明：云上 OLAP 报表场景可适当加大
OFF_HEAP_MEMORY并调大dn_mpp_data_exchange_port所在网卡带宽；写入密集场景优先保证 WAL 在 NVMe 上。
七、常见问题
Q1：改完配置不生效？
原因：conf/* 改动需要重启进程。执行 sbin/stop-standalone.sh 后 sbin/start-standalone.sh，再用 jps -v 或打开 iotdb-system.properties 二次核对。
Q2：dn_rpc_port 改了但 CLI 还连旧端口？
原因：CLI 需显式用 -p <新端口> 指定（默认 6667）。例如 sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4。
Q3：多块数据盘怎么写？
原因：dn_data_dirs 用分号 ; 分隔多个目录，如 data/datanode/data;/data/ssd/iotdb。改后重启。
Q4：timestamp_precision 想从 ms 改成 us？
原因：写入数据后不可改。需在正式导入前确定，或清空数据目录后重新初始化。
八、参考链接
- Apache IoTDB 配置文档：
https://iotdb.apache.org/zh/UserGuide/latest/ - 官方下载：
https://downloads.apache.org/iotdb/ - CLI 与工具使用见《Apache IoTDB 常用 CLI 命令与工具详解》篇；安装整体见《Ubuntu 22.04 安装 Apache IoTDB 2.0.11 指南》篇。