迁移Superset到Evidence并不是简单的图表搬家，而是把仪表板思维切换为数据故事思维。Superset更适合探索式分析和多图表联动，但嵌入React应用时，iframe隔离、权限和样式适配会带来额外成本。Evidence则鼓励用Markdown组织页面，在每个段落中直接嵌入SQL结果和可视化组件，输出更接近文章或报告。下面从实际项目经验出发，梳理两者差异和迁移路径。
一、Superset与Evidence的架构差异
Superset的前端主体基于React，但它通常作为一个独立服务运行，外部系统通过iframe嵌入仪表板。这种方式虽然省事，但会带来三个典型问题：跨域通信需要依赖postMessage，主题样式很难与宿主应用完全统一，以及每次展示都要加载完整的Superset前端资源。相比之下，Evidence生成的是静态优先的数据页面，构建阶段会执行SQL并预取数据，最终产物可以托管在任意静态服务器或Next.js应用中，不需要在浏览器端维护一个重型BI运行时。
从查询模型看，Superset主要围绕数据集和图表配置，用户通过界面拖拽生成查询，图表元数据存储在数据库中。Evidence则把查询直接写在Markdown文件里，用SQL代码块定义数据源，用组件标签渲染图表。这让图表逻辑与页面叙事耦合得更紧密，也更容易做版本管理和代码评审。
在可视化能力上，Superset的图表类型更丰富，尤其适合需要复杂聚合和过滤条件的探索场景。Evidence的组件库精简，但包含折线图、柱状图、表格、大数值卡片等常用类型，并且支持自定义组件。如果你的需求是给业务方呈现清晰的结论而不是自助分析，Evidence的组件已经足够。
二、迁移前需要盘点什么
决定迁移后，先不要急着新建Evidence工程。建议先把Superset中的看板按用途分类：哪些是长期监控类，哪些是周期性报告，哪些是临时分析。Evidence更适合后两类，监控类看板如果依赖实时刷新和告警，留在Superset可能更合理。
接着导出每个图表对应的SQL。在Superset图表编辑页的查看查询功能中可以拿到底层SQL，但要注意该SQL已经被Superset包装过，可能包含临时表名或自动生成的别名。清洗时需要把别名恢复成可读名称，并确认是否依赖Superset的行级权限或虚拟数据集。如果有跨库查询，要确认Evidence的数据源连接器是否支持相同数据库。
数据集权限也要重新设计。Superset有角色、行级安全和数据源级权限，Evidence更多依赖数据源连接账号的权限。迁移前应与数据负责人确认只读账号的授权范围，避免Evidence页面意外暴露未脱敏数据。
三、在Evidence中重建页面
Evidence工程通常使用npm初始化，核心文件是Markdown页面。每个页面的结构分为三部分：SQL查询块、数据引用和可视化组件。下面是一个典型的销售概览页面示例：
# 月度销售概览
```sql sales
select date_trunc('month', order_date) as month,
sum(amount) as revenue,
count(distinct customer_id) as customers
from orders
where order_date >= '2024-01-01'
group by 1
order by 1
```
<LineChart data={sales} x=month y=revenue />
<BigValue data={sales} value=revenue />
这里的查询块名称为sales，后续组件通过data={sales}引用查询结果。Evidence会在构建阶段执行SQL，把结果注入到页面变量中。与Superset不同，查询逻辑和图表配置在同一个文件里，评审时能直接看到数据处理过程。
对于Superset中常用的过滤器和日期范围控件，Evidence可以通过页面参数实现。比如在页面头部声明参数，然后在SQL中使用模板变量：
---
date_range: "last 90 days"
---
# 销售趋势
```sql filtered_sales
select date_trunc('day', order_date) as day,
sum(amount) as revenue
from orders
where order_date >= current_date - interval ${date_range}
group by 1
这比Superset中的原生筛选器更显式，也更适合做代码评审和自动化测试。
四、与React应用集成
Evidence页面构建后是一组静态资源，可以部署在独立域名，也可以放在React应用的同源静态目录下。最简单的集成方式是使用<iframe>嵌入指定页面，但与Superset的iframe不同，Evidence页面是静态资源，加载快且不需要额外运行时。若想避免iframe，可以在构建React应用时把Evidence输出复制到public目录，再用<iframe>或直接路由指向对应HTML。
更进一步的方案是把Evidence作为数据故事模块单独部署，用反向代理统一域名。以Nginx为例，可以把/reports路径代理到Evidence静态目录，这样React应用中的链接直接跳转到报告页，会话Cookie也能在同域下共享。反向代理配置如下：
location /reports/ {
alias /var/www/evidence/build/;
try_files $uri $uri/ /reports/index.html;
add_header Cache-Control "public, max-age=300";
}
如果React应用需要从报告页传参，比如当前用户ID或租户标识，可以通过URL查询参数传递。Evidence支持在页面中读取params对象，但要注意不要让敏感信息出现在URL中。对于需要登录保护的页面，建议在反向代理层校验会话，而不是依赖Evidence自身的认证。
五、迁移中的常见坑
第一个高频问题是日期字段的时区处理。Superset通常把日期格式化为UTC或本地时区，Evidence查询直接返回数据库原始时间，如果数据库时区与展示时区不一致，图表会出现偏移。建议在SQL中显式转换时区，而不是依赖前端组件。
第二个坑是查询性能。Evidence构建时会执行所有SQL，如果页面数量多或者查询没有限制，构建时间会迅速增长。迁移时应该把大查询拆成多个小查询，并为数据源连接设置查询超时。Evidence支持缓存查询结果，CI环境中可以配置增量构建，只重跑变更的查询。
第三个坑是权限测试。Superset的权限模型相对完善，Evidence页面如果没有在前置层做权限控制，任何能访问静态资源的人都能看到页面内容。不要只把Evidence部署在内网就认为安全，仍然需要在代理层做身份校验，并按报告目录拆分访问权限。
整体来看，从Superset迁移到Evidence并不是简单替换一个工具，而是重新梳理数据展示方式。把探索式分析留在Superset，把结论型报告迁移到Evidence，再通过React应用统一入口和权限控制，往往能让数据产品的维护成本明显下降。