看板要写交互别只拖：DataGear 把数据集、图表和 HTML 拆开

源微信页标题把产品说成「一款……平台」，抓取时常撞验证码。对过 GitHub README 和官网文档后，真实项目是 DataGear（仓库 datageartech/datagear，官网 datagear.tech），不是 DataEase，也不是 FineBI。开源协议 LGPL-3.0，当前稳定包是 6.0.0（2026 年 7 月），企业版另走商业授权，源码改不了就别装企业包。

它和拖拽 BI 的分界很具体：图表可以点选，看板模板却是一张原生 HTML 网页。你可以导入任意 HTML / JavaScript / CSS，切到可视模式拖布局，也可以切到源码模式写 Vue、React、Bootstrap、Tailwind。内置看板 API 负责图表联动、数据钻取、异步加载和交互表单。业务数据先进「数据集」，再钉到图表上，最后嵌进这张网页——三层拆开，而不是一块画布里又连库又画图。

本地 content/ 与 wechat_articles_list.md 里没有 DataGear 独立成篇，也没有 sn=1b450e38cdef562d。下文按 6.0 官方文档、更新日志和源码配置项重写，不复述源文营销句。

封面：可写看板与参数化数据集

一、先认产品：单体 Spring Boot，看板是网页不是积木

DataGear 自称「开源免费的数据可视化分析平台」，主功能是一条管理链：数据源、SQL 工作台、导入/导出、项目、数据集、图表、看板，外加用户、角色、数据源驱动、图表插件。技术栈写在 README 里，前后端一体：

层	选型	实际含义
后端	Spring Boot、MyBatis、Freemarker、Derby、Jackson、Caffeine、Spring Security	单体 JAR/ZIP，默认内嵌 Derby，不用先备 MySQL
前端管理台	Vue3、PrimeVue、CodeMirror	4.0 起重写管理界面
图表	ECharts、DataTables、jQuery	看板页仍大量走 jQuery + 图表对象 API
运行时	JDK 8+、Servlet 3.1+	WAR 还不支持 Jakarta EE，Tomcat 10 那条线先别硬上

模块划分也不是营销词。datagear-connection 负责从指定目录加载 JDBC 驱动并建连；datagear-meta 解析表结构；datagear-persistence 做表数据的读改查；datagear-dataexchange 管导入导出；datagear-analysis 定义数据集、图表、看板 API；datagear-management 是业务服务；datagear-web / datagear-webapp 分别是控制器和启动类 org.datagear.webapp.DataGearApplication。调试入口就是这个启动类，浏览器默认 http://localhost:50401。

和 DataEase 别混。DataEase 走「人人可用的拖拽 BI + AntV/SeaTunnel」，目标是少写代码出大屏；DataGear 的卖点反过来——允许你把看板当成前端项目来写。FineBI 是商业套件，权限、填报、集群都重；DataGear 是私有化单体，工作目录默认在 ~/.datagear。选型时先问：看板要不要自定义 JS？要不要 iframe 嵌进现有系统？数据源是 JDBC / 文件 / HTTP 就够，还是必须上大数据管道？前两个「要」且后一个「够」，才轮得到 DataGear。

开发分支（dev-*）启动会改工作目录里的内置库。README 写得很直：调试前先备份 [用户主目录]/.datagear，否则正式版可能再也起不来。

二、安装只要 JDK 和 ZIP，真正要守的是工作目录

官网提供两种包：datagear-6.0.0.zip（已集成运行容器，命令启动，仍要本机 JDK 8+）和 datagear-6.0.0.war（丢进 Java EE Servlet 3.1+ 容器）。没有官方 Docker 镜像。社区留言板里有人用 ccpp1985/datagear，那是第三方，版本往往停在 5.x，生产别当官方发行。

Linux 最小路径：

# 先确认 JDK
java -version   # 需要 8+

unzip datagear-6.0.0.zip
cd datagear-6.0.0
./startup.sh

Windows 双击 startup.bat。浏览器打开 http://[主机]:50401。本机就是 http://localhost:50401。系统内置管理员 admin / admin，右上角也可注册普通用户。公网暴露前必须改密，并考虑关掉注册、关掉匿名展示。

所有业务数据默认落在操作系统用户主目录的 .datagear：内置 Derby 在 ~/.datagear/derby，驱动在 driver/，看板文件在 dashboard/，数据集文件在 dataSet/，图表插件在 chartPlugin/。备份这一棵目录，等于备份整套实例。程序目录里的 config/application.properties 才是日常旋钮，改完要重启。

源码里的默认项值得直接抄进清单（键名以 6.x 源码为准，老文章里的 schemaPsd.* 已迁到 dtbsSourcePsd.*，工作目录变量也从 DATAGEAR_WORKSPACE 改成了 DATAGEAR_HOME）：

DATAGEAR_HOME=${user.home}/.datagear
server.port=50401
# 二级目录部署，例如挂在 /datagear
server.servlet.context-path=
disableAnonymous=false
disableShowAnonymous=false
disableRegister=false
# 数据源密码默认仍是明文存储，生产应打开加密
dtbsSourcePsd.crypto.enabled=false

登录还有 IP / 用户名错误次数闸：默认 1800 秒内同一 IP 错 5 次、同一用户名错 3 次。验证码默认开。需要跑在 Nginx 二级路径时，官方留言板的标准答法是加 server.servlet.context-path=/datagear，不要只改反向代理而忘了应用根路径——5.0 修过「配了根路径后看板图标丢」的问题，说明这条路径确实会改资源 URL。

从源码编译则是标准 Maven：mvn clean package，包打到 datagear-webapp/target/datagear-[version]-packages/。跳过测试用 -DskipTests。单元测试默认要本机 MySQL 8.0、库名 dg_test、root 密码 root，用 test/sql/test-mysql.sql 初始化。日常试用没必要走这条路，ZIP 就够。

三、四层模型：数据源只连库，看板不直接写 SQL

上手顺序被入门文档写死了，跳步就会在「图表没有字段可绑」处卡住。

Mermaid Diagram

1. 数据源。 左侧【数据源】添加连接，MySQL / PostgreSQL / Oracle / SQL Server 都走 JDBC。驱动可以运行时上传：任何提供 JDBC 的库都能挂上，官方点名还包括 Elasticsearch、ClickHouse、OceanBase、TiDB、人大金仓、达梦。连上之后，同一入口里可以增删改查表数据、开 SQL 工作台、做导入导出。5.1 起数据源路径从 /schema 改成 /dtbsSource，还支持指定数据库模式名。

2. 数据集。 这才是查询的落点。类型包括 SQL、CSV、CSV 文件、Excel、HTTP 接口、JSON、JSON 文件。文件类除了上传，还可以用服务器端文件，但目录必须由管理员在【文件源】（5.1 前叫「数据集资源目录」）里授权。点【预览】后系统解析字段；图表侧是靠这些字段绑「数据标记」，不是在看板里再写一遍 SELECT。6.0 起参数和字段都支持对象类型，内置参数新增 DG_DATETIME、DG_DATE。

3. 图表。 一张图可以绑定多个不同来源的数据集。内置 70+ 种。入门里的坑写在括号里：选定字段后要点字段右侧的 【+】 绑定数据标记，否则保存了也是空图。5.0 把旧概念「图表数据集」重构为「数据集绑定」；JS 侧 chart.chartDataSet*() 弃用，改 chart.dataSetBind*()。

4. 看板。 【添加】空白页，或从官网模板库导入 ZIP。设计页有可视 / 源码两种模式。5.5 可视模式加了手机 / 平板 / 桌面 / 大屏弹性布局。展示路径 5.1 起缩短为 /dv/*（图表展示 /cv/*），老文档里的 /analysis/dashboard/show/[id]/ 不要再当现行 URL 抄。

四层：数据源到可写看板

跨源不是口号。图表允许「一个图里绑两个数据集」，例如 SQL 出订单汇总、HTTP 出实时库存，再在看板上做联动。代价是每个数据集自己定义参数和刷新策略，别指望系统帮你做分布式 JOIN。

四、参数化语法：Freemarker 插值，SQL 还可以预编译

「支持多种数据源」真正能用的部分，是参数化数据集。给数据集加参数之后，SQL、CSV 文本、服务器文件名、HTTP 地址 / 请求体 / 请求头、JSON 文本都可以写模板。预览和展示时弹出参数面板，填完再查。底层解析是 Freemarker。

插值是 ${参数名}。条件用 <#if>，集合用 <#list>。常用判断：参数名?? 表示用户填了值（非必填场景）；布尔直接写参数名或 !参数名；字符串用 == "..."；数值用 gt / gte / lt / lte。官方教程里的订单分析写法，今天仍然适用：

SELECT NAME, VALUE FROM T_ANALYSIS
WHERE NAME = '${name}'
<#if 最小值??>
AND VALUE >= ${最小值}
<#else>
AND VALUE IS NOT NULL
</#if>
<#if 名称集合??>
AND NAME IN
(
  <#list 名称集合 as item> '${item}' <#sep>,</#list>
)
</#if>
<#if ascByName>
ORDER BY NAME ASC
</#if>
<#if limitCount??>
limit 0, ${limitCount}
</#if>

同一套参数还能灌进别的类型：CSV 单元格写 ${value}；服务器文件名写成 file-${value}.csv；HTTP 地址 http://api.example.com/stat?param=${value}；请求头 JSON 数组里同样插值。参数输入框类型可设成文本、下拉、日期、时间、日期时间、单选、复选、文本域。多选下拉和复选框的值是集合，SQL 里必须用 <#list>，不要当成标量拼接。

5.4.0 给 SQL 数据集加了预编译，用来补纯字符串拼接的注入面。5.4.1 立刻修了「开了预编译之后关键字拦截失效」的 bug，升级跨过 5.4.0 时不要停在那个点。application.properties 里还有按角色拆开的非法关键字表，默认读权限用户（SQL 工作台、SQL 数据集）禁止 INSERT,UPDATE,DELETE,TRUNCATE,CREATE,ALTER,DROP,...。字符串字面量和标识符引号内不做拦截——${name} 若未预编译、又被拼进引号外，仍可能被当成语句结构。能预编译的条件尽量预编译；动态 IN 列表继续用 <#list>，但项必须来自参数，不要把整段 SQL 暴露给匿名看板。

HTTP 数据集还有两条容易忽略的开关：4.7 的【编码请求地址】解决中文乱码；5.4 起支持文本 / 二进制响应，以及「附加数据」从同一数据源再读一块。请求第三方接口时，超时和鉴权头写在数据集里，不要写死在看板 JS 里再靠浏览器跨域——看板跑在用户浏览器，数据集跑在服务端。

五、看板页：可视拖布局，源码写联动，分享走短链

空白看板的最短路径：【看板】→【添加】→ 填名称 →【保存并设计】→【可视模式】插入标题、布局、图表，设颜色，【保存并展示】。不会前端的人可以在这一层停住。要图表显示/隐藏、钻取、表单提交，就切源码，看板就是普通 HTML。

联动不必先写 JS。元素属性 dg-chart-link 的核心字段是 trigger（默认 click）、target（目标图的元素 id）、data（事件字段映射到目标数据集参数）。简写可以把映射写成参数索引：

<div id="chartRegion"
     dg-chart-widget="订单柱状图部件ID"
     dg-chart-link="{ target: 'chartDetail', data: { name: 0 } }">
</div>
<div id="chartDetail" dg-chart-widget="明细图部件ID"></div>

原理是：源图绑事件 → 把 chartEvent.data 写进目标图的数据集参数 → 刷新目标图。所以目标图必须是参数化数据集，且元素 id 要自己写死。系统自动生成的 id 每次刷新可能变，联动就会丢。5.3 还把表单 / 联动配置里的 target 改成可选，允许直接在参数索引对象里写目标元素 id。

等价 API 在图表对象上：chart.dataSetParamValue(0, 'sqlParam', name) 或按索引 dataSetParamValueFirst，然后刷新。看板对象负责异步装图：

dashboard.loadChart($('#lazyBox'), '图表部件ID', function (chart) {
  var name = dashboard.renderContextAttr('name') || 'beijing';
  chart.dataSetParamValue(0, 'sqlParam', name);
});

URL 查询串会进渲染上下文。5.1 之后展示地址是 /dv/[看板ID]/?name=shanghai 这种短链；老教程的 /analysis/dashboard/show/[id]/ 只适合对照历史文章。renderContextAttr('param1') 遇到同名多值会拿到数组。地图场景常用 ?map=chongqing 在 onRender 里改地图名。

分享在看板管理页【分享】：指定用户、角色或匿名用户。匿名能看展示链接，但 6.0 起始终不开放数据源上的 SQL 工作台和导入导出。配置项 disableShowAnonymous=true 可以连展示链接的匿名访问一并关掉。分享密码默认同样明文存储，对应 dashboardSharePsd.crypto.enabled；乱改密钥会导致已设密码的看板全部校验失败，只能进系统重设。iframe 嵌入只要把展示 URL 放到业务系统页面；跨域头在 cors[0].config.*，默认比较松，生产应收紧 allowedOrigins。

参数化查询与图表联动

可视模式从 5.3 起能插 iframe、改元素 id，生成的 HTML 带缩进。源码模式 6.0 加了【替换】和【自定义插入图表元素属性】。两种模式来回切之前先保存：官方修过「源码改完切可视，导航栏残留」这类状态 bug，未保存关选项卡现在会确认。

六、6.0 换了看板 API，插件和表格导出要跟版本走

6.0.0 的主线是：看板新增 API-2.0 环境，内置图表插件整批按新 API 重构。旧看板不会自动「看起来一样」。新图要在插件选择里走【API-2.0】分类，例如表格选「基本表格」，不要继续用已经弃用的 V1。源码模式的替换、自定义插入属性，都是给这次换代准备的。

内置表格导出 Excel / CSV / PDF 仍然不自带 JS 依赖。官方示例要求把库上传为看板资源再引入：

<script src="lib/jszip@3.10.1/jszip.min.js"></script>
<script src="lib/pdfmake@0.2.23/pdfmake.min.js"></script>
<script src="lib/pdfmake@0.2.23/vfs_fonts.min.js"></script>

vfs_fonts 默认没有中文，导出 PDF 会方块字，需要换成思源黑体一类并 pdfMake.setFonts(...)。只导出 CSV/Excel 可以不引 pdfmake。图表选项里的 buttons 数组配置 extend: 'csv' | 'excel' | 'pdf' | 'print'。5.3 起表格还支持 serverSidePaging，大数据量不要把整表塞进浏览器。

扩展有两条官方路。

数据源驱动。 管理页上传 JDBC jar，运行时生效，不必为了一个达梦驱动重编译 DataGear。5.2 修过 JDK 9+ 外挂驱动失效。URL 里曾经出现过远程代码执行面，4.7 / 5.1 / 5.2 连续补了用户名、连接属性防护和 XXE，驱动文件也当成不可信输入。

看板要写交互别只拖：DataGear 把数据集、图表和 HTML 拆开

图表插件。 可以上传自定义类型，也可以覆盖内置插件、改图表选项。5.2 起插件可声明 JS 依赖，绘制前自动 loadLib()；规范是 renderer.js。不会写插件时，先在看板里引 Vue / Three.js，用看板 API 读数据集结果自己画——这正是案例里「前端团队把 DataGear 当宿主」的用法。

ECharts 在 5.3 升到 5.6.0。前端为了旧浏览器，Vue 和 PrimeVue 有过降级（Vue 3.4.5 → 3.2.47，PrimeVue 3.45.0 → 3.34.1），不要按「永远最新」去猜管理台的组件行为。

企业版从 1.0.0（2024-01）走到 1.5.0（2025-08），文档里出现 MQTT / WebSocket 实时集、Redis / MongoDB 数据集、组织机构、JWT、文件源增强。这些不在 LGPL 开源树里。开源版要实时，通常是 HTTP 数据集加图表定时刷新，或自己在看板里写 WebSocket，而不是幻想开源包里藏了企业功能。

七、上线前的坑：Derby 升级、Excel 炸弹、明文密码、匿名面

把「下个 ZIP 就能演示」当成生产就绪，会在这几处爆。

工作目录与升级。 启动按版本号自动升级 Derby，成功后不会重跑。调试中途库异常，要停服务，对照 datagear-management/src/main/resources/org/datagear/management/ddl/datagear.sql 手工补 SQL，再：

UPDATE DATAGEAR_VERSION SET VERSION_VALUE='6.0.0'

IDE 里可跑 org.datagear.web.util.DerbySqlClient，必须先停 DataGear。换外部 MySQL / Postgres 当系统库是进阶操作：自己按 DDL 初始化、改 datasource.*、把 JDBC 打进启动类路径。官方说 2.3.0 之前不要换库。

Excel「Zip bomb detected!」。 POI 默认解压比 0.01。真实宽表有时误伤。poi.zipSecureFile.minInflateRatio 调小能过，设 0 等于关掉防御。只对可信文件源放开，不要对匿名上传关。

密钥两对。 dtbsSourcePsd.crypto.secretKey / salt 和看板分享密码那一对，默认都是 "DataGear" 的 Base64 / hex。注释写明：改密钥会让已有密码全部失效。生产应开启加密，密钥放环境或外部配置，不要提交进 Git。

SQL 与匿名。 6.0 起匿名没有 SQL 工作台和导入导出；数据集查看页也禁用预览。这还不够：参数化模板 4.7 修过远程代码执行，Freemarker 能执行的东西比「插个数字」多。给匿名看板的数据集，参数类型收紧，禁止把整段 SQL 当参数。读权限关键字黑名单不要删成空。

文件与二进制。 5.4 允许 SQL / HTTP 出二进制字段，看板里直接显示库里的图。这意味着展示链能碰到 BLOB。权限按图表 / 看板分享走，数据源本身默认私有——分享图表不等于分享写库权限，但等于分享这一条查询结果。

版本错位。 看板展示短链、数据集绑定改名、地图选项从 dg-chart-map 换成 mapName/dgMap、表格 V1 弃用、6.0 API-2.0……抄 2.x 书栈教程时，把 API 名和 URL 对一下现行文档。chart.dataSetProperty*()、chart.map()、chart.chartDataSet*() 都已弃用。

容器。 没有官方镜像。自己封装时要映射 50401 和 ~/.datagear，JDK 用 8 或 11 这类仍带 Java EE 语义的发行，不要用只剩 Jakarta 的精简 JRE 去跑 WAR。Tomcat basedir 已被改到 ${DATAGEAR_HOME}/tomcatworkspace，因为默认临时目录在部分环境会搞丢上传。

默认管理员口令、开放注册、匿名可看、数据源密码明文、CORS allowedOrigins=*，这五件同时出现时，这台机器就不是「内部看板」，是未加固的数据网关。先收这五件，再谈大屏美不美。