TDengine IPv6 支持用户手册

TDengine IPv6 支持用户手册

概述

从 TDengine 3.3.7.0 版本开始，TDengine 支持 IPv6 网络协议。用户可以在 IPv6 环境中部署和使用 TDengine 集群，包括客户端连接、节点间通信、以及各种网络服务。

1. IPv6 功能特性

1.1 支持的 IPv6 功能

IPv6 地址解析和连接
IPv6 集群节点发现和通信
IPv6 客户端连接
IPv6 监控和管理接口
IPv6 白名单访问控制

1.2 支持的组件

TDengine 服务端 (taosd)
TDengine 客户端 (taos)
taosAdapter
taosKeeper
taosX
各语言连接器

2. 配置说明

2.1 启用 IPv6 支持

在 taos.cfg 配置文件中添加或修改以下配置项：

bash 复制代码

# 启用 IPv6 支持
enableIpv6 1

# 设置本地 FQDN (支持 IPv6 地址)
fqdn ::1

# 设置第一个端点 (IPv6 格式)
firstEp [::1]:6030

# 设置第二个端点 (可选)
secondEp [2001:db8::2]:6030

2.2 IPv6 地址格式规范

TDengine 支持以下 IPv6 地址格式：

bash 复制代码

# 标准 IPv6 地址
2001:db8::1

# IPv6 地址 + 端口号 (使用方括号)
[2001:db8::1]:6030

# IPv6 本地回环地址
::1

# IPv6 本地回环地址 + 端口号
[::1]:6030

# IPv6 零地址
::

# IPv4 映射的 IPv6 地址
::ffff:192.168.1.100

2.3 IPv4 与 IPv6 配置选择

bash 复制代码

# IPv4 模式 (默认)
enableIpv6 0
fqdn node1.example.com
firstEp 192.168.1.100:6030
secondEp 192.168.1.101:6030

# IPv6 模式
enableIpv6 1
fqdn [2001:db8::1]
firstEp [2001:db8::1]:6030
secondEp [2001:db8::2]:6030

:::warning
重要限制：

TDengine 不支持 IPv4/IPv6 双栈模式
enableIpv6 为 0 时使用 IPv4，为 1 时使用 IPv6
同一集群中的所有节点必须使用相同的 IP 协议版本
不支持同一集群中 IPv4 和 IPv6 节点混合部署
:::

3. 集群部署

3.1 IPv6 集群配置

所有节点都必须启用 IPv6 并使用 IPv6 地址：

节点 1 配置 (taos.cfg)

bash 复制代码

enableIpv6 1
fqdn [2001:db8::1]
firstEp [2001:db8::1]:6030
secondEp [2001:db8::2]:6030
serverPort 6030

节点 2 配置 (taos.cfg)

bash 复制代码

enableIpv6 1
fqdn [2001:db8::2]
firstEp [2001:db8::1]:6030
secondEp [2001:db8::2]:6030
serverPort 6030

节点 3 配置 (taos.cfg)

bash 复制代码

enableIpv6 1
fqdn [2001:db8::3]
firstEp [2001:db8::1]:6030
secondEp [2001:db8::2]:6030
serverPort 6030

3.2 添加 IPv6 节点到集群

sql 复制代码

-- 创建 dnode (IPv6 地址需要用方括号包围)
CREATE DNODE '[2001:db8::2]:6030';

-- 查看 dnode 状态
SHOW DNODES;

-- 删除 dnode
DROP DNODE '[2001:db8::3]:6030';

4. 客户端连接

4.1 taos 命令行客户端

bash 复制代码

# 使用 IPv6 地址连接
taos -h 2001:db8::1 -P 6030

# 使用 IPv6 地址连接（带方括号）
taos -h [2001:db8::1] -P 6030

# 连接到本地 IPv6 地址
taos -h ::1

# 使用完整的 endpoint 格式
taos -h [2001:db8::1]:6030

4.2 应用程序连接

C/C++ 连接示例

c 复制代码

#include <taos.h>

int main() {
    // IPv6 地址连接
    TAOS *conn = taos_connect("[2001:db8::1]", "root", "taosdata", NULL, 6030);
    
    if (conn == NULL) {
        printf("Failed to connect to TDengine server\n");
        return -1;
    }
    
    printf("Connected to TDengine server successfully\n");
    
    taos_close(conn);
    return 0;
}

Python 连接示例

python 复制代码

import taos

# IPv6 地址连接
conn = taos.connect(
    host='2001:db8::1',
    port=6030,
    user='root',
    password='taosdata'
)

# 或者使用完整格式
conn = taos.connect(
    host='[2001:db8::1]:6030',
    user='root',
    password='taosdata'
)

Java 连接示例

java 复制代码

import java.sql.*;

public class TDengineIPv6Example {
    public static void main(String[] args) {
        String jdbcUrl = "jdbc:TAOS://[2001:db8::1]:6030/test?user=root&password=taosdata";
        
        try {
            Connection conn = DriverManager.getConnection(jdbcUrl);
            System.out.println("Connected to TDengine via IPv6");
            conn.close();
        } catch (SQLException e) {
            e.printStackTrace();
        }
    }
}

Go 连接示例

go 复制代码

import (
    "database/sql"
    _ "github.com/taosdata/driver-go/v3/taosWS"
)

func main() {
    // IPv6 WebSocket 连接
    dsn := "root:taosdata@ws([2001:db8::1]:6041)/testdb"
    db, err := sql.Open("taosWS", dsn)
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()
}

Node.js 连接示例

javascript 复制代码

const taos = require('@tdengine/websocket');

// IPv6 WebSocket 连接
const dsn = 'ws://root:taosdata@[2001:db8::1]:6041';
const conn = taos.sqlConnect(dsn);

5. 网络服务配置

5.1 HTTP 服务 (taosAdapter)

taosAdapter 配置文件中启用 IPv6：

yaml 复制代码

# taosadapter.toml
[http]
enable = true
port = 6041

# 监听 IPv6 地址
address = "::"  # 监听所有 IPv6 地址
# 或指定特定 IPv6 地址
# address = "2001:db8::1"

5.2 监控服务 (taosKeeper)

yaml 复制代码

# taoskeeper.toml
[server]
port = 6043

# IPv6 监听地址
address = "::"

5.3 MQTT 服务

bash 复制代码

# taos.cfg 中配置 MQTT IPv6
mqttPort 6083
# MQTT 服务的 IPv6 支持依赖于整体的 enableIpv6 配置
enableIpv6 1

6. 安全和访问控制

6.1 IPv6 白名单配置

TDengine 支持基于 IPv6 地址的访问控制：

sql 复制代码

-- 创建用户并设置 IPv6 白名单
CREATE USER ipv6user PASS 'password';

-- 添加 IPv6 地址到白名单
ALTER USER ipv6user ADD WHITELIST '2001:db8::/64';

-- 添加特定 IPv6 地址
ALTER USER ipv6user ADD WHITELIST '2001:db8::100/128';

-- 查看用户白名单
SHOW USER ipv6user;

6.2 防火墙配置

确保 IPv6 防火墙允许相关端口：

bash 复制代码

# Ubuntu/Debian 系统
sudo ufw allow 6030/tcp
sudo ufw allow 6041/tcp

# CentOS/RHEL 系统  
sudo firewall-cmd --permanent --add-port=6030/tcp
sudo firewall-cmd --permanent --add-port=6041/tcp
sudo firewall-cmd --reload

# 专门针对 IPv6
sudo ip6tables -A INPUT -p tcp --dport 6030 -j ACCEPT

7. 故障排查

7.1 连接问题诊断

检查 IPv6 网络连通性

bash 复制代码

# 测试 IPv6 连通性
ping6 2001:db8::1

# 测试端口连通性
nc -6 -v 2001:db8::1 6030

# 使用 telnet 测试
telnet 2001:db8::1 6030

检查服务监听状态

bash 复制代码

# 查看 IPv6 监听端口
ss -lntp | grep :6030
netstat -lntp | grep :6030

# 专门查看 IPv6 监听
ss -6 -lntp | grep :6030

7.2 常见错误和解决方案

错误：无法解析 IPv6 地址

bash 复制代码

# 检查系统 IPv6 支持
cat /proc/sys/net/ipv6/conf/all/disable_ipv6

# 如果返回 1，表示 IPv6 被禁用，需要启用
echo 0 | sudo tee /proc/sys/net/ipv6/conf/all/disable_ipv6

错误：IPv6 地址格式错误

确保在配置文件中使用正确的格式
带端口的 IPv6 地址必须用方括号包围：[::1]:6030
不带端口的 IPv6 地址可以直接使用：::1

错误：连接被拒绝

bash 复制代码

# 检查 TDengine 服务状态
systemctl status taosd

# 检查配置文件
grep -i enableIpv6 /etc/taos/taos.cfg

# 查看日志
tail -f /var/log/taos/taosdlog.0

7.3 日志分析

在 TDengine 日志中查找 IPv6 相关信息：

bash 复制代码

# 查看连接日志
grep -i "ipv6\|::1\|2001:db8" /var/log/taos/taosdlog.0

# 查看网络相关错误
grep -i "network\|connection\|bind" /var/log/taos/taosdlog.0

8. 性能优化

8.1 网络配置优化

bash 复制代码

# 调整 IPv6 网络参数
echo 'net.ipv6.conf.all.accept_ra = 1' >> /etc/sysctl.conf
echo 'net.ipv6.conf.default.accept_ra = 1' >> /etc/sysctl.conf
echo 'net.core.rmem_max = 16777216' >> /etc/sysctl.conf
echo 'net.core.wmem_max = 16777216' >> /etc/sysctl.conf

# 应用配置
sysctl -p

8.2 TDengine 配置优化

bash 复制代码

# taos.cfg 中的网络相关配置
numOfRpcThreads 8
readTimeout 900
shellActivityTimer 3
compressMsgSize -1

# IPv6 特定优化
enableIpv6 1

9. 监控和维护

9.1 IPv6 连接监控

使用系统监控工具监控 IPv6 连接：

bash 复制代码

# 监控 IPv6 连接数
ss -6 -an | grep :6030 | wc -l

# 实时监控连接
watch -n 1 'ss -6 -tn | grep :6030'

9.2 TDengine 内置监控

sql 复制代码

-- 查看连接信息
SHOW CONNECTIONS;

-- 查看集群状态
SHOW DNODES;
SHOW VNODES;

-- 查看网络统计
SHOW SCORES;

10. 迁移指南

10.1 从 IPv4 迁移到 IPv6

由于 TDengine 不支持 IPv4/IPv6 混合部署，迁移需要完整重建集群：

准备阶段

备份所有数据和配置文件
记录当前的集群配置和用户权限
确保 IPv6 网络环境已正确配置

迁移步骤

停止所有 TDengine 服务

bash 复制代码

systemctl stop taosd
systemctl stop taosadapter
systemctl stop taoskeeper

修改配置文件

bash 复制代码

# 在所有节点的 taos.cfg 中添加
enableIpv6 1
fqdn [IPv6地址]
firstEp [IPv6地址]:6030
secondEp [IPv6地址]:6030

清理旧的集群数据（如果需要）

bash 复制代码

# 注意：这会删除所有数据
rm -rf /var/lib/taos/*

按顺序启动服务

bash 复制代码

# 先启动第一个节点
systemctl start taosd

# 确认启动成功后，启动其他节点
systemctl start taosd

重新创建集群
sql 复制代码
```
CREATE DNODE '[IPv6地址]:6030';
```

11. 注意事项

11.1 系统要求

操作系统必须支持 IPv6 协议栈
网络环境需要正确配置 IPv6 路由
DNS 需要支持 AAAA 记录解析

11.2 兼容性说明

IPv6 功能在 TDengine 3.3.7.0+ 版本中可用
不支持 IPv4/IPv6 双栈模式
不支持同一集群中 IPv4 和 IPv6 混合部署
所有节点的 firstEp、secondEp、fqdn 都必须能解析为相同协议版本的地址

11.3 安全考虑

IPv6 地址空间巨大，建议使用白名单进行访问控制
定期检查和更新 IPv6 防火墙规则
监控异常的 IPv6 连接尝试

11.4 限制说明

不支持动态修改 enableIpv6 参数，需要重启服务
部分第三方工具可能不完全支持 IPv6
某些操作系统的 IPv6 实现可能存在差异
建议在生产环境使用前充分测试

12. 参考资源

TDengine 官方文档：https://docs.taosdata.com
IPv6 RFC 文档：RFC 2460, RFC 4291
网络配置最佳实践文档
TDengine 社区论坛和技术支持

13. 常见问题 FAQ

Q: TDengine 支持 IPv4/IPv6 双栈吗？

A: 不支持 。TDengine 只能选择使用 IPv4 或 IPv6，通过 enableIpv6 参数控制，不支持双栈模式。

Q: 可以在同一集群中混合使用 IPv4 和 IPv6 节点吗？

A: 不可以。同一集群中的所有节点必须使用相同的 IP 协议版本。

Q: 如何从 IPv4 集群迁移到 IPv6？

A: 需要完整重建集群，不支持在线迁移。建议按照迁移指南进行操作。

Q: enableIpv6 参数可以动态修改吗？

A: 不可以。该参数不支持动态修改，修改后需要重启 taosd 服务。

Q: IPv6 环境下性能与 IPv4 有差异吗？

A: 在正确配置的网络环境中，性能差异很小。

Q: 如何确认 TDengine 正在使用 IPv6？

A: 检查配置文件中的 enableIpv6 参数，或使用 ss -6 -lntp 查看监听端口。

Q: 如何处理 IPv6 地址的 DNS 解析问题？

A: 确保 DNS 服务器配置了正确的 AAAA 记录，并且系统的 resolver 配置正确。

通过本手册，用户应该能够正确理解和配置 TDengine 的 IPv6 支持。如有其他问题，请参考官方文档或联系技术支持。