[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 作为补充。
-
推荐的安装部署文档
-
本文档默认基于 TD-Engine 3.4.2.8 (开源版、Docker部署方式) 进行试验。
1 使用指南
一、方案 A:Docker 部署服务端(亲测/推荐)
1.1 前置准备
- 安装 Docker Desktop for Windows(官网 https://docker.com 下载),并确保已启动。
- Windows 10/11 需开启 WSL2 或 Hyper-V(Docker Desktop 安装向导会引导)。
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)
-
配置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
-
浏览器访问: http://localhost:6060
登录:用户名
root,密码taosdata -
进入 数据浏览器:可查看数据库/超级表/子表,直接写 SQL 查询并出折线图
-
其他模块:数据写入、编程(一键复制各语言连接示例)、流计算、数据订阅、工具(Grafana / Excel / Tableau 等集成指引)、系统管理
登录 / 注册 / 数据浏览器

面板

数据写入

数据发布

编程

流计算

数据订阅

- 示例代码
参见: http://localhost:6060/docs/develop/tmq/#data-subscription
工具

系统管理


IDMP

四、使用教程:性能压测 taosBenchmark
在容器内或已装客户端的环境执行(自动生成 1 亿条智能电表数据):
taosBenchmark -y


实测耗时: 不足1分钟 (CPU: Intel i7-10700K , 3.8GHz; 内存:24GB; 显卡:12GB, RTX 3060; 磁盘: SSD + 机械)
写入完成后,回 CLI 查询验证性能:
表DDL:
CREATE STABLEmeters(tsTIMESTAMP,currentFLOAT,voltageINT,phaseFLOAT) TAGS (groupidINT,locationVARCHAR(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 上。
- 从 TDengine 产品下载中心下载 Windows 客户端安装包(
tdengine-tsdb-oss的 Windows 版本)。
-
运行安装程序,默认安装目录
C:\TDengine(可自选,若路径不以TDengine结尾会自动追加)。 -
安装前若缺 Microsoft Visual C++ Redistributable 2015-2022 x64,安装程序会自动装内置版本(14.50.35719.0)。
-
以管理员重新打开 cmd,进入安装目录执行
taos.exe连接本地/远端服务端。C:\TDengine\taos.exe -
如需连接远端服务端,编辑配置文件
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
- 用 Docker 快速体验 TDengine : https://docs.taosdata.com/get-started/docker/
- 网络端口要求 - 官方 FAQ : https://docs.taosdata.com/faq/faq/
X 参考文献
本文链接: https://www.cnblogs.com/johnnyzen
关于博文:评论和私信会在第一时间回复,或直接私信我。
版权声明:本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!
日常交流:大数据与软件开发-QQ交流群: 774386015 【入群二维码】参见左下角。您的支持、鼓励是博主技术写作的重要动力!


浙公网安备 33010602011771号