TDengine 安装与远程连接完整教程

场景：在 Linux 服务器上安装 TDengine 服务端，然后在 Mac 本地连接使用。 适用版本：TDengine 3.x（社区版，当前稳定版 3.3.6） 最后更新：2026-07-18

---

目录

1. 整体架构与连接方式
2. Linux 服务端安装
3. 服务启动与管理
4. FQDN 配置（TDengine 的关键特性）
5. 开放网络端口
6. Mac 本地连接（四种方式）
7. 常见问题排查
8. 面试要点速记

---

1. 整体架构与连接方式

TDengine 的服务端进程 taosd 只能在 Linux/Unix 上运行（Windows/macOS 暂不支持服务端）。Mac 作为客户端，有多种方式连接 Linux 上的 TDengine：

连接方式	端口	协议	是否需装客户端驱动	适用场景
Native（taosc）	6030	私有二进制协议	是，需装 macOS 客户端	性能最高，taos CLI、JDBC-JNI 都走这个
RESTful / WebSocket	6041	HTTP/WS	否，任何 HTTP 客户端即可	跨语言、跨平台最方便
JDBC-REST	6041	HTTP	否，仅一个 jar 包	Java 应用不想装 native 驱动时
JDBC-JNI	6030	私有协议	是，需装客户端 + JNI	Java 应用追求最高性能

⚠️ 重点：TDengine 用 FQDN（完全限定域名） 标识节点，不是 IP。这是它和 MySQL/Redis 等最大的区别，远程连接必须先解决 FQDN 解析问题。

---

2. Linux 服务端安装

2.1 环境准备

# 查看系统架构（x64 / arm64）
uname -m
​
# 查看系统版本
cat /etc/os-release
​
# 确保有 root / sudo 权限
sudo -v

TDengine 3.x 支持 x64 和 arm64，CentOS 7+/Ubuntu 18.04+/Debian 10+ 等主流发行版。

2.2 方式一：apt-get 安装（Ubuntu/Debian 推荐）

# 1. 添加官方仓库签名和源
wget -qO - http://repos.taosdata.com/tdengine.key | sudo apt-key add -
echo "deb [arch=amd64] http://repos.taosdata.com/tdengine-stable stable main" \
  | sudo tee /etc/apt/sources.list.d/tdengine-stable.list
​
# 2. 更新索引并安装
sudo apt-get update
sudo apt-get install -y tdengine

arm64 机器把 [arch=amd64] 改成 [arch=arm64]。

2.3 方式二：deb 包安装（离线 Ubuntu/Debian）

从官网下载页 https://docs.taosdata.com/releases/tdengine/ 获取类似 TDengine-server-3.3.6.13-Linux-x64.deb：

sudo dpkg -i TDengine-server-3.3.6.13-Linux-x64.deb
​
# 若提示缺依赖，补一下
sudo apt-get install -f -y

2.4 方式三：rpm 包安装（CentOS/RHEL）

sudo rpm -ivh TDengine-server-3.3.6.13-Linux-x64.rpm

2.5 方式四：tar.gz 安装（通用，无包管理器时）

# 解压
tar -zxvf TDengine-server-3.3.6.13-Linux-x64.tar.gz
cd TDengine-server-3.3.6.13
​
# 执行安装脚本（交互式，会问几个配置问题，回车走默认即可）
sudo ./install.sh
​
# 自定义安装目录示例：
# sudo ./install.sh -e no -d /opt/tdengine

安装完成后的默认目录结构：

路径	说明
/usr/local/taos/bin/	可执行文件：taosd、taos、taosAdapter、taosdump 等
/etc/taos/taos.cfg	主配置文件
/var/lib/taos/	数据目录
/var/log/taos/	日志目录

---

3. 服务启动与管理

TDengine 安装后会注册 systemd 服务 taosd：

# 启动
sudo systemctl start taosd
​
# 停止（会等数据落盘，数据量大时较慢，属正常现象）
sudo systemctl stop taosd
​
# 重启
sudo systemctl restart taosd
​
# 查看状态（看到 active (running) 即正常）
sudo systemctl status taosd
​
# 设置开机自启
sudo systemctl enable taosd

同时建议启动 taosAdapter（提供 RESTful/WebSocket 接口，Mac 远程连接会用到）：

sudo systemctl start taosadapter
sudo systemctl enable taosadapter
sudo systemctl status taosadapter

本地验证

在服务器上直接连：

taos

进入 CLI 后：

taos> SHOW DATABASES;
taos> CREATE DATABASE test_db VGROUPS 2;
taos> USE test_db;
taos> CREATE TABLE t (ts TIMESTAMP, v INT);
taos> INSERT INTO t VALUES (NOW, 1);
taos> SELECT * FROM t;
taos> exit;

能查到数据就说明服务端 OK。

---

4. FQDN 配置（TDengine 的关键特性）

TDengine 用 FQDN 而非 IP 标识节点，远程连接前必须配置好。

4.1 查看服务器当前 FQDN

hostname -f
# 例如输出: tdnode1

4.2 设置 FQDN（如未设置）

# 临时设置
sudo hostnamectl set-hostname tdnode1
​
# 永久生效：编辑 /etc/hosts，把本机 IP 和 FQDN 绑定
# 假设服务器内网 IP 是 192.168.1.100
sudo vim /etc/hosts

/etc/hosts 内容示例：

127.0.0.1   localhost
192.168.1.100  tdnode1

4.3 修改 taos.cfg（可选但推荐）

编辑 /etc/taos/taos.cfg，确认/修改：

# 节点 FQDN（默认会读 hostname，但显式指定更稳）
fqdn tdnode1
​
# 服务端口（默认 6030）
serverPort 6030

改完重启服务：

sudo systemctl restart taosd

4.4 验证 FQDN 可解析

在服务器本机：

ping -c 2 tdnode1

能 ping 通说明 FQDN 配置成功。

---

5. 开放网络端口

TDengine 使用一组端口，TCP 和 UDP 都要开：

端口	协议	用途
6030	TCP+UDP	taosd 客户端连接（native）
6041	TCP	taosAdapter RESTful / WebSocket
6043	TCP	taosd 内部
6044	UDP	taosd 内部
6045	UDP	taosd 内部
6046-6049	TCP+UDP	taosd 内部

最简实践：Mac 远程连接至少开 6030（native）和 6041（RESTful）。

5.1 防火墙（firewalld，CentOS）

sudo firewall-cmd --permanent --add-port=6030/tcp
sudo firewall-cmd --permanent --add-port=6030/udp
sudo firewall-cmd --permanent --add-port=6041/tcp
sudo firewall-cmd --reload

5.2 防火墙（ufw，Ubuntu）

sudo ufw allow 6030/tcp
sudo ufw allow 6030/udp
sudo ufw allow 6041/tcp

5.3 云服务器安全组

如果是阿里云/腾讯云/AWS 等，还要在控制台安全组里放行上述端口。

---

6. Mac 本地连接（四种方式）

假设服务器信息：

• 内网 IP：192.168.1.100
• FQDN：tdnode1
• TDengine 版本：3.3.6

6.1 前置：配置 Mac 的 /etc/hosts 解析 FQDN

这是最关键的一步，否则会报 Unable to resolve FQDN。

sudo vim /etc/hosts

添加一行：

192.168.1.100  tdnode1

验证：

ping -c 2 tdnode1

6.2 方式 A：安装 macOS 客户端 + taos CLI（native 连接）

步骤 1：下载 macOS 客户端包

到 https://docs.taosdata.com/releases/tdengine/ 下载对应架构的客户端：

• Apple Silicon（M1/M2/M3）：TDengine-client-3.3.6.X-macos-arm64.pkg
• Intel Mac：TDengine-client-3.3.6.X-macos-x64.pkg

步骤 2：安装

双击 .pkg 按提示安装。若被 Gatekeeper 拦截，右键 → 打开。

步骤 3：配置 firstEp

编辑 /etc/taos/taos.cfg（Mac 上的客户端配置）：

firstEp tdnode1:6030

注意：Mac 上只装客户端、不跑服务端，所以只需配 firstEp，不需要配 fqdn。

步骤 4：连接验证

taos -h tdnode1 -P 6030

或直接 taos（会读 taos.cfg 的 firstEp）：

taos

成功进入 taos> 提示符即 OK：

taos> SHOW DATABASES;
taos> SELECT SERVER_VERSION();

6.3 方式 B：RESTful 方式（curl，无需装客户端）

通过 taosAdapter 的 6041 端口，标准 HTTP 请求即可。无需在 Mac 装任何东西：

# 基本格式：
# curl -u <user>:<pass> -d '<SQL>' <host>:6041/rest/sql
​
# 查询数据库列表
curl -u root:taosdata \
  -d 'SHOW DATABASES' \
  192.168.1.100:6041/rest/sql
​
# 查询版本
curl -u root:taosdata \
  -d 'SELECT SERVER_VERSION()' \
  192.168.1.100:6041/rest/sql

默认账号 root / 密码 taosdata。返回 JSON。

RESTful 方式适合脚本、Postman、任何语言快速接入，是最方便的远程连接方式。

6.4 方式 C：JDBC-REST（Java 开发者推荐，免装 native 驱动）

这是 Java 应用远程连接 TDengine 最省事的方式，Mac 上只需一个 jar 包，不用装任何客户端驱动。

Maven 依赖：

<dependency>
    <groupId>com.taosdata.jdbc</groupId>
    <artifactId>taos-jdbcdriver</artifactId>
    <version>3.3.3</version>
</dependency>

JDBC URL 格式（REST 模式）：

jdbc:TAOS-RS://192.168.1.100:6041/test_db?user=root&password=taosdata

• TAOS-RS = REST 协议
• 端口 6041（taosAdapter）
• 不需要 Mac 配 /etc/hosts，直接用 IP 即可

示例代码：

import java.sql.*;
​
public class TDengineRestDemo {
    public static void main(String[] args) throws Exception {
        String url = "jdbc:TAOS-RS://192.168.1.100:6041/test_db?user=root&password=taosdata";
​
        try (Connection conn = DriverManager.getConnection(url);
             Statement stmt = conn.createStatement()) {
​
            // 建库建表（如果 test_db 已存在可省略）
            stmt.execute("CREATE DATABASE IF NOT EXISTS test_db");
            stmt.execute("USE test_db");
            stmt.execute("CREATE STABLE IF NOT EXISTS meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT)");
​
            // 写入
            stmt.executeUpdate("INSERT INTO d1001 USING meters TAGS('Beijing', 2) VALUES (NOW, 10.3, 219, 0.31)");
​
            // 查询
            try (ResultSet rs = stmt.executeQuery("SELECT * FROM meters")) {
                ResultSetMetaData meta = rs.getMetaData();
                while (rs.next()) {
                    for (int i = 1; i <= meta.getColumnCount(); i++) {
                        System.out.print(meta.getColumnName(i) + "=" + rs.getString(i) + "  ");
                    }
                    System.out.println();
                }
            }
        }
    }
}

6.5 方式 D：JDBC-JNI（追求最高性能时）

走 native 协议（6030），性能比 REST 高 2-5 倍，但必须先在 Mac 装 6.2 节的客户端驱动 + 配好 firstEp 和 /etc/hosts。

JDBC URL 格式（native 模式）：

jdbc:TAOS://tdnode1:6030/test_db?user=root&password=taosdata

• TAOS（不带 -RS）= native 协议
• 端口 6030
• 必须用 FQDN（tdnode1），不能用 IP，且 Mac 的 /etc/hosts 要能解析

依赖、代码和方式 C 完全一样，只换 URL。

6.6 方式对比与选型建议

方式	性能	部署成本	适用场景
taos CLI（native）	高	需装客户端	日常运维、调试 SQL
curl / RESTful	中	零依赖	脚本、快速验证、非 Java 语言
JDBC-REST	中	一个 jar	Java 应用远程连接，最推荐起步方案
JDBC-JNI	最高	jar + native 驱动	生产环境高性能 Java 应用

实践建议：开发/测试用 JDBC-REST 省事；上生产对延迟敏感时切 JDBC-JNI。

---

7. 常见问题排查

7.1 Unable to resolve FQDN

原因：Mac 无法把 FQDN 解析成 IP。

解决：检查 Mac /etc/hosts 是否有 192.168.1.100 tdnode1，ping tdnode1 能通即可。

7.2 Failed to connect to server, ... reason: 0x216

原因：服务端未启动或端口不通。

解决：

# 服务器上检查
sudo systemctl status taosd
sudo netstat -tlnp | grep 6030
​
# Mac 上测试端口
nc -zv 192.168.1.100 6030
nc -zv 192.168.1.100 6041

7.3 RESTful 401 Unauthorized

原因：账号密码错。默认 root / taosdata，首次登录后建议改密码：

taos> ALTER USER root PASS '新密码';

7.4 客户端与服务端版本不匹配

3.4.0.0 起企业版与社区版不完全兼容，会报 Edition not compatible。确保 Mac 客户端版本与服务端一致或更接近，社区版客户端连社区版服务端。

查看版本：

taos --version          # 客户端
taos> SELECT SERVER_VERSION();   # 服务端

7.5 云服务器连不上

九成是安全组没放行。到云控制台安全组规则里加 6030（TCP+UDP）和 6041（TCP）。

7.6 时区问题

RESTful 返回时间戳时区异常时，JDBC URL 加参数：

jdbc:TAOS-RS://host:6041/db?timezone=Asia/Shanghai

---

8. 面试要点速记

针对 Java 后端面试，TDengine 相关可聊的点：

8.1 TDengine 与传统数据库的区别

• 时序数据库：为时序数据优化，写入吞吐高、按时间范围查询快
• FQDN 标识节点：而非 IP，这是分布式集群寻址的基础
• 超级表（STable）+ 子表模型：一个设备一张子表，超级表定义 schema，查询自动聚合
• 标签（TAG）与数据分离：标签存在元数据，查询过滤不扫数据文件

8.2 为什么 TDengine 用 FQDN 而非 IP

• 集群节点 IP 可能变（DHCP、容器迁移），FQDN 稳定
• 配合 DNS 做 load balance 和故障切换
• 多网卡环境下 IP 歧义，FQDN 明确

8.3 native vs REST 连接的取舍

• native（6030）：私有二进制协议，连接池复用、批量写入压缩，性能高但需装客户端
• REST（6041）：HTTP，跨平台零依赖，但有 HTTP 开销和 JSON 序列化成本
• 生产选 native，开发/异构环境选 REST

8.4 可以聊的延伸

• 写入路径：WAL → 内存 buffer → 落盘（data/last 文件）
• 列式存储 + 时间分片（VGroup）
• 副本数（replica）与一致性
• taosAdapter 的作用：把 TDengine 暴露成 REST/WebSocket，还对接 Telegraf、Prometheus、Grafana

---

附录：快速操作清单

# ===== Linux 服务端 =====
sudo apt-get install -y tdengine            # 安装
sudo systemctl start taosd taosadapter      # 启动
sudo systemctl enable taosd taosadapter     # 开机自启
hostnamectl set-hostname tdnode1            # 设 FQDN
# /etc/hosts 加: 192.168.1.100 tdnode1
# /etc/taos/taos.cfg 确认 fqdn tdnode1
# 防火墙放行 6030(tcp/udp) 6041(tcp)
​
# ===== Mac 客户端 =====
# /etc/hosts 加: 192.168.1.100 tdnode1
# 装 macOS 客户端 pkg
# /etc/taos/taos.cfg 配 firstEp tdnode1:6030
taos                                         # native 连接
​
# ===== Mac RESTful（零依赖） =====
curl -u root:taosdata -d 'SHOW DATABASES' 192.168.1.100:6041/rest/sql
​
# ===== Mac JDBC-REST =====
# jdbc:TAOS-RS://192.168.1.100:6041/test_db?user=root&password=taosdata

---

参考资料：

• 官方文档：https://docs.taosdata.com/
• 安装包下载：https://docs.taosdata.com/releases/tdengine/
• 连接指南：https://docs.tdengine.com/develop/connect/
• JDBC 驱动：https://mvnrepository.com/artifact/com.taosdata.jdbc/taos-jdbcdriver