简介这是一套面向企业数据分析与BI开发场景的开源Web端商业智能平台源码适用于大数据开发工程师、Java后端开发者、BI报表二次开发人员及高校毕业设计学习者解决数据接入、SQL探查、多维统计、自定义报表与大屏可视化等核心需求。压缩包含1955个文件以Java591个.exs/.ex、TypeScript112个.tsx/86个.ts、Elixir模板121个.heex/50个.eex及配置类文件47个.yml、9个.sh、2个.sql为主涵盖前后端完整工程、MySQL初始化脚本、电商与用户行为等示例数据集及详细部署文档整体仅3.6MB轻量易上手。资源已提供清晰的模块化目录结构后端基于Spring Boot整合MyBatis-Plus与Quartz前端采用Vue 3 TypeScript ECharts 5支持拖拽式大屏编辑、动态数据绑定与权限集成。读者可直接运行验证OLAP分析、报表导出PDF/Excel、LDAP认证对接及Spark SQL扩展等工业级能力快速掌握现代BI系统架构与工程实践。1. 项目概述为什么要自己搭一套BI平台先把这个项目的定位说清楚。很多人一听BI平台就觉得是大厂才能玩的东西动辄上百万的商业软件采购或者得组一个专门团队去维护。但实际上基于Web的开源BI方案早就成熟了这个开源BI数据分析平台源码项目就是一条把报表、大屏、多维分析全部串起来的完整实现路径。那它到底解决了什么问题一句话概括**把企业里散落在数据库、Excel、业务系统里的数据变成能在浏览器里直接看的报表和可视化大屏同时让业务人员能自己拖拽分析不用每次取数都找开发排队。**这听起来好像不难但真做过的都知道中间全是坑——数据源五花八门要适配报表渲染性能要优化大屏动效要流畅多维分析要支持维度下钻和指标切换这些都得靠一套设计合理的架构去兜底。这套项目源码适合谁三类人。第一类是正在做数字化建设的中小团队技术负责人不想被商业BI的年费绑定想用开源技术栈自己掌控全链路第二类是数据开发或后端工程师想系统学习BI系统设计比如元数据管理、查询引擎、图表渲染这些模块到底怎么协同工作第三类是刚入行数据分析想转平台的同学用这套源码能直观理解数据从哪来、到哪里去、怎么被消费的完整链路比自己闷头学Python做几个静态图表强太多了。我实话说市面上的BI工具五花八门有像Power BI这种桌面端重度选手也有像帆软、永洪这类老牌报表商。但Web开源BI的核心优势在于可定制、可嵌入、可控成本。这套项目源码给你的是一个骨架你可以往里面填充自己的业务逻辑这是商业软件做不到的。2. 整体架构与设计思路拆解2.1 核心模块划分我从源码的结构反推了一下这套BI平台基本遵循了主流开源BI的分层设计整个体系可以拆成四层数据源层负责对接各种数据来源比如MySQL、PostgreSQL、ClickHouse这种关系型/分析型数据库也支持HTTP API接口还能上传Excel文件做临时分析。数据模型层这是BI的中枢神经负责把原始表加工成业务能看懂的数据模型。你写SQL做ETL、建维度表、建度量字段都是在这一层完成。查询引擎层当你在前端拖了一个维度、拉了一个指标、点了一下筛选条件前端会生成一个查询请求这一层负责把它翻译成真正的SQL去数据库执行然后把结果集压扁成前端需要的表格结构返回。展示层报表展示、大屏渲染、图表交互。这层是用户直接看到的也是最能出效果的部分。这种分层的好处很明显每一层可以独立演进。比如你前期数据量小查询引擎直接基于JDBC同步查询即可后面数据量大了可以无缝换成预聚合的Cube机制而不需要动前端代码。这也是我建议任何一个想做BI平台的人最先要建立的认知——别急着写页面先把数据链路想清楚。2.2 为什么选择Web架构而不是桌面端这里有一个很实际的原因**部署和分发的成本完全不同。**桌面端工具比如Excel、Power BI Desktop在个人分析场景很好用但一旦涉及多人协作、权限管理、定时刷新就得有一台服务器统一跑所有人通过浏览器访问。Web架构意味着你只要维护一套服务端浏览器里CtrlF5刷新就是最新版本不需要在每台电脑上装驱动、配ODBC。从数据安全角度也是Web架构更稳。数据统一从服务端拿客户端永远不直连数据库数据库账号密码不会散落在各个业务人员的电脑里。权限控制也可以在服务端做细——哪个用户能看哪个仪表盘、哪一行数据对他可见、哪个字段不能被导出这些在一个Web应用中实现成本远低于桌面端分发。2.3 对比商业BI的核心优势有朋友可能会问我用Power BI或者帆软不就行了为何要自己搞一套Power BI强在数据建模和与微软生态的集成但你得买Premium容量才能做到多人Web协同和Embedded嵌入这对预算敏感的中小团队并不友好。帆软报表的FineReport确实做得精致但价格确实劝退了一堆人而且二次开发的自由度和开源方案差了一个量级。自研的优势总结成三点可嵌入性开源项目天然支持OAuth、iframe嵌入或API对接你可以把报表嵌入到自己的管理系统里而不是让用户切换到另一个平台去看数据。这套源码里的大屏就是典型例子——它不是独立的网站而是可以被你的业务系统内嵌的页面。成本可控除了一台服务器和数据库授权费软件本身零成本。而且开源的生态有大量扩展插件比如富文本组件、3D地图、自定义图表基本你想要的功能社区都有轮子。学习价值你自己维护一套BI系统遇到问题了可以自己看源码。商业软件出了bug只能提工单等回复自研才知道底层发生什么排查问题效率天差地别。3. 核心功能模块与实操要点3.1 报表设计器从拖拽到出图的完整链路报表模块是整个BI平台里用户接触最多的部分。一个成型的报表设计器左侧通常是数据集列表——你提前配置好的数据模型或者SQL查询都在这里中间是画布你可以拖入图表组件、表格组件、筛选组件右侧是属性配置面板可以设置图表类型、维度、指标、颜色、联动关系等。实操的时候有几个关键点要留意**先说数据集的构建。**假设你想做一张各地区销售月度趋势报表。你在数据源管理里先配置好MySQL连接然后在数据集模块里写一条SQLSELECT region, DATE_FORMAT(order_date, %Y-%m) AS month, SUM(amount) AS total_amount FROM sales_order WHERE order_date ${startDate} AND order_date ${endDate} GROUP BY region, DATE_FORMAT(order_date, %Y-%m) ORDER BY month DESC注意这里用了${startDate}和${endDate}两个占位符这就是参数化查询。设计报表时你可以把这两个参数绑定到页面里的日期筛选组件上用户选择一个时间范围后点击查询服务端会用实际参数替换占位符再执行SQL。这是一个非常实用的安全实践——比把用户输入直接拼进SQL字符串靠谱得多。**然后是图表联动配置。**比如你有一个省份销售额柱状图和该省份每日趋势折线图你希望点击左边某个省份的柱子右边就刷新成对应省份的趋势。这个功能的实现原理其实不复杂在柱状图的点击事件里获取被点击省份的名称然后触发右侧折线图组件重新请求把省份名称作为过滤条件传给数据集接口。这套源码里是支持这种联动的你在属性面板里按提示配置联动关系即可。踩坑提醒做报表一定要先定好全局筛选器这个概念。很多新手设计报表时每个图表各自写死过滤条件结果用户换了一个时间范围只有一半图表跟着变体验很割裂。正确的做法是在报表顶部放统一的筛选器组件所有图表都关联到同一组筛选参数上这样全局统一刷新逻辑清晰得多。3.2 可视化大屏效果好才是硬道理大屏大概是这个项目最吸引眼球的部分。所谓大屏就是投到公司前台或会议室大电视上的数据面板通常是深色科技风或者极简商务风。这套源码里内置了几个大屏模板基于ECharts封装了轮播图表、动态数字、地图下钻等能力。做真正能上线的大屏核心考虑是三个维度指标要精不要多大屏是给领导一眼看趋势用的放8-10个关键指标足够。放30个数字上去反而谁也记不住。布局上一般上边是核心KPI卡片中间是地图或者主趋势图两侧是辅助指标和排行榜。轮播和动效要克制很多大屏开发一上来就想让所有图表动起来数字滚动、飞线动画、呼吸效果全拉满。实际投到会议室的大屏上炫酷的动效对看懂数据没有帮助反而会干扰阅读。建议把动效控制在两种核心数字的滚动更新这里源码里用了一个数字翻牌器组件实现以及地图的飞线强调重点区域。数据刷新策略大屏的实时性不能全指望前端轮询。我见过有人写setInterval每5秒刷一次整个大屏的请求后端就被打爆了。正确做法是服务端做缓存比如每1分钟从数据库拉一次数据生成JSON快照大屏前端每30秒问服务端要一次快照。这样数据库压力小前端体验也流畅。大屏iframe嵌入时有一个坑如果大屏页面和生产环境不同源嵌入到一个管理后台的iframe里浏览器可能会因为X-Frame-Options或者Content-Security-Policy的限制拒绝加载。解决办法是在大屏项目服务端响应头里加上X-Frame-Options: SAMEORIGIN或者更灵活一点在需要外嵌的页面去掉这个限制并加上明确的frame-ancestors白名单。3.3 多维分析维度、度量和下钻的玩法多维分析是BI区别于普通报表的核心能力。简单说报表是看结果的多维分析是探索原因的。比如我看到华东区6月销售额下降了15%接下来我想知道是哪个城市拖了后腿是哪个品类的下滑最严重是价格变动还是订单量变少在OLAP术语里这就是维度下钻从区域到城市、维度切块只看数码品类和度量切换从销售额切到订单量。这套源码里对多维分析的支持是通过一个透视表组件实现的。你在左侧拖入维度字段比如地区、品类、月份右侧拖入度量字段比如销售额、毛利额表格就会自动做分组聚合。字段可以随意拖拽交换行列位置就像Excel里的数据透视表一样但底层的查询是直接走SQL的GROUP BY。实现下钻需要两个数据结构支撑维度层级树比如国家 - 省份 - 城市 - 区县是一个层级树。设计数据模型时需要给每个层级字段分配一个parentId或者level字段。聚合粒度动态切换当用户从省份下钻到城市查询的目标表不变但GROUP BY的字段从province变成了city。前端发出一个新的查询请求服务端解析请求里的dimensionPath参数就知道该按哪个粒度聚合。这里有一个性能优化技巧不要在下钻时对明细表直接做group by。正确的做法是在数据集市层建好汇总表按省份、城市、品类、月份等多个维度预先GROUP BY好了查询时只需要查汇总表然后做SUM。如果用户要下钻到某个维度的更低层级就切换到粒度更细的汇总表。这才是支撑秒级响应的正路。3.4 用户权限与数据权限体系权限设计往往是BI项目里最容易出问题的环节。登录用户能看到哪些菜单是功能权限数据上只能看湖南大区的订单是数据权限这两个要同时满足。功能权限比较好理解就是RBAC模型用户关联角色角色关联菜单/按钮权限。比如销售总监这个角色有权限查看全国销售大屏但销售专员的角色只能看自己的销售报表。数据权限的常见实现方案有这么几类字段级脱敏比如某些人查看报表时手机号、身份证号自动打码。行级过滤这个更常用。比如一个表里有region字段销售总监的数据权限是全部门店华东区经理只能是region 华东。实现方式是给数据集配置一个数据权限表达式用户在查询报表时服务端在SQL末尾自动追加AND region 华东。维度级限制比如某些用户不能看利润字段即使维度可以全看。给这套源码提个建议如果它的权限模块比较基础你可以自己实现一个数据权限助手在数据集模型里加一个permission_table记录每个角色在哪张表、哪个维度、允许哪些值。然后在查询引擎的公共接口里统一做拦截解析当前用户角色后自动拼装过滤条件。这个思路不需要改动前端代码和后端查询层接好口子就行。注意做权限过滤一定不要只在前端隐藏服务端必须做同样的校验。前端隐藏只是体验优化服务端才是安全底线。4. 技术选型与部署实践4.1 后端技术栈选型分析这套源码的核心服务端我推测是基于Java Spring Boot体系来做的这也是国内开源BI项目最常见的组合。这类选型的好处在于Spring Boot生态极其成熟集成MySQL、Redis、Quartz定时任务都很方便。如果你部署时发现默认配置不是Spring Boot也别慌思路是一样的核心组件无非是接口层 业务逻辑层 数据访问层。关键技术组件清单技术组件作用选型理由Spring BootWeb服务端框架生态完善、社区活跃、上手快MySQL元数据存储存报表配置、用户信息、数据集定义通用且好维护ClickHouse可选大数据量分析加速如果明细数据上亿用它做OLAP查询秒出Redis缓存服务存热点查询结果、用户会话、大屏快照扛住高并发ECharts前端图表库开源免费图表能力最强交互丰富Vue.js前端框架组件化开发效率高配合vite构建秒级热更新**选型的核心思想是够用就好。**不要一上来就上Flink、Kafka这种重型设施除非你确认数据量已经大到需要的地步。很多BI项目前期死在复杂度上而不是死在功能上能用一条SQL解决的不要拆成三个微服务。4.2 前端渲染方案ECharts的深度使用前端可视化部分这套源码基本是把ECharts用透了。ECharts的option配置项可以动态修改数据然后setOption实现图表更新这就是BI报表实时数据刷新的核心机制。一个典型的大屏数据更新代码片段是这样的function updateDashboard(snapshotData) { // 更新核心指标翻牌器 document.getElementById(totalRevenue).innerText snapshotData.totalRevenue.toLocaleString(); // 更新柱状图 myBarChart.setOption({ series: [{ data: snapshotData.barData }] }); // 更新地图 myMapChart.setOption({ series: [{ data: snapshotData.mapData }] }); } // 每30秒请求一次服务端快照 setInterval(async () { const res await fetch(/api/dashboard/snapshot); const data await res.json(); updateDashboard(data); }, 30000);注意这里setOption的第二个参数不要传true默认就是merge模式这样ECharts会在旧配置基础上做增量更新不会刷新整张图导致闪屏。如果你需要完全替换配置比如切换了图表类型再传true做notMerge。实际项目中还容易遇到地图加载慢的问题。ECharts的地图GeoJSON体积不小全量的中国地图注册脚本有几MB直接打进页面首屏会很卡。技巧是不要全量加载只加载你需要展示的省份或城市的GeoJSON或者按需异步加载。同时用SVG模式渲染地图性能优于Canvas模式尤其元素多的时候。4.3 部署流程与关键配置部署这套BI平台我给出一个标准的Linux Docker Compose的路径这也是目前生产环境最常见的方式。先准备环境# 安装Docker和Docker Compose如果还没装 curl -fsSL https://get.docker.com | bash docker compose version然后编写docker-compose.yml把MySQL、Redis和应用服务编排起来version: 3.8 services: mysql: image: mysql:8.0 container_name: bi-mysql restart: always environment: MYSQL_ROOT_PASSWORD: bi_root_password MYSQL_DATABASE: bi_platform MYSQL_USER: bi_user MYSQL_PASSWORD: bi_user_password volumes: - ./mysql-data:/var/lib/mysql ports: - 3306:3306 redis: image: redis:7-alpine container_name: bi-redis restart: always ports: - 6379:6379 bi-app: build: . container_name: bi-app restart: always depends_on: - mysql - redis environment: SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/bi_platform?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai SPRING_DATASOURCE_USERNAME: bi_user SPRING_DATASOURCE_PASSWORD: bi_user_password SPRING_REDIS_HOST: redis SPRING_REDIS_PORT: 6379 ports: - 8080:8080创建容器时建议给MySQL挂载外部数据卷然后初始化数据库# 建好项目目录后启动服务 docker compose up -d mysql redis sleep 30 # 等MySQL初始化完成 # 导入初始化SQL docker exec -i bi-mysql mysql -ubi_user -pbi_user_password bi_platform ./docs/init.sql # 启动应用服务 docker compose up -d bi-app # 查看日志确认启动成功 docker logs -f bi-app部署中的三个常见坑提前说时区问题MySQL和Spring Boot的时区一定要统一否则时间字段全错8小时。连接串里的serverTimezoneAsia/Shanghai是必须的。内存分配如果服务器只有2GB内存同时跑MySQL、Redis和Java应用会比较紧张建议至少4GB。JVM参数可以调小一点-Xms512m -Xmx1024m这样。防火墙与暴露范围生产环境不要把MySQL的3306端口暴露到公网应用服务8080端口最好也通过Nginx反向代理来暴露HTTPS证书配置在Nginx层处理。4.4 二次开发实战给报表加一个新的图表组件拿到源码后肯定要改。我以一个实际需求为例用户要一个漏斗图来展示销售转化路径。在ECharts里漏斗图是原生支持的所以关键工作在如何把新组件接入报表设计器。大致三步前端注册组件在组件目录里新建FunnelChart.vue参考其他图表组件的写法核心是接收数据集字段配置比如步骤名称和数值渲染为ECharts漏斗图配置。后端注册类型报表保存时要有一个字段标识图表类型。在枚举类里加一个FUNNEL funnel确保设计器保存的JSON能被服务端正确识别。兼容旧数据如果之前是用channelType字段判断图表分类新增类型之后所有旧图表预览仍然能正常渲染否则一旦新枚举不兼容老报表也会被波及。扩展提示这套源码的组件化程度算做得不错的新增一个图表组件的改动量基本控制在两个文件以内。如果发现改起来牵一发动全身说明组件设计时耦合度较高那你正好可以通过这次二次开发顺手把公共逻辑抽出来。5. 实操过程从零搭建一套销售运营分析看板5.1 准备演示数据为了演示整个流程我建了一张模拟的订单表字段包括订单ID、订单日期、省份、城市、品类、销售额、成本、数量。数据量我造了10万条覆盖最近12个月。开发环境直接用一条SQL在MySQL里生成就行CREATE DATABASE IF NOT EXISTS demo; USE demo; CREATE TABLE sales_order ( order_id INT PRIMARY KEY AUTO_INCREMENT, order_date DATE NOT NULL, province VARCHAR(50) NOT NULL, city VARCHAR(50) NOT NULL, category VARCHAR(50) NOT NULL, amount DECIMAL(12,2) NOT NULL, cost DECIMAL(12,2) NOT NULL, quantity INT NOT NULL );然后写脚本插入数据。这里给一个简化版的Python脚本用于造数也可以用存储过程import random import pymysql from datetime import datetime, timedelta conn pymysql.connect(hostlocalhost, userbi_user, passwordbi_user_password, databasedemo) cursor conn.cursor() provinces [广东省, 江苏省, 浙江省, 四川省, 山东省, 湖南省, 湖北省, 福建省] cities { 广东省: [广州市, 深圳市, 东莞市], 江苏省: [南京市, 苏州市, 无锡市], 浙江省: [杭州市, 宁波市, 温州市], 四川省: [成都市, 绵阳市, 德阳市], 山东省: [济南市, 青岛市, 烟台市], 湖南省: [长沙市, 株洲市, 湘潭市], 湖北省: [武汉市, 宜昌市, 襄阳市], 福建省: [福州市, 厦门市, 泉州市], } categories [数码电器, 服装鞋帽, 食品生鲜, 家居日用, 美妆个护] for _ in range(100000): province random.choice(provinces) city random.choice(cities[province]) category random.choice(categories) order_date datetime(2024, 1, 1) timedelta(daysrandom.randint(0, 364)) amount round(random.uniform(50, 2000), 2) cost round(amount * random.uniform(0.4, 0.8), 2) quantity random.randint(1, 5) cursor.execute( INSERT INTO sales_order (order_date, province, city, category, amount, cost, quantity) VALUES (%s, %s, %s, %s, %s, %s, %s), (order_date.strftime(%Y-%m-%d), province, city, category, amount, cost, quantity) ) conn.commit() cursor.close() conn.close() print(演示数据生成完成)5.2 配置数据源与数据集在系统里进入数据源管理添加一个MySQL数据源填入刚才的demo库连接信息。测试通过后下一步创建数据集我直接使用SQL模式SELECT order_date, province, city, category, amount, cost, amount - cost AS profit, quantity FROM sales_order这个数据集是一个明细查询后续的报表和看板都是基于它或基于它的聚合结果。建议在实际项目里不要直接对着明细表做报表而应该把这层SQL查询变成物理视图或者定时汇总表以提高性能。演示阶段可以先用这个功能跑通了再优化性能。5.3 新建看板并配置图表进入可视化看板模块点击新建看板选择一个深色模板大屏效果更好。我先拖入一个指标卡片配置字段为SUM(amount)显示名称总销售额数字格式设为千分位展示。再拖入一个指标卡片显示SUM(profit)命名总毛利。接着拖入一个柱状图维度选province指标选SUM(amount)这样得到每个省份的销售总额排名。再拖一个折线图维度选DATE_FORMAT(order_date, %Y-%m)指标选SUM(amount)展示12个月的销售趋势。配置筛选器在组件列表里拖入日期范围筛选器绑定字段order_date。然后把这个筛选器分别关联到柱状图和折线图上配置方式是在图表的数据配置里选择关联筛选器。保存看板后切换日期范围两个图表会一起刷新。这一步是整个环节里新手最容易卡住的点。如果点击日期筛选器之后图表没反应优先检查两处一是筛选器的字段类型是否和数据集里的字段类型一致日期类型必须匹配二是联动设置里目标图表是否勾选了正确的依赖筛选器。5.4 预览与性能验证看板配置完成后点击预览这时候会在新标签页打开大屏页面。观察一下加载速度。10万行数据量并不大但如果你的查询直接扫了全表没有走索引首次加载可能也要一两秒。在MySQL里给order_date加一个索引对时间范围过滤帮助很大ALTER TABLE sales_order ADD INDEX idx_order_date (order_date);如果看板上同时有多个图表每个图表各自发一个查询请求同一时间有5-6个请求打到数据库。开发环境没感觉生产环境一旦用户多就可能拖垮数据库。我建议借助Redis做一层结果缓存给每个查询请求生成一个hash key缓存的key就是数据集ID 参数值 SQL哈希缓存的value就是JSON结果。当参数变化时key变化自然命中不同的缓存参数不变的重复查询直接从Redis返回响应时间能从700ms降到10ms级别。5.5 发布与嵌入看板做完了要分享给团队使用。这套源码支持两种方式一种是发布为公开链接任何人拿到链接都可以看适合客户演示另一种是嵌入到管理系统里用iframe的方式。iframe srchttps://bi.example.com/dashboard/preview?dashboardId123tokenyour_embed_token width100% height800 frameborder0 /iframe这里的token是嵌入凭证服务端会校验这个token是否有权限访问ID为123的看板。注意不要直接把dashboardId裸露在URL里不做校验否则权限绕过风险很大。建议在服务端用一次性的access token来换取临时的访问凭证token过期时间设置为2小时以内。6. 常见问题与排查技巧实录6.1 数据源连接失败症状添加MySQL数据源时提示Communications link failure。排查步骤检查MySQL服务是否启动systemctl status mysqld或docker ps | grep mysql。检查端口是否可达telnet 服务器IP 3306如果端口不通可能是云安全组没放行3306端口。检查MySQL用户权限用SELECT user, host FROM mysql.user;查看用户是否存在且host匹配。尤其要注意bi_user如果绑定的是localhost那么应用从Docker容器内连接时会被拒正确做法是创建用户时指定bi_user%。实操建议生产环境数据库和应用服务器不要放在不同的云账号下网络隔离问题排查起来非常费劲。把MySQL和应用部署在同一VPC内用内网IP连接安全性和响应时间都更好。6.2 大屏图表渲染空白症状看板能打开但部分图表区域空白控制台报ECharts相关的错误。常见的三个原因数据格式不对ECharts对数据格式要求很严格。比如柱状图的数据如果是[{name: 广东, value: 100}]这种对象数组饼图和地图也是这个结构但折线图需要的是{xAxis: [1月,2月], series: [{data: [100,200]}]}。如果你数据集返回的字段名不匹配比如label和name不一致图表就无法渲染。容器尺寸为0如果图表组件的父容器没有设置高度ECharts初始化的container是0px高自然画不出东西。给图表组件的外层div加一个height: 400px或者在初始化前用resize方法强制获取容器尺寸。异步加载时序问题如果你在页面mounted时就初始化图表但数据请求还没回来此时setOption会拿到空数据。等数据回来后再初始化或者初始化时传入dataset: []数据返回后做setOption更新。排查方法打开浏览器F12看Network里对应接口返回的JSON是否正常再看Console里是否有ECharts报错信息。ECharts的报错信息其实很友好比如data is not an array直接告诉你数据结构有问题。6.3 多维分析下钻时不生效症状用户点击报表中的省份字段期望下钻到城市但页面没有任何变化。排查步骤确认你是点击了维度字段而不是数据单元格。下钻交互通常绑定在行标题的字段上点击数据值只是选中。检查数据模型里有没有配置层级关系。如果province和city是两个并列的字段系统不知道该按什么顺序下钻。需要把两个字段配成省份 - 城市的层级树。看Network请求下钻操作应该发一个新的查询请求参数里带上了dimensionPath或drillDownField。如果请求根本没发说明前端事件绑定有问题如果请求发了但结果没变说明后端的group by字段没有切换成功。一个更隐蔽的问题如果数据集是明细查询下钻请求本来就会很快因为数据量小。一旦数据量到了百万级每次切换维度都需要几秒体验就非常差了。我在第3章提到过汇总表方案这里再强调一遍——多维分析下钻必须基于预聚合的Cube表否则性能是撑不住的。6.4 常见问题速查表问题可能原因快速解法登录后跳转回登录页会话过期或token未存储检查localStorage/sessionStorage清理后重新登录报表导出Excel中文乱码缺失BOM头导出时在文件流前加\xEF\xBB\xBF定时刷新的报表不更新定时任务未配置或时区错检查Quartz配置确认Cron表达式用的服务器本地时区大屏在手机上显示错乱没有做移动端适配大屏模板固定尺寸建议用transform: scale()做缩放适配用户看不到自己创建的数据集数据集权限默认私有在数据集管理里把数据集分享给对应角色聚合数据结果有重复SQL里JOIN产生笛卡尔积检查事实表和维度表关联字段是否唯一6.5 性能调优的进阶方向如果这套BI平台的数据量到了一定的规模比如明细表超过千万行有几个优化方向可以依次考虑查询缓存这是成本最低的效果最明显。短期内重复的查询同一个看板、同一个筛选条件直接返回Redis缓存。数据库压力直接降一个量级。汇总表把常用维度的聚合提前算好。比如每天凌晨跑一个定时任务把省份品类日期维度的销售额、订单数汇总到一张表。报表只查汇总表不碰明细表。ClickHouse替换查询引擎如果你有几千亿行明细要跑即时分析MySQL基本上到极限了。把这套BI的查询引擎层接上ClickHouseSQL语法支持度高性能提升100倍以上。很多开源BI项目都支持接入ClickHouse数据源你只需要在数据源管理里新增一个ClickHouse类型就行。异步查询对于非常复杂的分析请求不能同步等待SQL跑完再返回。改成提交任务、返回任务ID前端轮询任务状态跑完后拉取结果。这才是企业级BI处理重型查询的标配模式很多开源BI都是这样设计的。7. 我对这套源码的几点评价我正儿八经用下来这个开源BI项目的完成度在同类中算很不错的。从数据源接入到报表设计器到大屏展示闭环完整代码结构清晰适合拿来学习和二次开发。我最喜欢的一点是它的数据集/SQL模式设计很务实既保留了SQL的灵活度又提供了一定的参数化能力。对于有SQL基础的团队来说这种模式比纯拖拽式的模型配置更高效能够快速响应复杂的业务取数需求。如果说有什么不满意的大概有两处。一是多维分析的下钻能力还是相对基础和Power BI的层级钻取交互相比有差距二是移动端适配不是重点做出来的看板基本是为PC大屏服务的如果需要在手机上查看得自己做一套移动布局。不过考虑到这是开源项目这些问题都可以二次开发补上不影响整体评价。部署的时候建议先用Docker Compose在测试环境把全流程跑通确认架构和你团队的实际情况匹配再考虑接管生产环境。不要第一步就急着改源码——先把原版跑起来理解数据从MySQL到报表页面的完整流转再开始动手加功能这样踩坑最少。本文还有配套的精品资源点击获取 开源BI数据分析平台源码实战：从架构到二次开发
简介这是一套面向企业数据分析与BI开发场景的开源Web端商业智能平台源码适用于大数据开发工程师、Java后端开发者、BI报表二次开发人员及高校毕业设计学习者解决数据接入、SQL探查、多维统计、自定义报表与大屏可视化等核心需求。压缩包含1955个文件以Java591个.exs/.ex、TypeScript112个.tsx/86个.ts、Elixir模板121个.heex/50个.eex及配置类文件47个.yml、9个.sh、2个.sql为主涵盖前后端完整工程、MySQL初始化脚本、电商与用户行为等示例数据集及详细部署文档整体仅3.6MB轻量易上手。资源已提供清晰的模块化目录结构后端基于Spring Boot整合MyBatis-Plus与Quartz前端采用Vue 3 TypeScript ECharts 5支持拖拽式大屏编辑、动态数据绑定与权限集成。读者可直接运行验证OLAP分析、报表导出PDF/Excel、LDAP认证对接及Spark SQL扩展等工业级能力快速掌握现代BI系统架构与工程实践。1. 项目概述为什么要自己搭一套BI平台先把这个项目的定位说清楚。很多人一听BI平台就觉得是大厂才能玩的东西动辄上百万的商业软件采购或者得组一个专门团队去维护。但实际上基于Web的开源BI方案早就成熟了这个开源BI数据分析平台源码项目就是一条把报表、大屏、多维分析全部串起来的完整实现路径。那它到底解决了什么问题一句话概括**把企业里散落在数据库、Excel、业务系统里的数据变成能在浏览器里直接看的报表和可视化大屏同时让业务人员能自己拖拽分析不用每次取数都找开发排队。**这听起来好像不难但真做过的都知道中间全是坑——数据源五花八门要适配报表渲染性能要优化大屏动效要流畅多维分析要支持维度下钻和指标切换这些都得靠一套设计合理的架构去兜底。这套项目源码适合谁三类人。第一类是正在做数字化建设的中小团队技术负责人不想被商业BI的年费绑定想用开源技术栈自己掌控全链路第二类是数据开发或后端工程师想系统学习BI系统设计比如元数据管理、查询引擎、图表渲染这些模块到底怎么协同工作第三类是刚入行数据分析想转平台的同学用这套源码能直观理解数据从哪来、到哪里去、怎么被消费的完整链路比自己闷头学Python做几个静态图表强太多了。我实话说市面上的BI工具五花八门有像Power BI这种桌面端重度选手也有像帆软、永洪这类老牌报表商。但Web开源BI的核心优势在于可定制、可嵌入、可控成本。这套项目源码给你的是一个骨架你可以往里面填充自己的业务逻辑这是商业软件做不到的。2. 整体架构与设计思路拆解2.1 核心模块划分我从源码的结构反推了一下这套BI平台基本遵循了主流开源BI的分层设计整个体系可以拆成四层数据源层负责对接各种数据来源比如MySQL、PostgreSQL、ClickHouse这种关系型/分析型数据库也支持HTTP API接口还能上传Excel文件做临时分析。数据模型层这是BI的中枢神经负责把原始表加工成业务能看懂的数据模型。你写SQL做ETL、建维度表、建度量字段都是在这一层完成。查询引擎层当你在前端拖了一个维度、拉了一个指标、点了一下筛选条件前端会生成一个查询请求这一层负责把它翻译成真正的SQL去数据库执行然后把结果集压扁成前端需要的表格结构返回。展示层报表展示、大屏渲染、图表交互。这层是用户直接看到的也是最能出效果的部分。这种分层的好处很明显每一层可以独立演进。比如你前期数据量小查询引擎直接基于JDBC同步查询即可后面数据量大了可以无缝换成预聚合的Cube机制而不需要动前端代码。这也是我建议任何一个想做BI平台的人最先要建立的认知——别急着写页面先把数据链路想清楚。2.2 为什么选择Web架构而不是桌面端这里有一个很实际的原因**部署和分发的成本完全不同。**桌面端工具比如Excel、Power BI Desktop在个人分析场景很好用但一旦涉及多人协作、权限管理、定时刷新就得有一台服务器统一跑所有人通过浏览器访问。Web架构意味着你只要维护一套服务端浏览器里CtrlF5刷新就是最新版本不需要在每台电脑上装驱动、配ODBC。从数据安全角度也是Web架构更稳。数据统一从服务端拿客户端永远不直连数据库数据库账号密码不会散落在各个业务人员的电脑里。权限控制也可以在服务端做细——哪个用户能看哪个仪表盘、哪一行数据对他可见、哪个字段不能被导出这些在一个Web应用中实现成本远低于桌面端分发。2.3 对比商业BI的核心优势有朋友可能会问我用Power BI或者帆软不就行了为何要自己搞一套Power BI强在数据建模和与微软生态的集成但你得买Premium容量才能做到多人Web协同和Embedded嵌入这对预算敏感的中小团队并不友好。帆软报表的FineReport确实做得精致但价格确实劝退了一堆人而且二次开发的自由度和开源方案差了一个量级。自研的优势总结成三点可嵌入性开源项目天然支持OAuth、iframe嵌入或API对接你可以把报表嵌入到自己的管理系统里而不是让用户切换到另一个平台去看数据。这套源码里的大屏就是典型例子——它不是独立的网站而是可以被你的业务系统内嵌的页面。成本可控除了一台服务器和数据库授权费软件本身零成本。而且开源的生态有大量扩展插件比如富文本组件、3D地图、自定义图表基本你想要的功能社区都有轮子。学习价值你自己维护一套BI系统遇到问题了可以自己看源码。商业软件出了bug只能提工单等回复自研才知道底层发生什么排查问题效率天差地别。3. 核心功能模块与实操要点3.1 报表设计器从拖拽到出图的完整链路报表模块是整个BI平台里用户接触最多的部分。一个成型的报表设计器左侧通常是数据集列表——你提前配置好的数据模型或者SQL查询都在这里中间是画布你可以拖入图表组件、表格组件、筛选组件右侧是属性配置面板可以设置图表类型、维度、指标、颜色、联动关系等。实操的时候有几个关键点要留意**先说数据集的构建。**假设你想做一张各地区销售月度趋势报表。你在数据源管理里先配置好MySQL连接然后在数据集模块里写一条SQLSELECT region, DATE_FORMAT(order_date, %Y-%m) AS month, SUM(amount) AS total_amount FROM sales_order WHERE order_date ${startDate} AND order_date ${endDate} GROUP BY region, DATE_FORMAT(order_date, %Y-%m) ORDER BY month DESC注意这里用了${startDate}和${endDate}两个占位符这就是参数化查询。设计报表时你可以把这两个参数绑定到页面里的日期筛选组件上用户选择一个时间范围后点击查询服务端会用实际参数替换占位符再执行SQL。这是一个非常实用的安全实践——比把用户输入直接拼进SQL字符串靠谱得多。**然后是图表联动配置。**比如你有一个省份销售额柱状图和该省份每日趋势折线图你希望点击左边某个省份的柱子右边就刷新成对应省份的趋势。这个功能的实现原理其实不复杂在柱状图的点击事件里获取被点击省份的名称然后触发右侧折线图组件重新请求把省份名称作为过滤条件传给数据集接口。这套源码里是支持这种联动的你在属性面板里按提示配置联动关系即可。踩坑提醒做报表一定要先定好全局筛选器这个概念。很多新手设计报表时每个图表各自写死过滤条件结果用户换了一个时间范围只有一半图表跟着变体验很割裂。正确的做法是在报表顶部放统一的筛选器组件所有图表都关联到同一组筛选参数上这样全局统一刷新逻辑清晰得多。3.2 可视化大屏效果好才是硬道理大屏大概是这个项目最吸引眼球的部分。所谓大屏就是投到公司前台或会议室大电视上的数据面板通常是深色科技风或者极简商务风。这套源码里内置了几个大屏模板基于ECharts封装了轮播图表、动态数字、地图下钻等能力。做真正能上线的大屏核心考虑是三个维度指标要精不要多大屏是给领导一眼看趋势用的放8-10个关键指标足够。放30个数字上去反而谁也记不住。布局上一般上边是核心KPI卡片中间是地图或者主趋势图两侧是辅助指标和排行榜。轮播和动效要克制很多大屏开发一上来就想让所有图表动起来数字滚动、飞线动画、呼吸效果全拉满。实际投到会议室的大屏上炫酷的动效对看懂数据没有帮助反而会干扰阅读。建议把动效控制在两种核心数字的滚动更新这里源码里用了一个数字翻牌器组件实现以及地图的飞线强调重点区域。数据刷新策略大屏的实时性不能全指望前端轮询。我见过有人写setInterval每5秒刷一次整个大屏的请求后端就被打爆了。正确做法是服务端做缓存比如每1分钟从数据库拉一次数据生成JSON快照大屏前端每30秒问服务端要一次快照。这样数据库压力小前端体验也流畅。大屏iframe嵌入时有一个坑如果大屏页面和生产环境不同源嵌入到一个管理后台的iframe里浏览器可能会因为X-Frame-Options或者Content-Security-Policy的限制拒绝加载。解决办法是在大屏项目服务端响应头里加上X-Frame-Options: SAMEORIGIN或者更灵活一点在需要外嵌的页面去掉这个限制并加上明确的frame-ancestors白名单。3.3 多维分析维度、度量和下钻的玩法多维分析是BI区别于普通报表的核心能力。简单说报表是看结果的多维分析是探索原因的。比如我看到华东区6月销售额下降了15%接下来我想知道是哪个城市拖了后腿是哪个品类的下滑最严重是价格变动还是订单量变少在OLAP术语里这就是维度下钻从区域到城市、维度切块只看数码品类和度量切换从销售额切到订单量。这套源码里对多维分析的支持是通过一个透视表组件实现的。你在左侧拖入维度字段比如地区、品类、月份右侧拖入度量字段比如销售额、毛利额表格就会自动做分组聚合。字段可以随意拖拽交换行列位置就像Excel里的数据透视表一样但底层的查询是直接走SQL的GROUP BY。实现下钻需要两个数据结构支撑维度层级树比如国家 - 省份 - 城市 - 区县是一个层级树。设计数据模型时需要给每个层级字段分配一个parentId或者level字段。聚合粒度动态切换当用户从省份下钻到城市查询的目标表不变但GROUP BY的字段从province变成了city。前端发出一个新的查询请求服务端解析请求里的dimensionPath参数就知道该按哪个粒度聚合。这里有一个性能优化技巧不要在下钻时对明细表直接做group by。正确的做法是在数据集市层建好汇总表按省份、城市、品类、月份等多个维度预先GROUP BY好了查询时只需要查汇总表然后做SUM。如果用户要下钻到某个维度的更低层级就切换到粒度更细的汇总表。这才是支撑秒级响应的正路。3.4 用户权限与数据权限体系权限设计往往是BI项目里最容易出问题的环节。登录用户能看到哪些菜单是功能权限数据上只能看湖南大区的订单是数据权限这两个要同时满足。功能权限比较好理解就是RBAC模型用户关联角色角色关联菜单/按钮权限。比如销售总监这个角色有权限查看全国销售大屏但销售专员的角色只能看自己的销售报表。数据权限的常见实现方案有这么几类字段级脱敏比如某些人查看报表时手机号、身份证号自动打码。行级过滤这个更常用。比如一个表里有region字段销售总监的数据权限是全部门店华东区经理只能是region 华东。实现方式是给数据集配置一个数据权限表达式用户在查询报表时服务端在SQL末尾自动追加AND region 华东。维度级限制比如某些用户不能看利润字段即使维度可以全看。给这套源码提个建议如果它的权限模块比较基础你可以自己实现一个数据权限助手在数据集模型里加一个permission_table记录每个角色在哪张表、哪个维度、允许哪些值。然后在查询引擎的公共接口里统一做拦截解析当前用户角色后自动拼装过滤条件。这个思路不需要改动前端代码和后端查询层接好口子就行。注意做权限过滤一定不要只在前端隐藏服务端必须做同样的校验。前端隐藏只是体验优化服务端才是安全底线。4. 技术选型与部署实践4.1 后端技术栈选型分析这套源码的核心服务端我推测是基于Java Spring Boot体系来做的这也是国内开源BI项目最常见的组合。这类选型的好处在于Spring Boot生态极其成熟集成MySQL、Redis、Quartz定时任务都很方便。如果你部署时发现默认配置不是Spring Boot也别慌思路是一样的核心组件无非是接口层 业务逻辑层 数据访问层。关键技术组件清单技术组件作用选型理由Spring BootWeb服务端框架生态完善、社区活跃、上手快MySQL元数据存储存报表配置、用户信息、数据集定义通用且好维护ClickHouse可选大数据量分析加速如果明细数据上亿用它做OLAP查询秒出Redis缓存服务存热点查询结果、用户会话、大屏快照扛住高并发ECharts前端图表库开源免费图表能力最强交互丰富Vue.js前端框架组件化开发效率高配合vite构建秒级热更新**选型的核心思想是够用就好。**不要一上来就上Flink、Kafka这种重型设施除非你确认数据量已经大到需要的地步。很多BI项目前期死在复杂度上而不是死在功能上能用一条SQL解决的不要拆成三个微服务。4.2 前端渲染方案ECharts的深度使用前端可视化部分这套源码基本是把ECharts用透了。ECharts的option配置项可以动态修改数据然后setOption实现图表更新这就是BI报表实时数据刷新的核心机制。一个典型的大屏数据更新代码片段是这样的function updateDashboard(snapshotData) { // 更新核心指标翻牌器 document.getElementById(totalRevenue).innerText snapshotData.totalRevenue.toLocaleString(); // 更新柱状图 myBarChart.setOption({ series: [{ data: snapshotData.barData }] }); // 更新地图 myMapChart.setOption({ series: [{ data: snapshotData.mapData }] }); } // 每30秒请求一次服务端快照 setInterval(async () { const res await fetch(/api/dashboard/snapshot); const data await res.json(); updateDashboard(data); }, 30000);注意这里setOption的第二个参数不要传true默认就是merge模式这样ECharts会在旧配置基础上做增量更新不会刷新整张图导致闪屏。如果你需要完全替换配置比如切换了图表类型再传true做notMerge。实际项目中还容易遇到地图加载慢的问题。ECharts的地图GeoJSON体积不小全量的中国地图注册脚本有几MB直接打进页面首屏会很卡。技巧是不要全量加载只加载你需要展示的省份或城市的GeoJSON或者按需异步加载。同时用SVG模式渲染地图性能优于Canvas模式尤其元素多的时候。4.3 部署流程与关键配置部署这套BI平台我给出一个标准的Linux Docker Compose的路径这也是目前生产环境最常见的方式。先准备环境# 安装Docker和Docker Compose如果还没装 curl -fsSL https://get.docker.com | bash docker compose version然后编写docker-compose.yml把MySQL、Redis和应用服务编排起来version: 3.8 services: mysql: image: mysql:8.0 container_name: bi-mysql restart: always environment: MYSQL_ROOT_PASSWORD: bi_root_password MYSQL_DATABASE: bi_platform MYSQL_USER: bi_user MYSQL_PASSWORD: bi_user_password volumes: - ./mysql-data:/var/lib/mysql ports: - 3306:3306 redis: image: redis:7-alpine container_name: bi-redis restart: always ports: - 6379:6379 bi-app: build: . container_name: bi-app restart: always depends_on: - mysql - redis environment: SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/bi_platform?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai SPRING_DATASOURCE_USERNAME: bi_user SPRING_DATASOURCE_PASSWORD: bi_user_password SPRING_REDIS_HOST: redis SPRING_REDIS_PORT: 6379 ports: - 8080:8080创建容器时建议给MySQL挂载外部数据卷然后初始化数据库# 建好项目目录后启动服务 docker compose up -d mysql redis sleep 30 # 等MySQL初始化完成 # 导入初始化SQL docker exec -i bi-mysql mysql -ubi_user -pbi_user_password bi_platform ./docs/init.sql # 启动应用服务 docker compose up -d bi-app # 查看日志确认启动成功 docker logs -f bi-app部署中的三个常见坑提前说时区问题MySQL和Spring Boot的时区一定要统一否则时间字段全错8小时。连接串里的serverTimezoneAsia/Shanghai是必须的。内存分配如果服务器只有2GB内存同时跑MySQL、Redis和Java应用会比较紧张建议至少4GB。JVM参数可以调小一点-Xms512m -Xmx1024m这样。防火墙与暴露范围生产环境不要把MySQL的3306端口暴露到公网应用服务8080端口最好也通过Nginx反向代理来暴露HTTPS证书配置在Nginx层处理。4.4 二次开发实战给报表加一个新的图表组件拿到源码后肯定要改。我以一个实际需求为例用户要一个漏斗图来展示销售转化路径。在ECharts里漏斗图是原生支持的所以关键工作在如何把新组件接入报表设计器。大致三步前端注册组件在组件目录里新建FunnelChart.vue参考其他图表组件的写法核心是接收数据集字段配置比如步骤名称和数值渲染为ECharts漏斗图配置。后端注册类型报表保存时要有一个字段标识图表类型。在枚举类里加一个FUNNEL funnel确保设计器保存的JSON能被服务端正确识别。兼容旧数据如果之前是用channelType字段判断图表分类新增类型之后所有旧图表预览仍然能正常渲染否则一旦新枚举不兼容老报表也会被波及。扩展提示这套源码的组件化程度算做得不错的新增一个图表组件的改动量基本控制在两个文件以内。如果发现改起来牵一发动全身说明组件设计时耦合度较高那你正好可以通过这次二次开发顺手把公共逻辑抽出来。5. 实操过程从零搭建一套销售运营分析看板5.1 准备演示数据为了演示整个流程我建了一张模拟的订单表字段包括订单ID、订单日期、省份、城市、品类、销售额、成本、数量。数据量我造了10万条覆盖最近12个月。开发环境直接用一条SQL在MySQL里生成就行CREATE DATABASE IF NOT EXISTS demo; USE demo; CREATE TABLE sales_order ( order_id INT PRIMARY KEY AUTO_INCREMENT, order_date DATE NOT NULL, province VARCHAR(50) NOT NULL, city VARCHAR(50) NOT NULL, category VARCHAR(50) NOT NULL, amount DECIMAL(12,2) NOT NULL, cost DECIMAL(12,2) NOT NULL, quantity INT NOT NULL );然后写脚本插入数据。这里给一个简化版的Python脚本用于造数也可以用存储过程import random import pymysql from datetime import datetime, timedelta conn pymysql.connect(hostlocalhost, userbi_user, passwordbi_user_password, databasedemo) cursor conn.cursor() provinces [广东省, 江苏省, 浙江省, 四川省, 山东省, 湖南省, 湖北省, 福建省] cities { 广东省: [广州市, 深圳市, 东莞市], 江苏省: [南京市, 苏州市, 无锡市], 浙江省: [杭州市, 宁波市, 温州市], 四川省: [成都市, 绵阳市, 德阳市], 山东省: [济南市, 青岛市, 烟台市], 湖南省: [长沙市, 株洲市, 湘潭市], 湖北省: [武汉市, 宜昌市, 襄阳市], 福建省: [福州市, 厦门市, 泉州市], } categories [数码电器, 服装鞋帽, 食品生鲜, 家居日用, 美妆个护] for _ in range(100000): province random.choice(provinces) city random.choice(cities[province]) category random.choice(categories) order_date datetime(2024, 1, 1) timedelta(daysrandom.randint(0, 364)) amount round(random.uniform(50, 2000), 2) cost round(amount * random.uniform(0.4, 0.8), 2) quantity random.randint(1, 5) cursor.execute( INSERT INTO sales_order (order_date, province, city, category, amount, cost, quantity) VALUES (%s, %s, %s, %s, %s, %s, %s), (order_date.strftime(%Y-%m-%d), province, city, category, amount, cost, quantity) ) conn.commit() cursor.close() conn.close() print(演示数据生成完成)5.2 配置数据源与数据集在系统里进入数据源管理添加一个MySQL数据源填入刚才的demo库连接信息。测试通过后下一步创建数据集我直接使用SQL模式SELECT order_date, province, city, category, amount, cost, amount - cost AS profit, quantity FROM sales_order这个数据集是一个明细查询后续的报表和看板都是基于它或基于它的聚合结果。建议在实际项目里不要直接对着明细表做报表而应该把这层SQL查询变成物理视图或者定时汇总表以提高性能。演示阶段可以先用这个功能跑通了再优化性能。5.3 新建看板并配置图表进入可视化看板模块点击新建看板选择一个深色模板大屏效果更好。我先拖入一个指标卡片配置字段为SUM(amount)显示名称总销售额数字格式设为千分位展示。再拖入一个指标卡片显示SUM(profit)命名总毛利。接着拖入一个柱状图维度选province指标选SUM(amount)这样得到每个省份的销售总额排名。再拖一个折线图维度选DATE_FORMAT(order_date, %Y-%m)指标选SUM(amount)展示12个月的销售趋势。配置筛选器在组件列表里拖入日期范围筛选器绑定字段order_date。然后把这个筛选器分别关联到柱状图和折线图上配置方式是在图表的数据配置里选择关联筛选器。保存看板后切换日期范围两个图表会一起刷新。这一步是整个环节里新手最容易卡住的点。如果点击日期筛选器之后图表没反应优先检查两处一是筛选器的字段类型是否和数据集里的字段类型一致日期类型必须匹配二是联动设置里目标图表是否勾选了正确的依赖筛选器。5.4 预览与性能验证看板配置完成后点击预览这时候会在新标签页打开大屏页面。观察一下加载速度。10万行数据量并不大但如果你的查询直接扫了全表没有走索引首次加载可能也要一两秒。在MySQL里给order_date加一个索引对时间范围过滤帮助很大ALTER TABLE sales_order ADD INDEX idx_order_date (order_date);如果看板上同时有多个图表每个图表各自发一个查询请求同一时间有5-6个请求打到数据库。开发环境没感觉生产环境一旦用户多就可能拖垮数据库。我建议借助Redis做一层结果缓存给每个查询请求生成一个hash key缓存的key就是数据集ID 参数值 SQL哈希缓存的value就是JSON结果。当参数变化时key变化自然命中不同的缓存参数不变的重复查询直接从Redis返回响应时间能从700ms降到10ms级别。5.5 发布与嵌入看板做完了要分享给团队使用。这套源码支持两种方式一种是发布为公开链接任何人拿到链接都可以看适合客户演示另一种是嵌入到管理系统里用iframe的方式。iframe srchttps://bi.example.com/dashboard/preview?dashboardId123tokenyour_embed_token width100% height800 frameborder0 /iframe这里的token是嵌入凭证服务端会校验这个token是否有权限访问ID为123的看板。注意不要直接把dashboardId裸露在URL里不做校验否则权限绕过风险很大。建议在服务端用一次性的access token来换取临时的访问凭证token过期时间设置为2小时以内。6. 常见问题与排查技巧实录6.1 数据源连接失败症状添加MySQL数据源时提示Communications link failure。排查步骤检查MySQL服务是否启动systemctl status mysqld或docker ps | grep mysql。检查端口是否可达telnet 服务器IP 3306如果端口不通可能是云安全组没放行3306端口。检查MySQL用户权限用SELECT user, host FROM mysql.user;查看用户是否存在且host匹配。尤其要注意bi_user如果绑定的是localhost那么应用从Docker容器内连接时会被拒正确做法是创建用户时指定bi_user%。实操建议生产环境数据库和应用服务器不要放在不同的云账号下网络隔离问题排查起来非常费劲。把MySQL和应用部署在同一VPC内用内网IP连接安全性和响应时间都更好。6.2 大屏图表渲染空白症状看板能打开但部分图表区域空白控制台报ECharts相关的错误。常见的三个原因数据格式不对ECharts对数据格式要求很严格。比如柱状图的数据如果是[{name: 广东, value: 100}]这种对象数组饼图和地图也是这个结构但折线图需要的是{xAxis: [1月,2月], series: [{data: [100,200]}]}。如果你数据集返回的字段名不匹配比如label和name不一致图表就无法渲染。容器尺寸为0如果图表组件的父容器没有设置高度ECharts初始化的container是0px高自然画不出东西。给图表组件的外层div加一个height: 400px或者在初始化前用resize方法强制获取容器尺寸。异步加载时序问题如果你在页面mounted时就初始化图表但数据请求还没回来此时setOption会拿到空数据。等数据回来后再初始化或者初始化时传入dataset: []数据返回后做setOption更新。排查方法打开浏览器F12看Network里对应接口返回的JSON是否正常再看Console里是否有ECharts报错信息。ECharts的报错信息其实很友好比如data is not an array直接告诉你数据结构有问题。6.3 多维分析下钻时不生效症状用户点击报表中的省份字段期望下钻到城市但页面没有任何变化。排查步骤确认你是点击了维度字段而不是数据单元格。下钻交互通常绑定在行标题的字段上点击数据值只是选中。检查数据模型里有没有配置层级关系。如果province和city是两个并列的字段系统不知道该按什么顺序下钻。需要把两个字段配成省份 - 城市的层级树。看Network请求下钻操作应该发一个新的查询请求参数里带上了dimensionPath或drillDownField。如果请求根本没发说明前端事件绑定有问题如果请求发了但结果没变说明后端的group by字段没有切换成功。一个更隐蔽的问题如果数据集是明细查询下钻请求本来就会很快因为数据量小。一旦数据量到了百万级每次切换维度都需要几秒体验就非常差了。我在第3章提到过汇总表方案这里再强调一遍——多维分析下钻必须基于预聚合的Cube表否则性能是撑不住的。6.4 常见问题速查表问题可能原因快速解法登录后跳转回登录页会话过期或token未存储检查localStorage/sessionStorage清理后重新登录报表导出Excel中文乱码缺失BOM头导出时在文件流前加\xEF\xBB\xBF定时刷新的报表不更新定时任务未配置或时区错检查Quartz配置确认Cron表达式用的服务器本地时区大屏在手机上显示错乱没有做移动端适配大屏模板固定尺寸建议用transform: scale()做缩放适配用户看不到自己创建的数据集数据集权限默认私有在数据集管理里把数据集分享给对应角色聚合数据结果有重复SQL里JOIN产生笛卡尔积检查事实表和维度表关联字段是否唯一6.5 性能调优的进阶方向如果这套BI平台的数据量到了一定的规模比如明细表超过千万行有几个优化方向可以依次考虑查询缓存这是成本最低的效果最明显。短期内重复的查询同一个看板、同一个筛选条件直接返回Redis缓存。数据库压力直接降一个量级。汇总表把常用维度的聚合提前算好。比如每天凌晨跑一个定时任务把省份品类日期维度的销售额、订单数汇总到一张表。报表只查汇总表不碰明细表。ClickHouse替换查询引擎如果你有几千亿行明细要跑即时分析MySQL基本上到极限了。把这套BI的查询引擎层接上ClickHouseSQL语法支持度高性能提升100倍以上。很多开源BI项目都支持接入ClickHouse数据源你只需要在数据源管理里新增一个ClickHouse类型就行。异步查询对于非常复杂的分析请求不能同步等待SQL跑完再返回。改成提交任务、返回任务ID前端轮询任务状态跑完后拉取结果。这才是企业级BI处理重型查询的标配模式很多开源BI都是这样设计的。7. 我对这套源码的几点评价我正儿八经用下来这个开源BI项目的完成度在同类中算很不错的。从数据源接入到报表设计器到大屏展示闭环完整代码结构清晰适合拿来学习和二次开发。我最喜欢的一点是它的数据集/SQL模式设计很务实既保留了SQL的灵活度又提供了一定的参数化能力。对于有SQL基础的团队来说这种模式比纯拖拽式的模型配置更高效能够快速响应复杂的业务取数需求。如果说有什么不满意的大概有两处。一是多维分析的下钻能力还是相对基础和Power BI的层级钻取交互相比有差距二是移动端适配不是重点做出来的看板基本是为PC大屏服务的如果需要在手机上查看得自己做一套移动布局。不过考虑到这是开源项目这些问题都可以二次开发补上不影响整体评价。部署的时候建议先用Docker Compose在测试环境把全流程跑通确认架构和你团队的实际情况匹配再考虑接管生产环境。不要第一步就急着改源码——先把原版跑起来理解数据从MySQL到报表页面的完整流转再开始动手加功能这样踩坑最少。本文还有配套的精品资源点击获取