TDengine TDgpt 安装与调用常见问题排查指南:服务可用性、超时与错误码定位
TDengine TDgpt 安装与调用常见问题排查指南:服务可用性、超时与错误码定位
TDgpt(TDengine Analytics Platform)是 TDengine 内置的时间序列数据分析服务,通过 taosanode(Anode)以 HTTP 服务形式对外提供预测、异常检测、插值、相关性分析等高级分析能力。本文基于官方 FAQ 文档,系统梳理 TDgpt 安装、创建 anode、发起分析查询过程中最常见的六类故障——从 uWSGI 编译失败、服务无法访问、查询超时、返回非法 JSON,到日志级别调整与错误码对照,并结合当前仓库中的配置与源码给出可验证的排查路径。读完本文,你将掌握用 curl 探测服务、核对 Gunicorn/Waitress 超时参数、解读 taosanode.app.log 以及按错误码快速定位问题的完整方法。
1. 安装过程中 uWSGI 编译失败,如何处理
1.1 问题背景与规避方案
在 v3.4.1.0 之前的版本,TDgpt 安装包会在本地编译 uWSGI 作为 Web 服务载体。某些 Python 发行版(例如 Anaconda)会与编译流程产生冲突,导致安装流程无法继续。官方给出的规避方案是:在安装过程中忽略 uWSGI 的安装。
但忽略 uWSGI 后,taosanode 服务不会自动启动,需要手动执行以下命令启动应用:
python3.10 /usr/local/taos/taosanode/lib/taosanalytics/app.py
执行时必须使用虚拟环境中的 Python,才能正确加载依赖库。从源码结构看,app.py 是 TDgpt 的 Flask 应用入口,它负责初始化配置(Configure.init)、设置日志(AppLogger)并注册全部分析服务(loader.register_all_services),因此直接用系统 Python 启动很可能因缺少依赖而失败。
1.2 自 v3.4.1.0 起的替代方案
自 v3.4.1.0 起,Linux 环境改用 Gunicorn,Windows 环境改用 Waitress,不再依赖 uWSGI 的本地编译安装,从根上消除了该问题。
-
Linux:通过 Gunicorn 以
-c参数加载配置启动,参见 start.sh:source /usr/local/taos/taosanode/venv/bin/activate cd /usr/local/taos/taosanode/lib/taosanalytics/ /usr/local/taos/taosanode/venv/bin/gunicorn -c /usr/local/taos/taosanode/cfg/taosanode.config.py -
systemd 服务单元 taosanoded.service 中同样通过
ExecStart=/var/lib/taos/taosanode/venv/bin/gunicorn -c /usr/local/taos/taosanode/cfg/taosanode.config.py拉起服务,并设置TDGPT_CONF环境变量指向/etc/taos/taosanode.config.py。
1.3 升级安装后仍报 uWSGI 错误的排查
如果从旧版本升级后仍看到与 uWSGI / uwsgi 相关的报错,说明进程或包装脚本仍指向旧入口。此时应确认 taosanoded 使用的是当前安装目录下的 Gunicorn/Waitress 配置(/etc/taos/taosanode.config.py 或安装目录下的 cfg/taosanode.config.py),然后重启服务。
2. 创建 anode 失败:返回“指定服务无法访问”
在 TDengine 中通过 SQL 注册分析节点(anode)时,若服务未就绪会得到如下错误:
taos> create anode '127.0.0.1:6035';
DB error: Analysis service can't access[0x80000441] (0.117446s)
2.1 用 curl 探测服务是否真正可用
请务必使用 curl 检查 anode 服务是否正常,不要仅依赖 systemctl status taosanoded:
curl '127.0.0.1:6035'
正常的 anode 服务会返回:
TDgpt - TDengine© Time Series Data Analytics Platform (ver x.x.x)
该响应来自 app.py 中 index() 路由直接返回的版本标识 taosanalytics._ANODE_VER,是判断服务是否存活的最直接证据。
如果出现以下输出,则说明 anode 服务不正常:
curl: (7) Failed to connect to 127.0.0.1 port 6035: Connection refused
2.2 服务未运行的日志排查
若 anode 启动或运行不正常,应检查服务日志:
/var/log/taos/taosanode/error.log(Gunicorn 错误日志)/var/log/taos/taosanode/taosanode.app.log(TDgpt 应用日志)
服务可用性应以 curl 探测结果与业务日志为准,systemctl status 只能反映进程是否存活,无法体现应用层是否就绪。
3. 服务正常,查询过程却返回服务不可用
有时 curl 探测服务正常,但执行分析查询仍报错:
taos> select _frowts, forecast(current, 'algo=arima, conf=0.95, wncheck=0, rows=20') from d1 where ts<='2017-07-14 10:40:09.999';
DB error: Analysis service can't access[0x80000441] (60.195613s)
3.1 超时是首要怀疑对象
这类报错最常见的原因是请求超过了默认等待时间。SQL 侧的 timeout 参数可以延长单次请求等待时长,最大值为 1200 秒(即最长约 20 分钟)。
自 v3.4.1.0 起,Gunicorn 的超时相关配置集中在 /etc/taos/taosanode.config.py,相关项与默认值在 taosanode.config.py 中均有体现:
# Timeout settings
timeout = 1200
# keep-alive time
keepalive = 1200
3.2 需要同时核对的三类参数
排障时应同时核对:
- SQL 侧
timeout与 Web 服务侧超时的一致性:SQLtimeout、Gunicorn 的timeout/keepalive(Linux)或 Waitress 的channel_timeout(Windows,默认1200,见 taosanode.config.py 中的waitress_config)任一侧过小,都会表现为“服务不可用”。 bind地址与CREATE ANODE注册的 URL 是否一致:默认bind = "0.0.0.0:6035",创建 anode 时应使用可路由到的实际地址与端口(如127.0.0.1:6035)。- 日志中是否存在 worker 超时、内存不足(OOM)或模型加载失败记录:重点检查
/var/log/taos/taosanode/error.log(Gunicorn)与taosanode.app.log(应用)。
从配置加载实现看,conf.py 在 reload() 中解析 bind 得到 (host, port),模型服务地址则依据 models 配置中的 port + endpoint 自动推导,因此 bind 与模型端口的任何不匹配都可能被上层误报为“服务无法访问”。
4. 返回 Illegal json format 错误
SQL 查询返回“非法 JSON 格式”(Illegal json format)错误,说明 anode 返回给 TDengine 的分析结果中包含了错误信息,即分析链路已经打通,但结果内容异常。
此时应检查 anode 运行日志 /var/log/taos/taosanode/taosanode.app.log,从中找到具体出错的分析算法、模型或数据问题并解决。对应错误码 0x80000444 Analysis invalid buffer type 与 0x80000445 Analysis failed since anode return error 的官方建议同样是“Check the taosanode.app.log for more details”。
5. 调整 TDgpt 日志级别,获取详细错误信息
5.1 修改 log_level 配置
TDgpt 默认日志级别为 DEBUG。可通过修改 /etc/taos/taosanode.config.py 中的 log_level 配置项调整:
# default log level
log_level = 'DEBUG'
该配置项可选值包括:DEBUG、INFO、CRITICAL、ERROR、WARN。
在 conf.py 的 reload() 中,这些字符串被映射为 Python 标准 logging 级别后写入单例配置对象,随后 app.py 通过 AppLogger.set_log_level(conf.get_log_level()) 生效。这意味着修改配置后需重启 taosanode 服务才能生效。
5.2 日志文件说明
对于无法直接通过返回码识别的错误,请检查日志文件获取准确信息。日志文件位于 /var/log/taos/taosanode/ 目录:
| 日志文件 | 说明 |
|---|---|
taosanode.app.log |
TDgpt 应用日志,记录算法调用、模型加载与内部错误 |
access.log / error.log |
Gunicorn Web 服务日志(Windows 上对应 Waitress 相关日志,见 taosanode-service.log 配置) |
日志路径同样由配置驱动:Linux 下默认写入 /var/log/taos/taosanode/,Windows 与 GitHub Actions 环境则写入安装目录下的 log/ 子目录(见 conf.py 的默认配置分支)。
6. TDgpt 返回的错误码对照
TDgpt 的全部错误码定义于 错误码文档(错误码范围为 0x80000440 ~ 0x8000044A):
| 错误码 | 描述 | 可能原因 | 建议处理方式 |
|---|---|---|---|
| 0x80000440 | Analysis service response is NULL | 响应内容为空 | 查看 taosanode.app.log 获取详细响应信息 |
| 0x80000441 | Analysis service can't access | 服务运行异常或网络不通 | 检查 taosanode 状态与网络状况 |
| 0x80000442 | Analysis algorithm is missing | 分析中未指定算法 | 在 forecast 函数或 anomaly_window 子句中添加 "algo" 参数 |
| 0x80000443 | Analysis algorithm not loaded | 指定算法不可用 | 检查指定的算法 |
| 0x80000444 | Analysis invalid buffer type | 缓冲数据类型无效 | 查看 taosanode.app.log 获取更多细节 |
| 0x80000445 | Analysis failed since anode return error | anode 返回了错误消息 | 查看 taosanode.app.log 获取更多细节 |
| 0x80000446 | Analysis failed since too many input rows for anode | 输入数据过多 | 将输入数据行数减少到阈值以下 |
| 0x80000447 | white-noise data not processed | 白噪声数据未被处理 | 忽略白噪声检查或更换输入数据 |
| 0x80000448 | Analysis internal error, not processed | 发生内部错误 | 查看 taosanode.app.log 获取更多细节 |
| 0x80000449 | Analysis failed since not enough rows | 用于预测的输入数据不足 | 增加输入行数(预测至少需要 10 行) |
| 0x8000044A | Not support co-variate/multi-variate forecast | 算法不支持协变量/多变量预测 | 更换指定算法 |
其中 0x80000441 是本文第二、三节反复出现的核心错误码,其排查路径可归纳为“先 curl 探活、再核对超时与绑定参数、最后查日志定位根因”。
附:排查工具箱速查
| 场景 | 命令 / 配置 | 位置 |
|---|---|---|
| 探测 anode 服务 | curl '127.0.0.1:6035' |
任意终端 |
| 查看 Gunicorn 错误 | tail -f /var/log/taos/taosanode/error.log |
Linux |
| 查看 TDgpt 应用日志 | tail -f /var/log/taos/taosanode/taosanode.app.log |
Linux |
| 调整日志级别 | log_level = 'DEBUG' |
/etc/taos/taosanode.config.py |
| 调整超时/保活 | timeout = 1200、keepalive = 1200 |
taosanode.config.py |
| 服务启动入口 | gunicorn -c .../cfg/taosanode.config.py |
start.sh、taosanoded.service |
| 错误码对照 | TDgpt 段 | 错误码文档 |
掌握上述排查思路后,无论是安装阶段的编译冲突、anode 注册失败,还是运行期的查询超时与结果异常,都能按“探活 → 核对配置 → 查日志 → 对照错误码”的流程快速收敛问题。