前言：为什么选择 REST 方式连接？
TDengine（涛思数据库）作为开源高性能时序数据库，已与帆软（FineReport）完成官方适配，支持作为数据源用于报表可视化。在众多连接方式中，REST 无客户端方案是最优选择 ------ 无需安装 TDengine 本地客户端，跨 Windows/Linux/macOS 平台，仅需开放 6041 端口，即可避免 "本地库加载失败" 等常见问题，适配性和稳定性拉满。
本文将基于 taos-jdbcdriver-3.8.2-dist.jar（完整依赖包，无需额外补全依赖），详细讲解 FineReport11 设计器与服务器端的配置步骤，同时解答驱动选型、报错排查等关键问题。
一、前置准备（3 步必做）
1. 环境要求确认
|------------|--------------------------------|---------------------|
| 组件 | 版本要求 | 备注 |
| FineReport | 11.x 任意版本 | 设计器 / 服务器端通用 |
| TDengine | 3.x（推荐 3.3.6+） | 2.x 需调整 URL 格式（见文末） |
| JDBC 驱动 | taos-jdbcdriver-3.8.2-dist.jar | 完整打包版，自带所有依赖 |
| 网络端口 | 6041（TCP 入站） | REST 连接专用端口 |
2. 下载驱动包
- 直接下载：taos-jdbcdriver-3.8.2-dist.jar（带 dist 后缀为完整包，优先选择）
3. 驱动包部署（设计器 / 服务器通用）
- 找到 FineReport 安装目录下的 lib 文件夹（11以下版本方法）：
-
- 设计器：FineReport_11\webapps\webroot\WEB-INF\lib
-
- 服务器：FineReport_11\webapps\webroot\WEB-INF\lib（或 Tomcat 对应目录）
- 1将 taos-jdbcdriver-3.8.2-dist.jar 复制到该目录
- 2必须重启 FineReport 设计器 / 服务器（否则驱动无法加载）
2.fr11版本可以直接在管理系统-数据连接-数据连接管理-驱动管理
新建驱动-上传对应的.jar文件，选择驱动com.taosdata.jdbc.rs.RestfulDriver 即可
-
- 注意：目录中不要保留多个 TDengine 驱动包，避免版本冲突
4. TDengine 服务准备
- 确保 TDengine 服务（taosd）已启动
- 确保 taosAdapter 组件正常运行（REST 连接依赖此组件，默认随 TDengine 启动）
- 提前创建目标数据库（如 testdb），账号密码默认：root/taosdata
二、设计器端配置（本地开发首选）
步骤 1：打开数据连接界面
- 启动 FineReport11 设计器
- 顶部菜单栏 → 「服务器」→「定义数据连接」（快捷键：无，需手动点击）
- 左侧点击「+」号 → 选择「JDBC」（不要选其他类型）
步骤 2：核心配置（直接照抄，仅改 IP / 库名）
|-------|-----------------------------------------------------------------------|------------------------------------------------------------------------|
| 配置项 | 填写内容 | 说明 |
| 连接名称 | TDengine_REST（自定义，便于识别） | 无特殊限制，建议包含 "TDengine" 和 "REST" 关键词 |
| 数据库类型 | others（其他） | FineReport 未内置 TDengine 专属类型，选 "其他" 即可 |
| 驱动类型 | 自定义 | 手动填写驱动类，不要选系统自带选项 |
| 驱动类 | com.taosdata.jdbc.rs.RestfulDriver | REST 连接专用驱动类，核心关键！ |
| URL | jdbc:TAOS-RS://192.168.1.100:6041/testdb?user=root&password=taosdata | 替换 3 处：1. 192.168.1.100 → 你的 TDengine 服务器 IP. testdb → 目标数据库名 账号密码按需修改 |
| 用户名 | root（默认） | TDengine 管理员账号，若已修改则填自定义账号 |
| 密码 | taosdata（默认） | 若已修改 TDengine 密码，填写对应密码 |
| 其他配置 | 保持默认（连接池、编码等无需调整） | 如需优化连接池，可在 "高级" 中调整最大连接数等参数 |
步骤 3：测试连接与保存
- 点击配置界面顶部的「测试连接」按钮
- 弹出「连接成功」提示 → 点击「确定」
- 回到数据连接列表，可见新增的 TDengine_REST 连接 → 完成配置
三、服务器端配置（数据决策平台）
若需在 FineReport 数据决策系统中配置（供所有用户使用），步骤如下：
步骤 1：开启驱动上传功能（若未开启）
- 管理员登录数据决策系统 → 「管理系统」→「数据连接」→「驱动管理」
- 若提示 "不允许上传驱动 jar 包"，需先开启上传权限：
-
- 连接 FineDB 数据库（帆软系统库）
-
- 执行 SQL：UPDATE fine_conf_entity SET value='true' WHERE id='SystemConfig.driverUpload'
-
- 重启 FineReport 服务器 → 驱动上传功能生效
步骤 2：上传 TDengine 驱动
- 「管理系统」→「数据连接」→「驱动管理」→「新建驱动」
- 驱动名称：TDengine_3.8.2（自定义）
- 点击「上传驱动」→ 选择 taos-jdbcdriver-3.8.2-dist.jar → 保存
步骤 3：新建数据连接
- 「管理系统」→「数据连接」→「数据连接管理」→「新建数据连接」
- 选择「JDBC」→「others」
- 配置项与设计器一致：
-
- 驱动：选择刚上传的「TDengine_3.8.2」
-
- 驱动类：com.taosdata.jdbc.rs.RestfulDriver
-
- URL、用户名、密码：同设计器配置
- 点击「测试连接」→ 成功后「保存」→ 服务器端配置完成
四、驱动选型详解（为什么选 RestfulDriver？）
很多用户会纠结 4 种 TDengine 驱动类，这里直接给出对比结论，避免踩坑：
|--------------------------------------|------------|---------------|---------------|---------|
| 驱动类 | 连接方式 | 核心优势 | 适配 FineReport | 推荐程度 |
| com.taosdata.jdbc.rs.RestfulDriver | REST（HTTP） | 无客户端依赖、跨平台、稳定 | ✅ 完美适配 | 🌟 强烈推荐 |
| com.taosdata.jdbc.TSDBDriver | 原生 TCP | 性能略高 | ❌ 需装客户端、易报错 | ❌ 不推荐 |
| com.taosdata.jdbc.AbstractDriver | 抽象父类 | 无实际连接功能 | ❌ 直接报错 | ❌ 绝对不选 |
| com.taosdata.jdbc.ws.WebSocketDriver | WebSocket | 轻量连接 | ❌ 帆软支持差、易断连 | ❌ 不推荐 |
核心原因：FineReport 作为 Java 开发的 BI 工具，REST 驱动无需依赖本地库（如 taos.dll/libtaos.so），彻底避免 "加载本地库失败" 等兼容性问题，且跨平台部署更高效。
五、常见问题排查（避坑指南）
1. 测试连接失败：找不到驱动类
- 排查 1：驱动包是否放对目录（WEB-INF/lib）
- 排查 2：是否重启了设计器 / 服务器（驱动需重启加载）
- 排查 3：是否存在多个 TDengine 驱动包（删除旧版本，仅留 3.8.2-dist.jar）
2. 连接超时 / 拒绝连接
- 排查 1：TDengine 服务器 IP 是否可达（ping 测试）
- 排查 2：6041 端口是否开放（防火墙 / 安全组放行）
- 排查 3：taosAdapter 组件是否运行（执行 taosadapter status 检查）
- 排查 4：URL 中的端口是否写错（REST 是 6041，原生是 6030，不要混淆）
3. 报错：no suitable driver for jdbc:TAOS-RS://...
- 原因：驱动类填写错误，或 URL 前缀错误
- 解决：确认驱动类是 com.taosdata.jdbc.rs.RestfulDriver，URL 前缀是 jdbc:TAOS-RS://（不是 jdbc:TAOS://）
4. TDengine 2.x 版本适配
- 驱动类不变：com.taosdata.jdbc.rs.RestfulDriver
- URL 调整：jdbc:TAOS-RS://IP:6041?dbname=testdb&user=root&password=taosdata（2.x 需用 dbname 参数指定数据库）
六、使用示例：报表中调用 TDengine 数据
配置成功后，可直接在报表中使用 TDengine 数据：
- 新建报表 → 「数据集」→「新建」→「数据库查询」
- 选择数据源：TDengine_REST
- 编写 TDengine 标准 SQL（示例）：
-- 查询近1天的设备AI数据
SELECT *
FROM energy.`火法AI归档数据```
WHERE 归档时间 > now() - 24h``
- 点击「预览」→ 查看数据 → 即可用于报表表格 / 图表制作
总结
FineReport11 连接 TDengine 的核心是「REST 无客户端方案」，通过 taos-jdbcdriver-3.8.2-dist.jar + RestfulDriver 组合，实现零依赖、跨平台的稳定连接。关键步骤可概括为：
- 驱动包部署 + 重启服务
- 填写 REST 格式 URL 和驱动类
- 测试连接成功后即可使用
该方案已适配 TDengine 3.x 所有版本，且与帆软官方适配方案一致，适用于 IoT、工业互联网、运维监控等时序数据可视化场景。如果遇到特殊报错，可提供 IP、端口、报错信息，进一步排查问题！