Docker v2 部署

本文介绍如何使用 Docker Compose 部署 TimechoDB V2.0.10.1 及以上版本。

1. 环境准备

1.1 主机要求

部署主机需要提前安装以下组件：

• Docker Engine

• Docker Compose v2，即支持 docker compose 命令

可使用以下命令验证 Docker 和 Docker Compose 是否安装成功：

docker --version
docker compose version

1.2 获取部署文件和镜像

请联系 Timecho 获取以下文件：

• TimechoDB Docker 镜像或镜像压缩包

• Docker Compose 部署文件

Docker Compose 部署文件包含以下部署形态：

部署形态	Compose 文件	默认内存限制	说明
1C1D 单机模板	docker-compose-1c1d.yml	ConfigNode 2g，DataNode 8g	启动 1 个 ConfigNode 容器和 1 个 DataNode 容器，适用于快速验证和小规模单机环境
1C2D 集群模板	docker-compose-cluster-1c2d.yml	ConfigNode 2g，DataNode 每个 8g	启动 1 个 ConfigNode 容器和 2 个 DataNode 容器
3C3D 集群模板	docker-compose-cluster-3c3d.yml	ConfigNode 每个 2g，DataNode 每个 8g	启动 3 个 ConfigNode 容器和 3 个 DataNode 容器
单 ConfigNode	docker-compose-confignode.yml	2g	单独启动 ConfigNode，用于分离部署或自定义编排
单 DataNode	docker-compose-datanode.yml	8g	单独启动 DataNode，用于分离部署或自定义编排

上述值为 compose 模板默认值，不是生产环境统一容量建议；生产环境需要根据数据规模、写入负载、查询并发、保留周期和宿主机资源重新评估。实际可用的 compose 文件以获得的部署包为准。

1.3 加载镜像

如果获取到的是镜像压缩包，请在部署主机执行：

docker load -i <image-package>.tar.gz
docker images

如果镜像已推送到可访问的镜像仓库，请先登录镜像仓库并拉取镜像：

docker login <registry>
docker pull <registry>/timecho/timechodb:<version>-standalone

1.4 镜像说明

TimechoDB 镜像 tag 格式如下：

<registry>/timecho/timechodb:<version>-standalone

其中：

字段	含义
<registry>	镜像仓库地址
timecho/timechodb	镜像仓库路径
<version>-standalone	镜像 tag

1.5 修改镜像版本

部署前需要检查 compose 文件中的 image 字段，并替换为实际镜像名称。例如：

image: timecho/timechodb:<version>-standalone

如果使用私有镜像仓库，请写成完整镜像地址：

image: <registry>/timecho/timechodb:<version>-standalone

1.6 推荐资源配置

部署对象	默认内存限制	建议说明
1C1D Compose	ConfigNode 2g，DataNode 8g	用于快速部署、演示、单机测试；生产环境按负载调整
1C2D 集群模板	ConfigNode 2g，DataNode 每个 8g	用于验证多 DataNode 注册、查询和基础集群行为
3C3D 集群模板	ConfigNode 每个 2g，DataNode 每个 8g	用于验证多 ConfigNode / 多 DataNode 集群部署
单 ConfigNode	2g	用于分离部署或自定义编排
单 DataNode	8g	用于分离部署或自定义编排

上述值为 compose 模板默认值，不是生产环境统一容量建议；生产环境需要根据数据规模、写入负载、查询并发、保留周期和宿主机资源重新评估。

2. 1C1D 部署

1C1D 部署会启动 1 个 ConfigNode 容器和 1 个 DataNode 容器，适用于快速部署、功能验证、演示环境和小规模单机环境。

2.1 准备目录

以下示例将部署文件和数据目录统一放在 /docker-timechodb 下：

/docker-timechodb
├── docker-compose-1c1d.yml
└── data

进入部署目录：

cd /docker-timechodb

2.2 检查 compose 配置

打开 docker-compose-1c1d.yml，重点检查以下字段：

字段	示例值	说明
image	timecho/timechodb:<version>-standalone	ConfigNode 和 DataNode 使用同一个镜像
command	confignode、datanode	通过容器启动命令区分角色
mem_limit	ConfigNode 2g，DataNode 8g	每个容器独立设置内存上限
ports	6667:6667	通常只需将 DataNode 客户端端口映射到宿主机
volumes	./data/confignode:/iotdb/data、./data/datanode1:/iotdb/data	建议为不同角色配置独立数据目录

如需激活或保留日志，请确认 compose 文件中挂载了相应目录，例如：

volumes:
  - ./activation:/iotdb/activation
  - ./data/datanode1:/iotdb/data
  - ./logs/datanode1:/iotdb/logs

2.3 创建 Docker 网络

docker-compose-1c1d.yml 默认使用外部 Docker 网络 timechodb。首次启动前创建该网络：

docker network create --subnet=172.18.0.0/16 timechodb

如果网络已经存在，可忽略重复创建提示。

2.4 启动服务

docker compose -f docker-compose-1c1d.yml up -d

查看容器状态：

docker ps

查看日志：

docker logs -f timechodb-confignode
docker logs -f timechodb-datanode-1

2.5 激活

容器启动后，请参考 5. 数据库激活。

2.6 验证部署

进入 DataNode 容器执行 CLI：

docker exec -it timechodb-datanode-1 start-cli.sh

在 CLI 中执行：

show cluster;

预期可以看到 ConfigNode 和 DataNode 信息，节点状态为正常运行。

3. 跨机器 Confignode 和 Datanode 分离部署

适用于 ConfigNode 和 DataNode 部署在不同服务器上，或客户需要按机器、网络、存储和运维规范分别管理每个节点的场景。

该方式通常使用 docker-compose-confignode.yml 在 ConfigNode 所在服务器启动 ConfigNode，使用 docker-compose-datanode.yml 在 DataNode 所在服务器启动 DataNode。部署前需要确认服务器之间网络互通，并将节点地址配置为其他机器可访问的 IP 或域名。

3.1 部署 ConfigNode

1. 在 ConfigNode 所在服务器进入 compose 目录：

cd docker_v2/src/main/DockerCompose

1. 修改 docker-compose-confignode.yml：

字段	示例值	说明
image	customer-registry.example.com/timecho/timechodb:<version>-standalone	替换为客户环境可用的实际镜像。
command	["confignode"]	启动 ConfigNode 角色。
cn_internal_address	confignode-1.example.com	填写 DataNode 所在机器可访问的 ConfigNode 地址。
cn_internal_port	10710	ConfigNode 内部通信端口，需要对其他节点开放。
cn_consensus_port	10720	ConfigNode 共识端口，多 ConfigNode 时需要互通。

1. 启动 ConfigNode：

docker network create --subnet=172.18.0.0/16 timechodb 2>/dev/null || true
docker compose -f docker-compose-confignode.yml up -d

1. 查看 ConfigNode 日志：

docker logs -f timechodb-confignode

3.2 部署 DataNode

1. 在 DataNode 所在服务器进入 compose 目录：

cd docker_v2/src/main/DockerCompose

1. 修改 docker-compose-datanode.yml：

字段	示例值	说明
image	customer-registry.example.com/timecho/timechodb:<version>-standalone	替换为客户环境可用的实际镜像。
command	["datanode"]	启动 DataNode 角色。
dn_seed_config_node	confignode-1.example.com:10710	填写 ConfigNode 所在服务器可访问地址和端口。
dn_internal_address	datanode-1.example.com	填写其他节点可访问的 DataNode 地址。
dn_rpc_port	6667	客户端 RPC 端口。
dn_mpp_data_exchange_port	10740	MPP 数据交换端口，需要在 DataNode 间互通。
dn_schema_region_consensus_port	10750	SchemaRegion 共识端口。
dn_data_region_consensus_port	10760	DataRegion 共识端口。

1. 启动 DataNode：

docker network create --subnet=172.18.0.0/16 timechodb 2>/dev/null || true
docker compose -f docker-compose-datanode.yml up -d

1. 查看 DataNode 日志：

docker logs -f timechodb-datanode

3.3 激活

ConfigNode 和 DataNode 启动后，请参考 5. 数据库激活。

3.4 验证集群状态

docker exec -it timechodb-datanode start-cli.sh

在 CLI 中执行：

show cluster;

预期至少可以看到 1 个 ConfigNode 和 1 个 DataNode。

4. 多节点模板部署

如果部署包中提供了多节点 compose 模板，可以使用模板快速启动 1C2D 或 3C3D 集群。部署前请确认主机资源充足，并根据实际资源调整每个 service 的 mem_limit。

4.1 1C2D 集群

1C2D 模板会启动：

角色	容器
ConfigNode	timechodb-confignode
DataNode	timechodb-datanode-1、timechodb-datanode-2

启动：

docker compose -f docker-compose-cluster-1c2d.yml up -d

查看状态：

docker ps
docker logs -f timechodb-confignode
docker logs -f timechodb-datanode-1

容器启动后，请参考 5. 数据库激活。

停止：

docker compose -f docker-compose-cluster-1c2d.yml down

4.2 3C3D 集群

3C3D 模板会启动：

角色	容器
ConfigNode	timechodb-confignode-1、timechodb-confignode-2、timechodb-confignode-3
DataNode	timechodb-datanode-1、timechodb-datanode-2、timechodb-datanode-3

该模板通常用于验证多节点部署和高可用能力。部署前请确认副本数、共识协议、端口和内存配置符合实际环境要求。

启动：

docker compose -f docker-compose-cluster-3c3d.yml up -d

查看状态：

docker ps
docker logs -f timechodb-confignode-1
docker logs -f timechodb-datanode-1

容器启动后，请参考 5. 数据库激活。

停止：

docker compose -f docker-compose-cluster-3c3d.yml down

5. 数据库激活

Docker 部署支持命令激活和文件激活两种方式。

5.1 命令激活

进入任意一个可连接数据库的 DataNode 容器，并启动 CLI：

docker exec -it timechodb-datanode-1 start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw TimechoDB@2021

在 CLI 中执行以下语句获取激活所需机器码：

show system info;

执行以下语句获取待激活数据库的版本号：

show version;

将机器码和版本号提供给 Timecho 技术支持，获取激活码后，在 CLI 中执行：

activate '<activation-code>';

其中 <activation-code> 替换为实际激活码，激活码前后需要保留英文单引号。

5.2 文件激活

如果使用文件激活，首次启动 ConfigNode 和 DataNode 后，挂载到 /iotdb/activation 的宿主机目录中会生成 system_info 文件。请将该文件提供给 Timecho 技术支持，并将获取到的 license 文件放入对应节点的 activation 目录。

多 ConfigNode 部署时，请收集对应 ConfigNode 节点的 system_info 文件，并将返回的 license 文件放入对应节点的 activation 目录。

放入 license 文件后，再次启动服务。例如 1C1D 部署可执行：

docker compose -f docker-compose-1c1d.yml up -d

5.3 验证激活

进入 CLI 后执行：

show activation;

当结果中的 ClusterActivationStatus 显示为 ACTIVATED 时，表示激活成功。

6. 关键配置说明

6.1 容器角色

TimechoDB Docker v2 镜像通过容器启动命令区分角色：

command	启动内容
confignode	只启动 ConfigNode
datanode	只启动 DataNode

6.2 环境变量覆盖配置

容器启动时，replace-conf-from-env.sh 会读取小写环境变量，并按同名配置项写入 /iotdb/conf/iotdb-system.properties。compose 模板中的 cn_*、dn_*、共识协议和副本数配置都使用该机制。

使用环境变量时请注意：

• 环境变量名需要与 properties 中的配置 key 完全一致，不会匹配 xxx_key 这类子串。

• 如果文件中存在有效行 key=，优先替换有效行；只有不存在有效行时才在 #key= 注释行后插入。

• 配置值必须是单行。包含换行或回车的值会被跳过。

• /、&、反斜杠等字符会按普通值写入。

6.3 数据和日志目录

容器内路径	用途
/iotdb/data	TimechoDB 数据目录
/iotdb/logs	TimechoDB 日志目录
/iotdb/activation	激活相关文件目录
/iotdb/conf	配置文件目录

生产环境建议将数据目录和日志目录挂载到独立数据盘或指定宿主机目录，并定期备份。

6.4 端口说明

端口	配置项	用途
6667	dn_rpc_port	客户端 RPC 访问端口
10710	cn_internal_port	ConfigNode 内部通信端口
10720	cn_consensus_port	ConfigNode 共识端口
10740	dn_mpp_data_exchange_port	DataNode MPP 数据交换端口
10750	dn_schema_region_consensus_port	DataNode SchemaRegion 共识端口
10760	dn_data_region_consensus_port	DataNode DataRegion 共识端口

默认情况下，仅需要将 6667 映射到宿主机供客户端访问。其他端口用于集群内部通信，不建议在无必要时暴露到宿主机外部。

6.5 映射配置目录

如果需要在宿主机上直接维护配置文件，可先从容器中拷贝配置目录：

docker cp timechodb-datanode-1:/iotdb/conf ./conf

然后在 compose 文件中增加配置目录挂载：

volumes:
  - ./conf:/iotdb/conf

修改挂载后重新启动服务：

docker compose -f docker-compose-1c1d.yml up -d

7. 常用运维命令

查看容器：

docker ps

查看日志：

docker logs -f timechodb-confignode
docker logs -f timechodb-datanode-1

进入容器：

docker exec -it timechodb-datanode-1 bash

查看容器内存限制：

docker inspect timechodb-datanode-1 --format '{{.HostConfig.Memory}}'

停止服务：

docker compose -f docker-compose-1c1d.yml down

停止分离部署的服务：

docker compose -f docker-compose-datanode.yml down
docker compose -f docker-compose-confignode.yml down

8. 升级

升级前请先备份宿主机上的数据目录、日志目录和配置目录。

1. 获取新版本镜像，并通过 docker load 或 docker pull 导入部署主机。

2. 修改 compose 文件中的 image tag。

3. 停止旧容器。

4. 使用新镜像启动容器。

5. 使用 show cluster; 验证节点状态。

1C1D 部署示例：

docker compose -f docker-compose-1c1d.yml down
docker compose -f docker-compose-1c1d.yml up -d

分离部署示例：

docker compose -f docker-compose-datanode.yml down
docker compose -f docker-compose-confignode.yml down
docker compose -f docker-compose-confignode.yml up -d
docker compose -f docker-compose-datanode.yml up -d

9. 常见问题

9.1 拉取或加载镜像失败

请检查：

• 镜像文件是否完整。

• compose 文件中的 image 是否与本地镜像名称一致。

• 如果使用私有镜像仓库，部署主机是否可以访问该仓库。

• 如果使用私有镜像仓库，是否已执行 docker login。

9.2 容器启动后立即退出

查看容器日志：

docker logs timechodb-confignode
docker logs timechodb-datanode-1

重点检查：

• 镜像版本是否正确。

• command 是否为 confignode 或 datanode。

• 数据目录、日志目录和激活目录是否有写入权限。

• mem_limit 是否过小。

• 是否已完成激活。

9.3 DataNode 无法注册到 ConfigNode

请检查：

• timechodb Docker 网络是否存在。

• ConfigNode 容器是否已正常启动。

• DataNode 中的 dn_seed_config_node 是否指向正确的 ConfigNode 名称和端口。

• ConfigNode 和 DataNode 是否在同一个 Docker 网络中。

示例命令：

docker network inspect timechodb
docker logs timechodb-confignode
docker logs timechodb-datanode

9.4 端口 6667 冲突

如果宿主机已有服务占用 6667，可修改 compose 文件中的端口映射：

ports:
  - "16667:6667"

修改后客户端应连接宿主机的 16667 端口。

9.5 首次启动生成机器信息后服务退出

首次启动生成 system_info 后服务退出属于正常现象。请完成 license 文件放置后再次启动服务。