Dataease Xugudb Adapter

DataEase 适配虚谷数据库指南

概述

本技能提供 DataEase 开源 BI 工具适配虚谷数据库（XuguDB）的完整配置指南。DataEase 是人人可用的开源 BI 工具，支持丰富的数据源连接，能够通过拖拉拽方式快速制作图表。

适用场景：

• 企业数据可视化分析
• 自助式数据探索
• 仪表板和报表制作
• 数据大屏展示
• 团队协作和数据分享

核心特性：

• 支持 20+ 种数据源连接
• 拖拉拽式图表制作
• 丰富的图表类型
• 安全的分享机制
• AI 智能问数功能

快速开始

1. 安装部署

Docker 部署（推荐）：

# 拉取 DataEase 镜像
docker pull dataease/dataease:latest

# 启动 DataEase 容器
docker run -d \
  --name dataease \
  -p 80:80 \
  -v /opt/dataease:/opt/dataease \
  -e JAVA_OPTS="-Xms2g -Xmx4g" \
  dataease/dataease:latest

访问地址： http://your-server-ip

默认账号：

• 用户名：admin
• 密码：dataease

2. 配置虚谷数据库驱动

2.1 获取驱动文件

驱动文件： xugu-jdbc-12.3.4.jar

下载方式：

1. 从虚谷数据库官网下载
2. 从 Maven Central 下载：com.xugudb:xugu-jdbc:12.3.4

2.2 上传驱动到 DataEase

方式一：通过界面上传

1. 登录 DataEase 系统
2. 进入【系统管理】→【驱动管理】
3. 点击【新建驱动】
4. 填写驱动信息：

• 驱动名称：虚谷数据库驱动
• 驱动类型：MySQL（选择 MySQL 兼容模式）
• 驱动类名：com.xugu.cloudjdbc.Driver
• 驱动文件：上传 xugu-jdbc-12.3.4.jar

1. 点击【保存】

方式二：手动部署驱动文件

# 将驱动文件复制到 DataEase 的驱动目录
cp xugu-jdbc-12.3.4.jar /opt/dataease/drivers/

# 重启 DataEase 服务
docker restart dataease

2.3 驱动类名参考

| 数据库 | 驱动类名 | |--------|----------| | 虚谷数据库 | com.xugu.cloudjdbc.Driver | | MySQL | com.mysql.jdbc.Driver | | PostgreSQL | org.postgresql.Driver | | Oracle | oracle.jdbc.driver.OracleDriver | | SQL Server | com.microsoft.sqlserver.jdbc.SQLServerDriver | | 达梦（DM） | dm.jdbc.driver.DmDriver |

3. 配置数据源连接

3.1 新建数据源连接

1. 登录 DataEase 系统
2. 进入【数据准备】→【数据源】
3. 点击【新建数据源】
4. 选择数据源类型：

• 如果已配置虚谷数据库驱动，选择【虚谷数据库】
• 如果未配置专用驱动，选择【MySQL】（兼容模式）

3.2 配置连接参数

基本配置：

数据源名称：虚谷数据库
数据库类型：MySQL（兼容模式）或 虚谷数据库
IP 地址：127.0.0.1
端口：5138
数据库名称：SYSTEM
用户名：SYSDBA
密码：SYSDBA

高级配置：

查询超时时间：60（秒）
字符集：UTF-8
时区：Asia/Shanghai

连接字符串示例：

jdbc:xugu://127.0.0.1:5138/SYSTEM?current_schema=PUBLIC&CHAR_SET=UTF8&COMPATIBLE_MODE=MYSQL

3.3 配置 Schema

1. 在数据源配置页面，点击【获取 Schema】
2. 选择目标 Schema（如 PUBLIC）
3. 点击【校验】验证连接
4. 校验成功后点击【保存】

核心功能

1. 数据集配置

1.1 创建数据集

1. 进入【数据准备】→【数据集】
2. 点击【新建数据集】
3. 选择数据源：虚谷数据库
4. 选择数据表或编写 SQL 查询

1.2 数据表选择

-- 选择单表
SELECT * FROM users

-- 多表关联查询
SELECT 
    u.name AS 用户名,
    u.email AS 邮箱,
    o.order_date AS 订单日期,
    o.amount AS 订单金额
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
WHERE u.status = 1

1.3 自定义 SQL 查询

-- 聚合查询
SELECT 
    DATE_FORMAT(create_time, '%Y-%m') AS 月份,
    COUNT(*) AS 用户数量,
    SUM(amount) AS 总金额
FROM orders
WHERE create_time >= '2024-01-01'
GROUP BY DATE_FORMAT(create_time, '%Y-%m')
ORDER BY 月份

2. 仪表板创建

2.1 新建仪表板

1. 进入【仪表板】
2. 点击【新建仪表板】
3. 选择模板或空白仪表板
4. 配置仪表板名称和描述

2.2 添加图表组件

1. 从组件库拖拽图表到画布
2. 选择数据集
3. 绑定数据字段：

• 维度：分类字段（如用户类型、产品类别）
• 指标：数值字段（如金额、数量）

1. 配置图表样式和交互

2.3 常用图表类型

柱状图：

• 适用场景：比较不同类别的数据
• 配置示例：X 轴为产品类别，Y 轴为销售额

折线图：

• 适用场景：展示数据趋势
• 配置示例：X 轴为时间，Y 轴为用户增长数

饼图：

• 适用场景：展示占比关系
• 配置示例：展示不同渠道的销售占比

地图：

• 适用场景：展示地理分布数据
• 配置示例：展示各省份的销售分布

2.4 过滤组件配置

时间过滤器：

• 配置时间范围选择
• 支持相对时间和绝对时间

文本过滤器：

• 配置文本搜索条件
• 支持模糊匹配和精确匹配

数字过滤器：

• 配置数值范围筛选
• 支持大于、小于、等于等条件

3. 数据大屏创建

3.1 新建数据大屏

1. 进入【数据大屏】
2. 点击【新建数据大屏】
3. 选择模板或空白大屏
4. 配置画布尺寸（如 1920x1080）

3.2 布局设计

标题区域：

• 添加标题文本组件
• 配置字体、颜色、大小

数据展示区域：

• 添加图表组件
• 配置数据绑定和样式

装饰元素：

• 添加边框、背景、装饰线
• 配置动画效果

3.3 交互配置

联动效果：

• 配置图表间的联动关系
• 实现点击筛选功能

定时刷新：

• 配置数据自动刷新
• 设置刷新间隔时间

4. 报表与分享

4.1 创建报表

1. 进入【报表】
2. 点击【新建报表】
3. 选择数据集
4. 设计报表布局

4.2 分享配置

公开分享：

• 生成分享链接
• 设置访问密码
• 配置有效期

嵌入分享：

• 生成嵌入代码
• 集成到其他系统
• 配置单点登录

4.3 定时报告

1. 进入【定时报告】
2. 配置报告任务
3. 设置发送时间
4. 配置接收人

性能优化

1. 数据库优化

索引优化：

-- 为常用查询字段创建索引
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_orders_user_id ON orders(user_id);
CREATE INDEX idx_orders_create_time ON orders(create_time);

-- 复合索引
CREATE INDEX idx_orders_status_time ON orders(status, create_time);

查询优化：

-- 使用覆盖索引
SELECT id, name, email FROM users WHERE email = 'test@example.com';

-- 避免 SELECT *
SELECT name, email, phone FROM users WHERE status = 1;

-- 使用分页查询
SELECT * FROM users ORDER BY id LIMIT 100 OFFSET 0;

2. DataEase 配置优化

缓存配置：

• 启用查询缓存
• 配置缓存过期时间

连接池配置：

• 调整最大连接数
• 配置连接超时时间

查询超时配置：

• 设置合理的查询超时时间
• 避免长时间运行的查询

3. 硬件优化

内存配置：

• 增加 DataEase 的 JVM 内存
• 配置数据库服务器内存

存储优化：

• 使用 SSD 存储
• 配置 RAID 阵列

网络优化：

• 使用高速网络连接
• 配置负载均衡

常见问题与解决方案

1. 连接失败

问题：无法连接到虚谷数据库。

解决方案：

• 检查数据库服务是否启动
• 验证网络连接和防火墙设置
• 确认用户名和密码是否正确
• 检查驱动类名是否正确

2. 驱动加载失败

问题：驱动类名不正确或驱动文件损坏。

解决方案：

• 确认驱动类名：com.xugu.cloudjdbc.Driver
• 重新下载驱动文件
• 检查驱动文件版本兼容性

3. 查询超时

问题：查询执行时间过长。

解决方案：

• 优化查询 SQL 语句
• 创建合适的索引
• 增加查询超时时间
• 使用分页查询

4. 数据类型不兼容

问题：某些数据类型映射不正确。

解决方案：

• 使用 CAST 函数进行类型转换
• 在 SQL 查询中处理类型转换
• 检查虚谷数据库的数据类型文档

5. 中文乱码

问题：中文字符显示为乱码。

解决方案：

• 确保连接字符串中包含 CHAR_SET=UTF8
• 检查数据库字符集配置
• 验证 DataEase 的字符编码设置

最佳实践

1. 数据源管理：使用统一的命名规范管理数据源
2. 权限控制：为不同用户配置不同的数据访问权限
3. 性能优化：为常用查询创建索引，优化查询语句
4. 缓存策略：合理配置缓存，提高查询性能
5. 监控告警：配置查询性能监控和告警
6. 备份恢复：定期备份仪表板和数据集配置
7. 版本管理：及时更新 DataEase 和数据库驱动版本
8. 安全防护：配置访问控制和数据脱敏

相关资源

• DataEase 官方文档
• DataEase GitHub 仓库
• 虚谷数据库官方文档
• DataEase 社区论坛

参考文档

详细配置信息请参考：references/dataease-configuration.md

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kourou25
• Source: kourou25/xugudb-dev-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.