尧图网页设计 
1. 为什么需要搭建 datart 二开环境datart 这个项目做数据可视化的同学应该都听过。它算是我见过国内开源BI里代码结构比较清爽的一个后端基于 Spring Boot前端基于 React Vite整套链路不复杂拿来改一改做企业内部的看板平台比从零写省太多事。但正因为是开源项目文档里关于“怎么把环境跑起来做二次开发”的部分一直写得比较简单很多人在环境这步就卡住了。我自己在搭这套二开环境的时候前后折腾了大半天踩了不少坑。有的是因为版本选的太新有的是因为配置项没理解透还有的是前端代理和后端跨域之间互相牵扯。后来理清楚之后发现其实整个流程可以拆成几条清晰的线后端起来、前端起来、数据库通、联调通。今天就把这套完整的过程整理出来包括我选型时的考量和后来排过的坑给后面做二开的朋友一条好走的捷径。这套内容适合谁适合已经会用 Git、懂一点 Java 和 React 基础、准备在 datart 上做定制功能的研发同学。如果你是纯部署使用不打算改代码那直接找官方镜像跑即可不需要看这篇。2. 二开前的准备工作2.1 版本选型是第一步也是大部分人翻车的地方datart 的仓库里master 分支在不断迭代但开源项目的通病是主干分支不一定比稳定标签好用。我第一次直接拉了 master结果前端依赖安装时有一堆版本兼容报错折腾了半小时才意识到问题不在环境而在代码版本本身。我的建议是不要追求最新。去 GitHub 仓库的 Tags 页面找一个 release 版本像我这边用的就是 1.0.0-rc.2 这个版本。这个版本整体比较稳前后端配套完善社区讨论也多遇到问题搜得到答案。如果你所在团队有特殊需求必须用某个提交那至少也要确认前端 package.json 里的依赖是可以正常安装的再动手。这里顺便说一个选版本的小技巧看 release 页面的发布时间和配套说明。如果 release 说明里明确写了“前端构建通过”“后端启动验证通过”之类的字样说明作者至少自己跑通了一遍这种版本踩坑概率会小很多。2.2 本地环境需要准备哪些东西datart 前后端分离整套环境的依赖项如下组件版本建议用途说明JDK1.8 或 8u 以上datart 后端基于 Spring Boot 2.xJDK 8 完全够用Maven3.6 以上后端依赖管理和构建Node.js14.x 或 16.x前端构建环境太新的版本反而容易出问题npm / yarnnpm 6 或 yarn 1.x前端包管理工具MySQL5.7 或 8.0主数据库datart 默认使用 MySQLRedis5.0 以上缓存部分功能强依赖 RedisIDEIDEA 或 VS Code后端 IDEA前端 VS Code 即可有两点要特别提醒。第一Node.js 版本不要一上来就装 18 或 20虽然新版功能多但 datart 的 webapp 里不少旧依赖在新版本下会有兼容问题我实测 16.x 是最稳妥的。第二如果把 MySQL 和 Redis 都放在 Docker 里跑注意 Docker 的容器时间要和宿主机保持一致否则后端启动时会因为时间戳校验问题报错这个后面在排查章节再展开。2.3 拉取代码与目录结构速览确定好版本后直接拉代码git clone https://github.com/running-elephant/datart.git cd datart git checkout 1.0.0-rc.2拉下来之后先花五分钟把目录结构过一遍不要急着启动。datart 的代码组织比较清晰bin目录启动脚本、数据库初始化脚本等config目录配置文件模板里面包含application.yml的样例core目录后端核心逻辑server目录启动入口和控制器层webapp目录前端工程pom.xml后端 Maven 聚合配置我第一次看这个目录的时候有点懵因为很多开源项目会单独建一个backend目录放后端代码datart 直接把它落在了根目录这个刚开始会不习惯。记住一条核心线前端在webapp后端就是根目录这一堆 Maven 模块两者通过 HTTP API 通信理清这条线后面联调就顺了。3. 后端环境搭建与启动3.1 初始化数据库是第一步顺序不能反很多人习惯先把后端代码跑起来再说数据库这顺序在 datart 这里是行不通的。datart 启动时一定会连数据库做表结构校验如果没有库和表启动直接会失败。我用的方式是先用 MySQL 创建一个独立库然后导入官方提供的初始化脚本。脚本位置在bin目录下文件名一般是datart.sql或类似的名字具体以实际拉下来的版本为准CREATE DATABASE IF NOT EXISTS datart DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; USE datart; SOURCE /你的本地路径/datart/bin/datart.sql;注意字符集要使用utf8mb4不要用utf8。datart 里有存 JSON 字段utf8mb4对表情符号和特殊字符支持更好直接用utf8后续导入数据或者展示图表时会出现问号乱码。导入完成后可以验证一下核心表是否存在USE datart; SHOW TABLES;正常的表数量会有几十张包括user、organization、source、view、chart、dashboard等核心表。如果你看到只有寥寥几张表大概率是脚本没执行完整重新执行一次。3.2 修改配置文件核心就这几处数据库准备好之后打开config目录下的application.yml有些版本叫application-demo.yml作用一样需要关注和修改的地方其实不多spring: datasource: url: jdbc:mysql://localhost:3306/datart?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalseallowPublicKeyRetrievaltrue username: root password: 你的数据库密码 redis: host: localhost port: 6379 password: 如果你的 Redis 设置了密码就填否则留空 server: port: 8080有几个配置细节值得展开说一下。serverTimezoneAsia/Shanghai一定要加否则后端连接 MySQL 时会报时间区错误。allowPublicKeyRetrievaltrue是 MySQL 8.0 连接时需要的参数如果你用 5.7 不加也行但加了也没坏处索性一起写上。另外 datart 还有一个datart.security.token相关的配置控制 JWT 的 token 密钥和过期时间。如果是团队协作开发建议每个人都生成一个自己的密钥否则别人用你的接口文档调试时会因为 token 不匹配而失败。3.3 Maven 构建与启动配置文件改好后回到项目根目录mvn clean install -DskipTests第一次构建会比较慢Maven 要把所有依赖下载到本地仓库。这里有个网络上的建议如果 Maven 下载依赖卡住优先检查是不是镜像源问题换成阿里云的 Maven 镜像会快很多。配置方式是在settings.xml中增加镜像地址这个属于 Maven 基础操作不再赘述。构建完成后启动入口有两个方式。一种是在 IDE 中运行datart-server模块下的启动类类名一般是ServerApplication或类似名称另一种是在命令行中执行java -jar server/target/datart-server.jar看到日志中打印出Started ServerApplication in xx seconds并且没有异常堆栈说明后端启动成功了。此时在浏览器访问http://localhost:8080/api/v1/health如果返回一串 JSON 或正常的响应内容说明后端基础健康检查通过。后端启动这个阶段有几个高频报错先写在前面给各位提个醒如果报数据库连接失败优先检查数据库名、用户名和密码是否匹配如果报user表不存在说明初始化脚本没执行成功重新执行一次如果报端口占用直接改server.port或者把占用进程关掉。4. 前端环境搭建与启动4.1 前端依赖安装最容易出问题的环节后端启动只是个开始前端环境搭建是二开过程中的重头戏。进入webapp目录cd webapp npm install这里我第一次安装时踩了个大坑。因为网络原因npm install跑到一半失败报各种依赖版本冲突。后来我换成了 yarn 才顺利安装完成。这不是说 yarn 比 npm 好多少而是 yarn 的缓存机制和依赖解析策略在这种老项目里表现更稳定。如果你也遇到了 npm 安装失败的问题不妨直接试 yarnyarn install依赖安装成功后启动开发服务器npm run start或yarn start启动成功后终端会打印出开发服务器的访问地址。datart 前端默认端口不是 3000也不是 8080而是 7000。浏览器访问http://localhost:7000能看到 datart 的登录页面说明前端起来了。4.2 前端代理配置解决跨域问题的关键这里有一个非常关键的配置你要能打开登录页不代表能正常登录。因为前端跑在 7000 端口后端跑在 8080 端口如果前端直接向后端发请求浏览器会因跨域拦截导致登录失败。datart 前端的构建工具是 Vite代理配置在vite.config.ts文件中。开发环境下Vite 会在本地启动一个代理服务将请求转发到后端。默认配置长这样server: { host: 0.0.0.0, port: 7000, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }也就是说当你前端访问/api/v1/...时Vite 会把请求转发到http://localhost:8080从而避免跨域问题。大多数情况下这个配置不用改后端 IP 变了才需要跟着变。如果是团队协作开发你在 A 电脑改前端后端在 B 电脑那么目标地址就要改成 B 电脑的 IP。在这种模式下changeOrigin这个参数必须保持为true否则请求头里的 Host 信息会不对后端可能无法正确处理。4.3 首次登录与默认账号前后端都启动后在登录页输入默认账号密码。datart 默认的管理员账号一般是admin初始密码也是admin具体以官方文档为准不同版本有差异。登录成功后你会进入 datart 的主界面可以看到数据源管理、视图构建和仪表板等功能模块。到这一步一套最小的二开环境就算跑通了。你可以去数据源配置页面连一个自己的业务库然后试着创建视图、拖拽出一个图表。这个闭环跑通之后你后续改代码、加功能就有一个可用的验证环境了。5. Redi s与缓存问题的前置处理5.1 为什么 datart 离不开 Redis很多人在搭环境时会忽略 Redis等到运行某些功能报错了才回去补。datart 在多个核心场景依赖 Redis 做缓存数据源的元数据缓存图表查询结果缓存部分权限和会话信息管理。如果你本地没有装 Redis后端虽然能启动但到了实际执行查询、刷新视图这类操作时会遇到各种缓存异常报错信息五花八门最常见的是Caused by: redis.clients.jedis.exceptions.JedisConnectionException。解决方法很简单本地装一个 Redis或者用 Docker 快速起一个docker run -d --name datart-redis -p 6379:6379 redis:6如果 Redis 设置了密码要在application.yml中同步修改不要只改一处。我见过有同事改了数据库密码忘了改 Redis 密码结果缓存服务一直连不上排错了大半天。5.2 Redis 连接不上怎么办Redis 连接不上常见的排查步骤先确认 Redis 服务是否启动redis-cli ping返回PONG说明正常确认端口是否被占用或监听地址是否正确。Redis 默认只监听本机127.0.0.1如果你把 Redis 放到 Docker 里宿主机访问要用-p 6379:6379做映射确认application.yml中的spring.redis.host和port是否指向正确地址。如果你用的是 Docker 容器作为数据库和缓存还要注意一个问题容器内的服务之间存在网络通信需要用容器名或自定义网络来解析地址不要直接写localhost。6. 前后端联调中的关键问题实录6.1 Token 机制与登录态保持后端启动后第一次登录时前端会调用登录接口后端会返回一个 token前端将它保存在本地通常是 localStorage。后续的所有请求都会在请求头中带上这个 token后端拦截器校验通过后才会放行。二开过程中如果你经常使用 Swagger 或 Postman 调试接口记得先通过登录接口拿到 token然后在调试工具中配置请求头Authorization: Bearer 你的token不要手动把 token 拼到 URL 参数里datart 后端只从请求头读取拼在 URL 上不仅没用还可能被日志采集下来有一定安全风险。6.2 前端页面注册流程的定制datart 默认的注册逻辑是允许用户自助注册账号。在企业内部二开时这个功能通常要关掉改为管理员统一创建账号。相关开关在后端配置项里datart: user: register: false将注册开关设为false后前端登录页会隐藏“注册”入口只能通过管理员在后台创建用户。我实际改过这个配置确实生效。如果你还想做更细的权限控制比如指定某些组织下的用户才能注册那就需要改后端逻辑了这在二开中属于比较典型的定制场景。6.3 联调时前端改了代码不生效这个问题很常见不一定是你代码写错了。Vite 开发服务器会热更新但某些深层依赖修改后不会触发自动重载。我常用的办法是改完代码手动刷新页面还不生效时直接重启开发服务器# 在 webapp 目录下Ctrl C 退出 yarn start另外一个容易忽略的点是datart 前端部分代码是动态加载的浏览器缓存可能导致你改了代码看不到效果。打开开发者工具Network 面板里勾选 Disable cache或者直接强制刷新CtrlShiftR。6.4 后端热部署配置前端有 Vite 的热更新后端其实也可以配置热部署。Spring Boot 官方提供了spring-boot-devtools在pom.xml中引入后修改 Java 代码时IDEA 中按 Ctrl F9 可以快速重新编译省去重启整个应用的等待时间。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-devtools/artifactId optionaltrue/optional /dependency实际体验来看devtools 对中小项目的编译速度提升很明显。但它有个缺点会监听所有 classpath 文件变化偶尔会触发无意义的重启。如果你发现 IDE 卡顿或者频繁重启可以在配置里排除掉不需要监听的目录spring: devtools: restart: exclude: static/**,public/**7. 常见问题与排查技巧实录7.1 数据库连接失败与编码问题这个错误应该是出现频率最高的。排查步骤非常简单确认 MySQL 服务已启动在命令行用账号密码连一下库mysql -uroot -p看能不能进去确认 datart 库名与application.yml中填写的是否一致确认字符集是否为utf8mb4如果不是重新建库或修改字符集。另外MySQL 8.0 默认认证插件是caching_sha2_password有些旧版本的 JDBC 驱动不兼容报错信息会出现Public Key Retrieval is not allowed。解决方案就是在 URL 上加上allowPublicKeyRetrievaltrue和useSSLfalse我在 3.2 节里已经提过这里再强调一次因为这个参数太容易忽略了。7.2 前端编译报错与依赖冲突前端编译报错的表现形式很多常见的有ERESOLVE unable to resolve dependency tree依赖树解析失败。这种情况最常见的解法是改 npm 配置或者直接用 yarnTypeError: Cannot read properties of undefined多半是版本不兼容导致的 API 变化检查关键依赖的版本号Node.js version xxx is not supportedNode 版本太新或太旧切换到 14.x 或 16.x。如果你在安装依赖时遇到了 prisma、sharp 这类包含二进制文件的原生模块还需要注意本机是否安装了 Python 环境和 C 编译工具链。Windows 用户在安装这类依赖时经常会二次报错建议仔细看 npm 或者 yarn 的报错提示缺什么补什么。7.3 IDEA 启动后端时报错合集IDEA 启动后端最常见的错误有两种Error creating bean with name xxx这个一般是 Spring 容器初始化某个 Bean 失败。点开完整堆栈看最底下Caused by那一行通常是数据库连不上或者配置项缺失Port 8080 was already in use端口被占用。终端执行lsof -i:8080Mac/Linux或netstat -ano | findstr 8080Windows找到占用进程关掉或者改后端端口。在这里我有一个习惯每次新环境启动后端时都会用一个干净的日志输出方式mvn spring-boot:run -pl server -am -Dspring-boot.run.profilesdev这样可以在启动时指定 profile日志也会按模块输出排查问题比直接跑 jar 包清晰很多。7.4 数据导入导出异常datart 支持数据源的导入导出功能有一个很隐蔽的坑如果本地的时区与数据库的时区不一致导入数据后时间字段会出现偏移。解决方案是在数据库连接串上明确指定serverTimezoneAsia/Shanghai并且 MySQL 容器内部也要设置正确的时区。如果你的 MySQL 跑在 Docker 里可以在启动容器时加上环境变量docker run -d --name mysql-datart \ -e MYSQL_ROOT_PASSWORD你的密码 \ -e TZAsia/Shanghai \ -p 3306:3306 \ mysql:5.7这个参数不加哪怕后端配置了serverTimezone容器默认的 UTC 时区也会给数据写入带来各种奇怪的时间问题。7.5 常见问题速查表现象可能原因解决方案后端启动报 Unable to connect to MySQL数据库未启动或账号密码错误核对连接串与账号权限前端登录一直转圈后端未启动或代理配置错误检查后端进程与 vite.config.ts图标加载不出来前端构建不完整重新执行 yarn install yarn start图表查询超时Redis 未配置或查询过慢启动 Redis检查查询 SQL 性能注册按钮消失datart.user.register设为 false按需调整配置时间字段偏移MySQL 容器时区不为亚洲时区增加 TZAsia/Shanghai 环境变量依赖安装失败Node 版本过新或过旧切换 Node 14/168. 二开过程中的一些实操心得8.1 先跑通再改代码二开最忌讳上来就想改代码。先把原始项目完整跑通一次能够正常登录、建数据源、画图表再开始动刀。这样你能充分理解数据从哪来、接口怎么流转、界面怎么渲染后面改起来才不会抓瞎。我见过不少刚开始做二开的人在环境都还没完全跑通的情况下就直接修改权限逻辑结果改出来的功能自己都不清楚为什么生效或不生效后期排查非常痛苦。这不是技术能力的问题而是对系统全局认知不够。8.2 从最小闭环开始做定制做完环境验证后建议的第一个二开需求选一个小的、端到端的功能点。比如在仪表板增加一个自定义背景色设置或者修改用户列表的分页大小。这个闭环涉及前端菜单入口、后端 API、数据库存储做完后你就对 datart 的整体开发链路有了本能的熟悉感远比读源码来得快。8.3 保留一份干净的基线环境二开做久了你会发现改来改去环境越跑越脏。依赖冲突、配置混乱、数据被测试数据污染各种问题接踵而至。我的做法是维护一份干净的基线单独用一个目录存放未改动的原始代码本地数据库保持一个干净的备份脚本每次大改前用这份基线重新起一套环境确保问题的根源在自己的代码里而不是环境里。9. 二开场景扩展思路一套环境跑通之后可以做的事情就很灵活了。datart 本身的能力边界在于它是一套通用的可视化框架具体到某个行业的术语、交互方式、数据模型都需要二开来补齐。比较常见的二开方向包括登录对接企业内部统一认证比如 OAuth2 或 CAS数据源类型扩展适配公司内部自研的存储引擎图表类型的定制在原有基础上增加特定行业的图表权限模型调整把 datart 的组织权限与业务系统的角色体系打通前端主题改造让 UI 风格与公司产品保持一致。这里每个方向都有不少文章可以做但无论哪个方向前提都是你能独立把环境跑起来、看明白数据流。环境搭建这块敲门砖过了后面的二开就回到了日常开发的节奏难度反而没那么大了。最后再分享一个小经验在配置环境的过程中每一步操作尽量记录到自己的笔记里尤其是命令和配置项。因为二开不是一次性的团队里新同学入职、换电脑、代码回滚都需要重新搭环境。你手里的这份记录就是团队里最宝贵的实操文档。我自己的这套环境搭建笔记前前后后帮团队四个人省掉了重复踩坑的时间这也是我今天写这篇文章的初衷。 datart二次开发环境搭建全攻略：从0到1跑通前后端联调
1. 为什么需要搭建 datart 二开环境datart 这个项目做数据可视化的同学应该都听过。它算是我见过国内开源BI里代码结构比较清爽的一个后端基于 Spring Boot前端基于 React Vite整套链路不复杂拿来改一改做企业内部的看板平台比从零写省太多事。但正因为是开源项目文档里关于“怎么把环境跑起来做二次开发”的部分一直写得比较简单很多人在环境这步就卡住了。我自己在搭这套二开环境的时候前后折腾了大半天踩了不少坑。有的是因为版本选的太新有的是因为配置项没理解透还有的是前端代理和后端跨域之间互相牵扯。后来理清楚之后发现其实整个流程可以拆成几条清晰的线后端起来、前端起来、数据库通、联调通。今天就把这套完整的过程整理出来包括我选型时的考量和后来排过的坑给后面做二开的朋友一条好走的捷径。这套内容适合谁适合已经会用 Git、懂一点 Java 和 React 基础、准备在 datart 上做定制功能的研发同学。如果你是纯部署使用不打算改代码那直接找官方镜像跑即可不需要看这篇。2. 二开前的准备工作2.1 版本选型是第一步也是大部分人翻车的地方datart 的仓库里master 分支在不断迭代但开源项目的通病是主干分支不一定比稳定标签好用。我第一次直接拉了 master结果前端依赖安装时有一堆版本兼容报错折腾了半小时才意识到问题不在环境而在代码版本本身。我的建议是不要追求最新。去 GitHub 仓库的 Tags 页面找一个 release 版本像我这边用的就是 1.0.0-rc.2 这个版本。这个版本整体比较稳前后端配套完善社区讨论也多遇到问题搜得到答案。如果你所在团队有特殊需求必须用某个提交那至少也要确认前端 package.json 里的依赖是可以正常安装的再动手。这里顺便说一个选版本的小技巧看 release 页面的发布时间和配套说明。如果 release 说明里明确写了“前端构建通过”“后端启动验证通过”之类的字样说明作者至少自己跑通了一遍这种版本踩坑概率会小很多。2.2 本地环境需要准备哪些东西datart 前后端分离整套环境的依赖项如下组件版本建议用途说明JDK1.8 或 8u 以上datart 后端基于 Spring Boot 2.xJDK 8 完全够用Maven3.6 以上后端依赖管理和构建Node.js14.x 或 16.x前端构建环境太新的版本反而容易出问题npm / yarnnpm 6 或 yarn 1.x前端包管理工具MySQL5.7 或 8.0主数据库datart 默认使用 MySQLRedis5.0 以上缓存部分功能强依赖 RedisIDEIDEA 或 VS Code后端 IDEA前端 VS Code 即可有两点要特别提醒。第一Node.js 版本不要一上来就装 18 或 20虽然新版功能多但 datart 的 webapp 里不少旧依赖在新版本下会有兼容问题我实测 16.x 是最稳妥的。第二如果把 MySQL 和 Redis 都放在 Docker 里跑注意 Docker 的容器时间要和宿主机保持一致否则后端启动时会因为时间戳校验问题报错这个后面在排查章节再展开。2.3 拉取代码与目录结构速览确定好版本后直接拉代码git clone https://github.com/running-elephant/datart.git cd datart git checkout 1.0.0-rc.2拉下来之后先花五分钟把目录结构过一遍不要急着启动。datart 的代码组织比较清晰bin目录启动脚本、数据库初始化脚本等config目录配置文件模板里面包含application.yml的样例core目录后端核心逻辑server目录启动入口和控制器层webapp目录前端工程pom.xml后端 Maven 聚合配置我第一次看这个目录的时候有点懵因为很多开源项目会单独建一个backend目录放后端代码datart 直接把它落在了根目录这个刚开始会不习惯。记住一条核心线前端在webapp后端就是根目录这一堆 Maven 模块两者通过 HTTP API 通信理清这条线后面联调就顺了。3. 后端环境搭建与启动3.1 初始化数据库是第一步顺序不能反很多人习惯先把后端代码跑起来再说数据库这顺序在 datart 这里是行不通的。datart 启动时一定会连数据库做表结构校验如果没有库和表启动直接会失败。我用的方式是先用 MySQL 创建一个独立库然后导入官方提供的初始化脚本。脚本位置在bin目录下文件名一般是datart.sql或类似的名字具体以实际拉下来的版本为准CREATE DATABASE IF NOT EXISTS datart DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; USE datart; SOURCE /你的本地路径/datart/bin/datart.sql;注意字符集要使用utf8mb4不要用utf8。datart 里有存 JSON 字段utf8mb4对表情符号和特殊字符支持更好直接用utf8后续导入数据或者展示图表时会出现问号乱码。导入完成后可以验证一下核心表是否存在USE datart; SHOW TABLES;正常的表数量会有几十张包括user、organization、source、view、chart、dashboard等核心表。如果你看到只有寥寥几张表大概率是脚本没执行完整重新执行一次。3.2 修改配置文件核心就这几处数据库准备好之后打开config目录下的application.yml有些版本叫application-demo.yml作用一样需要关注和修改的地方其实不多spring: datasource: url: jdbc:mysql://localhost:3306/datart?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalseallowPublicKeyRetrievaltrue username: root password: 你的数据库密码 redis: host: localhost port: 6379 password: 如果你的 Redis 设置了密码就填否则留空 server: port: 8080有几个配置细节值得展开说一下。serverTimezoneAsia/Shanghai一定要加否则后端连接 MySQL 时会报时间区错误。allowPublicKeyRetrievaltrue是 MySQL 8.0 连接时需要的参数如果你用 5.7 不加也行但加了也没坏处索性一起写上。另外 datart 还有一个datart.security.token相关的配置控制 JWT 的 token 密钥和过期时间。如果是团队协作开发建议每个人都生成一个自己的密钥否则别人用你的接口文档调试时会因为 token 不匹配而失败。3.3 Maven 构建与启动配置文件改好后回到项目根目录mvn clean install -DskipTests第一次构建会比较慢Maven 要把所有依赖下载到本地仓库。这里有个网络上的建议如果 Maven 下载依赖卡住优先检查是不是镜像源问题换成阿里云的 Maven 镜像会快很多。配置方式是在settings.xml中增加镜像地址这个属于 Maven 基础操作不再赘述。构建完成后启动入口有两个方式。一种是在 IDE 中运行datart-server模块下的启动类类名一般是ServerApplication或类似名称另一种是在命令行中执行java -jar server/target/datart-server.jar看到日志中打印出Started ServerApplication in xx seconds并且没有异常堆栈说明后端启动成功了。此时在浏览器访问http://localhost:8080/api/v1/health如果返回一串 JSON 或正常的响应内容说明后端基础健康检查通过。后端启动这个阶段有几个高频报错先写在前面给各位提个醒如果报数据库连接失败优先检查数据库名、用户名和密码是否匹配如果报user表不存在说明初始化脚本没执行成功重新执行一次如果报端口占用直接改server.port或者把占用进程关掉。4. 前端环境搭建与启动4.1 前端依赖安装最容易出问题的环节后端启动只是个开始前端环境搭建是二开过程中的重头戏。进入webapp目录cd webapp npm install这里我第一次安装时踩了个大坑。因为网络原因npm install跑到一半失败报各种依赖版本冲突。后来我换成了 yarn 才顺利安装完成。这不是说 yarn 比 npm 好多少而是 yarn 的缓存机制和依赖解析策略在这种老项目里表现更稳定。如果你也遇到了 npm 安装失败的问题不妨直接试 yarnyarn install依赖安装成功后启动开发服务器npm run start或yarn start启动成功后终端会打印出开发服务器的访问地址。datart 前端默认端口不是 3000也不是 8080而是 7000。浏览器访问http://localhost:7000能看到 datart 的登录页面说明前端起来了。4.2 前端代理配置解决跨域问题的关键这里有一个非常关键的配置你要能打开登录页不代表能正常登录。因为前端跑在 7000 端口后端跑在 8080 端口如果前端直接向后端发请求浏览器会因跨域拦截导致登录失败。datart 前端的构建工具是 Vite代理配置在vite.config.ts文件中。开发环境下Vite 会在本地启动一个代理服务将请求转发到后端。默认配置长这样server: { host: 0.0.0.0, port: 7000, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }也就是说当你前端访问/api/v1/...时Vite 会把请求转发到http://localhost:8080从而避免跨域问题。大多数情况下这个配置不用改后端 IP 变了才需要跟着变。如果是团队协作开发你在 A 电脑改前端后端在 B 电脑那么目标地址就要改成 B 电脑的 IP。在这种模式下changeOrigin这个参数必须保持为true否则请求头里的 Host 信息会不对后端可能无法正确处理。4.3 首次登录与默认账号前后端都启动后在登录页输入默认账号密码。datart 默认的管理员账号一般是admin初始密码也是admin具体以官方文档为准不同版本有差异。登录成功后你会进入 datart 的主界面可以看到数据源管理、视图构建和仪表板等功能模块。到这一步一套最小的二开环境就算跑通了。你可以去数据源配置页面连一个自己的业务库然后试着创建视图、拖拽出一个图表。这个闭环跑通之后你后续改代码、加功能就有一个可用的验证环境了。5. Redi s与缓存问题的前置处理5.1 为什么 datart 离不开 Redis很多人在搭环境时会忽略 Redis等到运行某些功能报错了才回去补。datart 在多个核心场景依赖 Redis 做缓存数据源的元数据缓存图表查询结果缓存部分权限和会话信息管理。如果你本地没有装 Redis后端虽然能启动但到了实际执行查询、刷新视图这类操作时会遇到各种缓存异常报错信息五花八门最常见的是Caused by: redis.clients.jedis.exceptions.JedisConnectionException。解决方法很简单本地装一个 Redis或者用 Docker 快速起一个docker run -d --name datart-redis -p 6379:6379 redis:6如果 Redis 设置了密码要在application.yml中同步修改不要只改一处。我见过有同事改了数据库密码忘了改 Redis 密码结果缓存服务一直连不上排错了大半天。5.2 Redis 连接不上怎么办Redis 连接不上常见的排查步骤先确认 Redis 服务是否启动redis-cli ping返回PONG说明正常确认端口是否被占用或监听地址是否正确。Redis 默认只监听本机127.0.0.1如果你把 Redis 放到 Docker 里宿主机访问要用-p 6379:6379做映射确认application.yml中的spring.redis.host和port是否指向正确地址。如果你用的是 Docker 容器作为数据库和缓存还要注意一个问题容器内的服务之间存在网络通信需要用容器名或自定义网络来解析地址不要直接写localhost。6. 前后端联调中的关键问题实录6.1 Token 机制与登录态保持后端启动后第一次登录时前端会调用登录接口后端会返回一个 token前端将它保存在本地通常是 localStorage。后续的所有请求都会在请求头中带上这个 token后端拦截器校验通过后才会放行。二开过程中如果你经常使用 Swagger 或 Postman 调试接口记得先通过登录接口拿到 token然后在调试工具中配置请求头Authorization: Bearer 你的token不要手动把 token 拼到 URL 参数里datart 后端只从请求头读取拼在 URL 上不仅没用还可能被日志采集下来有一定安全风险。6.2 前端页面注册流程的定制datart 默认的注册逻辑是允许用户自助注册账号。在企业内部二开时这个功能通常要关掉改为管理员统一创建账号。相关开关在后端配置项里datart: user: register: false将注册开关设为false后前端登录页会隐藏“注册”入口只能通过管理员在后台创建用户。我实际改过这个配置确实生效。如果你还想做更细的权限控制比如指定某些组织下的用户才能注册那就需要改后端逻辑了这在二开中属于比较典型的定制场景。6.3 联调时前端改了代码不生效这个问题很常见不一定是你代码写错了。Vite 开发服务器会热更新但某些深层依赖修改后不会触发自动重载。我常用的办法是改完代码手动刷新页面还不生效时直接重启开发服务器# 在 webapp 目录下Ctrl C 退出 yarn start另外一个容易忽略的点是datart 前端部分代码是动态加载的浏览器缓存可能导致你改了代码看不到效果。打开开发者工具Network 面板里勾选 Disable cache或者直接强制刷新CtrlShiftR。6.4 后端热部署配置前端有 Vite 的热更新后端其实也可以配置热部署。Spring Boot 官方提供了spring-boot-devtools在pom.xml中引入后修改 Java 代码时IDEA 中按 Ctrl F9 可以快速重新编译省去重启整个应用的等待时间。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-devtools/artifactId optionaltrue/optional /dependency实际体验来看devtools 对中小项目的编译速度提升很明显。但它有个缺点会监听所有 classpath 文件变化偶尔会触发无意义的重启。如果你发现 IDE 卡顿或者频繁重启可以在配置里排除掉不需要监听的目录spring: devtools: restart: exclude: static/**,public/**7. 常见问题与排查技巧实录7.1 数据库连接失败与编码问题这个错误应该是出现频率最高的。排查步骤非常简单确认 MySQL 服务已启动在命令行用账号密码连一下库mysql -uroot -p看能不能进去确认 datart 库名与application.yml中填写的是否一致确认字符集是否为utf8mb4如果不是重新建库或修改字符集。另外MySQL 8.0 默认认证插件是caching_sha2_password有些旧版本的 JDBC 驱动不兼容报错信息会出现Public Key Retrieval is not allowed。解决方案就是在 URL 上加上allowPublicKeyRetrievaltrue和useSSLfalse我在 3.2 节里已经提过这里再强调一次因为这个参数太容易忽略了。7.2 前端编译报错与依赖冲突前端编译报错的表现形式很多常见的有ERESOLVE unable to resolve dependency tree依赖树解析失败。这种情况最常见的解法是改 npm 配置或者直接用 yarnTypeError: Cannot read properties of undefined多半是版本不兼容导致的 API 变化检查关键依赖的版本号Node.js version xxx is not supportedNode 版本太新或太旧切换到 14.x 或 16.x。如果你在安装依赖时遇到了 prisma、sharp 这类包含二进制文件的原生模块还需要注意本机是否安装了 Python 环境和 C 编译工具链。Windows 用户在安装这类依赖时经常会二次报错建议仔细看 npm 或者 yarn 的报错提示缺什么补什么。7.3 IDEA 启动后端时报错合集IDEA 启动后端最常见的错误有两种Error creating bean with name xxx这个一般是 Spring 容器初始化某个 Bean 失败。点开完整堆栈看最底下Caused by那一行通常是数据库连不上或者配置项缺失Port 8080 was already in use端口被占用。终端执行lsof -i:8080Mac/Linux或netstat -ano | findstr 8080Windows找到占用进程关掉或者改后端端口。在这里我有一个习惯每次新环境启动后端时都会用一个干净的日志输出方式mvn spring-boot:run -pl server -am -Dspring-boot.run.profilesdev这样可以在启动时指定 profile日志也会按模块输出排查问题比直接跑 jar 包清晰很多。7.4 数据导入导出异常datart 支持数据源的导入导出功能有一个很隐蔽的坑如果本地的时区与数据库的时区不一致导入数据后时间字段会出现偏移。解决方案是在数据库连接串上明确指定serverTimezoneAsia/Shanghai并且 MySQL 容器内部也要设置正确的时区。如果你的 MySQL 跑在 Docker 里可以在启动容器时加上环境变量docker run -d --name mysql-datart \ -e MYSQL_ROOT_PASSWORD你的密码 \ -e TZAsia/Shanghai \ -p 3306:3306 \ mysql:5.7这个参数不加哪怕后端配置了serverTimezone容器默认的 UTC 时区也会给数据写入带来各种奇怪的时间问题。7.5 常见问题速查表现象可能原因解决方案后端启动报 Unable to connect to MySQL数据库未启动或账号密码错误核对连接串与账号权限前端登录一直转圈后端未启动或代理配置错误检查后端进程与 vite.config.ts图标加载不出来前端构建不完整重新执行 yarn install yarn start图表查询超时Redis 未配置或查询过慢启动 Redis检查查询 SQL 性能注册按钮消失datart.user.register设为 false按需调整配置时间字段偏移MySQL 容器时区不为亚洲时区增加 TZAsia/Shanghai 环境变量依赖安装失败Node 版本过新或过旧切换 Node 14/168. 二开过程中的一些实操心得8.1 先跑通再改代码二开最忌讳上来就想改代码。先把原始项目完整跑通一次能够正常登录、建数据源、画图表再开始动刀。这样你能充分理解数据从哪来、接口怎么流转、界面怎么渲染后面改起来才不会抓瞎。我见过不少刚开始做二开的人在环境都还没完全跑通的情况下就直接修改权限逻辑结果改出来的功能自己都不清楚为什么生效或不生效后期排查非常痛苦。这不是技术能力的问题而是对系统全局认知不够。8.2 从最小闭环开始做定制做完环境验证后建议的第一个二开需求选一个小的、端到端的功能点。比如在仪表板增加一个自定义背景色设置或者修改用户列表的分页大小。这个闭环涉及前端菜单入口、后端 API、数据库存储做完后你就对 datart 的整体开发链路有了本能的熟悉感远比读源码来得快。8.3 保留一份干净的基线环境二开做久了你会发现改来改去环境越跑越脏。依赖冲突、配置混乱、数据被测试数据污染各种问题接踵而至。我的做法是维护一份干净的基线单独用一个目录存放未改动的原始代码本地数据库保持一个干净的备份脚本每次大改前用这份基线重新起一套环境确保问题的根源在自己的代码里而不是环境里。9. 二开场景扩展思路一套环境跑通之后可以做的事情就很灵活了。datart 本身的能力边界在于它是一套通用的可视化框架具体到某个行业的术语、交互方式、数据模型都需要二开来补齐。比较常见的二开方向包括登录对接企业内部统一认证比如 OAuth2 或 CAS数据源类型扩展适配公司内部自研的存储引擎图表类型的定制在原有基础上增加特定行业的图表权限模型调整把 datart 的组织权限与业务系统的角色体系打通前端主题改造让 UI 风格与公司产品保持一致。这里每个方向都有不少文章可以做但无论哪个方向前提都是你能独立把环境跑起来、看明白数据流。环境搭建这块敲门砖过了后面的二开就回到了日常开发的节奏难度反而没那么大了。最后再分享一个小经验在配置环境的过程中每一步操作尽量记录到自己的笔记里尤其是命令和配置项。因为二开不是一次性的团队里新同学入职、换电脑、代码回滚都需要重新搭环境。你手里的这份记录就是团队里最宝贵的实操文档。我自己的这套环境搭建笔记前前后后帮团队四个人省掉了重复踩坑的时间这也是我今天写这篇文章的初衷。