Apache Superset 0.35 二次开发指南：环境搭建、JWT 登录、ECharts 插件与权限扩展

Words 2285Read Time≈ 6 min
2021-4-16
2026-2-11
cover
type
Post
status
Published
date
Apr 16, 2021 14:41
slug
summary
本指南基于 Superset 0.35 源码二次开发实战，涵盖六大核心模块：环境配置 - Windows 下 Python 3.6 + Node 12 开发环境、依赖安装、软连接配置与前后端启动；JWT 认证 - 替换 Flask-Login 会话机制，通过重写 CustomAuthDBView 和 CustomSecurityManager 实现无状态 Token 登录；ECharts 集成 - 后端添加 EchartsBarViz 类处理数据，前端创建插件目录并注册到 MainPreset，配置 controlPanels 面板；页面扩展 - 新增路由与菜单、修改 webpack 入口构建独立 React 页面、移除默认导航栏；权限控制 - 使用 @has_access 装饰器，通过 ab_permission / ab_permission_view / ab_view_menu 三表管理角色与视图权限；生产优化 - 中文国际化设置、CSV 导出编码（utf-8-sig）、地图汉化（修改 china.geojson）、导出使用列别名（verbose_map）。
tags
Superset
Data Warehouse
Big Data
category
Data Engineering
icon
password
wordCount
2876
本文基于 Superset 0.35 的源码做二次开发实践，覆盖 Windows 下的开发环境搭建、接入 JWT 无状态登录、集成 ECharts 图表、扩展自定义页面与权限、以及常见国际化与导出问题处理。Superset 版本差异较大，其他版本请按思路自行对照源码调整。
🧩
Superset 简介
  • Apache Superset 是一个开源的 数据探索与可视化 平台，核心能力包括：连接多种数据源、编写 SQL 进行分析、构建图表与仪表盘，并支持权限与多租户等企业常见需求。
  • 典型使用场景：BI 报表、自助取数、指标看板、数据平台可视化层。
  • 架构上通常由 Python/Flask 后端（查询、权限、元数据）与 前端可视化框架（Explore、Dashboard、插件体系）组成，可通过插件和二次开发扩展图表类型、页面路由与安全认证逻辑。
⚠️
版本提示：文中示例以 superset==0.35 为基准。较新的 Superset（尤其 1.x/2.x）在前端构建体系、目录结构与安全模块上都有明显变化。
🧭
阅读顺序建议
  • 先完成「搭建开发环境」确保前后端能正常启动
  • 再按需选择：JWT 登录、ECharts、页面与权限、国际化与导出

实验环境

  • Windows 10
  • Python 3.6.8
  • pip 19.2.3
  • setuptools 41.4.0
  • Node.js 12.15.0
  • npm 6.13.4
  • superset 0.35
Superset 版本迭代快、变更大，本指南针对 0.35 版本，其他版本不保证可直接复现。

搭建开发环境

  1. 获取源码
    1. 配置 pip 国内源（可选）
      1. 安装 C++ Build Tools（可选）
      • Windows 下部分依赖可能需要编译环境。
      1. 创建虚拟环境（已有可跳过）
      1. 安装后端依赖
        1. Windows 下制作软连接（非 Windows 可跳过）
        Superset 源码目录名通常是 incubator-superset，其中 superset/static/assets 与 superset/assets 在 Windows 下需要用软连接来兼容。
        • 将 yourpath 替换成你的实际路径
        • 运行前建议先删除旧的 yourpath\incubator-superset\superset\static\assets
          1. 安装 Superset（开发者模式）
            1. 创建管理员账户
                2. 如果已创建会报主键重复，忽略后继续。
            1. 初始化数据库
              1. 应用初始化（后端配置完成）
                1. 前端依赖安装
                    2. 进入 superset/assets：
                    如果失败可尝试：
                    如果仍失败，清理后再装：
                    🛠️
                    常见坑：Node 13.8 安装依赖时可能报错，建议改用 12.15。
                    （示例报错截图）
                    notion image
                1. 启动前端开发模式
                    2. dev 会监听变更并自动编译，正常启动后不要关闭该终端。
                    notion image
                    如遇缺包报错：
                    notion image
                    执行：
                1. 启动后端
                    2. 新开终端，进入项目根目录（例如 yourpath\incubator-superset）：
                1. 验证
                    2. 打开 http://localhost:8088，若能看到 Superset 界面说明搭建成功。
                1. 开发工具建议
                • Python：PyCharm
                • 前端：VS Code

                自定义 JWT 登录验证

                Superset 默认使用 Flask-Login（有状态会话）。若你的项目需要无状态 Token（例如 JWT）登录，可通过重写安全管理器与登录 View 实现。
                1）Superset 登录逻辑入口
                入口文件：superset/__init__.py（示例行号可能随版本变化）
                2）BaseSecurityManager 初始化 auth view
                查看 BaseSecurityManager 中关于 AUTH_DB 的逻辑（示例）：
                self.authdbview 对应 AuthDBView，其内部包含登录逻辑。思路是：自定义 SupersetSecurityManager，并把 authdbview 指向你的自定义登录 View。
                3）编写自己的 JWT 验证
                1. 在 superset 下新建目录 customize
                notion image
                1. 新建 CustomAuthDBView.py
                  1. 新建 CustomSecurityManager.py
                    1. 修改 /superset/config.py
                        2. 将：
                        改为：
                    1. 启动服务，打开登录页
                    1. 携带 token 参数直接登录
                        2. 示例：
                        🔒
                        安全提示：示例代码仅做演示。
                        • secret 请使用安全存储与更复杂的签名策略
                        • jwt.decode 建议显式指定算法与校验项
                        • 生产环境建议增加用户状态校验、来源校验与更合理的过期策略

                    Superset 集成 ECharts

                    目标：新增一个自定义可视化类型 echarts_bar，后端提供数据，前端注册插件并渲染。

                    后端

                    修改 superset/viz.py（所有图表的后端处理入口之一），添加一个类（示例）：
                    • viz_type 用于标识图表类型，必须与前端注册一致
                    • query_obj 负责组织查询参数
                    • get_data 负责返回最终数据结构

                    前端

                    1. 新建目录 EchartsBar
                        2. notion image
                    1. 入口文件 index.js
                      1. transformProps.js
                        1. ReactEchartsBar.js
                          1. EchartsBar.js
                              2. 数据来自后端查询结果。调试时可先写死数据，再逐步接入真实数据结构。
                          1. EchartsBar.css
                            1. 创建 images/ 放置封面图
                                • thumbnail.png
                                • thumbnailLarge.png
                            1. 注册图表
                                2. 打开 /superset/visualizations/presets/MainPreset.js，添加：
                                notion image
                            1. 新建控制面板 controlPanels/EchartsBar.js
                              1. 注册面板
                                  2. 在 /superset/setup/setupPlugins.ts 添加：
                                  notion image
                              1. 重启前后端服务，验证新图表
                                  2. notion image
                                  notion image

                              自定义页面

                              新增路由

                              在 superset/view/core.py 末尾添加：
                              重启后访问：http://127.0.0.1:8088/lucas/theme/
                              <image source="file://%7B%22source%22%3A%22attachment%3Af7fb206b-863b-4c4b-9d14-97cf2dd08b99%3A12.png%22%2C%22permissionRecord%22%3A%7B%22table%22%3A%22block%22%2C%22id%22%3A%2230030b12-a8b4-8122-9d5a-f3dd160688de%22%2C%22spaceId%22%3A%221ad30b12-a8b4-8162-8963-0003ef9f171c%22%7D%7D" />

                              新增菜单选项

                              在同文件末尾添加（示例）：
                              重新执行：
                              notion image

                              新增 React 页面（独立入口）

                              1. 复制一份 Superset 工程（或在同工程内增加入口）
                                  2. notion image
                              1. 修改 superset.config.js，增加入口 myView
                                1. 构建
                                  1. 去掉 Superset 导航栏（可选）
                                      2. 复制 /superset/templates/superset/basic.html 到同目录并命名 myBasic.html，删除 navbar 相关 block：
                                  1. 后端新增路由，渲染自定义模板并指定入口
                                    1. 访问验证
                                        2. http://127.0.0.1:8088/lucas/theme/（示例）

                                    视图与角色权限

                                    Superset 默认将角色与视图权限存储在数据库中。若要新增权限，通常涉及三张表：
                                    • ab_permission
                                    • ab_permission_view
                                    • ab_view_menu
                                    并在路由上添加访问控制装饰器：
                                    notion image

                                    控制权限代码块

                                    • @has_access：用于 View
                                    • @has_access_api：用于 API

                                    插入权限数据

                                    两种思路：
                                    • 直接向上述三张表插入权限相关数据
                                    • 在代码中加入 db.create_all() 后执行 superset init，让系统初始化权限（是否适用取决于当前工程状态）

                                    自定义内置参数

                                    修改源码
                                    修改 superset/jinja_context.py，在 filter_values 方法后添加：
                                    在 BaseTemplateProcessor 类的 __init__ 中把 get_tenantid 注入模板上下文：
                                    使用方法
                                    示例（SQL Lab 或数据源）：

                                    设置 Superset 默认中文

                                    修改 config.py：
                                    改为：

                                    解决 CSV 导出乱码

                                    修改 config.py：
                                    改为：

                                    地图图表汉化

                                    汉化前：
                                    notion image
                                    汉化后：
                                    notion image
                                    修改两个文件：
                                    • ./superset/assets/node_modules/@superset-ui/legacy-plugin-chart-country-map/esm/countries/china.geojson
                                    • ./superset/assets/node_modules/@superset-ui/legacy-plugin-chart-country-map/lib/countries/china.geojson
                                    将 NAME_1 从拼音改为中文，例如：
                                    改为：
                                    然后重新编译前端：

                                    国际化

                                    找到安装目录下 translations/zh/LC_MESSAGES/，编辑其中的 messages.json，添加需要汉化的字符串。
                                    完成后在 superset/ 目录执行：
                                    编译完成后重启服务。

                                    CSV 导出别名

                                    修改 superset/viz.py 中 get_csv：
                                    Loading...