集群管理工具

1 工具概述

1.1 工具是什么

TimechoDB 集群管理工具是面向 IoTDB/TimechoDB 运维团队的集中式管理控制台，将服务器纳管、集群部署、Workbench、Prometheus/Grafana 监控、文件分发、巡检和实施记录集中到同一套 Web 界面中。

1.2 工具定位

• 统一入口：以浏览器访问工具，统一管理多台 Linux/Unix 服务器。

• 自动化执行：通过 SSH 连接目标主机，按依赖顺序执行数据库、Workbench 和监控组件部署。

• 可追溯运维：保留部署记录、日志、巡检报告和上传文件，便于交付审计。

• 轻量部署：将发布包解压后即可按本章步骤启动工具。

1.3 能做什么

能力域	主要功能	典型产出
资源纳管	服务器新增、分组、连接测试、批量导入/导出	可连接服务器清单
部署交付	IoTDB、Workbench、监控面板一键部署	集群记录、实例状态
监控运维	监控面板管理、集群健康观察	监控入口
巡检审计	巡检方案、模板、定时执行、报告历史	巡检报告
实施支持	部署记录筛选、实施手册生成	交付文档
文件分发	上传安装包、手册和脚本并分组管理	文件资产

1.4 菜单总览

左侧主导航包含服务器、集群管理、Workbench 管理、监控面板管理、实施手册、文件上传和运维工具。集群巡检为可展开菜单，下面包含巡检配置和报告历史。

2 工具安装与部署

2.1 获取与解压发布包

获取《集群管理工具》安装包，并上传到服务器

2.2 解压安装包并进入安装目录

tar -zxvf ops-management-platform-*.tar.gz
cd ops-management-platform-*

2.3 修改监听地址或数据目录

编辑安装目录下的 config/runtime.env。可先将 config/runtime.env.example 重命名为 config/runtime.env 后编辑。例如，工具安装在 /data/ops-management-platform-* 目录下：

cd config/
mv runtime.env.example runtime.env
vim runtime.env

将 runtime.env 配置为以下内容。TMPDIR 必须使用绝对路径，可根据实际环境选择目录。

APP_ADDR=0.0.0.0:8386
DATABASE_URL=./data/ops-platform.sqlite
UPLOAD_DIR=./data/uploads
TMPDIR=/data/tmp
WEB_DIR=./web
LOG_LEVEL=info
LOG_RETENTION_DAYS=365

2.4 启动并访问工具

在 ops-management-platform-* 安装目录下执行启动脚本：

./sbin/start.sh

启动成功之后

在浏览器中访问 http://<服务器IP>:8386。请将监听地址 0.0.0.0 替换为服务器的实际 IP 地址。

2.5 登录工具（v0.3.1 新增）

访问工具地址后进入登录界面。当前版本默认用户名和密码均为 admin。

3 服务器管理

服务器是后续部署、远程终端、性能测试、系统初始化和巡检的共同入口。建议先完成服务器添加和连接测试，再执行任何会修改目标主机的操作。

3.1 服务器列表字段与状态

列	含义	使用建议
服务器名称	工具内显示名称；为空时创建时默认取 IP 地址	建议使用 node-1、node-2 或“环境-角色-序号”命名
用户	普通 SSH 登录账号；页面以绿色账号标识显示	用于日常连接和非特权操作
分组	服务器分组，默认分组为“默认分组”	按项目、环境或机房分组，便于批量选择
IP / 地址	目标主机和 SSH 端口，如 172.20.31.61:22	修改前确认 DNS/IP 可从工具主机访问
连通性	按账号显示连接状态；可包含普通账号和提权账号结果	“连接测试”后再开展部署
操作	每行右侧的三横线菜单	所有单机操作均从此菜单进入

3.2 添加服务器

3.2.1 单台服务器

在 “服务器” 页点击 “添加服务器” 后，按表单逐项填写服务器信息。填写完成后先测试连接，确认通过再添加。

1. 点击《添加服务器》，打开对话框。

2. 填写名称、分组、主机地址、SSH 端口和 SSH 用户。端口必须是 1-65535 的整数。

3. 填写用户名和密码

4. 点击《测试连接》。测试只验证当前填写的信息，不会先将服务器加入列表。

5. 测试通过后点击《添加》。工具会保存服务器信息并刷新列表。

3.2.2 批量服务器

如果服务器过多，可以使用导入导出功能，点击右上角导入功能中的下载模板

下载完成后打开文件，进行相关配置

点击选择服务器导入文件，选择已配置的模板进行上传文件，等待导入完成即可

3.3 编辑服务器信息

在目标服务器行点击《操作》菜单，再点击《编辑》。编辑表单与新增表单基本一致。密码留空表示继续使用原密码；只有填写新密码时才会更新登录凭据。

• 修改名称或分组时，不会改变目标主机。

• 修改 IP 或 SSH 端口后，立即执行一次《连接测试》，确认新地址可用。

• 把普通用户改为 root 后，原有特权账号会被清理；把 root 改为普通用户时，重新配置特权账号。

• 点击《保存》后等待列表刷新；若保存失败，保留原记录并根据错误提示修正字段。

3.4 操作菜单总览

服务器每行最右侧的三横线按钮可打开操作菜单。菜单分为《操作》《测试》和《危险操作》三组。执行操作前，请先核对服务器名称和 IP 地址，避免误操作。

菜单项	作用
连接测试	测试已保存服务器的普通账号和特权账号连接，并刷新连通性状态
命令行工具	打开该服务器的远程命令行终端，在浏览器中操作
系统初始化	配置防火墙处理方式及系统参数，支持单台或批量
已安装服务	实时检查并列出工具登记的 JDK、IoTDB、Workbench、监控面板、GDAL、看门狗、Arthas 等资产
编辑	修改服务器地址、账号、分组和凭据
性能测试	采集系统信息并执行轻量 CPU/内存/磁盘测试
性能测试历史	列出该服务器历史测试，点击记录可查看详情
删除（危险操作）	删除工具中的服务器记录；弹窗明确提示不可恢复

3.4.1 连接测试

连接测试既可在新增或编辑表单中执行，也可从已保存服务器的操作菜单执行。测试结束后，页面会分别显示普通账号和特权账号的连接结果及提示信息。

3.4.2 命令行工具

点击操作菜单中的《命令行工具》后，工具会打开目标服务器的远程终端窗口。您可以在窗口中输入命令并查看执行结果。

3.4.3 系统初始化

系统初始化支持单台服务器和批量服务器两种方式。开始前需要选择防火墙处理策略：

策略	实际含义	适用场景
开放端口	保留 firewalld，仅开放 IoTDB、Workbench、监控面板和工具访问所需端口	生产环境的默认推荐策略
关闭防火墙	停止并禁用 firewalld	仅适用于现场明确要求关闭防火墙的服务器

风险提示：关闭防火墙是高风险操作，会改变目标主机安全边界。除非项目安全方案明确要求，不要选择该策略。

3.4.4 已安装服务与依赖资产

点击操作菜单 -> 已安装服务。页面打开时实时查询远端路径和依赖可用性，并展示工具登记的服务资产。表格字段包括服务类型/名称、状态、版本、安装路径、安装来源、最近复用、最近检查时间和操作。

3.4.5 性能测试

性能测试用于日常运维参考，不用于正式压测或采购验收。测试会在目标服务器上收集基础系统信息，并完成 CPU、内存和磁盘的轻量测试；结果会保存到性能测试历史。

1. 打开操作菜单 -> 性能测试，先核对目标服务器、连接地址和执行账号。

   

2. 点击“开始测试”。窗口分为“信息收集”和“性能测试”两组，每项显示状态、值、单位和失败/跳过原因。

3. 等待测试结束。成功会提示“性能测试完成”；失败会提示失败消息，但单个指标失败不应隐藏其他结果。

   

   解释结果：轻量测试只用于运维参考、同机趋势观察和部署前风险识别，不能替代正式压测、容量评估或采购验收。

3.4.6 性能测试历史

点击操作菜单中的“性能测试历史”，可查看该服务器过去的测试记录。列表会显示测试时间、测试结果和耗时；点击任意记录可查看系统信息、各项测试结果和失败原因。

• 历史列表为空是正常状态，至少执行一次性能测试后才会有记录。

• 点击记录查看 测试时间、耗时、系统信息、测试项目和结果摘要。

3.4.7 删除服务器与批量删除

删除入口位于操作菜单的“危险操作”组。可以删除单台服务器，也可以勾选多台服务器后批量删除。单台和批量删除都会弹出确认提示。确认后，工具中的服务器记录将无法恢复。

3.5 搜索、分组、导入和导出

列表顶部可按服务器名称、IP 地址、分组和连通性状态筛选。选择“全部分组”可恢复查看全部服务器。

• 搜索名称：选择“服务器名称”，输入完整或部分名称。

• 搜索 IP：选择“IP 地址”，输入地址或主机名片段。

• 按分组：选择“分组”，再选择“全部分组”或指定分组。

• 按连通性：选择“状态”，筛选全部、已连接或失败状态。

• 批量导入：先下载导入模板，按模板填写 host、port、用户名、密码和可选字段，再在页面上传；结果分为创建、跳过和失败三类，并显示行号及原因。

• 全量导出：导出当前服务器资产；导出文件可能包含敏感连接信息，必须按内部安全规范存储和脱敏。

• 分组管理：新增、修改或删除普通分组；系统默认分组不可随意删除。

3.6 已有部署（v0.3.1 新增）

一键纳管已有集群。如果服务器上已经部署并运行了 IoTDB 集群，无需重新安装，直接点击【已有部署】，工具会自动扫描并接管该集群，实现统一监控与运维

1. 点击已有部署按钮

   

2. 添加 DataNode 所在的服务器。

   目前仅支持端口号为 6667 的 DataNode，其他端口号将在后续版本支持。

   

3. 扫描结果如下，如果有扫描失败的，请查看集群是否正常启动

   

加入之后在集群管理中就能看见扫描到的集群，并且显示对应的信息

4 一键部署

4.1 一键部署工作方式

在服务器页和集群管理页均可进入“一键部署”。工具支持多选服务，并按 IoTDB、IoTDB Workbench、监控面板顺序执行。

1. 在服务器列表勾选目标服务器，点击“一键部署”。

2. 选择 IoTDB、IoTDB Workbench、监控面板中的一个或多个服务。

3. 点击“下一步”，确认目标服务器、部署参数和执行顺序。

4. 启动部署并观察任务进度；不要在执行期间停止工具服务。

5. 完成后进入“集群管理”核对集群记录和节点分布。

4.1.1 IoTDB

① 部署 IoTDB

进入服务器控制台的 IoTDB 部署入口，按向导填写：

填写对应的信息，可以批量的多个服务器部署，填写完对应信息后选择“下一步”。

点击下一步，开始安装部署，如果部署成功会提示，部署失败也会显示失败原因，最后显示部署结果

部署完成之后，就可以启动集群

查看集群信息

② 激活 IoTDB

进入集群管理，如果集群是未激活的状态，点击更多操作中的激活集群

点击打开可以看到机器码，将获取的机器码发送给天谋工作人员，天谋工作人员返回激活码后，在激活码的框输入激活码后点击确认激活。

激活后查看集群状态，确认 DataNode 不再处于 ReadOnly 状态。

4.1.2 部署 Workbench

进入服务器，点击一键部署，选择IoTDB Workbench，根据向导填写对应的信息，然后点击下一步

然后就会看到对应的部署结果

等待部署成功后，在 Workbench 管理页查看状态、启动/停止服务、重命名实例、同步连接或点击进入入口。常见访问形式为：http://IP:9190。

4.1.3 部署监控面板

进入服务器，点击一键部署，选择监控面板，根据向导选择对应的Prometheus包和Grafana包以及相关配置，再上传对应的监控面板

执行预检并开始部署，完成后按服务器查看 Prometheus/Grafana 状态，也可以在监控面板管理中启动监控面板

Prometheus 访问地址：http://IP:9090。

Grafana 访问地址：http://IP:3000。

4.1.4 部署看门狗

① IoTDB 集群看门狗

进入“集群管理”→目标集群→“更多操作”→“部署看门狗”。

识别完成运行用户后，点击部署

等待部署完成

② Workbench 看门狗

进入“Workbench 管理”，打开实例操作菜单→“部署看门狗”。

等待部署完成即可

③ 监控面板看门狗

进入“监控面板管理”，打开实例操作菜单→“部署看门狗”。

等待识别完成运行账户后，点击开始部署，等待部署完成即可

5 集群管理

5.1 服务器操作按钮

5.1.1 查看日志

进入集群管理，可以查看 ConfigNode 和 DataNode 的日志。

5.1.2 修改配置文件

进入集群管理，可以修改 iotdb-system、confignode-env 和 datanode-env 配置文件。

5.1.3 火焰图

在集群管理的服务器列表中，选择火焰图操作。

选择采集时长和目标 DataNode 节点。

生成完成之后下载即可

5.2 集群管理

5.2.1 查看集群

点击进入集群管理

打开目标集群，查看集群状态等信息。

5.2.2 CLI 操作

在集群管理中点击 CLI 图标，打开数据库 CLI，进行数据的增删查改操作。

5.2.3 更多操作

进入集群管理，打开“更多操作”菜单，按实际需求选择相应的集群操作。

6 Workbench / 监控面板管理

进入 Workbench 管理页面，新增监控集群。

监控面板管理的操作方式与 Workbench 管理相同。

7 文件上传与分组管理

文件上传用于集中保存安装包、配置模板、巡检模板、实施手册和脚本。

1. 进入“文件上传”，点击“增加文件”。

2. 选择文件，确认类型和大小。

3. 选择分组并提交上传。

4. 通过“分组管理”维护项目、环境或版本分组。

7.1 上传、分发和删除

1. 点击“增加文件”，可拖拽文件到上传区域或通过文件选择器选择；文件先进入“待上传”状态。

   

2. 选择文件分组后提交；页面按文件显示上传中百分比、完成或失败状态。上传失败可重新确认上传。

   

3. 勾选文件后点击“分发”，选择可连接服务器和远程目录，默认目录示例 /data/timecho/；分发窗口显示逐服务器进度。

   

   然后在服务器一键部署的时候就会自动选择

   

4. 修改文件分组支持单个或批量修改；系统默认分组可使用但不应删除。

5. 删除文件会同时删除工具文件记录和已上传文件，删除后无法恢复；批量删除失败时页面会列出成功和失败数量。

8 运维工具

集群操作和运维工具页面提供火焰图、线程栈和内存或线程转储采集能力。它们用于故障诊断，通常会在目标服务器生成临时文件或结果文件。

运维工具包含 jstack、Dump 和 Arthas 三个子菜单。

8.1 jstack 一键保存

jstack：选择集群节点执行线程栈采集，保存记录后可下载；工具重启后未完成的记录会显示为失败。

可以下载或查看结果，并按需检索。

8.2 Dump 文件一键保存

Dump：选择集群、节点角色和节点，可选择 heap/thread 类型、压缩 heap dump、线程锁信息、远程目录和文件名前缀；任务完成后下载或删除记录。

8.3 Arthas 排查工具

选择目标 DataNode 和采集时长，启动火焰图任务；任务运行期间可停止采集，完成后在历史记录查看或删除本地火焰图文件。

9 集群巡检

9.1 巡检配置

打开“集群巡检”菜单，进入“巡检配置”。工具支持从模板选择指标创建巡检方案，配置定时执行和通知推送。

1. 点击“巡检模板”，选择所需模板。

   

2. 点击“新建巡检方案”，填写名称并选择集群。

3. 选择“巡检模板”或点击“添加指标”。

4. 按指标配置时间范围、条件、阈值、模式和持续时间。

5. 配置执行周期和通知推送，点击“保存方案”。

   

6. 手动验证一次，确认指标均能返回结果。

   

9.2 报告历史

进入“报告历史”按方案、集群和时间范围筛选历史报告。建议将版本升级、重大变更和项目验收前的报告归档。

• 成功：检查项已执行并生成结果。

• 失败：查看失败指标和目标节点，结合工具日志排查。

• 缺少数据：检查监控采集、节点连通性和时间范围。

9.3 巡检模板与导入导出

• “巡检模板”用于维护可复用指标；模板指标可导出，便于在不同环境复用。

• “导入方案”用于导入已有巡检方案；导入后先检查集群、指标和阈值是否适配当前版本。

• 删除方案不会自动删除历史报告；删除报告则只影响工具保存的报告记录和下载文件。

10 故障排查

现象	优先检查	处理建议
工具无法打开	进程、APP_ADDR、8386 端口	查看 PID 和 logs，确认端口未占用。
服务器连接失败	IP、SSH 端口、凭据、防火墙	先测网络，再测 SSH；确认用户权限。
一键部署中断	失败步骤、磁盘、权限	查看部署记录和当天业务日志，修复前置条件后重试。
Workbench 未显示	部署是否成功、列表是否刷新	刷新列表，确认服务进程和端口。
监控无数据	采集目标、连接、时间范围	检查 Prometheus 目标、Grafana 数据源和节点时间。
巡检报告失败	方案指标、集群选择、采集状态	确认方案已保存且集群可用。