TDengine Docker 初学者完整指南
什么是 TDengine？
TDengine 是一款专为物联网、工业互联网等场景设计的高性能时序数据库（Time-Series Database, TSDB）。它能够高效地处理海量时序数据的写入、存储和查询，广泛应用于智能制造、能源监控、车联网等领域。
核心特点：
- 超高性能：写入速度可达百万级/秒
- 高压缩比：存储成本降低至传统数据库的 1/10
- SQL 支持：学习成本低，易于上手
- 内置缓存：查询速度极快
前置准备
1. 安装 Docker
在开始之前，请确保您的系统已安装 Docker。
检查 Docker 是否已安装：
bash
docker --version如果看到类似 Docker version 24.0.0 的输出，说明 Docker 已安装成功。
如果未安装 Docker，请访问：
- macOS/Windows: Docker Desktop
- Linux: Docker Engine
2. 系统要求
- 至少 2GB 可用内存
- 至少 10GB 可用磁盘空间
- 稳定的网络连接（用于拉取镜像）
3. 端口说明
TDengine 默认使用以下端口，请确保这些端口未被占用：
6030: TDengine 服务端口（客户端连接）6041: RESTful 接口端口6043: taosAdapter 服务端口6044-6049: 集群通信端口6050: Web 管理界面（Enterprise 版本）6055: Explorer Web 界面6060: 监控指标端口
检查端口占用（可选）：
bash
# macOS/Linux
lsof -i :6030
# 如果有输出，说明端口被占用快速启动（三步上手）
第一步：拉取 TDengine 镜像
我们使用企业版（TDengine TSDB-Enterprise）以体验完整功能。
bash
docker pull tdengine/tsdb-ee:latest说明：
tdengine/tsdb-ee：企业版镜像名称latest：最新稳定版本- 下载大小约 200-300MB，请耐心等待
如果下载速度慢，可使用国内镜像（可选）：
前往 TDengine 下载中心 获取离线镜像。
验证镜像是否下载成功：
bash
docker images | grep tdengine应该看到类似输出：
tdengine/tsdb-ee latest abc123def456 2 days ago 256MB第二步：启动 TDengine 容器
bash
docker run -d \
-v ~/data/taos/dnode/data:/var/lib/taos \
-v ~/data/taos/dnode/log:/var/log/taos \
-p 6030:6030 -p 6041:6041 -p 6043:6043 -p 6060:6060 \
-p 6044-6049:6044-6049 \
-p 6044-6045:6044-6045/udp \
-p 6050:6050 -p 6055:6055 \
--name tdengine-tsdb \
tdengine/tsdb-ee命令详解：
-d：后台运行容器-v ~/data/taos/dnode/data:/var/lib/taos：挂载数据目录（数据持久化）-v ~/data/taos/dnode/log:/var/log/taos：挂载日志目录-p 6030:6030：端口映射（主机端口:容器端口）--name tdengine-tsdb：容器名称tdengine/tsdb-ee：使用的镜像
重要说明：
- 数据目录会自动创建在
~/data/taos/下 - 即使容器删除，数据也会保留在主机上
第三步：验证启动状态
bash
docker ps -f name=tdengine-tsdb正常输出示例：
CONTAINER ID IMAGE STATUS PORTS NAMES
abc123def456 tdengine/tsdb-ee Up 30 seconds (healthy) 0.0.0.0:6030->6030/tcp tdengine-tsdb关键检查点：
STATUS列显示Up ... (healthy)表示启动成功- 如果显示
starting或unhealthy，请等待 30 秒后再次检查
如果启动失败，查看日志：
bash
docker logs tdengine-tsdb第一次体验 TDengine
方式一：命令行体验（推荐初学者）
1. 进入容器
bash
docker exec -it tdengine-tsdb bash你会看到提示符变成：root@abc123def456:/#
2. 启动 TDengine 命令行客户端
bash
taos成功输出示例：
Welcome to the TDengine Command Line Interface, Client Version 3.x.x.x
Copyright (c) 2022 by TDengine, all rights reserved.
Server is Community Edition.
taos>现在你已经进入 TDengine 的 SQL 交互环境！
3. 创建数据库
sql
CREATE DATABASE demo;输出：
Query OK, 0 of 0 rows affected (0.123456s)4. 使用数据库
sql
USE demo;5. 创建超级表（Super Table）
TDengine 的核心概念：超级表是一类数据的模板，包含多个子表。
sql
CREATE STABLE meters (
ts TIMESTAMP, -- 时间戳（主键）
current FLOAT, -- 电流
voltage INT, -- 电压
phase FLOAT -- 相位
) TAGS (
location BINARY(64), -- 标签：位置
groupId INT -- 标签：分组ID
);说明：
STABLE：超级表关键字ts TIMESTAMP：时序数据必须有时间戳字段TAGS：标签用于分类和过滤数据
6. 创建子表并插入数据
sql
-- 创建子表 d1001（代表北京某电表）
CREATE TABLE d1001 USING meters TAGS ('Beijing.Chaoyang', 1);
-- 插入数据
INSERT INTO d1001 VALUES
(NOW, 10.2, 219, 0.32),
(NOW + 1s, 10.3, 218, 0.31),
(NOW + 2s, 10.4, 220, 0.33);
-- 创建另一个子表 d1002（代表上海某电表）
CREATE TABLE d1002 USING meters TAGS ('Shanghai.Pudong', 2);
INSERT INTO d1002 VALUES
(NOW, 12.5, 221, 0.35),
(NOW + 1s, 12.6, 222, 0.36),
(NOW + 2s, 12.7, 220, 0.34);7. 查询数据
查询所有数据：
sql
SELECT * FROM meters;按时间范围查询：
sql
SELECT * FROM meters WHERE ts > NOW - 1h;聚合查询：
sql
-- 查询每个位置的平均电流
SELECT location, AVG(current) FROM meters GROUP BY location;降采样查询（时间窗口）：
sql
-- 每10秒统计一次平均值
SELECT _wstart, AVG(current), AVG(voltage)
FROM meters
INTERVAL(10s);8. 查看数据库信息
sql
-- 查看所有数据库
SHOW DATABASES;
-- 查看所有超级表
SHOW STABLES;
-- 查看所有子表
SHOW TABLES;
-- 查看表结构
DESCRIBE meters;9. 退出命令行
sql
quit;然后退出容器：
bash
exit方式二：使用 RESTful API
TDengine 提供了 HTTP 接口，无需进入容器即可操作。
1. 执行 SQL 查询
bash
curl -u root:taosdata -d "SELECT * FROM demo.meters" \
http://localhost:6041/rest/sql参数说明：
-u root:taosdata：默认用户名和密码-d：SQL 语句http://localhost:6041/rest/sql：REST 接口地址
2. 插入数据
bash
curl -u root:taosdata -d "INSERT INTO demo.d1001 VALUES (NOW, 11.5, 220, 0.34)" \
http://localhost:6041/rest/sql方式三：使用 Web 管理界面
1. 访问 TDengine Explorer
打开浏览器，访问：
http://localhost:60552. 登录
- 用户名 ：
root - 密码 ：
taosdata
3. 功能体验
- 数据查询：在 SQL 编辑器中输入查询语句
- 数据可视化：查看数据图表
- 监控面板：查看系统状态和性能指标
- 数据库管理：创建/删除数据库和表
进阶体验：实际场景模拟
场景：物联网传感器数据采集
模拟 100 个温度传感器，每秒采集一次数据。
1. 创建数据库和表结构
sql
CREATE DATABASE iot_sensors;
USE iot_sensors;
CREATE STABLE temperature_data (
ts TIMESTAMP,
temperature FLOAT,
humidity FLOAT
) TAGS (
sensor_id INT,
location BINARY(64),
device_type BINARY(32)
);2. 批量创建子表
sql
-- 创建 10 个传感器表（实际可创建更多）
CREATE TABLE sensor_001 USING temperature_data TAGS (1, 'Room-101', 'DHT22');
CREATE TABLE sensor_002 USING temperature_data TAGS (2, 'Room-102', 'DHT22');
CREATE TABLE sensor_003 USING temperature_data TAGS (3, 'Room-103', 'DHT22');
-- ... 可继续创建3. 模拟数据写入
sql
-- 批量插入数据（高性能写入）
INSERT INTO sensor_001 VALUES
(NOW, 22.5, 55.2),
(NOW - 1s, 22.4, 55.1),
(NOW - 2s, 22.6, 55.3);
INSERT INTO sensor_002 VALUES
(NOW, 23.1, 58.7),
(NOW - 1s, 23.0, 58.5),
(NOW - 2s, 23.2, 58.9);4. 实用查询示例
最新数据查询：
sql
SELECT LAST(*) FROM temperature_data GROUP BY tbname;异常检测：
sql
SELECT * FROM temperature_data
WHERE temperature > 30 OR humidity > 80;统计分析：
sql
-- 每小时平均温度
SELECT _wstart, location, AVG(temperature)
FROM temperature_data
WHERE ts > NOW - 1d
INTERVAL(1h)
GROUP BY location;与 Grafana 集成（数据可视化）
1. 启动 Grafana 容器
bash
docker run -d \
-p 3000:3000 \
--name grafana \
--link tdengine-tsdb:tdengine \
grafana/grafana2. 访问 Grafana
打开浏览器：http://localhost:3000
- 默认用户名：
admin - 默认密码：
admin（首次登录需修改）
3. 添加 TDengine 数据源
- 点击 Configuration → Data Sources
- 点击 Add data source
- 搜索并选择 TDengine（需安装插件）
- 配置连接：
- URL :
http://tdengine:6041 - User :
root - Password :
taosdata
- URL :
- 点击 Save & Test
4. 创建仪表板
-
创建新的 Dashboard
-
添加 Panel
-
编写 SQL 查询：
sqlSELECT ts, temperature FROM demo.d1001 -
选择可视化类型（折线图、柱状图等）
常见问题与解决方案
问题 1：容器启动失败
排查步骤：
-
查看日志：
bashdocker logs tdengine-tsdb -
检查端口占用：
bashlsof -i :6030 -
检查磁盘空间：
bashdf -h
问题 2：无法连接到 TDengine
解决方案：
-
确认容器状态为
healthy：bashdocker ps -f name=tdengine-tsdb -
检查防火墙设置
-
验证端口映射：
bashdocker port tdengine-tsdb
问题 3：数据丢失
说明：
数据存储在 ~/data/taos/ 目录下，只要该目录存在，数据就不会丢失。
问题 4：权限错误
解决方案：
确保挂载目录有足够权限：
bash
chmod -R 755 ~/data/taos/问题 5：忘记密码
重置 root 密码：
bash
docker exec -it tdengine-tsdb taos -s "ALTER USER root PASS 'new_password';"容器管理命令
启动/停止/重启
bash
# 停止容器
docker stop tdengine-tsdb
# 启动容器
docker start tdengine-tsdb
# 重启容器
docker restart tdengine-tsdb查看日志
bash
# 实时查看日志
docker logs -f tdengine-tsdb
# 查看最后 100 行日志
docker logs --tail 100 tdengine-tsdb监控资源使用
bash
# 查看容器资源占用
docker stats tdengine-tsdb备份数据
bash
# 备份数据目录
tar -czf tdengine-backup-$(date +%Y%m%d).tar.gz ~/data/taos/清理环境
bash
# 停止并删除容器
docker stop tdengine-tsdb
docker rm tdengine-tsdb
# 删除镜像（可选）
docker rmi tdengine/tsdb-ee
# 删除数据（谨慎操作！）
rm -rf ~/data/taos/性能测试体验
TDengine 内置了性能测试工具 taosBenchmark。
写入性能测试
bash
docker exec -it tdengine-tsdb taosBenchmark \
-t 10 \
-n 10000 \
-y参数说明：
-t 10：创建 10 个表-n 10000：每个表插入 10000 条数据-y：自动确认
查看测试结果
测试完成后，会显示：
- 总写入记录数
- 写入速度（records/s）
- 平均延迟
学习路径建议
入门阶段（1-2 周）
- ✅ 完成本文档的所有实践操作
- 📖 阅读官方文档：TDengine 快速入门
- 💻 练习基本 SQL 操作
进阶阶段（2-4 周）
- 📚 学习 TDengine 数据建模
- 🔧 尝试使用不同编程语言的连接器（Python、Java、Go）
- 📊 集成到实际项目中
高级阶段（1-2 月）
- 🏗️ 学习集群部署和高可用配置
- ⚡ 性能调优和最佳实践
- 🔒 安全配置和权限管理
学习资源
官方资源
- 官方文档：https://docs.taosdata.com/
- GitHub 仓库：https://github.com/taosdata/TDengine
- 社区论坛：https://github.com/taosdata/TDengine/discussions
视频教程
- 哔哩哔哩搜索：TDengine 教程
- YouTube: TDengine Tutorials
示例代码
- Python: https://github.com/taosdata/taos-connector-python
- Java: https://github.com/taosdata/taos-connector-jdbc
- Go: https://github.com/taosdata/driver-go
实战案例
- 官方示例：
/examples/目录 - 社区案例分享
下一步建议
恭喜你完成了 TDengine 的入门体验！以下是建议的下一步行动：
-
尝试编写程序连接 TDengine
- 使用你熟悉的编程语言（Python/Java/Go）
- 实现数据写入和查询
-
模拟真实场景
- 根据你的业务场景设计数据模型
- 测试高频写入和复杂查询
-
学习高级特性
- 流式计算
- 数据订阅
- 用户自定义函数（UDF）
-
参与社区
- 在 GitHub 提问题或参与讨论
- 分享你的使用经验
附录
A. Docker Compose 配置（推荐生产环境）
创建 docker-compose.yml：
yaml
version: "3"
services:
tdengine:
image: tdengine/tsdb-ee:latest
container_name: tdengine-tsdb
ports:
- "6030:6030"
- "6041:6041"
- "6043:6043"
- "6044-6049:6044-6049"
- "6044-6045:6044-6045/udp"
- "6050:6050"
- "6055:6055"
- "6060:6060"
volumes:
- ./data:/var/lib/taos
- ./log:/var/log/taos
environment:
- TZ=Asia/Shanghai
restart: unless-stopped启动：
bash
docker-compose up -dB. 常用 SQL 速查表
sql
-- 数据库操作
CREATE DATABASE db_name;
DROP DATABASE db_name;
SHOW DATABASES;
USE db_name;
-- 表操作
CREATE STABLE st_name (...) TAGS (...);
CREATE TABLE tb_name USING st_name TAGS (...);
DROP TABLE tb_name;
SHOW STABLES;
SHOW TABLES;
DESCRIBE tb_name;
-- 数据操作
INSERT INTO tb_name VALUES (...);
SELECT * FROM tb_name;
DELETE FROM tb_name WHERE ...;
-- 时间函数
NOW() -- 当前时间
TODAY() -- 今天零点
_wstart, _wend -- 窗口起止时间
-- 聚合函数
COUNT(), AVG(), SUM(), MIN(), MAX()
FIRST(), LAST()
STDDEV(), LEASTSQUARES()C. 性能优化建议
-
数据建模
- 合理设计超级表和标签
- 避免过多标签（建议 ≤ 8 个）
-
批量写入
- 使用
INSERT INTO ... VALUES (...), (...);批量插入 - 建议每批 1000-10000 条
- 使用
-
查询优化
- 善用标签过滤
- 使用时间范围限制
- 避免
SELECT *
-
缓存利用
- 查询最新数据自动使用缓存
总结
通过本指南，你已经：
- ✅ 成功安装并启动 TDengine
- ✅ 掌握基本的增删改查操作
- ✅ 了解 TDengine 的核心概念
- ✅ 体验了数据可视化和性能测试
TDengine 的强大之处在于它的简单易用和高性能。继续探索，你会发现更多强大的功能！
有问题？
祝你学习愉快！ 🚀
关于 TDengine
TDengine 专为物联网IoT平台、工业大数据平台设计。其中，TDengine TSDB 是一款高性能、分布式的时序数据库（Time Series Database），同时它还带有内建的缓存、流式计算、数据订阅等系统功能；TDengine IDMP 是一款AI原生工业数据管理平台，它通过树状层次结构建立数据目录，对数据进行标准化、情景化，并通过 AI 提供实时分析、可视化、事件管理与报警等功能。