企业官网建设流程全解析

TDengine 源码构建指南：从编译、测试到打包部署的完整实践

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

TDengine 是一个面向物联网（IoT）、车联网与工业物联网（IIoT）场景的开源高性能时序数据库。本篇指南基于仓库根目录 README.md 的完整脉络，系统讲解从源码构建 TDengine 的每一步：环境准备、CMake 构建选项、单元测试与集成测试、社区版打包、安装与运行，并结合 cmake/options.cmake 等源码文件对关键配置进行深度解读。读完本文，你将具备独立完成 TDengine 源码级构建、自测、打包与部署的全链路实战能力。

1. TDengine 是什么：面向工业物联网的高性能时序数据库

TDengine 是一个开源、云原生（cloud native）且由 AI 赋能的时序数据库，专为物联网、车联网和工业物联网设计，目标是高效支撑由数十亿传感器与采集设备产生的海量时序数据的实时写入、处理与分析。它通过以下核心设计区别于传统时序数据库（以下特性均源自 README.md 的项目定位说明）：

• 高性能（High Performance）：以解决高基数（high cardinality）问题为核心设计目标，支持数十亿采集点规模下的数据写入、查询与压缩，这是其架构设计的出发点。
• 简化方案（Simplified Solution）：内置缓存、流式计算、数据订阅与 AI Agent 能力，降低时序数据处理的系统设计复杂度与运维成本。
• 云原生（Cloud Native）：原生分布式设计、分片与分区、存储与计算分离、RAFT 一致性协议，支持 Kubernetes 部署与全链路可观测性，可部署于公有云、私有云或混合云。
• AI 赋能（AI Powered）：内置 AI Agent——TDgpt，可对接多种时序基础模型、大语言模型、机器学习与传统算法，提供时序数据预测、异常检测、插值与分类能力。最新组件说明见 tools/tdgpt/README.md。
• 易用性（Ease of Use）：对管理员降低部署与维护成本，对开发者提供简洁接口与第三方工具无缝集成，对数据使用者提供便捷的数据访问方式。
• 数据分析友好（Easy Data Analytics）：通过超级表（super table）、存储与计算分离、按时间区间分区、预计算与 AI Agent，让数据探索、格式化与访问变得高效。
• 开源（Open Source）：核心模块（含集群能力与 AI Agent）均以开源许可证发布，社区与运行实例广泛。

需要说明的是，README 中提到的"解决高基数问题""简化系统设计"等属于项目官方定位陈述，具体性能表现需以实际环境测试为准，本文不再重复其营销性表述。仓库根目录还提供 README-CN.md（简体中文）与 README-JP.md（日语）版本；完整用户手册与系统架构设计请查阅官方文档，而本指南聚焦于开发者视角的构建、测试、打包与运行。

2. 构建前置条件

2.1 系统要求

根据 README 的明确说明，构建 TDengine 需满足以下系统要求：

TDengine 主要在 Linux 上构建与测试，macOS 构建可用于本地开发；开源树中的 Windows 支持有限。为保证构建结果可复现，默认应选择 Linux 作为构建平台。

2.2 安装构建工具

Ubuntu/Debian：

sudo apt-get update sudo apt-get install -y build-essential cmake git

CentOS/RHEL：

sudo yum groupinstall -y "Development Tools" sudo yum install -y cmake3 git

注意：外部依赖构建要求CMake >= 3.21。如果你的发行版自带版本过低，需要安装更新版本的 CMake。此外，根据所构建内容还可能用到以下工具：

• Python 3：用于test/目录下的测试框架；
• Go 1.23+：用于构建 taosAdapter、taosKeeper 等 Go 组件。

2.3 可选工具

• ccache：加速增量重编译，sudo apt install ccache；
• Conan 2.x：仅taos-gen组件需要，pip3 install conan。

3. 从源码构建 TDengine

3.1 快速开始

git clone https://gitcode.com/GitHub_Trending/tde/TDengine cd TDengine mkdir debug && cd debug cmake .. -DBUILD_CONTRIB=ON # 首次构建：-DBUILD_CONTRIB=ON 必须指定 make -j$(nproc)

重要首次源码构建必须使用-DBUILD_CONTRIB=ON。该选项会下载并编译 xxhash、zstd、lz4 等外部依赖到.externals/目录。后续构建通常可以省略该选项，自动复用已缓存的构建产物。

常用构建变体：

# Release 构建并附带命令行工具 cmake .. -DBUILD_CONTRIB=ON -DCMAKE_BUILD_TYPE=Release -DBUILD_TOOLS=ON make -j$(nproc) # macOS 下并行构建 cmake .. -DBUILD_CONTRIB=ON -DCMAKE_BUILD_TYPE=Release cmake --build . --parallel "$(sysctl -n hw.ncpu)"

3.2 构建选项详解

README 表格中的默认值对应开源独立构建（standalone）场景下 cmake/options.cmake 的定义。该文件以option()与set(... CACHE ...)的形式集中管理全部构建开关，下面是与 README 一致的完整选项表：

从源码结构看，cmake/options.cmake 还在TD_COMMUNITY_STANDALONE分支下暴露了BUILD_ENTERPRISE、BUILD_VER_NUMBER、BUILD_VER_COMPATIBLE、BUILD_VER_TYPE等版本相关缓存变量，版本号的实际拼接逻辑位于 cmake/version.cmake，社区版打包时正是通过这些变量控制产物版本。

示例组合：

cmake .. -DBUILD_CONTRIB=ON -DCMAKE_BUILD_TYPE=Release -DBUILD_TOOLS=ON

该命令等价于 README 推荐的 Release 构建模板：开启第三方依赖源码构建、以 Release 优化级别编译、并同时产出 taosBenchmark 与 taosdump 工具。

3.3 构建产物

默认构建树（debug/下）的产物布局如下：

• 二进制文件位于debug/build/bin/
  • taosd—— TDengine 服务端守护进程
  • taos—— TDengine 命令行客户端
  • taosBenchmark—— 基准测试工具（需BUILD_TOOLS=ON）
  • taosdump—— 数据导入/导出工具（需BUILD_TOOLS=ON）
• 库文件位于debug/build/lib/
  • libtaos.so（Linux，或对应平台的客户端库）

4. 测试 TDengine

4.1 单元测试

TDengine 使用 googletest 组织单元测试，构建并运行方式：

cd debug cmake .. -DBUILD_CONTRIB=ON -DBUILD_TEST=ON make -j$(nproc) ctest --output-on-failure

部分单独的测试二进制也会输出到debug/build/bin/。仓库中单元测试源码分散于各模块的test/子目录，例如 source/util/test/、source/common/test/ 等，可用 ctest 统一调度执行。

4.2 集成测试

TDengine 在test/目录下提供了基于 Python 的集成测试框架（tests/system-test中的用例在仓库中对应test/cases/下的各类场景脚本）。完整流程：

# 先构建服务端与工具 cd debug cmake .. -DBUILD_CONTRIB=ON -DBUILD_TOOLS=ON -DBUILD_TEST=ON make -j$(nproc) # 使用生成的测试配置启动 taosd ./build/bin/taosd -c test/cfg & # 运行系统测试 cd ../tests/system-test python3 test.py -f 2-query/basic.py

说明：当前仓库中 README 引用的tests/system-test路径对应实际存在的 test/ 目录，更多测试框架细节可阅读 test/README.md。

5. 打包社区版

5.1 使用打包脚本

Linux 构建成功后，使用打包脚本组装开源社区版 tarball。README 中引用的脚本路径source/taos-community/packaging/pack_community_tar.sh在当前仓库中对应 packaging/pack_community_tar.sh，其脚本头注释完整说明了参数语义：

完整调用示例：

mkdir debug && cd debug cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_CONTRIB=ON -DBUILD_TOOLS=ON make -j$(nproc) cd .. ./packaging/pack_community_tar.sh -c debug -n 3.3.6.0

带全部可选参数的等价写法：

./packaging/pack_community_tar.sh \ -c debug \ -n 3.3.6.0 \ -m 3.0.0.0 \ -V stable

生成包输出到packaging/release/，典型产物为：

packaging/release/TDengine-server-3.3.6.0-Linux-x64.tar.gz packaging/release/TDengine-client-3.3.6.0-Linux-x64.tar.gz

从 packaging/pack_community_tar.sh 源码看，脚本通过getopts解析-c/-n/-m/-V参数（-h打印用法），并使用set -e保证出错即停；默认productName=TDengine、serverName=taosd、configFile=taos.cfg。服务端与客户端压缩包采用与既有打包流程一致的两层结构：外层为分发用 tarball，内层package.tar.gz包含bin/、cfg/、inc/三个目录。

5.2 打包内容范围

该脚本只打包由本仓库自身构建出的开源产物：

• taosd（服务端）
• taos（命令行客户端）
• taosBenchmark（BUILD_TOOLS=ON时存在）
• taosdump（BUILD_TOOLS=ON时存在）
• taosudf（存在时）
• libtaos.so
• libtaosnative.so
• 头文件、examples/c目录与安装脚本

它不打包位于其他仓库或需要独立构建流程的组件，例如taoskeeper、taos-explorer、taosx、各语言连接器以及taosinspect。这是仓库本地 OSS 制品的标准打包方式，后续仓库应保持一致。

6. 安装与运行

6.1 从安装包安装

对于由 packaging/tools/makepkg.sh 产出的官方安装包：

tar -xzf TDengine-server-<version>-Linux-x86_64.tar.gz cd TDengine-server-<version> sudo ./install.sh

如果是从本地源码构建树直接安装（而非打包归档），也可以：

cd debug sudo make install

install.sh脚本位于 packaging/tools/install.sh，负责将二进制、库、配置文件与启动脚本部署到系统目录。

6.2 启动服务并连接

# 安装后启动服务端 sudo systemctl start taosd # 使用 CLI 连接 taos

如需在构建树内快速本地运行：

cd debug ./build/bin/taosd -c test/cfg

另开一个终端连接：

cd debug ./build/bin/taos -c test/cfg

这里-c指定配置文件目录，构建树中test/cfg提供了一套便于本地调试的测试配置。

7. 持续集成工作流与测试覆盖率

TDengine 的构建检查工作流通过 GitHub Actions 中的taosd-ci-build.yml定义（见 README 的 Workflow 章节），更多工作流会陆续补充。

测试覆盖率方面，最新覆盖率报告可在 Coveralls 上查看。README 还给出了本地生成 HTML 覆盖率报告的方法：

cd tests bash setup-lcov.sh -v 1.16 && ./run_local_coverage.sh -b main -c task

其中-b指定分支、-c task指定运行longtimeruning_cases.task中的用例，更多选项可通过./run_local_coverage.sh -h查看。需要注意：-b与-i选项会以-DCOVER=true重新编译 TDengine，耗时较长。仓库中与覆盖率相关的脚本位于 test/ci/cov/。

8. 贡献与许可证

TDengine 以 GNU Affero General Public License 3.0 授权开源，许可证全文见 LICENSE。若你在使用过程中发现安全问题，可参考仓库的 SECURITY.md；社区构建、测试与 CI 相关的补充说明还可参考 test/ci/ 下的脚本与 tools/tdgpt/README.md。如需深入了解各模块的源码实现，仓库核心代码位于 source/（客户端、公共库、dnode 各节点与各类功能库），头文件定义集中在 include/，可直接按模块深入阅读。

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