TDengine TDgpt 常见问题排查指南:安装、部署与调用全流程排障

原创2026-09-21 16:28:461,718 阅读
文章标签:数据库时序数据库大数据实时分析物联网云原生机器学习

TDengine TDgpt 常见问题排查指南:安装、部署与调用全流程排障

TDgpt(Time Series Data Analytics Platform)是 TDengine 内置的时间序列数据分析引擎,通过 taosanode(Anode)服务为 forecast、anomaly-detect、imputation 等分析函数提供算法能力。本文以 TDgpt 官方 FAQ 为骨架,结合 taosanode 配置文件、配置解析实现、服务管理脚本 与 TDgpt 错误码表 等仓库源码,系统梳理从安装、启动到 SQL 调用过程中最常见的六类故障及其处理办法。读完本文,你将掌握 uWSGI/Gunicorn 环境差异的处理、anode 健康探测与注册排障、超时参数对齐、日志级别调整以及 TDgpt 错误码语义解读等完整实战能力。

前置认知:taosanode 的运行架构

在展开 FAQ 之前,先明确 TDgpt 的调用链路,这决定了排障时“该看哪一层”:

  1. TDengine 集群通过 CREATE ANODE 'ip:port' 将 taosanode 注册为分析节点;
  2. SQL 中的分析函数(如 forecast、anomaly_detect)由引擎转发给 anode;
  3. anode 本质是一个基于 Flask 的 REST 服务(入口见 app.py),由 Gunicorn(Linux)/ Waitress(Windows)托管;
  4. 算法侧按需加载 ARIMA、HoltWinters、TimeMoE、TDtsfm 等模型,模型服务可独立启停。

因此排查问题时应先确认“服务是否活着”“注册地址是否可达”“请求是否超时”“返回内容是否合法”四个层面,下面六个 FAQ 恰好覆盖了这四个层面。

1. 安装过程中编译 uWSGI 失败,如何处理

问题背景

v3.4.1.0 之前的 TDgpt 安装包在本地编译 uWSGI 时,某些 Python 环境(例如 Anaconda)会因与系统 Python 环境冲突导致编译失败,进而中断整个安装流程。可尝试在安装过程中忽略 uWSGI 的安装。

忽略 uWSGI 后的手动启动方式

由于忽略了 uWSGI 安装,后续启动 taosanode 服务时需要手动执行:

python3.10 /usr/local/taos/taosanode/lib/taosanalytics/app.py

执行该命令时必须使用虚拟环境中的 Python,才能正确加载依赖库。这与配置文件中 virtualenv 的定位一致——taosanode.config.py 中通过 virtualenv = base_dir + "venvs/venv" 指定独立虚拟环境,且 pythonpath 指向 lib/taosanalytics,wsgi_app = "app:app" 指明 Flask 应用入口。

自 v3.4.1.0 起的变更

自 v3.4.1.0 起,Linux 环境改用 Gunicorn(Windows 使用 Waitress),不再依赖 uWSGI 编译安装。这一点可以从 taosanode_service.py 中看到:Windows 下服务启动使用 waitress 并自动探测/安装该依赖,同时构建 PYTHONPATH 指向安装目录的 lib 目录。配置文件中也给出了完整的两套 Web 服务参数:

平台 Web 服务器 关键配置项 配置值
Linux Gunicorn bind 0.0.0.0:6035
Linux Gunicorn workers 2(推荐 2×CPU 核 + 1)
Linux Gunicorn worker_class sync
Linux Gunicorn threads max(cpu_count // 4 + 1, 2)
Linux Gunicorn max_requests / max_requests_jitter 1000 / 50(达到上限后自动重启 worker,释放内存)
Linux Gunicorn timeout / keepalive 1200 / 1200
Windows Waitress threads 4
Windows Waitress channel_timeout 1200
Windows Waitress connection_limit 1000

若升级后仍看到与 uWSGI / uwsgi 相关的报错,说明进程或包装脚本仍指向旧入口。此时应确认 taosanoded 使用的是当前安装目录下的 Gunicorn / Waitress 配置(/etc/taos/taosanode.config.py 或安装目录 cfg/taosanode.config.py),并重启服务。

2. 创建 anode 失败,返回“指定服务无法访问”

现象

taos> create anode '127.0.0.1:6035';

DB error: Analysis service can't access[0x80000441] (0.117446s)

错误码 0x80000441(Analysis service can't access)表示 TDengine 无法访问 anode 服务,这是创建 anode 时最常见的失败场景。

使用 curl 探测服务

请务必使用 curl 命令检查 anode 服务是否正常,而非仅依赖 systemctl status:

curl '127.0.0.1:6035'

正常的 anode 服务会返回版本标识字符串。在 app.py 中,根路径 / 直接返回 taosanalytics._ANODE_VER,而 init.py 中该常量定义为:

TDgpt - TDengine TSDB© Time-Series Data Analytics Platform (ver x.x.x)

如果出现以下结果,则表示 anode 服务不正常:

curl: (7) Failed to connect to 127.0.0.1 port 6035: Connection refused

进一步排障

  • 检查服务日志 /var/log/taos/taosanode/error.log(Gunicorn 错误日志),根据错误信息排查问题;
  • 确认端口监听状态:Linux 下可用 lsof -i :6035 / netstat -tlnp | grep 6035 查看(参考 INSTALL.md);
  • 确认防火墙已放行:Linux 需 ufw allow 6035/tcp,Windows 需放行 TCP 6035,6061-6070 端口;
  • 注册地址必须与配置 bind 一致。配置解析逻辑位于 conf.py 的 reload() 方法:bind 会被拆分为 host 与 port(默认 0.0.0.0:6035),服务实际监听于此。

请勿仅使用 systemctl status taosanoded 判断 taosanode 是否可用;应以 curl 探测与业务日志为准。因为 systemd 状态只代表进程存在,不代表 Web 服务已正常监听端口。

3. 服务正常,查询过程返回服务不可用

现象

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)

与问题 2 的立即失败不同,本例耗时约 60 秒后才报错,且 curl 探测服务是正常的。常见原因是分析过程超过默认最长等待时间。

SQL 侧 timeout 参数

可在 SQL 中通过 timeout 参数延长单次请求等待时间;timeout 最大值为 1200(秒),即单次请求最长约 20 分钟。例如:

select _frowts, forecast(current, 'algo=arima, conf=0.95, wncheck=0, rows=20, timeout=600') from d1 where ts<='2017-07-14 10:40:09.999';

注意,SQL 侧通过 parse_options(见 util.py)将 algo=arima,conf=0.95,... 这种逗号分隔的键值对解析为参数字典后传给算法,因此 timeout 同样作为选项传递。

Web 服务侧超时配置

自 v3.4.1.0 起,Gunicorn 的超时相关配置位于 /etc/taos/taosanode.config.py(或安装目录 cfg/taosanode.config.py):

# Timeout settings
timeout = 1200

# keep-alive time
keepalive = 1200

Windows 下 Waitress 对应为 waitress_config 中的 channel_timeout = 1200。更早版本若仍使用 uWSGI,则需在当时的 taosanode.ini 中调整 harakiri、http-timeout 等项。

排障建议:三层超时对齐

排障时建议同时核对:

  • SQL 侧 timeout 与 Gunicorn / Waitress 的 timeout(或 channel_timeout)是否匹配;任一侧过小都会表现为“服务不可用”(SQL 侧超时会导致引擎主动断开,Web 侧超时会导致 worker 被回收);
  • bind 地址与端口是否与 CREATE ANODE 注册的 URL 一致(默认 0.0.0.0:6035),不一致时引擎可能连到错误的端点;
  • 日志佐证:/var/log/taos/taosanode/error.log(Gunicorn)与 taosanode.app.log(应用)中是否有 worker 超时、OOM 或模型加载失败记录。

4. 返回结果出现非法 JSON 格式错误(Invalid json format)

错误信息 Invalid json format(对应 TDengine 通用错误码 0x8000011B,参见 错误码文档)表示从 anode 返回到 TDengine 的分析结果有误。

此时请检查 anode 运行日志 /var/log/taos/taosanode/taosanode.app.log 获得具体的错误信息。从 log.py 的实现可以看到,应用日志由 AppLogger 写入配置的 app_log 文件(默认 /var/log/taos/taosanode/taosanode.app.log),格式为 %(asctime)s - %(threadName)s - %(levelname)s - %(message)s,且日志目录不存在时会自动创建。

可能的原因包括算法执行抛出的异常未被序列化为合法 JSON、模型返回内容被截断、或算法输出中包含不可序列化的数据类型。由于 TDgpt 各 handler(如 forecast.py)在异常路径统一返回 {"msg": str(e), "rows": -1},因此业务侧最终看到的错误信息,往往直接来自算法内部的异常文本——务必以应用日志中的完整堆栈为准。

5. 如何调整 TDgpt 日志级别并获取详细错误信息

TDgpt 默认日志级别是 DEBUG。调整其日志级别需要更改 TDgpt 配置文件 /etc/taos/taosanode.config.py 中的 log_level 配置项:

# default TDgpt log level
log_level = 'DEBUG'

该配置项可选值包括:'DEBUG'、'INFO'、'CRITICAL'、'ERROR'、'WARN'。

从配置解析源码(conf.py 的 reload() 方法)可见其映射规则:配置文件中的字符串会被转换为 Python logging 标准级别——DEBUG→logging.DEBUG、INFO→logging.INFO、CRITICAL→logging.CRITICAL、ERROR→logging.ERROR、WARN→logging.WARNING,随后由 log.py 的 AppLogger.set_log_level() 应用到日志器上。若配置了非法值,会被忽略并继续使用默认的 DEBUG 级别。

注意区分两套日志级别配置:Gunicorn 的 loglevel(默认 "debug",控制 Web 服务日志)与 taosanode 的 log_level(控制 TDgpt 应用日志),两者位于同一配置文件但作用对象不同。

对于某些无法直接使用错误码返回的错误信息,请检查日志文件获得准确的错误信息。日志文件位于 /var/log/taos/taosanode/ 目录,对应关系如下:

  • taosanode.app.log:TDgpt 应用产生的日志(由 app_log 配置项指定,见 taosanode.config.py);
  • access.log 和 error.log:Gunicorn 产生的 Web 服务日志(Windows 上对应 Waitress 相关日志,如 taosanode-service.log)。

6. TDgpt 会返回哪些错误码

TDgpt 的分析错误码前缀为 0x8000044x,完整列表如下(详见 错误码文档 - TDgpt 一节):

错误码 错误描述 可能的出错场景或原因 建议采取的措施
0x80000440 Analysis service response is NULL 分析服务返回错误 检查服务端日志确认返回信息是否正确
0x80000441 Analysis service can't access 分析服务无法使用 检查 anoded 服务是否可用(参见 FAQ 2/3)
0x80000442 Analysis algorithm is missing 未指定分析算法名称 增加算法名称
0x80000443 Analysis algorithm not loaded 指定算法未加载 确认对应模型服务已启动
0x80000444 Analysis invalid buffer type 缓存数据格式不对 具体查看 server 端的错误日志
0x80000445 Analysis failed since anode return error anode 返回错误信息 请检查服务端日志确认问题原因
0x80000446 Analysis failed since too many input rows for anode 输入数据太多 减小分析数据输入规模
0x80000447 white-noise data not processed 白噪声数据不分析 输入数据不满足分析条件,可增大数据量(相关判断逻辑见 util.py 中的白噪声检测)
0x80000448 Analysis internal error, not processed anode 出现内部错误 具体查看 server 端的日志(taosanode.app.log)
0x80000449 Analysis failed since not enough rows 预测分析输入数据行数太少 增加输入数据规模(预测至少 10 行记录)
0x8000044A Not support co-variate/multi-variate forecast 不支持协变量/多变量预测 更换使用的预测模型

理解这组错误码的边界对排障很有帮助:0x80000441 是连接层/超时层错误(服务不可达或响应超时),0x80000445/0x80000448 是业务层错误(anode 已收到请求但算法执行失败),0x80000446/0x80000449 是输入校验层错误(数据规模不满足要求),而 0x80000447 则属于算法主动放弃分析(输入被判定为白噪声)。

附:一份排障速查清单

结合以上六个 FAQ,当 TDgpt 分析功能异常时,建议按如下顺序排查:

  1. 探测服务:curl '127.0.0.1:6035',确认返回 TDgpt - TDengine TSDB© Time-Series Data Analytics Platform (ver x.x.x);
  2. 确认注册:核对 CREATE ANODE 的地址端口与 bind(默认 0.0.0.0:6035)一致;
  3. 对齐超时:SQL 侧 timeout ≤ 1200,与 Gunicorn timeout/Waitress channel_timeout 匹配;
  4. 查看日志:先看 error.log(Web 层),再看 taosanode.app.log(应用层,默认 DEBUG 级别);
  5. 核对错误码:对照上表确定是连接层、业务层还是输入层问题;
  6. 确认模型服务:若错误码为 0x80000443,检查 taosanode_service.py model-status,并按需执行 model-start 启动对应模型。

上述命令、路径与配置均以当前仓库为准:配置文件为 tools/tdgpt/cfg/taosanode.config.py,服务管理脚本为 tools/tdgpt/script/taosanode_service.py,详细安装与节点管理可进一步参考 TDgpt 安装指南 与 Anode 节点管理。

登录后查看全文
tdengine