跳至主要內容

TimechoCLI

大约 10 分钟

TimechoCLI

1. 简介

TimechoCLI 是 Timecho 面向终端用户、自动化脚本和 AI Agent 推出的统一命令行工具，配套官方 Skills，以自然语言打通 TimechoDB、Apache IoTDB 与 TimechoAI 的产品使用链路，降低使用门槛，打通 DB × AI 的最后一公里。

面向 TimechoDB，CLI 提供从部署激活、SQL 执行、数据导入导出到运维诊断的全链条调度能力；面向 TimechoAI，支持数据载入、模型推理调度及结果可视化，并通过配套 Skills 减少命令臆造与参数误用，提升操作准确率。

TimechoCLI 兼容 Codex、Claude Code、Hermes 等主流 Agent 环境，为 Timecho 全产品线提供低门槛的 Agent 操作入口。

2. 安装部署

安装部署请参考TimechoCLI 部署。

3. 使用自然语言与大模型交互示例

3.1 前置操作：大模型先安装 CLI 并接入 Skills

对大模型说：

帮我安装 Timecho CLI: https://timecho.com/timecho-cli/installation-guide.md
帮我更新 Timecho CLI: https://timecho.com/timecho-cli/installation-guide.md

3.2 前置操作：单机 TimechoDB 一键部署 + 激活

对大模型说：

帮我在本机 D:\timecho 部署一套单机版（1C1D）TimechoDB，软件包 D:\TimechoDB\timechodb-2.0.10.2-bin.zip，部署完成后激活授权并确认服务可用。

3.3 场景 1：启动 TimechoDB

对大模型说：

检查我的 TimechoDB 启动状态，如未启动请帮忙启动，并确认服务可用。

3.4 场景 2：连接巡检 + 深度健康检查 + 诊断包（运维·巡检）

对大模型说：

帮我做一次 TimechoDB 全面巡检：看整体健康状态、磁盘/内存/WAL/Compaction 有没有异常，并生成巡检报告。

3.5 场景 3：配置巡检与调优（运维·配置）

对大模型说：

帮我看看当前 TimechoDB 配置和推荐值差在哪，把内存、WAL、Compaction 等关键参数按这台机器的资源调优，但先别真的改。

3.6 场景 4：SQL 开发 / Text2SQL + 数据导入导出（运维·数据开发）

对大模型说：

帮我把这个 CSV table_metrics.csv 导进 TimechoDB 的表模型中的 test 数据库中，如果表已存在请先删除表，并支持我用自然语言查数据：比如"最近 1 小时每台设备的平均温度，输出 CSV"。

3.7 场景 5：SQL 开发 / object 数据导入

对大模型说：

帮我在表模型下创建数据库 object_test，并创建表 device_obj，建表 DDL 如下：

CREATE TABLE "device_obj" (
  "device_id"  STRING      TAG,
  "file_name"  STRING      ATTRIBUTE,
  "file_size"  INT32       FIELD,
  "file_data"  OBJECT      FIELD
) WITH (ttl='INF')

将 D:\TimechoDB 目录下的图片插入到 device_obj 表中。

3.8 场景 6：故障诊断 + 日志分析（运维·排障）

对大模型说：

我的 DB 报如下错误，帮我定位根因并给出修复步骤。

There is not enough memory to execute current fragment instance, current remaining free memory is 86762854, estimated memory usage for current fragment instance is 270139392
我的 DB 报如下错误，帮我定位根因并给出修复步骤。

2026-08-21 10:12:33.815 [main] ERROR o.a.i.db.service.DataNodeStartUpCheck:70 - Reject DataNode restart.
Please clean the data directory before starting.
org.apache.iotdb.exceptions.StartupException: 203: Start up error. DataNode has been registered to cluster,
but data directory is not empty. Please clean the data/datanode/ directory and restart.
at org.apache.iotdb.db.service.DataNodeStartUpCheck.check(DataNodeStartUpCheck.java:68)
at org.apache.iotdb.db.service.IoTDB.startup(IoTDB.java:120)
at org.apache.iotdb.db.service.IoTDBEntryPoint.main(IoTDBEntryPoint.java:45)
2026-08-21 10:12:33.820 [main] ERROR org.apache.iotdb.db.service.IoTDB:152 - Failed to start IoTDB DataNode
because: 203: Start up error. DataNode has been registered to cluster, but data directory is not empty.
我的 DB 报如下错误，帮我定位根因并给出修复步骤。

2026-08-21 14:25:07.332 [pool-3-thread-1] WARN  o.a.i.db.mpp.execution.FragmentInstanceManager:218 -
Failed to execute fragment instance, instance_id=20260821_142507_00001_00003
org.apache.iotdb.exceptions.QueryProcessException: 709: MPP task execution memory is not enough.
current remaining free memory is 86762854, estimated memory usage for current fragment instance is 270139392.
Please try to reduce the query range or increase the memory allocation.
at org.apache.iotdb.db.mpp.execution.FragmentInstanceManager.checkMemory(FragmentInstanceManager.java:210)
at org.apache.iotdb.db.mpp.execution.FragmentInstanceManager.start(FragmentInstanceManager.java:165)
at org.apache.iotdb.db.mpp.plan.planner.DistributionPlanner.plan(DistributionPlanner.java:98)
at org.apache.iotdb.db.mpp.plan.Planner.planQuery(Planner.java:76)
at org.apache.iotdb.db.mpp.sql.Analyzer.analyzeQuery(Analyzer.java:112)
2026-08-21 14:25:07.335 [pool-3-thread-1] ERROR org.apache.iotdb.db.mpp.plan.PlanProcessor:89 -
Failed to process query: SELECT * FROM root.sg_1.d_1.* WHERE time > 2026-08-01T00:00:00.000+08:00
我的 DB 报如下错误，帮我定位根因并给出修复步骤。

2026-08-21 09:03:15.441 [disk-space-monitor-1] WARN  o.a.i.db.engine.StorageEngine:342 -
Disk space is insufficient. Path: D:\TimechoDB\data\datanode\data,
usage: 89.2%, threshold: 85.0%. System will switch to read-only mode.
2026-08-21 09:03:15.443 [disk-space-monitor-1] ERROR o.a.i.db.engine.StorageEngine:356 -
611: Disk space is insufficient. Triggering system read-only protection.
2026-08-21 09:03:15.445 [disk-space-monitor-1] WARN  o.a.i.db.service.IoTDB:430 -
System is now in READ_ONLY mode. All write operations will be rejected.
To restore write capability: clean up disk space and execute 'SET SYSTEM TO RUNNING ON CLUSTER;'.
2026-08-21 09:05:22.118 [ClientPool-thread-3] ERROR org.apache.iotdb.db.writelog.WriteLogManager:178 -
Failed to write WAL: 600: System is read-only. Write operation rejected.
insert into root.sg_1.d_1(timestamp, s_1) values (2026-08-21T09:05:22.000+08:00, 42.5)

4. Skills

#技能名称说明
1timecho-cli-guideTimecho CLI 命令使用指南。用于解析当前命令语法、选择安全参数、执行校验，并避免虚构命令、参数或数据库配置。
2timecho-forecast使用 Timecho CLI 对 CSV、TSV 或 JSON 时序数据进行预测、绘图、保存预测结果，并支持历史协变量、未来协变量和模型选择。
3timechoai-cli-guideTimechoAI CLI 使用指南。用于检查 AI 连通性、管理 API Key、执行已实现的 AI 命令、检查 AI 输出和确认能力是否可用。
4timechodb-backup-restoreTimechoDB 备份与恢复，包括 Schema 导出、TsFile 备份、全量/增量备份、PITR 灾难恢复，以及树模型和表模型处理。
5timechodb-benchmark集成 IoTDB Benchmark，根据机器资源自动调整测试规模，测试写入吞吐、延迟百分位和混合查询负载，并生成结构化指标。
6timechodb-client-refTimechoDB 或 Apache IoTDB 客户端集成参考，覆盖 Java、JDBC、C++、Python、REST、Spring Boot、MyBatis、Go、C、MQTT，以及连接池和客户端故障排查。
7timechodb-config-advisorTimechoDB 配置优化建议。根据 CPU、内存、磁盘和部署拓扑，推荐内存、副本、WAL、Compaction 等关键参数，并对比当前配置与推荐配置。
8timechodb-config-manage查看、修改和校验 TimechoDB 配置，支持 --dry-run、不可变参数拦截和高风险操作确认。
9timechodb-data-ops批量数据运维，包括执行 SQL 文件、初始化测试数据、清理数据、导入 TsFile、设置 TTL 和配置连续查询。
10timechodb-deploy-2activeTimechoDB 双活部署指南，覆盖两个独立实例、双向 Pipe 同步、断点续传、激活和许可证校验。
11timechodb-deploy-clusterTimechoDB 分布式集群部署，支持 3C3D 或自定义 Cn/Dn 规模，包含 Seed 节点加入、副本配置和跨节点连通性检查。
12timechodb-deploy-docker使用 Docker 或 Docker Compose 部署 TimechoDB，提供 1C1D、1C2D、3C3D 模板，以及持久化卷、端口映射和镜像版本配置。
13timechodb-deploy-standaloneTimechoDB 单机部署指南，支持自定义端口、路径和内存参数，并自动验证节点运行状态和节点数量。
14timechodb-development-guideTimechoDB 与 Apache IoTDB 应用开发指南，覆盖 Java、JDBC、Python、C++、REST、树/表模型选择、连接生命周期、读写限制和生产问题排查。
15timechodb-faq-diagTimechoDB 常见故障诊断，包括启动失败、连接拒绝、OOM、复制不一致、WAL 异常和配置错误，并结合 ERROR/WARN 日志定位问题。
16timechodb-health-check根据巡检报告 Word 模板执行只读健康巡检，并生成保持原版式的 .docx 巡检报告。
17timechodb-knowledge-baseTimechoDB 官方知识库，覆盖版本 Release Notes、配置项、错误码、树/表模型差异、SQL 语法、部署运维和版本对比。
18timechodb-log-analyze分析 TimechoDB 日志中的 ERROR/WARN 模式，包括 OOM、GC、WAL 刷盘、Compaction、线程激增和连接池耗尽，并生成摘要报告。
19timechodb-monitor-integrate集成 Prometheus 和 Grafana 监控，包括启用指标上报、配置端口、导入仪表盘和关联操作系统指标。
20timechodb-node-ops节点运维，包括扩缩容、数据迁移、Region 均衡、热点节点摘除、ConfigNode/DataNode 启停顺序，以及使用 jstack 分析线程和死锁。
21timechodb-pipe-sync配置 Pipe 数据同步，包括站点到中心、全量/增量/级联同步、隔离网穿透、加密压缩、双活镜像和同步延迟监控。
22timechodb-rn-issue-resolver将 RN 或 Issue 文本转换为可执行操作，包括参数调整、配置补丁、复现步骤、需求验证和问题复现。
23timechodb-schema-gen根据设备层级或表模型生成保守的 TimechoDB/Apache IoTDB Tree/Table Schema DDL，包括数据库、时间序列、表和 TAG/FIELD 映射。
24timechodb-sql-dev开发、审查和调试 TimechoDB/Apache IoTDB SQL，覆盖树/表方言、路径绑定、聚合、时间条件、函数选择和运行时错误改写。
25timechodb-test-gen根据知识库生成测试用例，包括部署验证、RN 缺陷和性能回归测试，并输出测试步骤、预期结果和测试报告。
26timechodb-text2sql将自然语言需求转换为一条可执行的 TimechoDB/Apache IoTDB SQL，支持树/表模型选择、路径绑定、过滤、聚合和 SQL 校验。
27timechodb-tier-storage多级存储方案设计，包括热数据 SSD、温数据和冷数据对象存储/HDD 的自动分层、访问频率规则、查询调度和参数调优。
28timechodb-tree-table-guide解释和选择 TimechoDB/Apache IoTDB Tree 与 Table 模型，覆盖层级路径、TAG/ATTRIBUTE/FIELD 映射、设备与测点边界及模型迁移。
29timechodb-upgrade-rollbackTimechoDB 升级与回滚指南，包括目标版本下载、配置和元数据备份、滚动升级、兼容性验证及失败回滚。

5. 命令总览

timecho-cli
├── activate         激活管理（machine-code/apply/status）
├── ai               TimechoAI 服务
│   ├── ping         测试 AI 连通性和认证
│   ├── dimensions   列出数据质量评估维度
│   ├── evaluate     评估时序表数据质量
│   └── forecast     序列预测（单/多目标）
├── completion       Shell 补全（bash/zsh/fish/powershell）
├── config           配置管理（get/set/diff/tune/schema）
├── ctx              连接上下文管理（add/list/show/use/update/remove/discover）
├── data             数据导入导出
│   ├── import
│   │   ├── csv      CSV 批量导入（Tree/Table mapping）
│   │   └── tsfile   TsFile 服务端路径 LOAD
│   └── export
├── diagnose         远程+本地脱敏诊断包
├── setup
│   └── skills       安装 Skills 到 Claude/Codex/OpenClaw/Hermes
├── sql              执行 SQL（tree/table 方言，支持 -f/--stdin）
├── status           健康汇总（版本/激活/集群/Region/磁盘）
└── version          显示 CLI 版本号

注：TsFile 导出不在 CLI 原语内，走 tsfile-backup 脚本或 Pipe tsfile-local-sink；AI 子树不读 DB Context。

详细的命令使用请参考 TimechoCLI 命令使用示例。

6. 全局参数

所有子命令均可前缀以下参数：

参数简写说明
--ctx-指定数据库连接上下文名称（不适用于 ai 子命令）
--help-h显示命令帮助信息
--json-输出稳定的 JSON Envelope（含 api_version、kind、data 等字段）
--no-color-禁用彩色输出
--non-interactive-禁止交互式输入（适用于 CI/CD 等自动化脚本）
--output-o指定输出格式：human（默认）、json 或 csv
--sql-dialect-临时覆盖数据库 SQL 方言：tree 或 table（不适用于 ai 子命令）
--timeout-设置命令整体超时时间（如 30s、2m、1h）
--trace-id-在结构化输出中附加自定义 Trace ID，便于链路追踪
--verbose-v启用详细诊断日志，输出到 stderr
--yes-y自动确认高风险操作，无需手动输入确认

说明：

  • --json 等价于选择 JSON 输出；不要同时显式传入冲突的 --output human 或 --output csv。
  • --output csv 主要用于返回结果集的 sql 查询；非查询 SQL 不接受 CSV 输出。
  • 全局参数可以写在子命令前后，但团队脚本建议统一放在一级命令前，便于阅读。
  • --non-interactive 只负责禁止提示，不会自动同意高风险操作；需要授权时仍应传入 --yes。
  • --yes 只表示确认写操作，不会绕过参数、安全、版本或校验和检查。
  • --verbose 的诊断信息写入 stderr，不应与 JSON/CSV stdout 混合。
  • ai 复用输出、超时、自动化和诊断类全局参数，但会拒绝显式传入的 --ctx 与 --sql-dialect。

6.1 全局参数示例

timecho-cli --ctx prod sql "show version"
timecho-cli --ctx prod --json status
timecho-cli --ctx prod --timeout 30s sql "show cluster"
timecho-cli \
  --ctx prod \
  --json \
  --non-interactive \
  --trace-id request-20260721-001 \
  status

临时覆盖 SQL 方言：

timecho-cli --ctx prod --sql-dialect table sql "show databases"

开启详细日志：

timecho-cli --ctx prod --verbose diagnose

JSON 与显式输出格式冲突，以下写法会在连接数据库前失败：

timecho-cli --json --output csv version

7. MCP Server

IoTDB MCP Server 是一个基于模型上下文协议（Model Context Protocol, MCP）的服务器实现，通过 IoTDB 提供数据库交互和商业智能能力。该服务器支持执行 SQL 查询，并可以通过不同的 SQL 方言（树模型和表模型）与 IoTDB 进行交互。

MCP 已开源，可直接从 GitHub iotdb-mcp-server 下载。

最近更新:

Copyright © 2026 Timecho Limited All rights reserved.
Apache IoTDB and the Apache IoTDB project logo are trademarks of The Apache Software Foundation.