场景：在 Linux 服务器上安装 TDengine 服务端，然后在 Mac 本地连接使用。 适用版本：TDengine 3.x（社区版，当前稳定版 3.3.6） 最后更新：2026-07-18
目录
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
参考资料：