datart 开源 BI 平台部署实战：从数据源接入到数据大屏

1. 先把 datart 的定位搞清楚别装完才发现不对路前阵子帮朋友的团队把内部数据看板从零搭起来前后折腾了差不多三天最后落地的就是 datart。这个决定不是拍脑袋定的我们前后对比过几套开源方案最终选它主要看中三点一是它把「数据源接入—数据集建模—图表—仪表板—数据大屏」这整条链路做全了不用在四五个工具之间来回搬数据二是前后端全开源可以完整部署在自己内网的服务器上数据不出机房三是图表插件机制相对开放后面业务想加自定义图形有地方下手。所以这篇就把 datart 部署使用的完整过程摊开写一遍包括我们踩过的坑和一些官方文档里不会写的细节尽量让你照着做就能跑起来。datart 本质上是一套数据可视化与 BI 平台核心使用场景就是让业务方不用等开发排期自己把数据变成能看的图。它适合三类人一类是数据开发或 BI 工程师负责接数据源、做数据集、定指标口径一类是业务分析师负责拖图、拼看板、调样式还有一类是管理层只看最后那块数据大屏。如果你的团队正卡在「运营每要一个数就要找开发写 SQL 导 Excel」这个阶段那这套东西确实能省事。下面先把定位说透再聊部署。1.1 它到底解决的是什么问题在没有这类工具的时候一个典型流程是这样的业务提需求开发写 SQL导出 Excel发邮件第二天业务说口径不对再改一轮。这个循环的成本极高而且每次都要重复。datart 的价值在于把这个循环切断——数据开发只需要把库接进来、把字段的维度指标属性定义清楚后面业务自己拖拽组合改一个筛选条件、换一种图形都不需要再找开发。它内部的结构大致是四层数据源层负责连接各种数据库数据集层负责把裸表加工成业务能理解的字段集合包含计算字段、变量、权限可视化层负责把数据集变成具体的图和看板应用层负责权限、分享、定时任务和对外发布。理解这四层后面用起来会顺很多因为绝大多数「为什么我的字段出不来」「为什么图表报错」的问题都能对应到这四层里的某一层去找原因。1.2 什么团队适合自己部署什么团队别折腾自己部署最大好处是数据边界可控所有查询都发生在你自己的内网里元数据也落在自己的数据库。如果你的数据涉及客户信息、经营数据、财务口径又明确不允许上公有云那自建几乎是唯一选择。另外它对国产数据库和常见的数仓组件适配比较全像 MySQL、PostgreSQL、Oracle、SQL Server、ClickHouse、Hive、Presto、Impala、Kylin、Druid 这些都能接做数仓的团队接入成本低。但有几类团队我建议先别急着上手一是公司里只有一两张表要看、每月更新一次那用现成的表格工具就够了装一套 BI 平台纯属给自己找运维负担二是团队里没人会 Java、也不熟悉 Linux 和容器一旦启动失败连日志在哪都不知道排查会很痛苦三是希望开箱即用、完全不想碰配置文件的那这类需要自己维护元数据库的系统都会让你难受。判断标准很简单如果你们内部已经有专职的运维或后端能腾出半天时间那就值得做否则先评估。1.3 部署前必须接受的几个现实约束第一个约束是元数据库独立。datart 自己的配置、用户、数据集定义、图表定义都放在一个 MySQL 库里这个库跟你要分析的业务库是分开的不能共用也不能随便删。第二个约束是前端产物和后端是同一个进程对外提供服务的也就是说你最终只需要暴露一个端口前端静态资源由后端直接托管不需要单独再起一个 Node 服务这一点跟很多前后端分离项目的部署方式不太一样第一次接触容易搞错。第三个约束是版本迭代比较快不同小版本之间的配置文件字段、初始化脚本可能有差异所以我不建议你拿搜到的某个旧教程里的配置直接照抄最好以你实际拉到的那份代码或镜像里的示例配置为准本文给出的是结构和方法具体字段名请以手上版本为准。第四个约束是内存后端是 Spring Boot 应用默认堆配置加上前端资源、连接池单机跑起来建议至少给 4G想跑得舒服给 8G低于 2G 会频繁出现卡顿甚至 OOM。2. 部署路线怎么选三条路各自的成本核算明确了定位之后第二条要想清楚的是走哪条部署路线。目前主流就三条源码编译、直接拉官方镜像跑容器、用 compose 编排容器加数据库。这三条路不存在谁绝对更好只存在谁更适合你当下的环境。我三条都实际走过一遍下面把成本拆开讲你可以直接对号入座。2.1 源码编译可控性最强但最耗时源码编译的好处是你能改代码、能打自己的补丁、能把前端做定制化改动比如换 Logo、改默认主题、加内部统一的登录逻辑。缺点也很明显需要同时准备 Java 和 Node 两套构建环境构建过程要下载大量依赖第一次跑通常十几分钟起步遇到依赖源慢的时候会更久。这条路的流程大致是先构建前端把产物放到后端工程的静态资源目录再用 Maven 打出可执行 jar最后写一个启动脚本或者交给 systemd 托管。坑主要在两个地方一是前端构建对 Node 版本有要求版本太高或太低都可能编译失败二是前端产物目录如果没放对地方后端启动是成功的但页面打开是 404 或者白屏这个后面会单独讲。2.2 容器镜像上手最快适合验证和中小规模如果你只是想快速验证这东西好不好用或者团队规模不大、没有定制需求容器方式最省事。拉镜像、挂数据卷、暴露端口、连上外部数据库四条命令就能起来。它的另一个好处是升级方便换 tag 重启就行回滚也简单把 tag 换回去即可。容器方式需要你提前准备好两样东西一个可用的 MySQL 实例以及一个持久化的数据目录用来存放上传的文件、图片、导出产物等。千万不要不挂卷就跑容器否则容器一重建用户上传的资源全丢这个坑我见人踩过不止一次。2.3 环境依赖逐项过一遍不管你走哪条路下面这张表里的东西都是绕不开的建议动手前先对着检查一遍缺什么补什么别装到一半才发现少了东西。组件建议版本作用是否必须MySQL8.0 及以上存放元数据、用户、数据集与图表定义必须JDK8 或 11运行后端服务源码部署必须Node.js16 左右构建前端产物源码部署必须Maven3.6 及以上打包后端源码部署必须Redis5 及以上缓存与集群会话共享单机可选多实例建议Nginx任意稳定版反向代理、统一入口生产建议Docker20 及以上容器化部署容器路线必须表里 Redis 那一行值得多说一句。单机部署时不配 Redis 通常也能跑但登录态、缓存这些会有影响尤其是你后面想扩成两个实例做负载均衡的时候没有共享缓存会出现「刷新一下就要重新登录」的诡异现象。所以我的习惯是只要这台机器上已经有 Redis就直接配上多花两分钟省掉后面一堆玄学问题。3. 手把手实操从建库到服务跑起来这一节是全文最实打实的部分我按实际操作顺序来写你照着顺序做就行。顺序是先建库导脚本再改配置再启动最后验收。顺序反了会出现「服务起来了但登录报错」这类问题排查起来很费时间。3.1 数据库初始化字符集和时区是两个易错点先建库。字符集一定要用 utf8mb4不要用 utf8因为很多业务字段里会有特殊符号和表情用 utf8 会直接插入失败。排序规则选一个通用的即可。建库语句大概是这样CREATE DATABASE datart DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;建完之后把项目里的初始化脚本导进去。初始化脚本一般在工程目录或者官方镜像的初始化目录里容器方式的 compose 文件里通常已经帮你挂载好了第一次启动会自动执行。手工部署的话就手动导mysql -h 127.0.0.1 -u root -p datart datart_init.sql这里有两个注意点。第一如果你的服务器时区和数据库时区不一致后面图表按时间筛选会出现整体偏移几小时的现象看着像数据错其实是时区问题建议在连接串里显式指定时区参数或在数据库层面统一。第二导入完成后用SHOW TABLES;确认一下表是不是都建出来了有些脚本中途报错但 mysql 客户端不会中断会给你一种「导入成功」的错觉。3.2 配置文件里真正需要改的就那几项配置文件看着长但真正必须改的没几个。核心是下面几块server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://127.0.0.1:3306/datart?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalse username: datart password: 你的密码 jpa: hibernate: ddl-auto: none show-sql: false redis: host: 127.0.0.1 port: 6379 password: 你的Redis密码ddl-auto这一项一定要设成none绝对不要图省事设成update。原因很直接这是生产系统的元数据库让框架自动改表结构意味着某次升级可能悄无声息地把你已有的表结构改了或者删了字段等你发现数据对不上就晚了。表结构变更应该由升级时的初始化脚本显式控制而不是交给框架猜。文件存储路径那一项也建议改到独立的数据盘比如/data/datart/files。原因是用户上传的图片、大屏素材、导出文件都会往这里堆放在系统盘迟早撑爆。改完配置后用df -h看一眼挂载点确认这个目录所在的分区有足够空间别弄成软链接指向了根分区。3.3 容器编排落地一份能直接用的 compose如果你走容器路线下面这份编排可以直接拿来改。它包含两个服务一个是数据库一个是应用本体数据目录和数据库数据都做了持久化。version: 3 services: datart-db: image: mysql:8.0 container_name: datart-db restart: always environment: MYSQL_ROOT_PASSWORD: 换成你的强密码 MYSQL_DATABASE: datart TZ: Asia/Shanghai command: - --character-set-serverutf8mb4 - --collation-serverutf8mb4_general_ci volumes: - ./mysql-data:/var/lib/mysql ports: - 3306:3306 datart-app: image: datart/datart:latest container_name: datart-app restart: always depends_on: - datart-db environment: TZ: Asia/Shanghai SPRING_DATASOURCE_URL: jdbc:mysql://datart-db:3306/datart?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalse SPRING_DATASOURCE_USERNAME: root SPRING_DATASOURCE_PASSWORD: 换成你的强密码 volumes: - ./datart-files:/data/datart ports: - 8080:8080几点实操说明。第一两个容器之间用服务名通信也就是datart-db这个主机名不要写127.0.0.1因为容器里的 localhost 指的是容器自己不是宿主机这是新手最常见的连接失败原因。第二restart: always要加上否则宿主机重启后服务不会自己回来第二天上班发现打不开页面。第三depends_on只保证启动顺序不保证数据库已经准备好接受连接如果应用启动时报连接拒绝等十几秒重试一次通常就好了或者干脆先起数据库、确认能连上再起应用。3.4 源码编译的完整命令链路源码路线按下面的顺序来每一步都别有跳跃# 1. 构建前端 cd frontend npm install npm run build # 2. 把前端产物复制到后端静态资源目录 cp -r dist/* ../server/src/main/resources/static/ # 3. 打包后端 cd ../server mvn clean package -DskipTests # 4. 启动 java -jar target/datart-server.jar --spring.config.location./application.yml这里要解释两个为什么。为什么先打前端再打后端因为后端打包时会把静态资源一起塞进 jar如果顺序反了打出来的包里就没有前端页面访问时只能看到接口返回的 JSON 而不是界面。为什么要用--spring.config.location显式指定配置因为把配置写在 jar 外面的文件里以后改数据库密码、改端口就不用重新打包直接改文件重启即可这在生产环境是刚需。前端构建如果卡在依赖下载可以换一个国内镜像源再重试通常能解决大半问题。如果报 Node 版本相关的语法错误多半是版本不合适装一个和项目要求接近的版本即可不必纠结用最新版。3.5 启动之后的验收清单服务起来不等于能用我习惯按下面这份清单逐项过一遍全过了才算部署完成访问http://服务器IP:8080能看到登录页不是 404 也不是白屏首次部署时能完成管理员账号的初始化或使用默认账号正常登录登录后能进入工作台左侧菜单能正常展开说明前后端接口通了新建一个数据源测试连接返回成功说明数据库连通没问题上传一张图片素材然后重启服务图片还在说明持久化目录挂对了用tail -f看日志确认没有反复刷的异常堆栈尤其是连接池相关的。这六条里第四条和第五条是最容易暴露隐藏问题的。很多人只看页面能打开就认为部署完了结果一接数据源就报驱动缺失或者重启后素材全丢。4. 跑起来之后从数据源到大屏的完整链路服务跑起来只是开始真正的活是把数据接进来、把图做出来。这一节按实际使用顺序讲一遍每个环节我会点出最容易卡住的地方。4.1 接数据源驱动和账号权限是关键进后台第一件事是新建数据源。填主机、端口、库名、账号密码点测试连接。这里最常见的三类问题一是驱动缺失某些数据库的 JDBC 驱动不在默认包里需要你手动把驱动 jar 放进指定目录再重启二是账号权限不足用于接数据的账号至少要有目标库的读权限只给SELECT通常够用但如果数据集里要用到存储过程或者临时表就需要额外授权三是网络不通特别是数仓在另一个网段的时候先确认这台服务器能不能 telnet 到目标端口别在页面上反复改配置。我一般会专门建一个只读账号给 datart 用而不是直接用 root。这么做有两个好处一是避免误操作改到业务数据二是权限清晰出问题能追溯。给权限的时候按库授权不要图省事给全局。4.2 数据集把裸表加工成业务能懂的东西数据集这一层是最值得花时间的地方。很多人接完数据源就急着做图结果后面每张图都要重写一遍 SQL改口径的时候改到崩溃。正确做法是把公共逻辑沉到数据集里需要过滤的软删除记录在这里过滤需要关联的基础表在这里关联需要算的同比环比在这里定义成计算字段。这样后面所有基于这个数据集的图都自动继承口径改一次全生效。字段的维度/指标属性一定要标对。维度会被当成分组依据指标会被当成聚合后的数值。如果你把一个数字字段标成了维度做图时它就不会求和而是每一行单独显示看起来图表乱七八糟。这个错误非常常见遇到了先检查字段属性。4.3 图表与仪表板样式和性能要一起考虑做图本身没什么门槛拖字段、选图形类型即可。真正影响体验的是两件事筛选器和性能。筛选器建议放在仪表板层级而不是每张图里各放一个这样一改全局联动用户体感完全不同。性能方面图表一多页面会同时发很多查询如果底层数据量大又没有索引第一次打开会很慢。我的经验是明细类图表尽量加时间范围默认值不要让用户一进来就查全量数据大表上的聚合尽量在数据集里预处理好或者干脆接数仓的汇总层不要直接怼原始明细表。如果某个看板打开要十几秒先看是哪个图慢把那个图的查询单独拎出来在数据库里跑一遍八成是缺索引或者扫描行数太大。4.4 数据大屏布局逻辑和普通看板不一样数据大屏是这套系统里比较有特色的部分它是自由布局用绝对定位的方式来摆组件跟普通仪表板的流式布局完全是两种思路。做大屏有几个实操要点一是先定分辨率再动手建议按主流的 1920×1080 设计然后让浏览器全屏展示尺寸对不上会出现组件错位二是素材提前准备好背景图、边框、图标统一风格临时找的素材拼出来会很乱三是动效克制一点滚动、闪烁、轮播这些用一两个点缀就够全屏都在动反而看不清数据。还有一点容易被忽略大屏通常挂在会议室的大电视上长时间开着所以数据刷新频率不要设得太高一分钟一次足够了设成几秒一次既浪费数据库资源也可能因为频繁查询导致页面卡顿。4.5 权限、分享与定时推送做完看板要给别人看这里涉及权限模型。它的权限一般是按组织、角色、资源三个维度来管你可以把某个仪表板授权给某个角色也可以只给某几个人。比较实用的做法是按部门建角色把看板授权到角色上新同事入职只要加到对应角色就能看到该看的东西不用一个个单独授权。分享方面有两个选择一个是把看板公开成链接适合内部大屏这种不需要登录的场景另一个是指定用户可见适合含敏感数据的看板。定时任务则用于定期把报表导出并推送到指定邮箱做日报周报很省事。配置定时任务时注意执行时间避开业务高峰导出本身也是一次全量查询放在凌晨比较稳妥。5. 踩坑实录我遇到过的那些报错这一节是我觉得全文最有价值的部分因为下面这些坑官方文档里基本不会写但实际部署时十有八九会碰到。5.1 启动阶段的问题页面能打开但白屏、控制台报资源 404。这是最典型的静态资源路径问题。多发生在源码部署时前端产物放错位置或者用 Nginx 做了反向代理但没有正确转发静态资源路径。排查方法是打开浏览器开发者工具看 Network找到具体 404 的是哪个文件然后回到服务器上看那个文件到底在不在对应目录里。如果是 Nginx 代理导致的检查一下location配置有没有把/全部转发给后端。启动时报数据库连接失败。先区分是「连不上」还是「认证失败」。连不上多半是地址写错或网络不通容器场景下最常见的就是把主机名写成了localhost认证失败就是账号密码问题注意密码里如果有特殊字符写在 YAML 里可能需要引号包裹否则会被解析错。还有一种少见情况是驱动版本和数据库版本不匹配报的错很含糊这种时候看完整堆栈最下面那个Caused by通常能找到真凶。启动很慢几分钟后才响应。一般是连接池或者初始化脚本在等待也可能是 JPA 在扫描实体。如果日志里一直在刷某个连接超时优先去查配置项里的地址是不是指向了一个不可达的主机程序在等超时。5.2 使用阶段的问题图表查询报错但数据集预览正常。这种情况通常是图表层拼出来的 SQL 有问题比如某个字段被当成了指标去聚合而它本身是文本类型也可能是筛选条件里传了空值导致语法错误。解决办法是把系统日志里的实际 SQL 复制出来在数据库里跑一遍报错信息会秒定位问题。数据量一上来页面就转圈。这是查询性能问题先确认是不是每次都查全量。可以让用户先选时间范围再查或者在数据集里加必要的过滤条件。另外如果连接的库里同一张表既要给业务系统用又要给 BI 用BI 的查询最好走从库或者专门的只读实例不要跟业务争资源。下面这张表把我们遇到的典型现象和对应排查方向列出来遇到问题可以直接对照现象优先排查方向常见原因页面白屏浏览器 Network 面板静态资源路径不对或代理配置错误登录后立刻被踢出Redis 配置未配置共享缓存或缓存不可用数据源测试失败网络与驱动端口不通、驱动缺失、账号无权限图表字段为空数据集字段属性维度指标标错或字段未授权时间筛选整体偏移时区设置数据库与应用服务器时区不一致重启后素材丢失数据卷挂载未做持久化或挂载路径写错看板打开极慢底层查询缺索引、扫全表、未加默认时间范围5.3 几条我踩出来的经验第一所有配置改动都留一份记录。改了什么、为什么改、改之前是什么值用文本记下来。这套系统配置项多三个月后你自己都不记得当初为什么把某个参数设成那个值有记录能省很多复盘时间。第二升级前一定先备份元数据库和文件目录。升级失败想回滚靠的就是这两样东西。备份命令简单但真正出事的时候有没有备份决定了你是半小时恢复还是一周重来。第三别在生产库上直接做实验。想试新图表、新数据源用一套测试环境练手。我见过有人直接在生产环境删数据集连带几个看板一起废掉。6. 上生产之前还得补的几个动作本地跑通和能上生产是两回事。如果你的看板要给整个部门甚至全公司用下面这几件事建议在正式上线前做完。6.1 反向代理与统一访问入口直接用 IP 加端口访问的方式对内网临时用还行正式用一定要套一层 Nginx。好处有三可以绑域名可以配 HTTPS可以统一做访问日志。配置思路很简单把 80 或 443 的请求转发到后端的 8080 端口同时把请求头里的真实 IP 传递下去否则你在系统里看到的访问来源全是代理服务器的地址。server { listen 80; server_name bi.example.com; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }如果大屏要在会议室长时间挂着建议单独给大屏页面开一个不带登录态的公开链接或者配一个长期有效的账号避免开会时弹出登录框的尴尬。6.2 备份、升级与回滚备份要做两件事数据库逻辑备份和文件目录打包。数据库用常规的导出工具每天定时导一份文件目录按周打一次包保留最近几份即可。恢复的时候顺序是先恢复数据库再把文件目录放回原位然后启动服务顺序反了可能出现引用不到文件的情况。升级建议的节奏是先在测试环境用同样的数据快照升级一次确认页面正常、图表正常、权限正常再动生产。生产升级前先把服务停掉备份完再替换出问题立刻把旧版本和旧数据一起换回来。回滚方案要在动手之前就想好不是出问题之后再想。6.3 监控与日志日志是最基础的排查手段。至少要保证应用日志按天切割、保留一段时间否则日志文件会把磁盘撑满这是个很常见但很致命的低级问题。查询日志也建议开着但不建议长期开得太详细量大了很占空间需要排查时临时打开即可。监控方面最基本的是三件事进程是否存活、端口是否可达、磁盘是否够用。前两个可以用简单的定时探活脚本第三个靠常规的磁盘监控。如果团队已经有监控体系就把这几项接进去比什么都强。另外建议对大屏和核心看板的打开速度做个记录一旦明显变慢往往说明底层数据量或者库的性能发生了变化。7. 一些零散的个人体会最后聊几句不成体系的感受。这套系统我前后部署过三次第一次踩了一堆坑第二次顺畅很多第三次基本就是按清单走流程。回头看真正花时间的从来不是命令本身而是搞清楚每个配置项为什么存在、每个选择会带来什么后果。比如为什么元数据库要独立、为什么前端产物必须先构建、为什么持久化目录一定要挂出来这些问题想明白了后面遇到任何变体你都能自己判断而不是到处搜教程。另一个体会是BI 类工具的价值七分在数据、三分在图表。我见过不少团队把大量时间花在调图表颜色和动效上结果数据口径对不上开会时两边数打架。先把指标定义清楚再谈好不好看这个顺序千万别颠倒。上线第一版宁愿只有五张图但这五张图的数字要经得起追问。如果你正准备动手我的建议是先花一个小时把官方仓库的说明和示例配置读一遍然后按本文的顺序走一遍遇到报错就去看日志最下面那个Caused by。绝大多数问题都不是系统本身的问题而是环境配置的差异。等你把这套东西跑通一次后面再做类似平台的部署思路基本都是通用的。