如果你在项目列表或者某个技术讨论群里看到Madeira这个名字第一反应很可能是葡萄牙那个火山岛或者那种带着焦糖味的强化葡萄酒。但在我们团队它是一个代号——一个从零搭建的轻量级自助式BI分析平台。我们花了大半年时间把它从一张白纸做到业务部门真正在天天用中间踩过的坑、推翻过的设计、总结出的经验我想系统性地写一写。这篇文章适合那些准备做数据产品、或者在团队里负责搭建内部报表平台的人尤其是资源不多、又想快速落地的中小团队。1. 为什么我们给BI工具起名Madeira1.1 这个代号从哪来Madeira这个名字在软件行业其实有过一次很有分量的出场微软早期做自助式BI产品时内部项目代号就叫Madeira也就是后来Power BI那条产品线的雏形。做技术的人多少都有点代号情结喜欢用地名、酒庄、甜品这类词给内部项目命名既好记又有辨识度。我们立项时起过不少名字什么SparkBoard、DataCanvas翻了一圈不是被占用了就是太普通最后有人翻到当年的项目代号表说了一句要不叫Madeira吧有地缘特色还带点酒香就这么定了下来。代号这东西说重要也重要说不重要也不重要。它最重要的作用是让团队内部讨论时有个清晰的指代词而不是承担多少业务含义。真正决定项目命运的是立项时你对问题本身的定义。1.2 立项背景我们要解决什么问题当时我们公司有两套数据体系在并行运转一套是数仓团队维护的正式报表面向会写SQL的报表工程师提出一个需求到上线基本要排两三周另一套是业务部门自己用Excel维护的月度汇总每个团队一张表口径经常对不上。业务负责人想看清楚某个区域的销售趋势得同时打开三个Excel文件自己比对没人敢拍板以哪个数为准。所以我们的目标从一开始就不是做一个Power BI的替代品而是做一个中间层让业务人员能自助连接经过治理的数据表通过拖拽完成看板搭建同时平台在背后自动记录每一次查询和指标口径。产品定位一句话就能说清——面向业务分析师的轻量级自助BI平台。它不服务专业的报表工程师那些复杂需求该走数仓还是走数仓。1.3 设计原则少做功能多做收敛第一版我们砍掉了很多BI工具的标配功能不做ETL编排、不做自定义SQL编辑器、不做报表的复杂分享权限只保留三条链路数据连接、模型配置、看板拖拽。砍功能的原因是团队就五个人前三个月要出可用版本。与其做一堆半成品功能堆在界面上不如把三条核心链路彻底跑通。这个决策后来被反复证明是对的业务方反馈最多的一句话是你们的功能真不多但我想做的事基本都能自己做出来。这比一堆花哨但没人用得上的功能有价值得多。2. 数据接入与关系建模第一版架构的取舍2.1 数据源适配器应该做到哪一层第一版我们支持的数据源有四种MySQL、PostgreSQL、ClickHouse还有Excel上传。这四种数据源的能力差异非常大如果你试图把它们抽象成一套完全统一的接口后面会非常痛苦。我直接用一张表说明这些差异数据源查询下推能力主要差异点MySQL支持常见聚合函数齐全语法标准PostgreSQL支持支持JSON操作、窗口函数更丰富ClickHouse支持日期函数、聚合函数与MySQL差异大Excel上传不支持只能全量导入后在内存里处理如果强行把where和group by都下推到所有数据源ClickHouse的语法差异会让你维护一套非常臃肿的方言层而Excel又根本没法下推。我们最后把查询引擎拆成两层SQL方言层和结果集操作层。SQL方言层维护了一套轻量的方言映射负责把常用操作日期截断、字符串拼接、空值处理翻译成目标数据源的语法。结果集操作层则兜底处理那些无法下推的部分——比如Excel数据源的过滤和聚合直接在应用内存里完成。这套设计换来的是同一个看板在不同数据源上表现一致业务人员不需要关心底层是Excel还是ClickHouse。提示不是所有数据源都需要做查询下推优化。Excel上传这种小数据量场景内存聚合的延迟远小于维护方言解析的成本。做适配器之前先想清楚每个数据源的量级和查询模式。2.2 星型模型简化为宽表优先一开始我们也想跟专业BI工具看齐做一套完整的语义层定义事实表、维度表、度量字段、计算字段、层级关系。做了一半发现我们服务的业务团队绝大多数场景其实就是一张宽表加上几个维度过滤条件很少用到真正的星型模型。最终我们做了一个简化版的关系模型规则非常明确每个数据集由一到多张表组成表之间最多支持两张关联键关联方式限定为LEFT JOIN或INNER JOIN度量字段必须来自事实表维度字段可以来自任意关联表关联键之外不做二次粒度控制这个简化的核心好处是前端拖拽时用户完全不需要理解粒度这个概念系统通过主键约束保证聚合结果不会因为关联而翻倍。代价是如果业务确实需要多级明细分析比如订单、订单明细、退款明细这种链路就必须在数仓侧先做宽表预处理。我们跟使用方明确了一条边界宽表建设是数仓的责任BI工具不做多级建模。这条边界省了无数沟通成本。2.3 缓存刷新策略查得快的代价看板查询最快能做到几百毫秒靠的不是什么高深的数据库调优是缓存。我们用Redis存查询结果缓存key由数据源ID、数据集ID和查询条件哈希组成value是序列化后的表格结构。刷新策略有两种定时任务刷新每天凌晨2点把常用数据集预跑一遍写入缓存上班打开就是热数据手动刷新业务人员点界面上的刷新数据按钮清掉该数据集的所有缓存下一次查询触发重建这里有个非常容易被忽视的细节手动刷新必须做缓存失效而不是覆盖写。早期我们图省事直接覆盖写结果两个用户同时触发刷新时出现了串数据的情况。排查了半天才定位到是缓存竞争问题。改成先失效后由查询触发重建之后问题彻底消失代价是刷新后第一次打开会慢一些但对报表场景来说完全可以接受。3. 可视化渲染层的技术选型与性能优化3.1 图表库选型ECharts还是Recharts可视化是BI工具的门面业务人员第一眼感受到的好不好用基本都是靠图表交互。我们当时在ECharts、Ant Design Charts、Recharts三者之间做了对比结论很直接图表库包体影响定制灵活性社区活跃度适合场景ECharts较大可按需引入强高复杂图表、深度定制Ant Design Charts中等中中与Ant Design体系强绑定Recharts小中中React技术栈、图表形态简单我们最终选了ECharts。原因是看板里总会出现一些比较特殊的图表形态——地图下钻、旭日图、多指标联动这种ECharts的配置项最全遇到边界问题时试错成本最低。而且它还有服务端渲染的能力这对后面做报表分享和打印导出很有价值。包体问题通过按需引入和CDN拆分解决实际页面加载性能并没有成为瓶颈。3.2 拖拽面板的数据结构一切皆Schema拖拽式操作的核心难点不在前端的拖拽交互而在拖拽结果如何序列化成稳定、可迁移的JSON结构。我们为看板定义了一套Schema它是前端交互和后端查询之间唯一的协议{ version: 1, dataSetId: ds_12345, metrics: [ {field: amount, aggregation: sum} ], dimensions: [ {field: province} ], filters: [ {field: date, operator: gte, value: 2024-01-01} ], chartType: bar, layout: {w: 6, h: 4, x: 0, y: 0} }这套Schema的关键设计是图表类型与查询逻辑完全解耦。用户拖拽时不管是选了柱状图还是折线图metrics、dimensions、filters这部分完全不变变化的只有chartType和layout。这个设计让看板的复制和迁移变得异常简单——从一个数据集复制到另一个数据集只需要换dataSetId然后做一次字段映射查询逻辑天然兼容。有了这套约定后端查询的接口设计也简单了前端把整个Schema作为参数提交后端统一解析执行。这比传统的前端传query参数、后端拼SQL的方式规范得多也方便做权限拦截。3.3 数据量变大后的渲染优化降采样与分批渲染业务方最爱拖的图是近三年每日订单量趋势一拖就是上万甚至十万个点。ECharts直接渲染十万个SVG节点浏览器会卡到没法滚动。我们做了两层优化采样压缩当单图表点数超过5000时用LTTB降采样算法把数据压缩到5000点以内。这个算法保留的是趋势极值点人眼几乎分辨不出压缩前后的差异但渲染压力直接降了一个量级。分批渲染图表先渲染首屏可见区域等用户滚动或交互触发后再补全剩余部分避免一次性阻塞主线程。这两招配合下来十万点级别的折线图也能稳定在60帧左右。建议所有做可视化的人提前掌握LTTB这个算法它比简单等间隔采样实用得多网上有现成的开源实现。4. 权限模型从能用到敢用4.1 行级权限RLS怎么让不同的销售看不同的数在BI工具里行级权限不是加分项是硬门槛。企业内部的数据看板必然存在销售A不能看到销售B的客户数据这类需求。我们没有去做复杂的表达式规则引擎而是用了一张字段映射表来落地数据集上配置一个权限维度比如region用户与权限值的关系维护在独立表里user_id、region、access_type查询时系统在模型层自动拼接过滤条件WHERE region IN (SELECT region FROM user_region WHERE user_id ?)这里面有一个非常关键的坑权限条件拼接必须发生在服务端模型层而不是前端传参。如果前端能够通过接口直接传入region参数用户完全可以构造请求绕过权限看到不属于自己的数据。我们的做法是权限上下文在服务端Session中维护前端只提交用户身份可见范围完全由后端决定。4.2 多租户隔离缓存串号的事故复盘SaaS部署方式下多租户隔离是另一个容易出事的地方。我们第一版把租户ID当作普通查询参数处理结果发生了一次真实的事故两个租户看到了同一份数据。排查过程不复杂但教训很深刻。日志显示租户A查询的数据集ID和租户B完全相同缓存key又是按数据源ID数据集ID查询条件哈希生成的完全没有租户维度。于是租户A先查了一次缓存被写入租户B发起相同查询直接命中了A的缓存。修复方案有三步所有缓存key强制以租户ID开头数据库连接池按租户隔离每个租户使用独立的数据源配置和连接把是否包含租户ID写进代码评审的必查清单最后一步是最重要的因为这类问题在测试环境基本发现不了只有并发租户多了才会暴露而且一暴露就是数据安全事故。4.3 审计日志不为了追责为了定位问题审计模块我们一开始完全没做直到有次业务负责人问这个看板里的数字是谁改的我们翻遍了数据库都没找到答案。后来补的日志又是SQL级的业务人员根本看不懂。现在我们的审计日志记录的是人话事件谁在什么时间打开了哪个看板谁修改了哪个数据集的指标口径改了什么字段、从哪个聚合方式改成了哪个谁导出了数据导出了哪些维度范围的数据实现上就是一个异步管道操作事件推送到消息队列消费者写入ClickHouse查询端提供按人、按看板、按时间段的过滤。注意审计日志不只是合规要求它更是产品迭代的依据。我们靠审计日志发现导出Excel是高频操作后把导出功能做成了带水印的一键下载反而减少了大量为什么不能复制粘贴出来发给我的客服咨询。5. 上线之后踩过的坑与排查思路5.1 慢查询排查一个看板转圈十几秒的真正原因项目上线两周后销售团队反馈某个看板打开要等十几秒。我们的第一反应是渲染性能问题结果用性能面板一测渲染只花了300毫秒剩下的时间全花在查询上。完整的排查链路是这样的打开出问题的看板在服务端日志里找到对应的query id用query id反查到执行计划发现命中的是一张几千万行的订单明细表而不是数仓预聚合的表检查数据集配置发现字段的默认聚合选择的是明细行数导致查询退化成了全表扫描修复分两步把数据集的默认聚合改成sum(amount)同时把数仓侧的查询超时时间从60秒压到10秒。压超时时间这个操作很多人不理解逻辑其实很简单如果一个看板查询10秒都出不来大概率是配置有问题与其让用户无限等待然后超时不如快速报错让问题提前暴露。5.2 Excel上传导致的内存溢出Excel上传功能是给业务临时导入数据用的第一版做得很粗暴文件直接读进内存转DataFrame。测试环境传几MB的文件完全没问题生产环境有次用户传了一个80MB的Excel每个sheet还有合并单元格服务端直接OOM连带着同一个节点上的其他租户查询一起挂了。修复方案分三层上传文件先落盘用流式方式逐行读取边读边转不在内存里放完整文件行数超过50万的Excel直接拒绝导入页面提示用户走数仓同步流程JVM堆内存增加监控告警堆内存超过阈值自动告警并触发扩容这里我有一条很深的体会Excel处理的坑比数据查询的坑多得多。合并单元格、公式引用、日期格式被转成科学计数法、字符集乱码每一个细节都能让报表数据错得离谱。我们的解决方案是在解析完成后做一次数据体检抽样打印前20行数据让用户确认后再入库。这个功能看起来不起眼但上线后挡掉了90%的脏数据投诉。5.3 看板白屏一个ResizeObserver引发的兼容性问题项目上线第三周有客户反馈某个浏览器打开看板白屏。我们自己在Chrome上完全复现不了后来才知道客户公司的内部浏览器是旧版Chromium内核。排查链路的起点是浏览器控制台报错信息是ResizeObserver is not defined。全局搜索代码里用到ResizeObserver的地方发现是拖拽面板在窗口大小变化时用来重新计算布局的。查了一下兼容性ResizeObserver要到Chrome 64才支持客户的内网浏览器内核还是60多的版本。修复本身很简单加了个polyfill就解决了。但这个问题暴露的是企业级应用的一个通病浏览器兼容性永远要当成一等公民对待。我们在产品文档里明确写了支持Chrome 80及以上版本、Edge、Firefox同时在打包层面统一引入core-js补齐polyfill彻底断了这类问题的后路。5.4 并发刷新导致的数据不一致最后补一个并发问题。有次十几个业务人员同时点了同一个数据集的手动刷新结果出现了数据不一致一部分人看到的是新数据一部分人看到的是旧数据。原因是刷新流程本身是先删缓存再查库并发请求全都在删完缓存后涌向数据库但由于时序不同查到的数据快照不是同一批。我们改成双缓冲机制新数据查询全量完成后再原子替换缓存替换之前旧缓存继续对外服务。刷新接口加了一把互斥锁同一数据集同一时刻只允许一个刷新任务在跑。这个方案上线后再也没出现过刷新导致的脏读问题。类似的思路在缓存更新的很多场景都能复用如果你的某个接口有类似问题可以考虑同样的手段。尾声关于Madeira的几句话项目上线八个月后回头看Madeira真正的成功点不在于技术选型有多先进而在于我们想清楚了一件事给业务人员用的BI工具核心不是功能堆叠而是把数据链路的可信度做出来。每一次查询都有归属每一个指标口径都有记录每一层权限都清晰可见——做到这些用户自然愿意放下Excel。如果你们也打算做一个类似的自助分析项目我的建议是先用两周时间把产品定位和边界写在纸上想清楚哪些功能坚决不做这比想清楚要做哪些功能更重要。选型上不要迷信大而全的框架按自己的数据量级和使用场景来。另外权限和审计模块一定要从第一天就开始设计后期补的成本会翻好几倍。最后再分享一个小技巧给内部项目起个像Madeira这样的地名代号团队聊起来真的会更有归属感。