TDengine TDGPT（taosanode）安装部署与使用指南：Linux/Windows 双平台从零搭建时间序列 AI 分析服务-平芜编程栈

TDengine TDGPT（taosanode）安装部署与使用指南：Linux/Windows 双平台从零搭建时间序列 AI 分析服务

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine

TDGPT 是 TDengine 内置的 AI 分析平台（在源码与安装目录中对应taosanode服务），它把时间序列预测、异常检测、数据补齐等大模型/深度学习能力以 RESTFul 服务的形式提供给 TDengine 使用。本文以 tools/tdgpt/INSTALL-CN.md 为主体骨架，结合仓库内配置与脚本源码，完整讲解在 Linux 与 Windows 上的安装、服务管理、模型管理、配置调优与故障排查，帮助读者从零搭建起可用的 TDGPT 分析服务。

一、系统要求与端口规划

支持的平台

Linux：Ubuntu 18.04+、CentOS 7+ 或其他主流发行版；
Windows：Windows Server 2016+ 或 Windows 10/11。

Python 版本

TDGPT 的 taosanode 服务与模型服务全部由 Python 实现（见 tools/tdgpt/README.md 的说明，构建过程无需编译），因此 Python 解释器版本是唯一的硬性依赖：

Python 3.10、3.11 或 3.12（必需）

Python 3.10 以下或 3.13+ 不在官方支持范围内，因为 torch、tensorflow 等深度学习依赖对解释器版本敏感。

硬件要求（建议值）

资源	建议
CPU	4+ 核心
内存	8GB+
磁盘	20GB+（模型权重与数据）

网络端口规划

端口	服务	说明
6035	主 taosanode 服务	RESTFul 分析服务入口
6061	tdtsfm	时间序列基础模型
6062	timemoe	时间序列专家混合模型（TimeMoE）
6063	chronos	Amazon Chronos
6064	moirai	Salesforce Moirai
6065	timesfm	Google TimesFM
6066	moment	AutonLab MOMENT
6067-6070	预留	后续模型服务端口

从仓库配置 tools/tdgpt/cfg/taosanode.config.py 可以看到，这些端口在models字典中逐一声明，且模型服务的port与endpoint是服务 URL 的“单一事实来源”：conf.py会根据http://<ip>:<port><endpoint>自动推导每个模型的实际调用地址（见 tools/tdgpt/taosanalytics/conf.py），因此调整端口时只需修改配置中对应模型的port即可。

二、Linux 安装

1. 前置条件

安装 Python 3.10+：

# Ubuntu/Debian sudo apt-get update sudo apt-get install python3.10 python3.10-venv python3.10-dev # CentOS/RHEL sudo yum install python310 python310-devel

同时确保当前用户具备系统级sudo权限，因为安装脚本需要写入/usr/local/taos、创建虚拟环境并注册 systemd 服务。

仓库 tools/tdgpt/README.md 还提供了 Ubuntu 下通过 deadsnakes PPA 安装 Python 3.10 并配置update-alternatives的完整流程，适用于系统自带 Python 版本较旧的场景。

2. 解压与安装

# 解压安装包 tar -xzf tdgpt-linux-x.x.x.tar.gz cd tdgpt-linux-x.x.x # 标准安装 bash install.sh # 离线安装（安装包内包含 wheels 时使用） bash install.sh -o # 自定义安装目录 bash install.sh -d /opt/tdgpt

安装脚本会完成以下工作（依据 tools/tdgpt/script/install.sh 与 tools/tdgpt/script/install.py 的实现）：

在默认目录（Linux 为/usr/local/taos/taosanode）展开服务文件；
在/var/lib/taos/taosanode/venv（或venvs/venv）创建 Python 虚拟环境并安装requirements.txt中锁定的依赖，包括flask、numpy、pandas、torch、tensorflow、keras等（依赖清单见 tools/tdgpt/requirements.txt 与 tools/tdgpt/requirements_ess.txt）；
注册 systemd 服务（服务单元文件定义可参考仓库内的 tools/tdgpt/cfg/taosanoded.service）。

注意：安装完成不会自动启动服务，需要手动执行启动命令（见下一节）。这与 TDengine 主服务taosd的安装习惯一致，方便用户先完成配置再启动。

3. 验证安装

# 检查服务状态 python /usr/local/taos/taosanode/bin/taosanode_service.py status # 检查模型状态 python /usr/local/taos/taosanode/bin/taosanode_service.py model-status

三、Windows 安装

1. 前置条件

Python 3.10 / 3.11 / 3.12：从 python.org 下载安装，务必勾选Add Python to PATH，安装后执行python --version验证。
Microsoft Visual C++ Redistributable x64 14.44+：TensorFlow、PyTorch 及其他原生 Python 依赖所必需，建议直接安装最新支持的 VC++ 2015-2022 运行库（64 位版本）。
管理员权限：服务注册与端口放行均需要管理员权限，请以管理员身份运行命令提示符。

2. 安装步骤

方式一：运行图形安装程序

右键点击.exe安装程序，选择“以管理员身份运行”；
按安装向导操作即可；
若为升级安装，安装器会先停止当前安装目录下已存在的 Taosanode 服务与模型服务，再替换打包文件（避免文件占用与进程残留）。

方式二：手动解压 ZIP 包

解压到所需位置，例如C:\TDengine\taosanode；
以管理员身份打开命令提示符，进入安装目录后运行install.bat。

验证安装：

python C:\TDengine\taosanode\bin\taosanode_service.py status

Windows 平台的服务逻辑与 Linux 有两点关键差异（见 tools/tdgpt/script/taosanode_service.py）：

主服务由Waitress（纯 Python WSGI 服务器）承载而非 gunicorn，因为 gunicorn 不支持 Windows；
服务可通过winsw 包装器（taosanode-winsw.exe）注册为 Windows 服务。

四、服务管理

1. Linux：systemd 管理（推荐）

安装脚本会自动创建 systemd 服务：

# 启动服务 sudo systemctl start taosanode # 停止服务 sudo systemctl stop taosanode # 重启服务 sudo systemctl restart taosanode # 检查状态 sudo systemctl status taosanode # 启用开机自启 sudo systemctl enable taosanode # 禁用开机自启 sudo systemctl disable taosanode # 实时查看日志 sudo journalctl -u taosanode -f

仓库内 tools/tdgpt/cfg/taosanoded.service 展示了服务单元的关键配置，从中可以理解服务的运行方式：

Type=simple，ExecStart直接调用虚拟环境中的gunicorn -c /usr/local/taos/taosanode/cfg/taosanode.config.py拉起 WSGI 服务；
通过Environment="TDGPT_CONF=/etc/taos/taosanode.config.py"注入配置文件路径（taosanalytics.app的_init_app()会优先读取该环境变量，见 tools/tdgpt/taosanalytics/app.py）；
Restart=always配合StartLimitBurst=6/StartLimitInterval=60s实现崩溃自动拉起与防抖动；
LimitNOFILE=1048576放开文件句柄限制，TimeoutStopSec=120s给模型进程足够的优雅退出时间。

2. Linux：直接使用 Python 脚本

python /usr/local/taos/taosanode/bin/taosanode_service.py start python /usr/local/taos/taosanode/bin/taosanode_service.py stop python /usr/local/taos/taosanode/bin/taosanode_service.py status

3. Linux 卸载

# 运行卸载脚本（会移除 systemd 服务，但保留虚拟环境目录） bash /usr/local/taos/taosanode/uninstall.sh # 或手动删除 sudo rm -rf /usr/local/taos/taosanode sudo systemctl disable taosanode

4. Windows：服务管理

选项 1：注册为 Windows 服务（推荐）

# 安装为 Windows 服务 python C:\TDengine\taosanode\bin\taosanode_service.py install-service # 启动服务 net start Taosanode :: 或：python C:\TDengine\taosanode\bin\taosanode_service.py start-service # 停止服务 net stop Taosanode :: 或：python C:\TDengine\taosanode\bin\taosanode_service.py stop-service # 检查服务状态 sc query Taosanode # 卸载服务 python C:\TDengine\taosanode\bin\taosanode_service.py uninstall-service

选项 2：批处理脚本（前台模式）

C:\TDengine\taosanode\bin\start-taosanode.bat C:\TDengine\taosanode\bin\stop-taosanode.bat C:\TDengine\taosanode\bin\status-taosanode.bat

选项 3：直接使用 Python 脚本

python C:\TDengine\taosanode\bin\taosanode_service.py start python C:\TDengine\taosanode\bin\taosanode_service.py stop python C:\TDengine\taosanode\bin\taosanode_service.py status

5. Windows 防火墙配置

# 自动放行端口（以管理员身份运行） netsh advfirewall firewall add rule name="TDGPT" dir=in action=allow protocol=TCP localport=6035,6061-6070 profile=any # 或手动配置：Windows Defender 防火墙（高级安全）→ 入站规则 → 新建规则 # 端口 → TCP → 特定本地端口：6035,6061-6070 → 允许连接

6. Windows 卸载

# 运行卸载脚本 C:\TDengine\taosanode\uninstall.bat # 或手动卸载： :: 1. 卸载 Windows 服务（如果已安装） python C:\TDengine\taosanode\bin\taosanode_service.py uninstall-service :: 2. 删除安装目录 rmdir /s /q C:\TDengine\taosanode

7. 统一服务管理入口：taosanode_service.py

无论是 Linux 还是 Windows，tools/tdgpt/script/taosanode_service.py 都是统一的管理入口。从脚本的模块划分可以看出其设计：

Config：从taosanode.config.py动态加载配置（通过importlib导入配置模块并提取pidfile、app_log、model_dir、virtualenv、bind、workers、models等属性，见 tools/tdgpt/script/taosanode_service.py），配置文件缺失时回退到内置默认值，不会因配置损坏而彻底无法管理；
ProcessManager：负责 PID 文件读写、进程存活探测（Linux 用信号 0，Windows 用tasklist精确匹配）、优雅/强制停止；
TaosanodeService：实现主服务的 start/stop/status，并内置了启动前诊断能力——通过 AST 静态分析taosanalytics.app的 import 依赖，在启动失败时逐个探测waitress、numpy、pandas、flask、torch、tensorflow、keras等模块的导入情况，将根因精确到“哪一个依赖缺失/损坏”（见 tools/tdgpt/script/taosanode_service.py）。

五、配置详解

配置文件位置

Linux：/usr/local/taos/taosanode/cfg/taosanode.config.py
Windows：C:\TDengine\taosanode\cfg\taosanode.config.py

该文件同时是 gunicorn 的启动配置（Linux）与 taosanode 的业务配置（双平台通用），仓库内对应模板为 tools/tdgpt/cfg/taosanode.config.py。

1. 服务绑定（HTTP 层）

# 监听地址和端口 bind = '0.0.0.0:6035' # 工作进程数 workers = 2 # worker 类型，默认 sync；IO 密集型可考虑 eventlet 或 gevent worker_class = "sync" # 每个进程的线程数，默认按 CPU 核数推导 threads = max(multiprocessing.cpu_count() // 4 + 1, 2) # 每个 worker 处理满 max_requests 后重启，用于释放累积内存 max_requests = 1000 max_requests_jitter = 50 # 超时与 keep-alive（秒），模型推理耗时长，需要较大值 timeout = 1200 keepalive = 1200

配置注释中明确指出：workers的典型推荐值为2 * CPU 核数 + 1；threads的推导公式cpu_count // 4 + 1（下限 2）是为了让模型部署场景下每个进程拥有充足的并发推理线程。timeout = 1200与keepalive = 1200则是考虑到深度学习模型单次推理可能耗时较长，若沿用默认的 30 秒超时，长任务会被 gunicorn 提前掐断。

2. 日志配置

# 日志级别：DEBUG、INFO、WARNING、ERROR、CRITICAL log_level = 'DEBUG' # 日志文件位置 app_log = '/var/log/taos/taosanode/taosanode.app.log' # Linux app_log = 'c:/TDengine/taosanode/log/taosanode.app.log' # Windows

日志级别会经过 tools/tdgpt/taosanalytics/conf.py 的映射（DEBUG/INFO/WARNING/ERROR/CRITICAL，兼容WARN写法）转换为 Pythonlogging级别常量；app_log的所在目录会被解析为log_dir，所在文件名会被解析为log_file。此外 Linux 下 gunicorn 还会单独输出access.log与error.log（配置中的accesslog/errorlog）。

3. 模型配置

# 模型存储目录 model_dir = '/usr/local/taos/taosanode/model/' # Linux model_dir = 'c:/TDengine/taosanode/model/' # Windows # 动态模型目录：运行期间可随时增删，无需重启服务 dynamic_model_dir = <model_dir>/dynamic # 模型定义 models = { "tdtsfm": { "script": "tdtsfm-server.py", "port": 6061, "endpoint": "/tdtsfm", "algo_name": "tdtsfm_1", "required": True, # 必需，缺失时报错 }, "timemoe": { "script": "timemoe-server.py", "default_model": "Maple728/TimeMoE-200M", "port": 6062, "endpoint": "/ds_predict", "algo_name": "timemoe-fc", "required": True, # 必需 }, "chronos": { "script": "chronos-server.py", "default_model": "amazon/chronos-bolt-base", "port": 6063, "endpoint": "/ds_predict", "required": False, # 可选，缺失时跳过 }, # ... 其他模型（moirai、timesfm、moment） }

仓库配置 tools/tdgpt/cfg/taosanode.config.py 给出了每个模型的完整字段，相比文档示例多出endpoint、ip、algo_name、default_model等关键项：

script：该模型服务的启动脚本名（位于bin/或模型目录，如tdtsfm-server.py）；
default_model：默认加载的 HuggingFace 模型仓库 ID，如Maple728/TimeMoE-200M、amazon/chronos-bolt-base、google/timesfm-2.5-200m-pytorch、AutonLab/MOMENT-1-base、Salesforce/moirai-moe-1.0-R-small；
endpoint+port：服务 URL 的组成部分，conf.py会自动推导http://127.0.0.1:<port><endpoint>作为该算法的回调地址；
algo_name：算法在 SQL / 服务注册表中的对外名称（如tdtsfm_1、timemoe-fc）；
required：必需模型缺失会导致启动失败，可选模型缺失则自动跳过。

另外，可选模型（timesfm、moirai、chronos、moment）可以各自指定独立的虚拟环境（timesfm_venv、moirai_venv、chronos_venv、momentfm_venv），默认共用主虚拟环境virtualenv。若想通过enabled_models.txt白名单机制只启用部分模型，只需在cfg目录下放置一个逐行列出模型名的enabled_models.txt，服务管理器会按DEFAULT_MODEL_ORDER顺序过滤加载（见 tools/tdgpt/script/taosanode_service.py）。

4. Windows Waitress 配置

# Waitress 服务器配置（仅 Windows） waitress_config = { 'threads': 4, # 工作线程数 'channel_timeout': 1200, # 通道超时（秒） 'connection_limit': 1000, # 最大连接数 'cleanup_interval': 30, # 清理间隔（秒） 'log_socket_errors': True # 记录 socket 错误 }

TaosanodeService._get_waitress_settings()会解析bind中的 host:port，并将该字典逐项传给waitress.serve()（见 tools/tdgpt/script/taosanode_service.py），因此这里的参数名必须与 Waitress 的签名一致。

5. 修改配置后的生效方式

用文本编辑器修改taosanode.config.py；
重启服务使配置生效：

# Linux sudo systemctl restart taosanode # Windows net stop Taosanode net start Taosanode

六、模型管理

支持的模型一览

模型	必需	端口	描述
tdtsfm	是	6061	时间序列基础模型
timemoe	是	6062	时间序列专家混合（TimeMoE）
chronos	否	6063	Amazon Chronos
moirai	否	6064	Salesforce Moirai
timesfm	否	6065	Google TimesFM
moment	否	6066	AutonLab MOMENT

从服务端路由看，主服务对外暴露的分析能力包括：/forecast（预测）、/anomaly-detect（异常检测）、/imputation（数据补齐）、/correlation（相关性）、/regression（回归），以及/list（服务列表）、/models（模型列表）、/status（健康检查，返回{"protocol": 1.0, "status": "ready"}）等管理接口（见 tools/tdgpt/taosanalytics/app.py）。启动后可直接访问http://<ip>:6035/status验证服务就绪。

启动模型

# 启动必需模型（tdtsfm、timemoe） python <install_dir>/bin/taosanode_service.py model-start all # 启动特定模型 python <install_dir>/bin/taosanode_service.py model-start chronos # 检查模型状态 python <install_dir>/bin/taosanode_service.py model-status

停止模型

# 停止所有模型 python <install_dir>/bin/taosanode_service.py model-stop all # 停止特定模型 python <install_dir>/bin/taosanode_service.py model-stop chronos

模型服务由model-start/model-stop子命令按DEFAULT_MODEL_ORDER = ["tdtsfm", "timemoe", "moirai", "chronos", "timesfm", "moment"]顺序拉起或回收，每个模型进程的 PID 记录在<install_dir>/data/pids/<model_name>.pid中，便于精确控制单个模型的启停与状态查询。

七、故障排查

1. 服务无法启动

Linux：

# 查看 systemd 最近 50 行日志 sudo journalctl -u taosanode -n 50 # 直接前台运行，直接观察 Python 报错 python /usr/local/taos/taosanode/bin/taosanode_service.py start

Windows：

:: 查看启动日志 type C:\TDengine\taosanode\log\taosanode_startup.log :: 前台运行直接看错误输出 python C:\TDengine\taosanode\bin\taosanode_service.py start

值得说明的是，taosanode_service.py在启动失败时会自动输出“根因诊断”：它先通过 AST 扫描taosanalytics.app的 import 依赖树，然后逐个探测waitress、numpy、pandas、flask、torch、tensorflow、keras等模块能否导入，并把ModuleNotFoundError、ImportError、Windows 下 DLL 加载失败（如vcruntime、msvcp、0xc0000005、winerror 126/127/193等）识别为import_native类故障（见 tools/tdgpt/script/taosanode_service.py），从而让用户一眼定位是哪个依赖缺失。同时，该诊断有 300 秒冷却期（可用环境变量TAOSANODE_STARTUP_DIAGNOSTIC_COOLDOWN调整），避免 systemd 自动重启时反复刷屏。

2. 端口已被占用

# Linux：查找占用 6035 的进程 sudo lsof -i :6035 # Windows netstat -ano | findstr :6035 # 结束进程 # Linux：sudo kill -9 <PID> # Windows：taskkill /PID <PID> /F

服务管理器把“地址被占用”单独识别为bind类故障（Linux 的EADDRINUSE/EACCES，Windows 的winerror 10048/10013），日志中会给出明确的失败分类，便于快速判断根因。

3. 模型无法启动

# Linux ls -la /usr/local/taos/taosanode/model/ # Windows dir C:\TDengine\taosanode\model\

检查模型日志：

# Linux tail -f /var/log/taos/taosanode/taosanode_service_tdtsfm.log # Windows type C:\TDengine\taosanode\log\taosanode_service_tdtsfm.log

验证深度学习依赖：

python -m pip list | grep -E "torch|transformers"

4. 连接被拒绝

检查服务是否在运行：python <install_dir>/bin/taosanode_service.py status
检查防火墙：

# Linux sudo ufw status sudo ufw allow 6035/tcp # Windows netsh advfirewall firewall show rule name="TDGPT"

检查绑定地址：

# Linux sudo netstat -tlnp | grep 6035 # Windows netstat -ano | findstr :6035

如果bind配置成了127.0.0.1而客户端从其他主机访问，同样会表现为连接被拒绝；需要将bind改为0.0.0.0:6035并重启服务。

八、常见问题（FAQ）

Q：如何检查服务是否运行？

python <install_dir>/bin/taosanode_service.py status

Q：可以运行多个实例吗？

不推荐。服务按单实例设计，PID 文件全局唯一；如确有需要，可通过修改配置文件的bind端口运行多个实例，但需自行处理 PID 文件与模型端口冲突。

Q：如何查看日志？

Linux：tail -f /var/log/taos/taosanode/taosanode.app.log（服务管理日志另见<install_dir>/log/taosanode-service.log，gunicorn 的访问日志见access.log）；
Windows：type C:\TDengine\taosanode\log\taosanode.app.log。

Q：如何更新配置？

编辑taosanode.config.py后重启服务，改动在重启后生效。注意模型端口的修改会自动联动更新各模型的回调 URL（由 tools/tdgpt/taosanalytics/conf.py 推导）。

Q：需要重新安装怎么办？

先卸载当前版本（Linux 运行uninstall.sh，Windows 运行uninstall.bat并卸载服务）；
删除安装目录（Linux 卸载脚本会保留虚拟环境，可手动清理）；
运行新安装程序。

Q：如何启用调试日志？

编辑配置文件，将log_level = 'DEBUG'，重启服务即可；Linux 下 gunicorn 的loglevel也可同步调为debug以输出更详细的请求处理日志。

Q：可以使用自定义 Python 虚拟环境吗？

可以。修改配置文件中的virtualenv指向您的虚拟环境；可选的 timesfm、moirai、chronos、moment 模型还支持通过timesfm_venv、moirai_venv、chronos_venv、momentfm_venv分别为其指定独立环境。

Q：如何备份配置？

# Linux cp /usr/local/taos/taosanode/cfg/taosanode.config.py ~/taosanode.config.backup.py # Windows copy C:\TDengine\taosanode\cfg\taosanode.config.py C:\backup\taosanode.config.backup.py

九、与 TDengine 生态的配合要点

TDGPT 的 taosanode 配置目录与taosd保持在同一体系（Linux 下服务配置文件可放置于/etc/taos，见 tools/tdgpt/README.md），便于统一管理；
安装包构建可通过仓库脚本完成，例如在tools/tdgpt/script目录执行./release.sh -e community -v <版本号>，产物输出到release目录（对应社区版 tar 包）；Windows 侧由 tools/tdgpt/packaging/win_release.py 负责打包；
更多设计文档、架构说明可参考 TDengine 官方文档集中与 TDGPT 相关的章节，本仓库的源码入口集中在 tools/tdgpt/taosanalytics（Flask 应用、算法注册与模型文件管理）与 tools/tdgpt/script（安装与服务管理脚本）。

十、总结

TDGPT（taosanode）把 TDengine 从“存得下、查得快”的时序数据库，扩展为具备预测、异常检测、补齐、相关性与回归分析能力的 AI 增强分析平台。部署上它遵循“Python 虚拟环境 + WSGI 服务 + 独立模型进程”的经典架构：主服务在 Linux 由 gunicorn、在 Windows 由 Waitress 承载，六个模型服务各自占用独立端口，通过taosanode_service.py统一管理。掌握本文的安装步骤、配置项语义与排查手段，即可在 Linux 或 Windows 上快速落地一套可投入生产使用的 TDGPT 分析服务。

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考