企业官网建设流程全解析

提起 TDengine，很多人第一印象是性能优秀的时序数据库，真正上手才发现命令行工具 taos 里暗藏着不少门道。我最早被这东西折磨是在一次调整数据保留策略时，明明执行了 ALTER DATABASE，结果怎么改都不生效，后来才意识到自己连 SHOW DATABASES 的输出列都没看清。从那之后，我专门花了几个晚上把 TDengine 的常用命令过了一遍，又结合生产环境的踩坑记录，整理成这篇笔记，希望能帮到正在学 TDengine 或者准备做选型、运维的同行。这篇文章没有高深的理论，就是把那些会让你卡壳的命令、参数和报错掰开揉碎讲清楚。

1. 服务管理：先把 taosd 伺候好

1.1 服务的启动、停止与状态查看

TDengine 的服务器端核心进程叫 taosd，客户端是 taos 命令行工具。在很多基于 systemd 的发行版上，管理 taosd 跟管理别的服务没有区别，但有几个细节值得单独拿出来说。

常用命令其实很简单：

• systemctl start taosd
• systemctl stop taosd
• systemctl restart taosd
• systemctl status taosd --no-pager -l

我先说一个容易踩的坑：执行 taos 客户端时，如果服务没有起来，它不会立刻提示“服务没启动”，而是会尝试重连，然后抛出Unable to resolve FQDN或者connect refused。这种问题经常被误认为是网络故障，其实只要先看一眼 systemctl status 就能定位。

日志默认在 /var/log/taos/ 目录下，文件名一般是 taosdlog.0。启动失败时，排查顺序我建议是：先看日志尾部有没有 ERROR，再 grep 一下Out of memory或failed to create data dir。很多 2.x 老用户后来升级到 3.x 时，还会遇到日志格式完全变化的情况，这时候别慌，3.x 的日志会按天切分，并且多了好多模块名，直接按时间点过滤更高效。

服务启动的用户和目录权限也要留意。如果之前用 root 安装过，数据目录权限没改干净，换成普通用户启动时会报目录不可写。我的习惯是在生产环境用 systemd 管理，并且把数据盘单独挂载，taos.cfg 里的 dataDir 指向独立目录，避免系统盘被时序数据打满。

1.2 命令行客户端 taos 的连接参数与配置文件

taos 客户端默认连接本机的 6030 端口，用户名 root，密码 taosdata。这种默认值在测试环境很爽，但到了生产环境一定要改，否则内网里谁都能连上来操作数据。

常用连接参数我也列一下：

• taos -h hostname -P port -u user -p password：显式指定连接目标和账号。
• taos -c config_dir：指定配置文件目录。
• taos -f script.sql：批量执行 SQL 脚本。
• taos -s "show databases"：直接执行单条语句后退出。

配置文件是 taos.cfg，3.x 版本默认在 /etc/taos/ 下，也可以通过taos -c指定其他路径。很多朋友改完配置发现不生效，大概率是因为没重启 taosd，或者配置项名称写错了。我自己比较常用的配置项有 fqdn、serverPort、dataDir、logDir、tmpDir、charset、timezone。其中 fqdn 最容易被忽视，如果机器 hostname 变了或者 /etc/hosts 没配对，客户端会连不上。设置 fqdn 时尽量用完全限定域名，别用 localhost，因为多节点组集群时 localhost 会出错。

提示：修改 taos.cfg 里的 serverPort 后，客户端连接时也必须显式指定 -P 新端口，否则默认 6030 会连接超时。

1.3 安装、升级与服务注册

虽然安装不是日常命令，但经常有朋友问。在 CentOS 或 Ubuntu 上，TDengine 提供 rpm 和 deb 包，安装命令就是rpm -ivh tdengine-xxx.rpm或dpkg -i tdengine-xxx.deb。装完以后，服务会自动注册成 systemd 单元，不需要手动写守护脚本。

升级时要特别注意：跨大版本升级，比如 2.x 到 3.x，数据文件的格式不兼容，需要先用旧版本导出备份，再安装新版本导入。我见过有人在生产环境直接rpm -Uvh升级，结果启动时数据目录报错，折腾了大半天。所以升级前一定看官方升级文档，别把重启服务当成升级完成的标准。

另外，如果你手动解压 tar.gz 包安装，服务不会自动注册，需要自己写 systemd 文件。我建议直接用包管理器安装，省掉后续一堆麻烦。

2. 数据库和表对象的常用命令

2.1 建库与数据库参数

在 TDengine 里面，数据库是隔离的单位，一个数据库拥有自己的存储策略和副本数。建库时如果不指定任何参数，系统会用默认值，但这在正式环境往往不合适，所以你必须理解几个关键参数的意义。

一条典型的建库语句长这样：

CREATE DATABASE power KEEP 365 DURATION 10 BUFFER 256 WAL_LEVEL 2 REPLICA 1;

• KEEP：数据保留时长，单位是天。默认是 3650 天，生产环境按数据量来算，不能拍脑袋。设太短会丢历史数据，设太长会把磁盘撑爆。
• DURATION：一个数据文件组的时长，默认 10 天。它会影响系统自动合并文件的粒度，DURATION 越小，文件越多，合并越频繁。
• REPLICA：副本数，多副本能保证高可用，但前提是集群里有足够的 vnode 组资源，否则副本会一直处于 unsynced 状态。
• BUFFER 和 WAL_LEVEL：一个是内存缓冲池大小，一个是 WAL 级别。这两个直接决定写入吞吐和宕机恢复能力，千万不要在业务高峰期去调。

修改数据库参数用ALTER DATABASE power KEEP 180;。注意，修改 KEEP 只会影响后续数据文件的保留策略，已经生成的过期文件会在后台异步清理，不会立刻看到效果。如果需要快速释放空间，可以用DROP DATABASE直接删库，但这个操作不可逆，而且会连带删除所有表和超级表，执行前一定确认备份。

列出当前所有数据库用SHOW DATABASES;，切换当前库用USE power;。查看一个库的具体属性可以执行：

SHOW CREATE DATABASE power\G

这里的\G会以纵向格式显示，列很多时比普通表格清晰得多。我经常用这个命令把建库参数复制出来，用于在另一套环境重建一模一样的库。

2.2 创建普通表和超级表

普通表就是单张时间序列表，适合设备数量固定且很少变动的场景。超级表则是一类表的模板，用于管理大量同构的设备，每个设备一张子表，子表继承超级表的列结构，同时拥有不同的标签值。

创建一张普通表：

CREATE TABLE sensor (ts TIMESTAMP, temperature FLOAT, humidity FLOAT);

创建超级表：

CREATE STABLE sensor_stable (ts TIMESTAMP, temperature FLOAT, humidity FLOAT) TAGS (location BINARY(64), device_id INT);

然后为每个设备创建子表：

CREATE TABLE sensor_t1 USING sensor_stable TAGS ('beijing', 1);

这里最核心的是标签（TAGS）。标签是静态属性，不随时间变化，所以它不会像普通列那样占用存储，而是作为索引来加速查询。设计标签时，尽量把设备 ID、地域、型号这类属性放进去，别把实时变化的数据放标签里，否则每次更新标签会在后台引发额外同步。

查看表结构用：

DESCRIBE sensor_t1;

它会列出普通列和标签列，并用 TAG 字段标识标签。SHOW TABLES和SHOW STABLES分别查看当前库里的普通表和超级表，注意 SHOW TABLES 默认只显示普通表，如果你拿超级表当普通表查，可能什么也看不到。

2.3 表结构的变更与清理

普通过程中经常会遇到需要加列的情况：

ALTER TABLE sensor ADD COLUMN battery INT;

这个命令在 3.x 里很常用，而且执行速度很快，不会阻塞写入。如果超级表要增加标签列，可以用ALTER TABLE sensor_stable ADD TAG city BINARY(32);，然后新加的子表就能带上这个标签，旧子表的标签值需要自己更新。

修改标签值用：

ALTER TABLE sensor_t1 SET TAG location='shanghai';

删除表用DROP TABLE IF EXISTS sensor;，删除超级表用DROP STABLE IF EXISTS sensor_stable;。如果表里有数据，删除后数据文件也是异步释放的，别指望马上看到磁盘空间回来，这在 TDengine 里是正常现象。

如果只想清空一张表的数据，可以用：

TRUNCATE TABLE sensor;

这个命令在 3.2 之后变得比较好用，之前老版本没有，只能 DROP 再重建。使用时要注意它只能清当前表，不会影响超级表下的其他子表。

3. 写入、查询与时间窗口操作

3.1 INSERT 语法与参数绑定的坑

插入数据的标准写法：

INSERT INTO sensor_t1 VALUES (now, 23.5, 60.2);

一次写多条：

INSERT INTO sensor_t1 VALUES (now, 23.5, 60.2) (now + 1s, 24.0, 59.8);

这里有个常见理解误区：now 解析的是执行 taos 命令所在机器的当前时间，而且时间精度受数据库的 precision 参数影响。比如数据库精度是毫秒，那么 now + 1s 会精确到秒级别。

如果你用 JDBC 或 JNI 做参数绑定，时间戳一般用 long 类型。给初学者一个建议：先确认数据库的 precision（us/ms/ns），再决定时间戳的转换单位，否则容易出现“阴阳时间”或者乱序数据。乱序数据过多会触发落盘时的合并逻辑，影响查询性能。

taos 命令行能不能从文件导入？直接 import 不行。真正的导入导出要用独立工具 taosdump，后面我会单独讲。日常开发需要批量灌数据时，我一般写一个循环脚本，用taos -s一条一条执行，数据量不大还凑合，数据量大就得走原生写入接口了。

3.2 查询、聚合与过滤

最基础的查询是：

SELECT * FROM sensor_t1 WHERE ts >= '2024-01-01 00:00:00' AND ts < '2024-01-02 00:00:00' LIMIT 100;

TDengine 对时间范围查询做了优化，但如果你不给时间过滤条件，像SELECT * FROM 大表这种操作，它会很痛苦地全表扫描。时序数据的查询原则永远是“先限时间，再聚合”，这不仅能减少网络传输，还能避免扫描过多无效数据。

聚合函数方面，常用的 COUNT、SUM、AVG、MIN、MAX 都支持，但要注意函数处理 NULL 的策略。TDengine 里的 FLOAT 和 DOUBLE 列可能出现 NULL，默认情况下大多数聚合函数会跳过 NULL。如果你希望显式处理 NULL，可以用 CASE WHEN 或相关函数。

更典型的时序查询是降采样：

SELECT _wstart, AVG(temperature) FROM sensor_stable INTERVAL(10m) WHERE ts > now - 1d GROUP BY location;

这里_wstart是窗口起始时间，GROUP BY location是对标签列分组。INTERVAL 是时间窗口，默认是左闭右开，计算时会自动对齐到自然时间边界。如果希望滑动窗口，可以用：

SELECT _wstart, AVG(temperature) FROM sensor_stable INTERVAL(1h) SLIDING(30m) WHERE ts > now - 1d;

SLIDING 设置了滑动步长，每次往前挪 30 分钟。注意 SLIDING 必须小于或等于 INTERVAL，否则会报错。

很多人问我 INTERVAL 和普通GROUP BY time有什么区别。TDengine 的 INTERVAL 是专门针对时序的窗口函数，它不仅会把数据按时间段划开，还会在内部维护一张虚拟时间轴，所以即使某个窗口内没有数据，它也能结合 FILL 生成填充行。我常用的填充方式包括FILL(PREV)和FILL(NULL)，前者用上一个值填充，适合传感器短时断链的场景。

3.3 标签过滤与超级表聚合

在超级表上查询时，可以通过标签条件来筛选设备：

SELECT AVG(temperature), COUNT(*) FROM sensor_stable WHERE location='beijing' AND ts >= now - 24h;

这个语句会在后台自动定位location='beijing' 的那些子表，然后并行扫描。所以标签条件的写法直接影响查询性能。在子表数量很大的场景下，建议把查询频率最高的标签放在前面，同时避免在标签上使用函数，比如LOWER(location)='beijing'，否则会失去索引优化能力。

如果要按设备维度输出每个设备的平均值：

SELECT device_id, AVG(temperature) FROM sensor_stable WHERE ts >= now - 1d PARTITION BY device_id;

PARTITION BY 会按某个字段或标签分片聚合，效果等于多个 GROUP BY 的并行版本，在 TDengine 3.3 以后还能配合窗口使用，性能很稳。我实际测试过，设备数量达到几万张子表时，用 PARTITION BY 比 GROUP BY 明显快。

3.4 插值与填充

时序数据经常有缺失，TDengine 提供了 INTERPOLATE 语句做插值。比如每 5 分钟采集一次，但中间一分钟数据没上来，可以这样补全：

SELECT _wstart, INTERPOLATE(temperature) FROM sensor_stable WHERE ts >= now - 1h INTERVAL(5m) FILL(PREV);

这个写法要注意：INTERPOLATE 是逐点线性插值，而 FILL 是窗口内的值填充，两者不能混用。如果只需要简单填充，用FILL(LAST/PREV/NULL)就够；如果要做精细插值，可以考虑在应用层算好后写入，毕竟 TDengine 的插值函数目前只支持数值列，字符串标签不能插值。

我记得刚用 3.0 的时候，把 INTERPOLATE 放在了 WHERE 前面，结果语法报错，后来查文档才知道它要放在 INTERVAL 和 FILL 之后。这种语法顺序问题没有捷径，多写几次就记住了。另外，插值的时间分辨率要和 INTERVAL 对齐，否则可能出现插值点比真实数据点还密的奇怪结果。

4. 用户权限与系统管理命令

4.1 创建用户和权限分配

TDengine 默认只有 root 用户，生产环境不能把所有账号都给别人。创建用户：

CREATE USER user1 PASS 'password';

查看用户：

SHOW USERS;

修改密码：

ALTER USER user1 SET PASS 'newpassword';

授权用 GRANT：

GRANT READ ON db1 TO user1; GRANT WRITE ON db1 TO user1; GRANT ALL ON db1.* TO user1;

撤销权限用 REVOKE：

REVOKE WRITE ON db1 FROM user1;

系统权限除了数据库级别，还有全局权限，像GRANT ALL ON *.* TO user1要特别小心。TDengine 的权限体系相比 MySQL 简化了很多，目前只有全局、库、表三级粒度，表级细粒度权限在 3.3 里仍然有限。我的经验是，尽量按“每个业务一个库”的方式来隔离，比单库多表隔离更省心，权限也好管理。

4.2 查看节点与集群状态

多节点集群管理离不开几个 SHOW 命令：

• SHOW DNODES;：查看数据节点。
• SHOW MNODES;：查看管理节点。
• SHOW CNODES;：查看计算节点（如果启用了原生计算节点）。
• SHOW VNODES;：查看虚拟节点，能真实看到数据分片分布。
• SHOW CLUSTER;：查看集群整体信息。

在排查节点离线问题时，我会先SHOW DNODES看 status 是 ready 还是 offline，然后用SHOW VNODES看看哪些 vnode 还处于 unsynced。集群环境里最怕脑裂，而 vnode 的状态能直观反映数据副本同步情况。

我还要强调一下，TDengine 的集群命令和单机命令没有太大区别，你在一台节点上执行 SHOW DNODES 看到的其实是管理节点上维护的全局视图。所以当某台数据节点连不上时，不要在客户端反复重连，直接登录该节点看一下 taosd 进程和日志，这是排查网络分区最快的方法。

4.3 查询系统库和性能视图

TDengine 3.x 在库里隐藏了一个系统库 information_schema，可以通过它来查看表结构、视图、集群配置等。我常用的两个查询：

SELECT * FROM information_schema.ins_tables; SELECT * FROM information_schema.ins_stables; SELECT * FROM information_schema.ins_databases;

这些视图返回的信息比 SHOW 系列更结构化，适合写到监控脚本里。比如我想知道某张超级表下有多少张子表，直接查 insc_stables 比用 SHOW TABLES 然后数行数要快得多。

另外，TDengine 自带一个 performance_schema 系统库，里面有一些性能相关的表，但不同版本差异很大，建议先SHOW DATABASES看看有没有。如果要做完整的性能监控，更推荐用 taosAdapter 对接 prometheus，这些属于运维体系建设的范畴，这里先不展开。

5. 高频报错与避坑速查

5.1 error (0x83a): query denied by license: external query is restricted

这个报错最近在社区里被问得很多。它的字面意思是“查询被 license 拒绝：外部查询被限制”。翻译成人话就是：当前环境的许可证授权不包含这样的外部查询能力。通常在两种场景下出现：

• 使用了一些需要额外授权的功能，比如跨集群查询、新建 UDF（用户自定义函数）、外部数据源查询。
• 社区版或者试用版 license 对某些高级特性做了限制。

解决办法很直接：先用SHOW LICENSE查看当前授权范围和到期时间，确认功能是否在授权列表里。如果业务确实需要该能力，联系官方申请或购买对应授权；如果只是误用，比如在 3.0 里调用了 taosAdapter 的某些外部接口，可以检查一下查询语法，避免触发授权限制的接口。

我遇到过一个很容易误判的情况：明明是普通查询，却报 0x83a。后来发现是因为我在一个带 UDF 的查询里用了非白名单函数，导致外部函数执行被拒。把这个函数换成内置函数后，问题消失。所以看到这个错误码，先别急着怀疑 license，先看看 SQL 里有没有自定义函数或非标函数。

5.2 HoltWinters 算法 double 类型报错

有一个热搜词叫“使用 tdengine holtwinters 怎么 double 报错”，这其实涉及 TDengine 内置的时序预测函数 HOLTWINTERS。这个函数返回 forecast 和 confidence interval，输出类型设计上比较特殊，如果直接把它作为普通 DOUBLE 字段去比较或计算，很容易报类型不匹配错误。

实际使用中，建议把预测结果包裹一层子查询。比如：

SELECT _ts, CAST(forecast_val AS DOUBLE) FROM ( SELECT _wstart AS _ts, HOLTWINTERS(val) AS forecast_val FROM metrics WHERE ts >= now - 7d INTERVAL(1d) FORECAST(7d) );

在 3.x 中，HOLTWINTERS 的输出是一个复合结构，需要配合窗口和 FORECAST 参数使用。如果只是想要一个 DOUBLE 数值，最安全的办法就是放进子查询后再取值。

我自己的体会是，这类函数的报错绝大多数不是函数本身的问题，而是调用姿势不对。比如数据库时间精度不一致导致返回空值，空值再去强转 double 就崩了。解决思路是尽量保持数据库精度与查询参数一致，比如数据库用毫秒，查询 INTERVAL 也用毫秒级别的表达方式。

5.3 连接失败与 DBeaver/JDBC 驱动问题

DBeaver 连 TDengine 也是很多人关心的话题。新版 TDengine 的 JDBC 驱动和 2.x 版本完全不同，连接 DBeaver 时要用官方的 JDBC 驱动 jar 包，而 DBeaver 的默认驱动库里不一定内置，所以会看到Can't create driver instance之类的错误。解决方法是手动下载对应版本的 taos-jdbcdriver 并添加为 DBeaver 驱动。

连接 URL 示例：

jdbc:TAOS-RS://host:6041/db?user=root&password=taosdata

注意 TAOS-RS 走的是 taosAdapter 的 REST 服务，端口默认 6041，而jdbc:TAOS://走的是原生连接，端口 6030。DBeaver 里更容易成功的是 TAOS-RS，因为原生驱动依赖本地客户端库，环境变量配置不到位容易失败。

排查连接问题时，先用命令行工具试一下taos -h host -P 6030能否连上。如果能连上，说明服务本身没问题，再去查驱动和端口。我见过很多人服务好好的，就是 DBeaver 选错驱动类型，导致连不上。

5.4 其他常见错误速查表

我把自己工作中常碰到的几个报错整理成一张表，方便你后面当速查手册用。

这张表其实是我整理问题时的习惯，你可以拿它做模板，把公司里遇到的错误码都沉进去，省得下次再搜一次。

6. 备份、脚本与监控这些“非命令”的细节

6.1 用 taosdump 备份和恢复数据

数据备份是运维中最容易被忽视的环节。taosdump 是 TDengine 的专用备份工具，在 3.0 之后通常需要单独安装。我的建议是先确认工具版本，然后看帮助信息：

taosdump --help

常用参数有这些：

• -h：服务器地址，默认 localhost。
• -P：端口，默认 6030。
• -u：用户名，默认 root。
• -p：密码，默认 taosdata。
• -o：输出目录，比如-o /backup/2024/。
• -d：指定数据库，多个库用逗号分隔。
• -S：备份开始时间，格式2024-01-01 00:00:00。
• -E：备份结束时间。

恢复数据用taosdump -i /backup/2024/ -d dbname把数据导入目标服务器。

备份这个动作看着简单，但真实生产环境里经常因为数据量太大把磁盘写满。我建议你先估算一下备份体积：TDengine 的压缩比和数据类型强相关，时序数值列通常能压缩到原体积的 30%~50%，但仍然要留足临时空间。另外，备份文件不要直接写到系统盘，最好挂载独立备份盘，并且加上定期清理策略。

6.2 让命令行脚本化：taos -f

如果我们每天要执行同样的一批查询，不可能每次都手敲。最简单的办法是把 SQL 写进一个文件，然后用taos -f query.sql批量执行。这个命令会逐条执行文件里的语句，某一条失败时会打印错误，但不会影响后续语句继续执行，所以写脚本时要在每个关键步骤之间检查输出，不能假设全对。

另外，结果输出格式可以调整。在 taos 客户端里执行：

SET max_binary_display_width = 256; SET timezone = 'UTC'; SET output_format = 'table';

这些会话级变量对脚本化输出很有用。特别是时间显示，默认时区和数据库时区不一致时，查询结果会让人摸不着头脑。我的习惯是无论客户端在哪个时区，都先看一眼SELECT timezone()，确保时间戳解读正确。

6.3 集成到监控与告警体系

如果只是用 taos CLI 做日常管理，那还远没有发挥 TDengine 的价值。生产环境里我通常会通过 taosAdapter 把数据指标暴露给 Prometheus，再由 Grafana 做可视化。TDengine 提供了一整套 RESTful 接口，端口 6041，可以很容易地从自定义程序里调用 SQL，也可以直接写入。

在监控场景中，常用命令就不再是 INSERT SELECT 了，更多是检查连接数、查询延迟和磁盘使用率。我偶尔会在凌晨写个脚本，把SHOW DNODES和SHOW VNODES的状态采集到监控平台，一旦出现 offline 或 vnode 未同步就告警。这个思路适合大多数中大型集群，比单纯依赖默认工具更可控。

7. 最后分享两个小技巧

7.1 调试时多用 \G 纵向显示

SHOW DATABASES\G和DESCRIBE table\G是我检查字段最常用的方式。列很多时，普通表格会折行，根本没法看。\G是 MySQL 风格，TDengine 客户端也支持。比如：

SHOW CREATE DATABASE power\G

输出一目了然，还能直接复制 SQL 去重建库。这个小技巧我几乎每天都会用到，尤其是在确认建库参数和表结构时，比默认输出省眼神。

7.2 批量删除旧数据别用 DELETE，用 KEEP 策略

有些新手会用DELETE FROM sensor WHERE ts < '2023-01-01'，在 TDengine 3.x 里虽然支持 DELETE，但它不是为高频删除设计的。真正推荐的方式是设置合理的 KEEP，让过期数据自动被系统清理。如果你只是要快速清除一张子表的数据，TRUNCATE 比 DELETE 更快。

按照自己的习惯，我一般把“自动过期删除”作为默认选项，KEEP 在业务允许范围内尽量短，这样既省空间又不影响查询效率。这几条命令看起来不起眼，但真正在生产环境里处理过数据膨胀的人，一定会理解自动清理比手动 DELETE 省心太多了。