TDgpt 常见问题排查指南:TDengine 时序数据分析服务的安装、连接与调优
TDgpt 常见问题排查指南:TDengine 时序数据分析服务的安装、连接与调优
TDgpt 是 TDengine 内置的时序数据分析引擎,通过 taosanode(Analysis Node)向 SQL 提供 forecast、异常检测等高级分析能力。本文是 TDgpt 官方 FAQ 的深度实战版:围绕安装编译失败、Anode 创建失败、查询超时、JSON 解析错误、日志调优与错误码六个高频问题,给出完整排查步骤、配置参数说明与底层实现依据,帮助你快速定位并解决 TDgpt 在生产环境中的常见故障。
1. 安装过程中 uWSGI 编译失败
TDgpt 的历史版本在本地编译 uWSGI 作为 Web 服务容器,某些 Python 发行版(如 Anaconda)会与编译过程产生冲突。针对这一情况,官方提供了两条处理路径:
- 选择不安装 uWSGI:安装完成后,手动启动 taosanode 服务,命令为
python3.10 /usr/local/taos/taosanode/lib/taosanalytics/app.py。官方特别强调,执行该命令时应使用 Python 虚拟环境,以确保依赖可以被正确加载。 - 升级到新版本:自
v3.4.1.0起,TDgpt 已全面弃用 uWSGI——Linux 平台改用 Gunicorn,Windows 平台改用 Waitress。如果你是从旧版本升级安装后仍报 uWSGI 错误,请确认taosanoded正在使用当前的taosanode.config.py配置文件,然后重启服务。
这一变更可以从仓库源码得到印证:在 script/start.sh 中,服务通过 Gunicorn 启动,命令为 /usr/local/taos/taosanode/venv/bin/gunicorn -c /usr/local/taos/taosanode/cfg/taosanode.config.py;而在 Windows 侧,script/taosanode_service.py 中通过 from waitress import serve 启动服务,并会在虚拟环境中自动安装 waitress 依赖。这意味着,新版本安装包在正常情况下不会再与 uWSGI 有任何关联,若仍出现相关报错,几乎可以断定是残留的旧配置或旧进程所致。
2. Anode 创建失败:服务无法访问
执行 CREATE ANODE 时可能返回如下错误:
taos> create anode '127.0.0.1:6035';
DB error: Analysis service can't access[0x80000441] (0.117446s)
该错误的完整名称是 TSDB_CODE_ANA_URL_CANT_ACCESS,在 taoserror.h 中定义,说明 TDengine 无法访问注册的 Anode 服务地址。
2.1 第一步:用 curl 验证服务是否存活
官方推荐的判断方式是直接向 Anode 端口发起 HTTP 请求:
curl '127.0.0.1:6035'
- 服务正常时,输出应为:
TDgpt - TDengine© Time Series Data Analytics Platform (ver x.x.x) - 服务异常时,典型输出为:
curl: (7) Failed to connect to 127.0.0.1 port 6035: Connection refused
2.2 第二步:检查应用日志
如果 curl 无法连接,说明 Anode 未在运行或监听端口不对,应检查以下日志:
/var/log/taos/taosanode/error.log(Gunicorn 错误日志)/var/log/taos/taosanode/taosanode.app.log(TDgpt 应用日志)
官方同时给出了一条重要提示:不要只依赖 systemctl status taosanoded 判断服务状态,进程存在不代表 HTTP 服务可用,必须以 curl 结果与应用日志为准。这一建议与源码中的配置行为一致——在 taosanode.config.py 中,服务默认绑定地址为 bind = "0.0.0.0:6035",如果配置文件被修改、进程僵死或端口被占用,都会出现进程活着但无法访问的情况。
3. 服务运行正常,但查询仍返回"服务不可用"
有时服务本身可以访问,但执行分析类 SQL 仍会超时并报错:
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)
注意报错耗时(60 秒),这通常意味着请求已超出超时上限。排查要点如下:
- SQL 超时参数:TDgpt 分析类 SQL 的
timeout参数最大可设置为1200秒。 - Gunicorn/Waitress 超时:自
v3.4.1.0起,Gunicorn 的timeout与keepalive配置位于/etc/taos/taosanode.config.py,默认值均为1200(单位秒)。请确保 SQL 超时与 Gunicorn(或 Windows 下的 Waitress)超时保持一致。 - 绑定地址一致性:配置中的
bind必须与CREATE ANODE时注册的 URL 匹配。例如注册的是127.0.0.1:6035,而配置里是0.0.0.0:6035,虽然0.0.0.0覆盖了所有本地网卡,但如果集群节点间通过其他网段通信,仍可能出现无法访问的情况。 - 日志排查:确认日志中没有 worker timeout、内存不足(OOM)或模型加载失败的记录。
在 taosanode.config.py 中可以看到默认配置的完整定义:timeout = 1200、keepalive = 1200、max_requests = 1000(worker 处理满 1000 个请求后自动重启以释放内存)、max_requests_jitter = 50(随机抖动,避免所有 worker 同时重启)。这些参数共同决定了分析请求的吞吐与稳定性,修改后需重启 taosanoded 生效。
另外需要特别留意模型推理耗时。从 taosanode.config.py 的 models 配置可以看出,TDgpt 内嵌了多个大模型推理服务(tdtsfm 端口 6061、timemoe 端口 6062、chronos 端口 6063、moirai 端口 6064、timesfm 端口 6065、moment 端口 6066)。像 forecast 这类算法若触发模型推理,实际耗时会显著大于传统 ARIMA 算法,SQL 超时设置必须为其预留足够余量。
4. 返回 Illegal json format 错误
当查询返回 Illegal json format 错误时,说明分析结果中包含错误信息。这类错误通常不会体现在返回码中,需要直接查看 Anode 运行日志定位:
/var/log/taos/taosanode/taosanode.app.log
可能的原因包括:模型返回了空结果、推理服务异常、算法参数非法等。找到日志中对应的异常堆栈后,按提示修正 SQL 参数或重启相关模型服务即可。
5. 调整 TDgpt 日志级别,获取详细错误信息
TDgpt 默认日志级别为 DEBUG,日志级别在 /etc/taos/taosanode.config.py 中通过 log_level 配置:
# default log level
log_level = 'DEBUG'
可选的取值包括:DEBUG、INFO、CRITICAL、ERROR、WARN。
这一配置的底层解析逻辑位于 taosanalytics/conf.py:加载配置文件时,conf.py 会将 log_level 字符串转换为 Python logging 模块的常量(如 DEBUG → logging.DEBUG),并支持大小写不敏感匹配;同时通过 app_log 配置项推导出应用日志的目录与文件名。也就是说,日志相关的目录默认由 app_log 的路径决定(Linux 下为 /var/log/taos/taosanode/,Windows 下位于安装目录的 log 子目录)。
TDgpt 的日志文件分为两类:
| 日志文件 | 说明 |
|---|---|
taosanode.app.log |
TDgpt 应用日志,记录算法执行、模型调用与内部异常 |
access.log、error.log |
Gunicorn Web 服务日志;Windows 平台使用 Waitress 对应的日志 |
当返回码无法直接定位问题时,务必结合这些日志获取精确错误信息。例如 Illegal json format 类错误、worker 超时、模型加载失败等,都只能在日志中看到完整堆栈。
6. TDgpt 返回的错误码
TDgpt 相关的错误码集中在 10-developer-guide/09-error-codes.md 中,其中与本文问题直接相关的核心错误码如下:
| 错误码 | 含义 | 排查方向 |
|---|---|---|
0x80000441 |
Analysis service can't access(分析服务无法访问) | 检查 taosanode 服务状态与网络连通性 |
0x80000442 |
Analysis algorithm is missing(分析算法缺失) | 在 forecast 函数或 anomaly_window 子句中补充 algo 参数 |
两个错误码在 taoserror.h 中均有对应定义(TSDB_CODE_ANA_URL_CANT_ACCESS 等)。其中 0x80000441 是本文第 2、3 节所有"服务不可用"报错的根本来源;0x80000442 则常见于调用 forecast/异常检测时未显式指定算法,此时需检查 SQL 中是否遗漏了 algo 参数。
7. 快速排查清单
综合上述六个问题,可将 TDgpt 故障排查浓缩为如下清单:
- 服务可用性:用
curl '127.0.0.1:6035'确认 Anode 返回平台标识字符串,而不是 Connection refused。 - 绑定与端口:确认
/etc/taos/taosanode.config.py中bind与CREATE ANODE注册地址一致。 - 超时一致性:SQL
timeout与 Gunicorn/Waitress 的timeout、keepalive保持一致,且为模型推理预留余量。 - 日志先行:优先查看
/var/log/taos/taosanode/下的taosanode.app.log、error.log,不要只依赖systemctl status。 - 错误码定位:根据
0x80000441(服务不可访问)与0x80000442(算法缺失)快速区分故障类别。 - 升级残留:升级到
v3.4.1.0及以后版本后若仍报 uWSGI 错误,确认 taosanoded 加载的是当前taosanode.config.py并重启服务。