这套东西我前前后后折腾了差不多两个星期中间踩了不少坑也把datart的前后端结构、启动流程、配置链路摸了个七七八八。这里把所有经验整理出来给准备做datart二次开发的朋友一个可以直接照着抄的环境搭建手册。datart本身就是一款开源的数据可视化平台核心能力是做大屏、报表、数据洞察这类场景。二开之前首先要明白一点你在本地搭出来的这个环境不只是为了把项目跑起来看一眼而是要保证后面改代码、调试、加功能的时候整个链路是通的。要做到这一步前后端的启动方式、数据库初始化、接口代理、配置文件这些东西都得搞清楚否则后面每改一行代码都要猜半天。这个环境搭建手册适合谁一类是公司想基于datart做内部BI平台需要改品牌、改权限、接自己的登录体系的开发同学另一类是个人想研究可视化平台底层实现准备深度参与开源贡献的开发者。不管你属于哪一类只要把下面这套流程走完对datart的二次开发就算正式进门了。1. 先搞清楚datart的整体结构再动手1.1 datart是什么二开之前必须知道的几个模块datart的总体架构不算复杂但对第一次接触的人来说它的目录结构、模块划分、前后端分离方式需要花点时间理解。从功能上讲datart覆盖了数据源接入、数据集建模、图表配置、看板编排、用户权限管理这几条主线。从代码仓库的角度看datart大致可以分成几个部分前端工程、后端服务、部署相关脚本、文档示例。前端是标准的React单页应用负责页面展示和交互后端提供REST API和WebSocket能力负责数据查询、权限控制、元数据管理数据库则存放用户、组织、角色、数据源配置、看板定义等业务数据。二开之前建议先把官方仓库的README读一遍同时把根目录下的目录结构过一眼不要急着跑。很多新手一上来就执行构建命令结果各种报错根本原因就是没搞清楚模块之间的依赖关系。datart后端用的是Gradle多模块工程你如果对Gradle不熟至少要知道它和Maven类似都是做依赖管理和构建的只是语法和配置方式不同。1.2 官方代码仓库拿下来之后先看什么代码拉到本地之后我建议先按这个顺序看内容根目录的README和LICENSE确认协议和基本说明后端模块目录看清楚有几个子模块每个模块大概负责什么前端目录确认用的什么框架、什么构建工具数据库脚本和配置文件的大致位置docker-compose或部署相关脚本了解生产环境的部署方式这个顺序能帮你建立一张“地图”后面遇到问题的时候能快速定位到对应的模块和文件。比如你改了前端页面接口调不通你至少要知道接口是后端哪个Controller提供的而不是两眼一抹黑。我在第一次看代码的时候专门把后端几个模块的build.gradle文件打开扫了一遍确认了依赖关系。这一步很有价值因为后面你新增自定义功能的时候很可能需要往某个模块里加依赖如果不知道模块之间的边界很容易加错位置导致编译都过不去。2. 后端环境的搭建与数据库初始化2.1 本机需要装哪些东西版本怎么选后端部分最基本的三件套是JDK、Gradle、IDE。datart后端基于Spring BootJDK版本建议直接用8或者11具体看你拉取的代码版本。有些新版本代码可能要求更高的JDK所以先看一眼项目文档或者CI配置里的Java版本再决定。Gradle这块建议不要依赖IDE自带的Gradle而是自己装一个和项目匹配的版本。怎么判断项目用的Gradle版本看gradle/wrapper/gradle-wrapper.properties文件里的distributionUrl里面写得很清楚。最好使用Gradle Wrapper来构建也就是执行./gradlew命令这样会用项目指定的Gradle版本避免版本不一致带来的麻烦。IDE方面后端用IntelliJ IDEA是主流选择社区版就够用了不用非得破解旗舰版。导入Gradle工程的时候IDEA会自动下载依赖这个过程在国内网络环境下可能很慢甚至失败。我会在常见问题部分专门说这个事。2.2 配置文件与数据库初始化这是最容易被卡住的一步datart后端启动之前必须先把数据库准备好。项目默认可以跑H2内存数据库但这个模式只适合快速体验不适合二开调试因为服务一重启数据就没了。做二次开发建议直接上MySQL。操作步骤在MySQL里创建一个独立数据库名字随意比如datart_dev字符集用utf8mb4找到项目里的数据库初始化脚本通常在bin目录或config目录下文件名一般类似datart.sql或schema.sql也可能在db目录下按顺序执行脚本把初始表结构和基础数据导入到刚才创建的库修改后端配置文件把数据库连接信息改成你自己的配置文件的文件名一般是application.yml老版本可能是application.properties。在配置文件里需要改的核心项包括spring.datasource.url数据库连接地址注意加上useSSLfalsecharacterEncodingutf8之类的参数spring.datasource.username和spring.datasource.password数据库账号密码服务端口默认一般是8080如果你想换改server.port还有一个容易忽略的地方datart有license相关的配置。有些版本启动时会校验license文件如果缺失或者格式不对服务可能直接起不来。具体看项目里config目录有没有license相关说明按文档放在指定位置即可。2.3 启动后端服务的详细过程以及怎么确认启动成功数据库配置完成之后启动后端就比较机械了。在项目根目录执行./gradlew :datart-server:bootRun如果你用的是Windows命令换成gradlew.bat :datart-server:bootRun。这里datart-server是后端启动模块的名字具体名称以你拉的代码为准。首次运行时Gradle会下载大量依赖这个过程可能持续十几分钟甚至更久。下载完成后看到类似Started DatartServerApplication的日志说明启动成功。启动成功之后先别急着高兴。我习惯做三个验证打开浏览器访问http://localhost:8080看有没有返回页面或接口文档看后端日志里有没有报错尤其是数据库连接、Flyway迁移、license校验这三类错误用接口工具调一个简单的接口比如登录接口确认数据库读写正常后端启动的问题绝大多数集中在数据库配置不对、依赖下载不完整、端口被占用这三类。数据库配置错了日志里会直接抛连接异常端口被占用换一个或者杀掉占用进程就行。3. 前端环境的搭建与调试3.1 Node版本、包管理器选择别在这一步翻车前端这一侧核心工具是Node.js和包管理器。datart前端用的是React技术栈构建工具在不同版本里可能有差异有的用Webpack有的用Vite。不管你拉到的版本用哪个先看package.json里的scripts和devDependencies里面能看出构建工具和所需Node版本。Node版本是一个大坑。版本太高或者太低都可能导致依赖安装失败、构建报错。建议直接用Node 14或16的LTS版本这是大多数datart版本验证过的范围。如果本机Node版本不对推荐用nvm来切换不要硬在系统里改装多个版本。包管理器方面项目里有yarn.lock就用Yarn有package-lock.json就用npm尽量和项目锁文件保持一致避免依赖版本漂移。我自己的习惯是优先用项目锁文件对应的包管理器这样能最大程度复现开发者环境。3.2 接口代理配置前后端联调的关键前端服务默认跑在独立的端口上比如5173Vite或3000Webpack dev server。如果直接用这个地址访问页面你会发现页面能打开但数据请求全部失败因为前端页面请求的后端接口地址是8080端口而页面本身在另一个端口跨域了。解决方案就是配置开发代理。Vite项目在vite.config.ts里配置server.proxyWebpack项目在webpack.config.js里配置devServer.proxy。核心逻辑是把接口请求路径代理到后端地址比如server: { host: 0.0.0.0, port: 5173, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }除了普通HTTP接口datart里还有WebSocket连接用于图表和看板的实时交互。代理配置里如果涉及/ws这类路径也需要一并转发否则看板页面可能加载不出数据。这一步很容易漏我一开始就是只配了HTTP代理结果看板一直转圈。3.3 启动前端并完成前后端联调一切配置好之后安装依赖并启动yarn install yarn start依赖安装时间取决于网络和镜像源。国内环境建议先把npm或yarn的镜像源切换到国内源否则有些包下载会很慢。启动成功后终端会显示本地访问地址打开它能看到登录页说明前端服务正常。接下来做联调测试。用默认账号登录看文档或README登录成功后随便打开一个图表或看板页面确认数据能正常加载。这里有个小技巧打开浏览器开发者工具切到Network面板看接口请求是否都返回200如果有401、403、500按状态码去排查。前端和后端都跑通之后你的二开环境就算真正立起来了。后面改前端代码保存之后浏览器自动刷新改后端代码用IDEA的热重载或手动重启服务就能看到效果。整体调试体验是顺畅的这也是为什么值得花时间把环境彻底跑通。4. 二开环境里的常见问题与排坑实录4.1 前端依赖安装失败大概率是镜像和版本的问题前端依赖装不上是大家问得最多的问题。常见表现有几个node-sass安装失败编译报错某个包下载超时yarn install执行到一半进程崩溃node-sass这个问题根源在于它需要下载对应的二进制文件下载源在国外或者被墙的时候很容易失败。解决办法是换镜像源并把sass_binary_site指向国内镜像。新版datart可能已经用dart-sass替代了node-sass如果你的项目里没有node-sass那就不用担心这个问题。还有一个常见原因Node版本和某些依赖不兼容。比如用Node 18去装为Node 14编写的依赖经常会出现奇怪的报错。遇到这种情况先切换到项目推荐的Node版本再删除node_modules和锁文件重新安装。提示删除node_modules后重装是解决前端依赖问题的终极手段但每次重装都很耗时所以最好先确认Node版本和镜像源没问题再动手。4.2 后端构建慢、Gradle依赖下载失败的处理方式后端依赖下载慢尤其是Spring Boot相关的依赖包国内环境经常让人崩溃。我试过几种方案最有效的是给Gradle配置国内镜像源。在~/.gradle/init.gradle或项目里的build.gradle中添加阿里云或腾讯云的Maven镜像仓库配置。这样大部分依赖都能从国内镜像拉取速度会快很多。还有一种情况是某些依赖在镜像源里没有导致构建失败。这时候需要把官方Maven Central仓库也加上让Gradle按照仓库的顺序依次查找。配置完成后重新构建一次基本能解决。另外IDEA导入Gradle工程时如果显示依赖解析失败建议把IDEA的Gradle JVM版本设置成和项目一致同时开启“离线模式”不要勾选让IDEA尽量用本地缓存。4.3 数据库相关的坑以及启动时的其它报错后端启动失败最常见的原因还是数据库配置。整理一个速查表方便对照排查现象可能原因处理方式启动报数据库连接超时MySQL未启动或地址端口不对用客户端工具测试连接确认URL无误报Access denied for user账号密码错误或权限不足用root账号重新授权报Unknown database数据库还没创建执行CREATE DATABASE报表或字段不存在初始化脚本没执行或执行不完整重新执行初始化脚本启动时License相关异常license文件缺失或过期按文档放置license文件除了数据库后端启动还可能出现端口占用、Redis连接失败等问题看你拉取的版本有没有依赖Redis。如果用了Redis确保本机Redis服务已启动并且配置的地址端口正确。最后提醒一件事修改配置文件后一定要重新启动后端服务不要以为改完就自动生效。有些配置项需要重启进程才加载改动后顺手重启一下能省去很多无意义的排查。5. 二开环境里的后续操作建议5.1 跑通基础流程后再改代码这句话值得反复强调很多人把环境跑起来之后第一件事就是放飞自我直接动手改代码结果改了半天发现连基础流程都没走通问题根本分不清是环境还是代码引起的。我建议先做一次完整的“新建数据源-新建数据集-新建图表-保存看板”的流程确认系统核心链路是通的。这一步走通之后你的心里就有底了后面改任何功能出了问题至少能判断是改出来的bug还是原有问题。具体来说可以用默认账号登录接一个简单的数据源可以是MySQL里随便一张表也可以直接用datart自带的示例数据。然后创建一个数据集拖拽字段做一张图表再放到看板里保存。整个流程走一遍你对datart的数据流、API调用、页面路由都会有个直观认知。这个过程还有一个额外好处你会发现datart某些交互细节和普通BI工具不一样这些细节恰恰是后面二开时要注意的地方。提前熟悉能避免后面做功能时踩业务逻辑的坑。5.2 二开常用目录与扩展点知道改哪里最关键环境跑通之后你会发现datart的功能扩展点相对清晰但前提是知道去哪找。我自己常用的几个位置前端页面入口和路由配置决定了你新增页面时需要动哪些文件前端组件目录图表、按钮、弹窗这些可复用组件基本都在这里后端Controller层前端API对应的方法基本都能在这里找到数据源扩展相关的代码如果你想支持一个新的数据源类型主要改这里权限和用户体系相关代码企业二开基本都会动这一块我的习惯是在IDE里把项目结构树按模块折叠只展开当前要改的部分。这样不会被庞大的代码量吓到也能更快定位问题。特别是在刚开始接触大项目的时候一次只看一个模块效率远高于通读全部源码。还有一点datart的配置中心化和前后端分离做得比较好所以二开时尽量遵循它现有的分层方式不要为了一时方便在前端代码里硬塞后端逻辑或者在后端代码里写死前端页面路径。保持边界清晰后续维护会轻松很多。写在最后环境搭建这件事本质上没有什么高深的技术含量但确实很考验耐心和细心。我第一次搭建的时候光数据库初始化就卡了快一天后来发现只是初始化脚本跑的顺序不对。前端代理也踩过WebSocket的坑看板数据加载不出来排查了半天才发现是代理配置少了一段。这些经历让我养成了一个习惯每做一步先验证这一步的结果再进入下一步。磨刀不误砍柴工环境搭得稳后面二开才有好心情。最后分享一个小技巧把本地环境的启动步骤写成一个简单的脚本或者文档放在项目目录下。别笑很多项目组换了新电脑、来了新同事重新搭环境的时候那种每个人靠记忆摸索的痛苦经历过的人都懂。有一份清晰的启动文档既能帮自己省事也能帮整个团队减少不必要的沟通成本。整个流程走完你对datart的理解已经超过大多数只看过文档的人了。接下来就放心大胆地去改吧基于这套环境不管是接内部登录、改看板样式还是新增数据源类型你都有了坚实的起点。