Apache Superset 最新源码本地部署与前端开发调试学习笔记

一、学习概述

本次完整完成了 Apache Superset 7.0-dev（main 最新开发分支） 的源码级本地开发环境搭建，涵盖：

• 源码拉取

• WSL 虚拟环境配置

• Python 后端部署

• React + TS 前端编译调试

• 源码热更新验证

• 线上报错排查

• 浏览器兼容适配

• VS Code 远程开发配置

区别于 pip 安装的正式稳定版，本次基于 开发版源码 部署，适配：

• 二次开发

• 源码阅读

• 组件自定义

• 功能调试

等深度开发场景。

核心收获：

• 掌握 Superset 前后端分离开发架构

• 理解源码热更新机制

• 掌握开发环境常见报错解决方案

• 熟悉 WSL + VS Code 远程开发规范

• 适配新版源码目录结构变更

二、整体开发架构认知

Superset 采用标准的 前后端分离架构，开发环境双进程独立运行，互不干扰。

开发环境核心特点：

• 前后端独立运行

• 前端支持热更新

• 后端支持热重载

• 无需全量重启服务

（Superset 开发环境整体架构图）

三、环境搭建全流程（实操记录）

3.1 基础环境准备（WSL Ubuntu）

基于 Windows WSL2 搭建 Linux 开发环境，规避 Windows 系统权限、换行符、编译兼容问题。

核心依赖：

• Python 3.11（适配 Superset 7.0-dev 新版依赖）

• Node.js + Npm（前端编译必备）

• 虚拟环境工具（隔离项目依赖，避免全局环境冲突）

关键操作：

• 通过 deadsnakes 源安装指定版本 Python

• 配置独立虚拟环境 .venv

• 保证项目依赖纯净可复现

3.2 源码拉取与初始化

拉取 Apache Superset 官方 main 分支最新源码，即开发版，包含最新未发布功能与架构重构。

关键目录：

完成项目可编辑模式安装：

pip install -e ".[dev]"

作用：

• 实现后端源码修改实时生效

• 适配开发调试场景

3.3 后端部署与数据库初始化

3.3.1 核心踩坑：配置文件报错解决

初始执行：

superset db upgrade

报错：

KeyError: 'superset_config'

核心原因：

• 7.0-dev 新版源码的内置 config.py 包含动态执行逻辑

• 不可直接复制作为运行配置文件

• 旧版 6.x 可直接复制，新版已废弃该方式

解决方案：

• 删除默认复制的配置文件

• 手动创建极简独立配置文件 superset_config.py

• 规避源码动态加载 bug

3.3.2 关键配置写入

自定义开发环境核心配置，适配本地调试、关闭冗余日志、开启实验性功能：

• 配置 SQLite 本地数据库，简化本地开发部署

• 自定义密钥，适配开发环境

• 关闭前端埋点日志报错：

  FRONTEND_LOGGING = False

• 开启 AG-Grid 高级表格实验功能：

  AG_GRID_TABLE_ENABLED = True

  作用：解决示例仪表盘图表渲染报错。

3.3.3 环境变量永久配置

通过 echo 写入 ~/.bashrc + source 热加载，永久生效：

SUPERSET_CONFIG_PATH

优点：

• 无需每次新开终端手动导出变量

• 保证配置长期有效

3.3.4 数据库与管理员初始化

完整执行开发初始化命令：

superset db upgradesuperset fab create-adminsuperset load-examplessuperset init

3.4 前后端服务启动规范（核心知识点）

Superset 开发环境必须 双终端独立运行，目录严格区分，不可混淆。

3.4.1 后端服务（终端1）

运行目录：

~/superset

前置操作：

source .venv/bin/activate

启动命令：

superset run -p 8088 --with-threads --reload --host 0.0.0.0

参数作用：

• --reload：开启后端代码热重载

• Python 源码修改自动重启服务

• 配置文件修改仍需手动重启

3.4.2 前端服务（终端2）

运行目录：

~/superset/superset-frontend

启动命令：

npm run dev

核心能力：

• 监听前端 TS/TSX 源码变更

• 自动 Webpack 编译

• 支持页面热更新

• 需手动 F5 刷新生效

四、VS Code 远程开发配置（标准化开发环境）

4.1 WSL 远程连接原理

VS Code 远程开发架构：

• Windows 提供 GUI 界面

• WSL 内部运行 VS Code Server

• 所有代码解析、依赖读取、编译执行均在 Linux 环境完成

优势：

• 彻底规避 Windows 与 Linux 文件格式、权限、编译兼容问题

核心操作：

• 安装官方 WSL 扩展

• 通过 code . 命令一键打开 WSL 项目目录

• 左下角显示 WSL: Ubuntu 即为正常远程环境

4.2 必备插件配置（WSL 端安装）

4.3 虚拟环境解释器绑定

通过：

Python: Select Interpreter

选中项目 .venv 虚拟环境。

解决问题：

• 源码包导入报错

• 代码提示失效

五、新版源码目录结构革新（重点区别旧版）

Superset main 7.0-dev 分支完成前端目录重构，与 6.x 旧版差异极大。

核心变更：

重点结论：

• 旧版仪表盘页面 src/views/dashboard 已废弃

• 新版仪表盘页面为独立顶层目录 src/dashboard/

• 图表插件统一存放：superset-frontend/plugins/

• ag-grid-table 表格插件位于 plugin-chart-aggrid 目录

• src/views/ 仅存放后台管理列表页，不再包含仪表盘核心渲染逻辑

六、前端热更新调试验证（实操测试）

6.1 测试方案

修改仪表盘主页面：

DashboardPage.tsx

在页面根节点插入自定义测试文本，保存源码观察编译与页面渲染效果。

6.2 完整热更新链路

1. VS Code 远程修改前端 TSX 源码并保存

2. 前端 npm run dev 监听到文件变更，自动执行 Webpack 编译

3. 编译成功后，浏览器 Ctrl + F5 强制清缓存刷新

4. 页面实时展示自定义修改内容，验证热更新机制正常

6.3 热更新核心结论

七、核心报错排查与解决方案（实战踩坑汇总）

7.1 ModuleNotFoundError: No module named 'rich'

原因：

• 新版 Superset 新增日志美化依赖，默认未预装

解决方案：

pip install rich

7.2 KeyError: 'superset_config' 配置报错

根源：

• 7.0-dev 源码内置 config.py 含动态执行逻辑

• 禁止直接复制为运行配置

解决方案：

• 手动创建极简独立配置文件

• 规避源码内部执行异常

7.3 Item with key "ag-grid-table" is not registered

原因：

• AG-Grid 高级表格为实验性功能

• 默认功能开关关闭，插件未注册

解决方案：

• 在配置文件开启：

  AG_GRID_TABLE_ENABLED =True

• 重启前后端服务

• 插件正常注册渲染

7.4 华为浏览器登录卡住、前端埋点报错

原因：

• 华为定制浏览器内核版本偏低

• 不兼容新版 React/TS 现代语法

• 存在缓存与内核兼容双重问题

解决方案：

• 开发调试统一使用 Edge / Chrome 标准 Chromium 内核浏览器

• 配置：

  FRONTEND_LOGGING =False

  关闭前端埋点报错弹窗。

7.5 superset: command not found

原因：

• 未激活 Python 虚拟环境

• 系统无法识别项目局部命令

解决方案：

source .venv/bin/activate

八、关键命令与开发规范总结

8.1 环境操作命令

8.2 服务启动命令（固定规范）

8.3 开发调试核心规范

1. 所有源码编辑必须在 WSL 远程 VS Code 环境操作，禁止 Windows 本地修改

2. 前端改代码：保存自动编译，浏览器强制刷新生效

3. 后端改代码：自动重启生效；改配置文件：手动重启服务

4. 开发调试优先使用标准 Chrome / Edge 浏览器，规避定制内核兼容问题

九、学习总结与后续方向

本次学习完整打通了 Superset 最新开发版源码部署、前后端联动调试、报错排查、远程开发配置全流程。

彻底区分了：

• 生产版 pip 安装

• 开发版源码部署

熟练掌握：

• 新版源码目录重构后的开发规范

• 开发环境高频踩坑问题解决方案

后续可深入学习：

• 自定义图表插件开发

• 仪表盘组件二次封装

• 数据源对接改造

• 权限逻辑源码解析

• 前端工程化配置优化