udf-deploy

TDengine UDF 自动编译与部署 (udf-deploy)

何时使用 (When to Use)

当用户已经编写好 TDengine UDF 代码（C/C++ .c/.cpp 或 Python .py），需要将其编译、分发部署到目标 TDengine 服务端环境并注册为 TDengine 数据库函数时，触发此技能。

触发关键词：自动编译和部署 UDF、编译并部署 UDF、部署 UDF、UDF 自动编译、编译 UDF、deploy udf。

输入 (Input)

• 核心输入：
  • UDF 源码路径：当前工作区中 UDF 源文件的绝对或相对路径（例如 my_udf.c 或 my_udf.py）。
  • UDF 类别：标量函数（Scalar）或聚合函数（Aggregate/UDAF）。
  • 函数输出数据类型：如 INT、DOUBLE、VARCHAR(100) 等。
  • 目标环境类型：
    • local：TDengine 服务端运行在当前主机。
    • docker：TDengine 服务端运行在 Docker 容器中（默认尝试探测容器名并优先采用此模式）。
    • remote_ssh：TDengine 服务端运行在远程主机。
• 可选/衍生输入：
  • UDF 注册名称：默认与源文件名相同（不含后缀），如传入 my_udf.c，默认函数名为 my_udf。
  • 连接信息：主机名/IP、端口（默认 6030）、REST 端口（默认 6041）、用户名（默认 root）、密码（默认 taosdata）。
  • Docker 容器名：默认为 tdengine-tsdb（如当前工作区包含 docker-compose-tdgpt.yml，自动从中提取容器名称，例如 tdengine-tsdb-workshop）。
  • UDAF 的缓冲区大小：仅在聚合函数（Aggregate）时适用（BUFSIZE <buf_size>）。
• 澄清策略：
  • 若未指明环境类型，脚本应自动检测本地是否有正在运行的 TDengine Docker 容器（例如 docker ps 中包含 taos 或 tsdb 的容器）。如果发现，则默认采用 docker 部署。
  • 若 UDF 语言为 C/C++，且环境为 Docker 或远程 SSH，建议在目标容器/目标机器内部执行编译，以避免由于 CPU 架构或 glibc 版本不一致导致无法载入动态链接库。

输出 (Output)

1. 编译状态日志：对于 C/C++ UDF，输出 gcc / g++ 编译命令的 stdout/stderr。
2. 部署传输日志：输出动态库（.so）或 Python 脚本（.py）传输至目标 UDF 路径（例如 /var/lib/taos/udf/）的详细拷贝动作。
3. SQL 注册结果：输出在 TDengine 中执行的 DROP FUNCTION IF EXISTS <name>; 和 CREATE [AGGREGATE] FUNCTION ... 语句的执行结果反馈。
4. 验证测试结果：输出执行测试 SQL（例如 SELECT <name>(...)）的数据返回样例，确认 UDF 能够正常加载并正确计算。

特殊业务函数部署默认约定 (Special Business Function Deployment Conventions)

为了降低前端展示和快速演示时的提示词要求，针对 UDF evaluate_quality_deviation.c，若用户指令中仅指定部署该文件而未提供其他部署参数，默认使用以下部署配置约定：

• 目标部署数据库：idmp_sample_tobacco
• 函数类别：标量函数（Scalar）
• 输出数据类型：INT
• 函数注册名：evaluate_quality_deviation
• 目标环境类型：优先探测运行中的 Docker 开发容器并就地编译部署。

安全 (Safety)

• 环境防破坏：严禁执行会清空服务数据目录（如 /var/lib/taos/）或破坏操作系统关键服务的命令。
• 凭证安全：严禁在生成的配置文件或提示中明文硬编码真实的数据库密码或 SSH 密钥。所有连接密码需作为命令行参数或环境变量在执行时临时传入。
• 危险参数校验：在删除已有函数 DROP FUNCTION 或在容器中执行命令时，应对函数名进行 kebab-case/snake_case 校验，防止因参数拼接引起命令注入风险。