TDengine TDgpt 常见问题排查指南:安装、部署与调用全流程排障
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 的调用链路,这决定了排障时“该看哪一层”:
- TDengine 集群通过
CREATE ANODE 'ip:port'将 taosanode 注册为分析节点; - SQL 中的分析函数(如
forecast、anomaly_detect)由引擎转发给 anode; - anode 本质是一个基于 Flask 的 REST 服务(入口见 app.py),由 Gunicorn(Linux)/ Waitress(Windows)托管;
- 算法侧按需加载 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 需放行 TCP6035,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 分析功能异常时,建议按如下顺序排查:
- 探测服务:
curl '127.0.0.1:6035',确认返回TDgpt - TDengine TSDB© Time-Series Data Analytics Platform (ver x.x.x); - 确认注册:核对
CREATE ANODE的地址端口与bind(默认0.0.0.0:6035)一致; - 对齐超时:SQL 侧
timeout≤ 1200,与 Gunicorntimeout/Waitresschannel_timeout匹配; - 查看日志:先看
error.log(Web 层),再看taosanode.app.log(应用层,默认 DEBUG 级别); - 核对错误码:对照上表确定是连接层、业务层还是输入层问题;
- 确认模型服务:若错误码为
0x80000443,检查taosanode_service.py model-status,并按需执行model-start启动对应模型。
上述命令、路径与配置均以当前仓库为准:配置文件为 tools/tdgpt/cfg/taosanode.config.py,服务管理脚本为 tools/tdgpt/script/taosanode_service.py,详细安装与节点管理可进一步参考 TDgpt 安装指南 与 Anode 节点管理。