Apache IoTDB Docker Compose 部署指南

使用 Docker Compose 在 Ubuntu 22.04 上快速部署安装 Apache IoTDB 2.0.11（standalone），覆盖镜像选型、compose 编排、数据持久化、常用环境变量与等价 docker run 运行方式。

Apache IoTDBApache IoTDB数据库容器化部署ApacheDocker Compose时间序列2026/10/11

Apache IoTDB Docker Compose 部署指南

目标：用 Docker Compose 一条命令在 Ubuntu 22.04 上启动 Apache IoTDB 2.0.11 单机（standalone，一体包含 ConfigNode 与 DataNode），并完成数据持久化、配置注入与常用运维验证。已验证官方镜像 apache/iotdb:latest 实为 2.0.11（iotdb-*-2.0.11.jar、SHOW VERSION 显示 2.0.11）。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS，x86_64
  • Docker / Docker Compose v2（docker compose 子命令）
  • 镜像：apache/iotdb:2.0.11
  • 镜像默认工作目录：/iotdb/sbin；默认启动命令：bash -c "entrypoint.sh all"（standalone）
  • 镜像内目录：配置 /iotdb/conf、数据 /iotdb/data、日志 /iotdb/logs
  • 暴露端口：6667/tcp（CLI 与 RPC）
  • 关键端口：6667（CLI/RPC）、10710（ConfigNode RPC）、10730（DataNode 内部 RPC）、9092（Prometheus 指标）
  • 测试账号：root / 密码 q1w2e3r4（由默认 root 修改而来）
  • 版本：Apache IoTDB 2.0.11（Build 7c0de06）

二、镜像选型说明

镜像说明建议
apache/iotdb:latest官方最新，当前为 2.0.11快速体验/调试
apache/iotdb:2.0.11官方 2.0.11 固定标签生产固定版本
apache/iotdb:2.0.10官方 2.0 稳定线前序版本需要旧系时
其他第三方镜像来源与构建不可控不推荐

💡 说明：官方镜像内置完整 sbin（start-standalone.sh 等）、lib 与 conf，与 tar 包部署的配置文件/目录结构一致，版本间切换只需改动 image: 标签即可。

三、前置条件

  • 已安装 Docker Engine 与 Docker Compose v2（建议 Compose 1.27.3+）。
  • 具备拉取 docker.io 镜像的网络能力并配置好镜像加速（若使用国内加速源，个别标签可能出现 502/denied，重试或换加速源即可）。
  • 至少分配 2GB 内存给该服务（ConfigNode + DataNode 双进程），并按需求注入 JVM 堆参数。

四、部署步骤

4.1 准备编排目录与 compose 文件

mkdir -p /opt/iotdb-compose
cat > /opt/iotdb-compose/docker-compose.yml <<'EOF'
services:
  iotdb:
    image: apache/iotdb:2.0.11
    container_name: iotdb
    restart: unless-stopped
    environment:
      - MST_JVM_OPTS=-Xms512m -Xmx512m -XX:MaxDirectMemorySize=256m
      - MEMORY_SIZE=512M
    ports:
      - "6667:6667"
      - "10710:10710"
      - "10730:10730"
      - "9092:9092"
    volumes:
      - iotdb-data:/iotdb/data
      - iotdb-logs:/iotdb/logs
    ulimits:
      nofile:
        soft: 65535
        hard: 65535

volumes:
  iotdb-data:
  iotdb-logs:
EOF

💡 说明：MST_JVM_OPTS 与 MEMORY_SIZE 会被镜像内 datanode-env.sh/confignode-env.sh 读取，用于把两个进程的堆限制在 512MB（见「六、常用环境变量表」）。

4.2 启动服务

cd /opt/iotdb-compose
docker compose up -d
docker compose ps

实测（对应服务）回显：

NAME   IMAGE                COMMAND                 SERVICE   STATUS        PORTS
iotdb  apache/iotdb:2.0.11  "bash -c entrypoint.sh all"  iotdb     Up 3 minutes  0.0.0.0:6667->6667/tcp, 0.0.0.0:10710->10710/tcp, 0.0.0.0:10730->10730/tcp, 0.0.0.0:9092->9092/tcp

💡 说明：以上为 docker compose ps 的示意输出（列宽与排序略作收拢，命令与端口为实际映射值）。

4.3 验证进程与端口

进入运行中的容器确认两个进程并核对 JVM 堆：

docker exec -it iotdb bash -c 'jps -v'

回显（摘录关键 JVM 参数，主类与堆设置）：

org.apache.iotdb.confignode.service.ConfigNode  -Xms512m -Xmx512m -XX:MaxDirectMemorySize=256m
org.apache.iotdb.db.service.DataNode            -Xms512m -Xmx512m -XX:MaxDirectMemorySize=256m

端口（docker exec -it iotdb netstat -tlnp 摘录）：

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

4.4 用 CLI 验证建库建测点与查询

进入容器并用 CLI 连接（默认账号 root/root，先改成公共演示密码 q1w2e3r4）：

docker exec -it iotdb bash
cd /iotdb
sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root -e "ALTER USER root SET PASSWORD \"q1w2e3r4\";"
sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4 -e "SHOW VERSION;"

回显：

Msg: The statement is executed successfully.
+-------+---------+
|Version|BuildInfo|
+-------+---------+
| 2.0.11|  7c0de06|
+-------+---------+
Total line number = 1
It costs 0.026s

建库建测点、插入与查询（同 tar 部署，实测通过）：

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 "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 "INSERT INTO root.iot.sensor(timestamp, temperature) VALUES (1690000000000, 25.5);"
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|
+------------------------+---------------------------+
|2023-07-22T04:26:40.000Z|                       25.5|
+------------------------+---------------------------+
Total line number = 1

五、数据持久化说明

  • 通过命名卷 iotdb-data:/iotdb/data 持久化数据与 WAL、iotdb-logs:/iotdb/logs 持久化日志。
  • 即使 docker compose down 后重建容器，数据仍保留在命名卷中，容器删除不丢数据。
  • 若要备份数据，可直接备份卷：docker run --rm -v iotdb-data:/data -v /backup:/backup alpine tar czf /backup/iotdb-data.tar.gz -C /data .

六、常用环境变量表

环境变量说明默认
MEMORY_SIZE由脚本计算结果得到的每个节点内存上限，格式如 512M/2G按系统自动计算（1/2 内存）
MST_JVM_OPTS / IOTDB_JMX_OPTS直接注入 JVM 参数，优先级最高；含 -Xms/-Xmx/-XX:MaxDirectMemorySize空
IOTDB_*replace-conf-from-env.sh 支持把 IOTDB_ 前缀环境变量写入 conf/iotdb-system.properties（如 IOTDB_DN_RPC_PORT=6667）空

⚠️ 注意：MST_JVM_OPTS 若包含 -Xmx，会覆盖环境脚本里 ON_HEAP_MEMORY 的设定；保持 -Xms 与 -Xmx 一致可避免抖动。

七、常用配置参数说明（command）

官方镜像默认 COMMAND 为 bash -c "entrypoint.sh all"，即 standalone。可在 compose 的 command: 覆盖：

command行为
bash -c "entrypoint.sh all"（默认）同时启动 ConfigNode + DataNode（单机）
bash -c "start-confignode.sh"仅启动 ConfigNode（集群拆分场景）
bash -c "start-datanode.sh"仅启动 DataNode（集群拆分场景）

💡 说明：单机直接保持默认即可；多节点集群时用不同 compose/构建分别在多台机器部署 Confignode 与 DataNode，并统一 cn_seed_config_node。

八、配置文件持久化（conf 挂载）

如需把自定义 conf/iotdb-system.properties、conf/datanode-env.sh 落到宿主机统一管理，可加 bind mount：

mkdir -p /opt/iotdb-compose/conf
cp <你的服务器>/apache-iotdb-2.0.11-all-bin/conf/iotdb-system.properties /opt/iotdb-compose/conf/

在 compose 的 volumes: 追加：

    volumes:
      - iotdb-data:/iotdb/data
      - iotdb-logs:/iotdb/logs
      - /opt/iotdb-compose/conf/iotdb-system.properties:/iotdb/conf/iotdb-system.properties

⚠️ 注意：把宿主机文件 bind 进容器前先备份镜像内原始配置；写坏配置会导致启动失败，可 docker compose down 并移除该 bind 后重新 up -d。

九、等价 docker run 运行方式

不用 compose 时，等价的一条 docker run：

docker run -d --name iotdb \
  -p 6667:6667 -p 10710:10710 -p 10730:10730 -p 9092:9092 \
  -e MST_JVM_OPTS="-Xms512m -Xmx512m -XX:MaxDirectMemorySize=256m" \
  -e MEMORY_SIZE=512M \
  -v iotdb-data:/iotdb/data -v iotdb-logs:/iotdb/logs \
  --ulimit nofile=65535:65535 \
  --restart unless-stopped \
  apache/iotdb:2.0.11

十、常用运维命令

docker compose -f /opt/iotdb-compose/docker-compose.yml ps       # 查看状态
docker compose -f /opt/iotdb-compose/docker-compose.yml logs -f  # 跟踪日志
docker compose -f /opt/iotdb-compose/docker-compose.yml restart  # 重启
docker compose -f /opt/iotdb-compose/docker-compose.yml down     # 停止（数据仍在命名卷）
docker compose -f /opt/iotdb-compose/docker-compose.yml down -v  # 停止并删除命名卷（清数据，慎用）

进入容器并交互使用 CLI：

docker exec -it iotdb bash
cd /iotdb
sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw q1w2e3r4

交互模式连接成功横幅（实测）：

---------------------
Starting IoTDB Cli
---------------------
 _____       _________  ______   ______
|_   _|     |  _   _  ||_   _ `.|_   _ \
  | |   .--.|_/ | | \_|  | | `. \ | |_) |
  | | / .'`\ \  | |      | |  | | |  __'.
 _| |_| \__. | _| |_    _| |_.' /_| |__) |
|_____|'.__.' |_____|  |______.'|_______/  version 2.0.11 (Build: 7c0de06)
Successfully login at 127.0.0.1:6667
IoTDB>

十一、常见问题（FAQ）

Q1：docker pull apache/iotdb:2.0.11 报 denied 或 502 Bad Gateway？ 原因：多为镜像加速源临时故障或该标签在加速源未同步。换用 apache/iotdb:latest（当前即 2.0.11），或更换加速源后重试。

Q2：容器启动后 nofile 超限导致连接被拒？ 原因：默认文件句柄数不足。compose 中通过 ulimits 设置为 65535，或用 --ulimit nofile=65535:65535 覆盖。

Q3：用宿主机 6667 联不通？ 原因：检查端口映射与容器内进程是否就绪。先 docker compose logs 看日志中出现 IoTDB DataNode is set up successfully 后再连接。

Q4：改了 env 变量的 JVM 参数不生效？ 原因：-Xmx 只认 MST_JVM_OPTS/IOTDB_JMX_OPTS；若同时在环境脚本里写死了 ON_HEAP_MEMORY，会被 IOTDB_JMX_OPTS 中的 -Xmx 覆盖。修改后用 docker exec -it iotdb jps -v 核对。

十二、参考链接

  • 官方镜像：https://hub.docker.com/r/apache/iotdb
  • Apache IoTDB 文档：https://iotdb.apache.org/
  • 配置文件参数说明见《Apache IoTDB 配置参数详解》篇；非容器的手工安装见《Ubuntu 22.04 安装 Apache IoTDB 2.0.11 指南》篇。