企业官网建设流程全解析

TDengine 网络配置实战：IPv6 支持、TLS 加密通信与源码级解析

【免费下载链接】tdengineTDengine is an open source, high-performance, cloud native time-series database optimized for Internet of Things (IoT), Connected Cars, Industrial IoT and DevOps.项目地址: https://gitcode.com/taosdata/tdengine

本文聚焦 TDengine 网络层的两大能力：自 3.3.7.0 起提供的 IPv6 网络环境支持，以及自 3.3.8 起提供的传输层 TLS 加密通信。文中完整给出服务端与客户端的配置步骤、证书生成与部署示例，并结合仓库源码说明enableIPv6、enableTLS等参数的注册位置与 IPv6 监听、连接的底层实现，帮助运维与开发人员在生产网络中正确启用并排障。

一、IPv6 支持概览

1.1 版本与组件范围

自 TDengine 3.3.7 版本起，官方全面支持 IPv6 网络环境，允许在纯 IPv6 或 IPv4/IPv6 双栈基础设施中部署和访问 TDengine，解除对 IPv4 的依赖。支持范围如下：

• 支持版本：TDengine 服务端与客户端 >= 3.3.7.0；
• 支持组件：
  • taosd：TDengine 数据库服务端；
  • taos：命令行客户端（CLI）；
  • 各类连接器（JDBC、Go、Python、C#、Rust 等），须使用支持 IPv6 的版本；
• 网络环境：纯 IPv6 与双栈 IPv4/IPv6 环境均支持。

1.2 服务端（taosd）配置

启用 IPv6 需要修改 taosd 的配置文件taos.cfg（默认路径/etc/taos/taos.cfg），仓库中随安装包下发的配置模板见 taos.cfg。关键参数如下：

// 设置 TDengine 服务端监听指定网卡接口的 IPv6 地址；设为 "::" 表示监听所有可用的 IPv6 接口。 serverIPv6 :: firstEp ipv6_address1:port secondEp ipv6_address2:port fqdn ipv6_address1 enableIPv6 1

参数说明：

• serverIPv6：指定服务端绑定的 IPv6 地址；配置为::时监听本机全部 IPv6 接口。
• firstEp/secondEp：本地节点在集群中的端点（地址:端口），可分别指向 IPv6 与 IPv4 地址，即双栈部署下的一主一备端点表达。
• fqdn：本节点的全限定域名。
• enableIPv6：IPv6 总开关，置1生效。

从源码结构看，该开关在服务端与客户端两侧的公共配置中注册。在 tglobal.c 中可以看到配置项enableIpv6以CFG_SCOPE_BOTH（服务端和客户端均生效）注册，且全局校验逻辑会依据它选择解析 fqdn 时的地址族：

// source/common/src/tglobal.c TAOS_CHECK_RETURN( cfgAddBool(pCfg, "enableIpv6", tsEnableIpv6, CFG_SCOPE_BOTH, CFG_DYN_NONE, CFG_CATEGORY_LOCAL, CFG_PRIV_SYSTEM)); ... int32_t code = taosGetIpFromFqdn(tsEnableIpv6, tsLocalFqdn, &addr);

监听侧同样体现了这一开关：传输层服务端初始化时，若启用了 IPv6，则构造 IPv6 监听地址并绑定::（见 transSvr.c）：

// source/libs/transport/src/transSvr.c if (srv->ipv6) { struct sockaddr_in6 bind_addr; if ((code = uv_ip6_addr("::", srv->port, &bind_addr)) != 0) { ... } }

修改配置后必须重启服务才能生效：

sudo systemctl restart taosd

重要建议：强烈建议使用 FQDN 而非直接 IP 配置firstEp/secondEp。通过 DNS 解析自动选择 IPv6 地址，在双栈环境中灵活性和兼容性更好。默认端口 6030 对 IPv6 连接同样适用。

1.3 客户端连接方式

方式一：使用 FQDN（推荐）。在客户端的taos.cfg或连接串中使用服务器域名，只要该域名的 AAAA 记录正确指向 IPv6 地址，客户端即自动走 IPv6 连接：

taos -h your_server_fqdn -P 6030

从源码结构看，客户端通过getaddrinfo解析 fqdn，优先识别AF_INET6结果族（见 osSocket.c 中taosGetIpFromFqdn的实现），连接阶段再按地址类型构造sockaddr_in6并调用inet_pton(AF_INET6, ...)完成地址转换（见 transCli.c）。

方式二：直接使用 IPv6 地址。注意 IPv6 地址在命令行或连接串中必须用方括号包裹：

taos -h [2001:db8::1] -P 6030

验证连接：连接成功后，可在 TDengine 日志中确认所有连接均通过 IPv6 建立。仓库中也提供了传输层 IPv6 的单元/集成测试 transUTIPv6.cpp 可作为行为验证参考。

1.4 IPv6 注意事项与排障

• 网络基础设施：确保服务器、客户端及所有中间路由器/防火墙都正确配置了 IPv6，并放行默认端口 6030；
• DNS 配置：使用 FQDN 时，确认 DNS 上配置的是 AAAA 记录（指向 IPv6），而不是 A 记录（指向 IPv4）；
• 双栈环境优先级：在同时支持 IPv4 与 IPv6 的主机上，应显式让 FQDN 解析到 IPv6 地址；
• 连接器版本：JDBC、Go、Python 等所有客户端连接器需升级至 3.3.7.0 及以上版本，才能获得完整的 IPv6 兼容性。

二、TLS 加密通信配置

2.1 参数一览

自 TDengine 3.3.8 起，传输层提供加密通信支持，涉及 6 个配置参数：

这些参数在源码中同样注册于 tglobal.c 的公共配置表，且均标记为不可动态修改（CFG_DYN_NONE，enableTLS例外标记为可动态），权限类别为CFG_PRIV_SECURITY，路径值均受PATH_MAX长度校验约束。

2.2 查看 TLS 参数

在 SQL 中可查看各节点的 TLS 文件路径配置：

SHOW VARIABLES LIKE '%tls%';

注意：该命令用于查看集群中每个节点上的 TLS 证书文件路径，排查两端证书不一致问题时非常有用。

2.3 约束条件（务必理解）

1. 服务端：启用 TLS 必须配置齐全部 5 个证书/密钥参数，任一缺失即启动失败；若 5 个参数全部未配置，则服务端以非 TLS 模式正常启动。
2. 客户端：启用 TLS 必须配置tlsCaPath/tlsCliCertPath/tlsCliKeyPath（即参数 1/4/5），任一缺失即启动失败；若三者全部未配置，则以非 TLS 模式启动。
3. 集群所有节点必须统一以 TLS 模式或非 TLS 模式启动；混合模式下节点间无法通信。
4. 非 TLS 客户端无法访问启用了 TLS 的集群（连接失败）。
5. 启用了 TLS 的客户端无法访问非 TLS 集群（连接失败）。
6. 启用 TLS 后，所有网络数据传输都经过双向认证（mutual authentication）。即便是单个 taosd，其内部 RPC 通信也需要双向认证。

2.4 部署示例

第一步：生成证书（自签 CA + 服务端证书 + 客户端证书）：

openssl req -newkey rsa:2048 -nodes -keyout ca.key -x509 -days 365 -out ca.crt -subj "/CN=MyCA" # 生成服务端私钥和 CSR openssl genrsa -out server.key 2048 openssl req -new -key server.key -out server.csr -subj "/CN=localhost" # CN 通常为服务器域名或 IP # 使用 CA 签发服务端证书 openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 365 # 生成客户端私钥和 CSR openssl genrsa -out client.key 2048 openssl req -new -key client.key -out client.csr -subj "/CN=Client" # 使用 CA 签发客户端证书 openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt -days 365

仓库的 TLS 回归测试用例目录 73-TLS 中还附带了证书批量生成脚本tlsFileGen.sh，其产物被 test_tls.py 用于端到端验证 TLS 集群的部署与连接流程，可参考其证书组织方式。

第二步：客户端配置（客户端taos.cfg）：

tlsCliKeyPath /path/client.key tlsCliCertPath /path/client.crt tlsCaPath /path/ca.crt enableTLS 1

第三步：服务端配置（服务端taos.cfg，比客户端多两个服务端专用参数）：

tlsCliKeyPath /path/client.key tlsCliCertPath /path/client.crt tlsSvrKeyPath /path/server.key tlsSvrCertPath /path/server.crt tlsCaPath /path/ca.crt enableTLS 1

第四步：启动服务端，并使用客户端连接验证。

2.5 性能影响与运维升级

• 性能：开启 TLS 会带来一定开销，官方口径为整体性能通常下降 5% 以内（吞吐量保持在原来的 96%～99%）。
• 运维升级：不支持动态升级。由于所有 TLS 参数（除开关外）均不可动态修改，切换 TLS 模式需要停机并重启所有节点，请提前规划变更窗口；同时牢记第 2.3 节的约束：集群内模式必须统一，客户端与服务端的 TLS 状态必须匹配，否则连接直接失败。

三、小结

TDengine 的网络能力由两条主线构成：IPv6 通过enableIPv6开关、serverIPv6绑定地址与 fqdn/AAA 解析链实现（底层由 transSvr.c 的AF_INET6监听与 transCli.c 的 IPv6 连接构造支撑）；TLS 则通过 5 个证书/密钥路径参数加enableTLS开关实现全链路双向认证，参数注册与长度校验集中在 tglobal.c。两者均以重启生效为原则（CFG_DYN_NONE），配置时必须保证服务端、客户端与集群内所有节点的状态一致，方能稳定运行于纯 IPv6 或加密通信环境。

本文基于当前仓库的 网络配置文档 及相关源码整理，适用前提为 TDengine >= 3.3.7.0（IPv6）与 >= 3.3.8（TLS）；具体参数默认值请以所安装版本随附的taos.cfg为准。

【免费下载链接】tdengineTDengine is an open source, high-performance, cloud native time-series database optimized for Internet of Things (IoT), Connected Cars, Industrial IoT and DevOps.项目地址: https://gitcode.com/taosdata/tdengine