[TSDB] TDengine 使用指南

0 序

  • 编写日期:2026-10-13 | 已在 Windows 10/11(x64)亲测

  • 关键前提(务必先读):从 TDengine 3.1.0.0 起,社区版在 Windows 上只提供"客户端安装包"(taos CLI / 驱动 / taosAdapter),不再随社区版提供 Windows 服务端(taosd);Windows 服务端仅随企业版提供。因此要在 Windows 上"亲测、使用"完整 TDengine,官方推荐且最稳妥的路径是:

方案 A(推荐):Docker 跑服务端 + 浏览器/容器内 CLI 使用(社区版 TSDB 全功能,免装服务端)
方案 B:安装 Windows 客户端,连接远端/Linux/Docker 上的服务端(仅客户端在 Windows 上)

本文档以 方案 A 为主线(一键即可在 Windows 亲测),方案 B 作为补充。


1 使用指南

一、方案 A:Docker 部署服务端(亲测/推荐)

1.1 前置准备

1.2 拉取镜像

注意:从 3.3.7.0 起社区版镜像名由 tdengine/tdengine 改为 tdengine/tsdb;企业版为 tdengine/tsdb-ee。本教程用社区版镜像。

# 拉取指定版本(开源版) (笔者的选择 | 2026.10.13)
> docker pull tdengine/tsdb:3.4.2.8
# 或 企业版本(ee): docker pull tdengine/tsdb-ee:3.4.3.1
# 或 拉取最新版本: docker pull tdengine/tsdb:latest

# 查验拉取的镜像
> docker images
IMAGE                      ID             DISK USAGE   CONTENT SIZE   EXTRA
tdengine/tsdb:3.4.2.8      44f58e6f9b01       1.23GB          332MB

如果你无法直接访问 Docker Hub,可以前往 TDengine 产品下载中心的 Docker 镜像下载页面,获取 Docker 镜像下载链接。完成下载后,请根据页面中的离线安装提示加载镜像,并修改镜像名称和标签。

1.3 启动容器(Windows PowerShell / cmd)

用 Docker 快速体验 TDengine TSDB | TDengine 文档 | 涛思数据

  • 配置1个系统环境变量 (便于后续统一引用,可选步骤)

    • TD_DATA_HOME=D:\Program-Data\TD-Engine-Data\

    • 验证

# git-bash 下:
$ echo $TD_DATA_HOME
D:\Program-Data\TD-Engine-Data

# powershell 下:
PS C:\Users\xxx> echo $env:TD_DATA_HOME
D:\Program-Data\TD-Engine-Data

# cmd 下:
C:\Users\xxx> echo %TD_DATA_HOME%
D:\Program-Data\TD-Engine-Data
  • 启动容器 (git-bash)
docker run -d \
   -v ${TD_DATA_HOME}\data\taos\dnode\data:/var/lib/taos \
   -v ${TD_DATA_HOME}\data\taos\dnode\log:/var/log/taos \
   -p 6030:6030 \
   -p 6041:6041 \
   -p 6043:6043 \
   -p 6044-6049:6044-6049 \
   -p 6044-6045:6044-6045/udp \
   -p 6060:6060 \
   --name tdengine-tsdb \
   tdengine/tsdb:3.4.2.8

端口说明:

  • 6030:客户端与服务端原生协议通信
  • 6041:RESTful API(taosAdapter)
  • 6043:taosKeeper(监控)
  • 6060:taosExplorer(可视化 Web UI)

1.4 检查容器状态

$ docker ps -f name=tdengine-tsdb
CONTAINER ID   IMAGE                   COMMAND                   CREATED              STATUS              PORTS

          NAMES
4230d6344c91   tdengine/tsdb:3.4.2.8   "/usr/bin/tini -- /u…"   About a minute ago   Up About a minute   0.0.0.0:6030->6030/tcp, [::]:6030->6030/tcp, 0.0.0.0:6041->6041/tcp, [::]:60
41->6041/tcp, 0.0.0.0:6043-6049->6043-6049/tcp, [::]:6043-6049->6043-6049/tcp, 0.0.0.0:6060->6060/tcp, [::]:6060->6060/tcp, 0.0.0.0:6044-6045->6044-6045/udp, [::]:6044-6045->6044-60
45/udp   tdengine-tsdb

看到 STATUS 为 Up ... (healthy) 即启动成功。

1.5 进入容器

$ docker exec -it tdengine-tsdb bash
root@4230d6344c91:/# cat /etc/os-release
PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
NAME="Debian GNU/Linux"
VERSION_ID="12"
VERSION="12 (bookworm)"
VERSION_CODENAME=bookworm
ID=debian
HOME_URL="https://www.debian.org/"
SUPPORT_URL="https://www.debian.org/support"
BUG_REPORT_URL="https://bugs.debian.org/"
root@4230d6344c91:/#

进入后即可执行 taos 命令(见下文使用教程)。


二、使用教程:taos CLI(核心)

2.1 进入 CLI

在容器内(或 Linux/Mac)执行:taos

root@4230d6344c91:/# taos
Welcome to the TDengine TSDB Command Line Interface, Native Client Version:3.4.2.8.community
Copyright (c) 2025 by TDengine TSDB, all rights reserved.


  *********************************  Tab Completion  *************************************
  *   The TDengine TSDB CLI supports tab completion for a variety of items,              *
  *   including database names, table names, function names and keywords.                *
  *   The full list of shortcut keys is as follows:                                      *
  *    [ TAB ]        ......  complete the current word                                  *
  *                   ......  if used on a blank line, display all supported commands    *
  *    [ Ctrl + A ]   ......  move cursor to the st[A]rt of the line                     *
  *    [ Ctrl + E ]   ......  move cursor to the [E]nd of the line                       *
  *    [ Ctrl + W ]   ......  move cursor to the middle of the line                      *
  *    [ Ctrl + L ]   ......  clear the entire screen                                    *
  *    [ Ctrl + K ]   ......  clear the screen after the cursor                          *
  *    [ Ctrl + U ]   ......  clear the screen before the cursor                         *
  ****************************************************************************************

Server is TDengine TSDB-OSS ver:3.4.2.8.community. License will never expire.

taos>
taos> show databases;
              name              |
=================================
 information_schema             |
 performance_schema             |
 log                            |
Query OK, 3 row(s) in set (0.001433s)
  • 在 Windows 本地(安装了客户端,见方案 B)执行:
taos.exe

进入后提示符为:

taos>

默认账号/密码:root / taosdata

2.2 建库、建表、写入、查询(快速上手)

-- 创建数据库
CREATE DATABASE IF NOT EXISTS demo; -- 或: CREATE DATABASE demo;

-- 列出(所有)数据库
SHOW DATABASES;

-- 切换数据库
USE demo;

-- 创建【普通表】
CREATE TABLE t (ts TIMESTAMP, speed INT);
SHOW TABLES;

-- 写入
INSERT INTO t VALUES ('2019-07-15 00:00:00', 10);
INSERT INTO t VALUES ('2019-07-15 01:00:00', 20);

-- 查询
taos> SELECT * FROM t;
           ts            |    speed    |
========================================
 2019-07-15 00:00:00.000 |          10 |
 2019-07-15 01:00:00.000 |          20 |
Query OK, 2 row(s) in set (0.001187s)

2.3 超级表(STable)+ 子表(贴合:物联网模型)

  • 表的设计:超级表 + 子表
meters(超级表 = 类模板)
│  列:ts, current, voltage, phase
│  标签定义:location, groupId
├── d1001(子表 = 采集点1)  tags: Beijing.Beijing, 1
├── d1002(子表 = 采集点2)  tags: Shanghai.Shanghai, 2
└── d1003(子表 = 采集点3)  tags: Beijing.Chaoyang, 1
       ...(可到上百万张子表)

对照普通表方案:

如果每台设备1张普通表,表数量爆炸且难以做跨设备聚合;

如果所有设备塞进1张大表,又难以区分各设备。

超级表 + 子表正好化解这对矛盾 —— 结构统一、可聚合,又保留每个采集点的独立性与标签。

  • DDL/DML SQL:

CLI 模式下,需手动清理下所有SQL注释。

DDL + DML

USE demo;

-- 创建超级表 meters:一个【采集点】一张【子表】,公共结构 + 静态标签
-- 1、超级表:
-- 1.1、用来把 "【同一类数据采集点】" 聚合成一张逻辑上的统一表,从而支撑【跨采集点的统一查询和聚合】。
-- 1.2、超级表 = 模板/类型定义:定下【公共列结构】 + 【标签名和类型】(此刻还没有实际标签值)
-- 2、子表:
-- 2.1 子表(Subtable)= 具体采集点实例:用超级表当模板创建,【一张子表对应一个采集点】,并填入该点自己的标签值。
-- 2.2 【物理数据】落在每张子表,【超级表】本身不存数据,只是【逻辑视图】
CREATE STABLE meters ( -- 假设采集、存储: 智能电表/meters 的时序数据
  ts TIMESTAMP,  -- 时间戳主键,第1列必须是它
  current FLOAT, -- 电流(随时间变化的采集量)
  voltage INT,   -- 电压
  phase FLOAT    -- 相位
) TAGS (location BINARY(64), groupId INT); -- TAG=位置/location:字符串,最长 64 字节
-- 3、TAGS:
-- 0) 标签的价值:
--  A、分组/过滤:`WHERE location='Beijing'` 直接按标签筛选子表,高效聚合;
--  B、与数据分离存储:避免重复存储冗余静态信息,节省空间。
-- 1) 每个采集点的【静态属性】,不随时间变化(设备位置、所属分组等);
-- 2) 它们【不随每条记录存储】,而是作为元数据独立存放,【只对超级表生效,普通表没有 TAGS】。 

-- 查询有哪些超级表
SHOW STABLES;

-- 查看指定的超级表的DDL定义
taos> SHOW CREATE STABLE meters;
             Table              |          Create Table          |
==================================================================
 meters                         | CREATE STABLE `meters` (`ts... |
Query OK, 1 row(s) in set (0.002173s)

-- 为具体采集点创建子表 d1001(指定标签值)
CREATE TABLE d1001 USING meters TAGS ('Beijing.Beijing', 1);
CREATE TABLE d1002 USING meters TAGS ('Shanghai.Shanghai', 2);

-- 写入
INSERT INTO d1001 VALUES (now, 10.5, 220, 0.3);
INSERT INTO d1002 VALUES (now, 11.2, 220, 0.5);

DQL(子表)

  • 查询:有哪些【普通表 + 子表】
taos> show tables;
           table_name           |
=================================
 t                              |
 d1001                          |
 d1002                          |
Query OK, 3 row(s) in set (0.005674s)
  • 查询:指定超级表下有哪些子表 (列出该超级表下所有子表名及 TAG 值)
-- 查询:指定超级表下有哪些子表 (列出该超级表下所有子表名及 TAG 值)
taos> SELECT DISTINCT tbname, location, groupId FROM meters;
             tbname             |            location            |   groupid   |
================================================================================
 d1002                          | Shanghai.Shanghai              |           2 |
 d1001                          | Beijing.Beijing                |           1 |
Query OK, 2 row(s) in set (0.002302s)

-- 统计:超级表下,子表的数量
taos> SELECT COUNT(DISTINCT tbname) FROM meters;
 count(distinct tbname) |
=========================
                      2 |
Query OK, 1 row(s) in set (0.002138s)

tbname 是 TDengine 的内置伪列,代表每行数据所属的子表名。

  • 从系统表查:查子表对应的 TAG 值
taos> SELECT * FROM information_schema.ins_tags WHERE stable_name = 'meters';
           table_name           |            db_name             |          stable_name           |            tag_name            |            tag_type            |           tag_value            |
======================================================================================================================================================================================================
 d1001                          | demo                           | meters                         | location                       | VARCHAR(64)                    | Beijing.Beijing                |
 d1001                          | demo                           | meters                         | groupid                        | INT                            | 1                              |
 d1002                          | demo                           | meters                         | location                       | VARCHAR(64)                    | Shanghai.Shanghai              |
 d1002                          | demo                           | meters                         | groupid                        | INT                            | 2                              |
Query OK, 4 row(s) in set (0.005759s)
  • 查询子表的数据
taos> select * from d1001;
           ts            |       current        |   voltage   |        phase         |
======================================================================================
 2026-10-13 02:51:22.430 |                 10.5 |         220 |                  0.3 |
Query OK, 1 row(s) in set (0.001552s)

或: SELECT * FROM d1001 LIMIT 10;

DQL(超级表)

-- 超级表聚合查询(跨子表)
SELECT COUNT(*), AVG(current), MAX(voltage) FROM meters;
taos> SELECT COUNT(*), AVG(current), MAX(voltage) FROM meters;
       count(*)        |       avg(current)        | max(voltage) |
===================================================================
                     2 |          10.8499999046326 |          220 |

-- 按标签过滤
SELECT * FROM meters WHERE location = 'Beijing.Beijing';
taos> SELECT * FROM meters WHERE location = 'Beijing.Beijing';
           ts            |       current        |   voltage   |        phase         |            location            |   groupid   |
=====================================================================================================================================
 2026-10-13 02:51:22.430 |                 10.5 |         220 |                  0.3 | Beijing.Beijing                |           1 |
Query OK, 1 row(s) in set (0.003631s)

-- 按时间窗口聚合(每 10 秒)
SELECT _wstart, AVG(current), MAX(voltage) FROM meters INTERVAL(10s);
taos> SELECT _wstart, AVG(current), MAX(voltage) FROM meters INTERVAL(10s);
         _wstart         |       avg(current)        | max(voltage) |
=====================================================================
 2026-10-13 02:51:20.000 |          10.8499999046326 |          220 |
Query OK, 1 row(s) in set (0.008276s)

2.4 查看状态

SHOW DATABASES;      -- 查看所有数据库
SHOW TABLES;         -- 查看当前库所有表
SHOW STABLES;        -- 查看超级表

三、使用教程:Taos Explorer Web GUI

  1. 浏览器访问: http://localhost:6060

    登录:用户名 root,密码 taosdata

  2. 进入 数据浏览器:可查看数据库/超级表/子表,直接写 SQL 查询并出折线图

  3. 其他模块:数据写入、编程(一键复制各语言连接示例)、流计算、数据订阅、工具(Grafana / Excel / Tableau 等集成指引)、系统管理


登录 / 注册 / 数据浏览器

image

面板

image

数据写入

image

数据发布

image

编程

image

流计算

image

数据订阅

image

  • 示例代码

参见: http://localhost:6060/docs/develop/tmq/#data-subscription
image

工具

image

系统管理

image

image

IDMP

image

四、使用教程:性能压测 taosBenchmark

在容器内或已装客户端的环境执行(自动生成 1 亿条智能电表数据):

taosBenchmark -y

image
image

实测耗时: 不足1分钟 (CPU: Intel i7-10700K , 3.8GHz; 内存:24GB; 显卡:12GB, RTX 3060; 磁盘: SSD + 机械)

写入完成后,回 CLI 查询验证性能:

表DDL:CREATE STABLE meters (tsTIMESTAMP,currentFLOAT,voltageINT,phase FLOAT) TAGS (groupidINT,location VARCHAR(24)) SECURITY_LEVEL 0 SECURE_DELETE 0

SELECT COUNT(*) FROM test.meters; -- 100000000 (0.077475s)

taos> SELECT AVG(current), MAX(voltage), MIN(phase) FROM test.meters;
       avg(current)        | max(voltage) |      min(phase)      |
==================================================================
           10.209845130825 |          258 |                  145 |
Query OK, 1 row(s) in set (0.559602s)

taos> SELECT _wstart, AVG(current), MAX(voltage), MIN(phase) FROM test.d1001 INTERVAL(10s);
         _wstart         |       avg(current)        | max(voltage) |      min(phase)      |
============================================================================================
 2017-07-14 02:40:00.000 |           10.209845130825 |          258 |                  145 |
Query OK, 1 row(s) in set (0.007204s)

五、使用教程:RESTful API(curl)

taosAdapter 提供 6041 REST 接口,用 curl 即可查询(Windows 自带 curl):

root@4230d6344c91:/# curl -u root:taosdata -d "show databases" http://localhost:6041/rest/sql
{"code":0,"column_meta":[["name","VARCHAR",64]],"data":[["information_schema"],["performance_schema"],["demo"],["log"],["test"]],"rows":5}root@4230d6344c91:/#

返回 JSON 结果。


六、方案 B:Windows 客户端安装包(仅客户端,可选/未亲测)

适用:你想在 Windows 本地用 taos CLI / 各语言驱动,但服务端在 Linux / 云端 / Docker 上。

  1. 从 TDengine 产品下载中心下载 Windows 客户端安装包(tdengine-tsdb-oss 的 Windows 版本)。

https://www.taosdata.com/downloads/?product=TDengine+TSDB-OSS+Client&platform=Windows&version=3.4.2.8&architecture=x64&type=Client

  1. 运行安装程序,默认安装目录 C:\TDengine(可自选,若路径不以 TDengine 结尾会自动追加)。

  2. 安装前若缺 Microsoft Visual C++ Redistributable 2015-2022 x64,安装程序会自动装内置版本(14.50.35719.0)。

  3. 以管理员重新打开 cmd,进入安装目录执行 taos.exe 连接本地/远端服务端。

    C:\TDengine\taos.exe
    
  4. 如需连接远端服务端,编辑配置文件 C:\TDengine\taos.cfg 指定 FQDN:

    fqdn 192.168.1.100
    serverPort 6030
    

提示:Windows 上如需服务端(taosd),官方要求联系销售升级为企业版;社区版服务端请在 Linux 上部署,或用 Docker(方案 A)。


七、常用运维命令(未亲测)

场景 Linux/systemd Windows(若有服务端)
启动 sudo systemctl start taosd sc start taosd 或 taosd.exe
状态 sudo systemctl status taosd sc query taosd
停止 sudo systemctl stop taosd sc stop taosd
一键启停 start-all.sh start-all.bat
数据目录 /var/lib/taos C:\TDengine\data
日志目录 /var/log/taos C:\TDengine\log
配置文件 /etc/taos/taos.cfg C:\TDengine\taos.cfg

八、卸载

  • Docker 方式:docker rm -f tdengine-tsdb(如需彻底删数据,删除映射的 ${HOME}\data\taos 目录)。
  • Windows 客户端:控制面板 → 卸载程序 → 卸载 TDengine(会保留数据/日志/配置目录)。

Z FAQ/常见问题 for TD-Engine 部署/使用

Q:taos 连不上服务端 / 提示连接失败?

  • 检查 taosd 服务是否已启动(docker ps -f name=tdengine-tsdb 是否 healthy)。
  • 检查端口 6030 是否被占用、防火墙是否放行。
  • Windows 客户端若连接远端,确认 taos.cfg 的 fqdn 与 serverPort。

Q:Docker 无法访问 Docker Hub / 拉镜像失败?

  • 配置国内镜像加速,或到 TDengine 产品下载中心下载离线镜像后 docker load。

Q:社区版在 Windows 能装服务端吗?

  • 不能。3.1.0.0 起社区版 Windows 仅提供客户端;服务端需 Linux 部署或 Docker,或用企业版。

Q:taosBenchmark 命令找不到?

  • 它随服务端/客户端安装包提供;容器内直接可用,Windows 客户端安装后在安装目录下。

Q:默认用户名密码是什么?

  • root / taosdata。

Y 推荐文献

  • TD-Engine

X 参考文献

posted @ 2026-10-13 11:16  千千寰宇  阅读(36)  评论(0)    收藏  举报