跳到主内容

设置开发环境

本节文档是一系列知识的拼凑，代表了运行 Superset 的多种方式（docker compose、仅“docker”、在“裸机”上、使用 Makefile）。

注意

现在我们已经发展到更积极地推荐和支持 docker compose 作为运行 Superset 进行开发和保持理智的主要方式。 大多数人应该坚持阅读前几个部分——（“Fork & Clone”、“docker compose”和“安装开发工具”）

Fork 和 Clone​

首先，在 GitHub 上 Fork 仓库，然后克隆它。

其次，您可以直接克隆主仓库，但这样将无法发送拉取请求。

git clone git@github.com:your-username/superset.git
cd superset

将“hello world”挤进 Superset 任何部分的设置应该像这样简单：

# getting docker compose to fire up services, and rebuilding if some docker layers have changed
# using the `--build` suffix may be slower and optional if layers like py dependencies haven't changed
docker compose up --build

请注意

  • 这将拉取/构建 docker 镜像并运行一组服务，包括
    • 一个 Superset Flask Web 服务器，挂载本地 python 仓库/代码
    • 一个 Superset Celery worker，也挂载本地 python 仓库/代码
    • 一个 Superset Node 服务，挂载、编译和打包 JS/TS 资产
    • 一个 Superset Node websocket 服务，用于支持异步后端
    • Postgres 作为元数据数据库和存储示例数据集、图表和仪表板，这些应在启动时填充
    • Redis 作为我们异步后端的消息队列和缓存后端
  • 它会在首次启动时将示例加载到数据库中
  • compose.yml 中提供了所有其他详细信息和提示
  • 本地仓库被挂载在服务中，这意味着在主机上更新代码将反映在 docker 镜像中
  • Superset 服务地址为 localhost:9000/
  • 您可以使用 admin/admin 登录
注意

在 superset-node 中安装和构建 Apache Superset 的 Node 模块可能需要大量时间。由于依赖项的大小，这是正常的。请耐心等待过程完成，长时间等待并不表示您的设置有问题。如果延迟似乎过长，请检查您的互联网连接或系统资源。

注意

由于 docker compose 主要设计用于在单个主机上运行一组容器，因此无法可靠地支持高可用性，所以我们不支持也不推荐使用我们的 docker compose 结构来支持生产类型用例。对于单个主机环境，我们建议结合我们的 在 k8s 上安装 文档，使用配置为安全的 minikube。

支持的环境变量​

影响 Docker 构建过程

  • SUPERSET_BUILD_TARGET (默认=dev)： 要构建的 --target，lean 或 dev 是常用选项
  • INCLUDE_FIREFOX (默认=false)： 是否在构建中包含 Firefox 无头浏览器
  • INCLUDE_CHROMIUM (默认=false)： 是否在构建中包含 Firefox 无头浏览器
  • BUILD_TRANSLATIONS(默认=false)： 是否从可用的 .po 文件编译翻译
  • SUPERSET_LOAD_EXAMPLES (默认=yes)： 是否在启动时将示例加载到数据库中，通过 SUPERSET_LOAD_EXAMPLES=no docker compose up 可以节省宝贵的启动时间
  • SUPERSET_LOG_LEVEL (默认=info): 可以设置为 debug、info、warning、error、critical 以获取更详细的日志

有关影响您配置的更多环境变量，请参阅 superset_config.py，该文件在 docker compose 环境中用于将环境变量分配给 Superset 配置。

访问 Postgres 数据库​

有时直接访问 docker 容器中的数据库很有用。您可以通过运行以下命令进入 psql shell（官方 Postgres 客户端）

docker compose exec db psql -U superset

另请注意，数据库暴露在 5432 端口上，因此您可以使用您喜欢的 Postgres 客户端连接到它，甚至直接在 Superset 中通过创建新的数据库连接到 localhost:5432 来使用 SQL Lab。

清除 Postgres 数据库​

有时，您的开发数据库可能会陷入糟糕的状态，例如在切换包含迁移的分支时，alembic 管理的数据库版本戳在切换分支后可能不再可用。

在这种情况下，简单的解决方案是清除 postgres 数据库并重新开始。请注意，执行此操作后，数据库的完整状态将丢失，因此请谨慎。

# first stop docker-compose if it's running
docker-compose down
# delete the volume containing the database
docker volume rm superset_db_home
# restart docker-compose, which will init a fresh database and load examples
docker-compose up

安装开发工具​

注意

虽然 docker compose 简化了许多设置，但您仍然需要本地设置许多东西来支持您的 IDE，以及像 提交钩子、代码检查工具 和 测试运行器 这样的工具。请注意，您可以在 docker 镜像中通过诸如 docker compose exec superset_app bash 等命令来完成这些事情，但许多人喜欢从其主机运行这些工具。

Python 环境​

假设您已经有设置 Python 环境的方式，例如 pyenv、virtualenv 或其他工具，那么您只需在安装 操作系统依赖项 中提到的先决条件之后，安装我们的开发版、固定版本的 Python 依赖包。

pip install -r requirements/development.txt

Git Hooks​

Superset 使用 Git pre-commit 钩子，由 pre-commit 提供。要安装，请运行以下命令

pre-commit install

这将在您的本地仓库中安装钩子。从现在开始，每当您进行 Git 提交时，都会自动运行一系列检查。

手动运行 Pre-commit​

您还可以通过多种方式手动运行 pre-commit 检查

  • 在所有文件上运行 pre-commit（与 CI 相同）

    要在仓库中的所有文件上运行 pre-commit 检查，请使用以下命令

    pre-commit run --all-files

    这与在 CI 期间运行的检查集相同，确保您的更改符合项目的标准。

  • 在特定文件上运行 pre-commit

    如果您想检查或修复特定文件，可以通过指定文件路径来完成

    pre-commit run --files path/to/your/file.py

    这将只对您指定的文件运行检查。

  • 运行特定的 pre-commit 检查

    要在所有文件或特定文件上运行特定检查（hook），请使用以下命令

    pre-commit run <hook_id> --all-files

    或针对特定文件

    pre-commit run <hook_id> --files path/to/your/file.py

    将 <hook_id> 替换为您要运行的特定钩子的 ID。您可以在 .pre-commit-config.yaml 文件中找到可用钩子的列表。

docker compose 的替代方案​

注意

文档的这一部分是关于在不使用 docker compose 的情况下设置开发环境的信息拼凑，其文档和支持程度各不相同。维护如此广泛的方法并确保它们在各种环境中正常运行一直很困难。

Flask 服务器​

操作系统依赖​

在执行这些步骤之前，请确保您的机器满足操作系统依赖。您还需要安装 MySQL。

确保您使用的是 Python 3.9、3.10 或 3.11 版本，然后继续

# Create a virtual environment and activate it (recommended)
python3 -m venv venv # setup a python3 virtualenv
source venv/bin/activate

# Install external dependencies
pip install -r requirements/development.txt

# Install Superset in editable (development) mode
pip install -e .

# Initialize the database
superset db upgrade

# Create an admin user in your metadata database (use `admin` as username to be able to load the examples)
superset fab create-admin

# Create default roles and permissions
superset init

# Load some data to play with.
# Note: you MUST have previously created an admin user with the username `admin` for this command to work.
superset load-examples

# Start the Flask dev web server from inside your virtualenv.
# Note that your page may not have CSS at this point.
# See instructions below on how to build the front-end assets.
superset run -p 8088 --with-threads --reload --debugger --debug

或者您可以通过 Makefile 安装它

# Create a virtual environment and activate it (recommended)
$ python3 -m venv venv # setup a python3 virtualenv
$ source venv/bin/activate

# install pip packages + pre-commit
$ make install

# Install superset pip packages and setup env only
$ make superset

# Setup pre-commit only
$ make pre-commit

注意：FLASK_APP 环境变量通常不需要设置，因为它目前由 .flaskenv 控制；但是，如果需要，它应该设置为 superset.app:create_app()

如果您对 FAB 管理的模板进行了更改（这些模板的构建方式与较新的、React 驱动的前端资产不同），则需要不带 --with-threads 参数启动应用程序，如下所示：superset run -p 8088 --reload --debugger --debug

依赖​

如果添加了新要求或更新了现有要求（根据 setup.py 中的 install_requires 部分），则必须重新编译（冻结）Python 依赖项，以确保 CI、测试等的构建是确定性的。这可以通过以下方式实现：

python3 -m venv venv
source venv/bin/activate
python3 -m pip install -r requirements/development.txt
./scripts/uv-pip-compile.sh

当升级单个包的版本号时，您应该运行带有 -P 标志的 ./scripts/uv-pip-compile.sh

./scripts/uv-pip-compile.sh -P some-package-to-upgrade

要根据 setup.py 和 requirements/*.in 中定义的限制将所有依赖项更新到最新版本，请运行 ./scripts/uv-pip-compile.sh --upgrade

./scripts/uv-pip-compile.sh --upgrade

这应该定期进行，但建议对应用程序进行彻底的手动测试，以确保没有引入单元测试和集成测试未捕获的重大更改。

日志输出到浏览器控制台​

此功能仅在 Python 3 上可用。调试应用程序时，您可以使用 ConsoleLog 包将服务器日志直接发送到浏览器控制台。您需要通过在 config.py 或 superset_config.py 中添加以下内容来修改应用程序：

from console_log import ConsoleLog

def FLASK_APP_MUTATOR(app):
    app.wsgi_app = ConsoleLog(app.wsgi_app, app.logger)

然后确保使用正确的 worker 类型运行 WSGI 服务器

gunicorn "superset.app:create_app()" -k "geventwebsocket.gunicorn.workers.GeventWebSocketWorker" -b 127.0.0.1:8088 --reload

您可以将任何内容记录到浏览器控制台，包括对象

from superset import app
app.logger.error('An exception occurred!')
app.logger.info(form_data)

前端​

前端资产（TypeScript、JavaScript、CSS 和图像）必须经过编译才能正确显示 Web UI。superset-frontend 目录包含所有 NPM 管理的前端资产。请注意，对于某些旧版页面，还有一些额外的、与 Flask-Appbuilder 捆绑在一起的前端资产（例如 jQuery 和 bootstrap）。这些资产不由 NPM 管理，未来可能会被逐步淘汰。

先决条件​

nvm 和 node​

首先，请确保您正在使用以下版本的 Node.js 和 npm

  • Node.js：版本 20
  • npm：版本 10

我们推荐使用 nvm 来管理您的 Node 环境

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.0/install.sh | bash

in case it shows '-bash: nvm: command not found'
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

cd superset-frontend
nvm install --lts
nvm use --lts

或者如果你使用 macOS Catalina shell zsh，尝试

sh -c "$(curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.0/install.sh)"

对于感兴趣的人，您也可以尝试 avn 来自动切换到运行 Superset 前端所需的 Node 版本。

安装依赖​

通过以下命令安装 package.json 中列出的第三方依赖项：

# From the root of the repository
cd superset-frontend

# Install dependencies from `package-lock.json`
npm ci

请注意，Superset 使用 Scarf 来捕获有关已安装版本的遥测/分析数据，包括 scarf-js npm 包和一个分析像素。正如本文档其他地方所述，Scarf 收集聚合统计数据以用于安全/发布策略，并且不捕获/保留个人身份信息 (PII)。 您可以在此处阅读 有关 scarf-js 包及其各种选择退出方式的信息，但您可以通过将 SCARF_ANALYTICS 环境变量设置为 false 来选择退出 npm 包*和*像素，或者通过在 superset-frontend/package.json 中添加此设置来选择退出像素。

// your-package/package.json
{
  // ...
  "scarfSettings": {
    "enabled": false
  }
  // ...
}

构建资产​

您可以构建三种类型的资产

  1. npm run build：生产资产，CSS/JSS 经过缩小和优化
  2. npm run dev-server：本地开发资产，支持 sourcemap 和热刷新
  3. npm run build-instrumented：用于从 Cypress 测试中收集代码覆盖率的插桩应用程序代码

如果在运行上述命令时遇到与文件监视器限制相关的错误

Error: ENOSPC: System limit for number of file watchers reached

此错误是因为系统监控的文件数量已达到限制。您可以通过增加 inotify 监视器的数量来解决此错误。

最大监视数当前值可以通过以下命令检查：

cat /proc/sys/fs/inotify/max_user_watches

编辑文件 /etc/sysctl.conf 以增加此值。该值需要根据系统内存来决定 （有关更多上下文，请参阅此 StackOverflow 答案）。

用编辑器打开文件，并在底部添加一行，指定最大监视值。

fs.inotify.max_user_watches=524288

保存文件并退出编辑器。要确认更改成功，请运行以下命令从 sysctl.conf 加载更新后的 max_user_watches 值

sudo sysctl -p

Webpack 开发服务器​

开发服务器默认在 http://localhost:9000 启动，并将后端请求代理到 http://localhost:8088。

所以典型的开发工作流程如下：

  1. 在本地使用 Flask 运行 Superset，端口为 8088 — 但不要直接访问它，

    # Install Superset and dependencies, plus load your virtual environment first, as detailed above.
    superset run -p 8088 --with-threads --reload --debugger --debug

  2. 同时，在本地端口 9000 运行 Webpack 开发服务器，

    npm run dev-server

  3. 在您的网络浏览器中访问 http://localhost:9000（Webpack 服务器，不是 Flask）。这将使用来自 Webpack 开发服务器的热重载前端资产，同时将后端查询重定向到 Flask/Superset：您对 Superset 代码库（无论是前端还是后端）的更改将在浏览器中实时反映。

可以更改 Webpack 服务器设置

# Start the dev server at http://localhost:9000
npm run dev-server

# Run the dev server on a non-default port
npm run dev-server -- --port=9001

# Proxy backend requests to a Flask server running on a non-default port
npm run dev-server -- --env=--supersetPort=8081

# Proxy to a remote backend but serve local assets
npm run dev-server -- --env=--superset=https://superset-dev.example.com

--superset= 选项在您想要调试生产问题或必须在防火墙后设置 Superset 的情况下很有用。它允许您在其他环境中运行 Flask 服务器，同时在本地构建资产以获得最佳开发人员体验。

其他 npm 命令​

此外，您可能会发现其他 NPM 命令很有用

  1. npm run build-dev：在开发模式下构建资产。
  2. npm run dev：在监视模式下构建开发资产，文件更改时将自动重建

Docker (docker compose)​

请参阅此处的文档

更新 NPM 包​

按照规定的方式使用 npm，确保 superset-frontend/package-lock.json 已根据 npm 规定的最佳实践进行更新。

功能标志​

Superset 支持全服务器范围的功能标志系统，这简化了功能的增量开发。要添加新的功能标志，只需像下面这样修改 superset_config.py

FEATURE_FLAGS = {
    'SCOPED_FILTER': True,
}

如果您想在客户端代码中使用相同的标志，也请将其添加到 @superset-ui/core 中的 FeatureFlag TypeScript 枚举中。例如，

export enum FeatureFlag {
  SCOPED_FILTER = "SCOPED_FILTER",
}

superset/config.py 包含 DEFAULT_FEATURE_FLAGS，它将被 superset_config.py 中 FEATURE_FLAGS 指定的值覆盖。例如，superset/config.py 中的 DEFAULT_FEATURE_FLAGS = { 'FOO': True, 'BAR': False } 和 superset_config.py 中的 FEATURE_FLAGS = { 'BAR': True, 'BAZ': True } 将导致组合后的功能标志为 { 'FOO': True, 'BAR': True, 'BAZ': True }。

每个标志的可用性当前状态（稳定版 vs 测试版等）可在 RESOURCES/FEATURE_FLAGS.md 中找到。

Git Hooks​

Superset 使用 Git pre-commit 钩子，由 pre-commit 提供。要安装，请运行以下命令

pip3 install -r requirements/development.txt
pre-commit install

现在，当您进行 git 提交时，将运行一系列检查。

代码检查​

请参阅操作指南

GitHub Actions 和 act​

提示

Superset 的 GHA 对 act 的兼容性尚未完全测试。在本地运行 act 可能对不同的操作有效，也可能无效，并且可能需要微调和本地秘密处理。对于那些在本地难以运行的更复杂的 GHA，我们建议直接在 GHA 的基础设施上迭代，通过直接推送到分支并监控 GHA 日志。对于更有针对性的迭代，请参阅 GitHub CLI 的 gh workflow run --ref {BRANCH} 子命令。

为了自动化和 CI/CD，Superset 广泛使用了 GitHub Actions (GHA)。您可以在 .github/ 文件夹下找到所有工作流和其他资产。这包括

  • 运行后端单元测试套件（tests/）
  • 运行前端测试套件（superset-frontend/src/**.*.test.*）
  • 运行我们的 Cypress 端到端测试（superset-frontend/cypress-base/）
  • 代码库的 linting，包括所有 Python、Typescript 和 Javascript、yaml 等
  • 检查各种其他规则约定

当您打开拉取请求 (PR) 时，相应的 GitHub Actions (GHA) 工作流将根据您分支中的更改自动运行。依赖这种自动化是完全合理（并且必需！）的。然而，缺点是它大多是“全有或全无”的方法，并且没有提供太多控制来定位特定测试或快速迭代。

有时，在本地运行 GHA 工作流可能更方便。为此，我们使用 act，一个允许您在本地运行 GitHub Actions (GHA) 工作流的工具。它模拟 GitHub Actions 环境，使开发人员能够在将更改推送到仓库之前在本地机器上测试和调试工作流。

注意

在 GHA 和 act 中，我们可以为测试运行更复杂的矩阵，针对不同的数据库引擎（PostgreSQL、MySQL、SQLite）和不同版本的 Python 执行。这使我们能够确保在各种环境中的兼容性和稳定性。

使用 act​

首先，安装 act -> https://nektosact.com/

要列出工作流，只需

act --list

要运行特定的工作流

act pull_request --job {workflow_name} --secret GITHUB_TOKEN=$GITHUB_TOKEN --container-architecture linux/amd64

在上面的示例中，请注意

  • 我们使用 --job 指定一个特定的工作流
  • 我们使用 --secret 传递一个秘密，因为许多作业需要对仓库的读取权限（公共）
  • 我们通过将其作为第一个参数来模拟 pull_request 事件，类似地，我们可以模拟 push 事件或其他事件
  • 我们指定 --container-architecture，这通常能更可靠地模拟 GHA
注意

act 是一个功能丰富的工具，提供了各种特性，允许您模拟不同的事件（pull_request、push等），传递所需秘密的语义等等。更多信息，请参阅 act 的文档

注意

某些作业需要秘密才能与您可能没有的外部系统和帐户进行交互。在这些情况下，您可能需要依赖远程 CI 或进一步参数化作业以针对不同的环境/沙盒或您自己的环境以及相关的秘密。

测试​

Python 测试​

单元测试​

对于位于 tests/unit_tests/ 的单元测试，通常很容易直接在本地运行脚本，使用

pytest tests/unit_tests/*

集成测试​

对于更复杂的 pytest 定义的集成测试（不要与我们的端到端 Cypress 测试混淆），许多测试将需要一个正常工作的测试环境。有些测试需要数据库、Celery 以及可能安装的其他服务或库。

使用 act 运行测试​

要在本地使用 act 运行集成测试，请确保您已遵循 GitHub Actions 和 act 部分的设置说明。您可以运行包含集成测试的特定工作流或作业。例如

act --job test-python-38 --secret GITHUB_TOKEN=$GITHUB_TOKEN --event pull_request --container-architecture linux/amd64

使用测试脚本在本地运行​

Superset 代码库中还包含一个实用脚本，用于运行 Python 集成测试。 README 可在此处找到。

Superset 代码库中还包含一个实用脚本，用于运行 Python 集成测试。 README 可在此处找到

例如，要运行所有集成测试，请从根目录运行此脚本

scripts/tests/run.sh

您可以使用 pytest 运行 ./tests/unit_tests 中的单元测试。这是一种运行不需要任何数据库设置的独立测试的简单方法

pytest ./link_to_test.py

前端测试​

我们使用 Jest 和 Enzyme 来测试 TypeScript/JavaScript。测试可以通过以下方式运行

cd superset-frontend
npm run test

要运行单个测试文件

npm run test -- path/to/file.js

调试服务器应用程序​

本地​

要使用 VSCode 进行本地调试，您可以配置一个 .vscode/launch.json 启动配置文件，例如

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Flask",
      "type": "python",
      "request": "launch",
      "module": "flask",
      "env": {
        "FLASK_APP": "superset",
        "SUPERSET_ENV": "development"
      },
      "args": ["run", "-p 8088", "--with-threads", "--reload", "--debugger"],
      "jinja": true,
      "justMyCode": true
    }
  ]
}

原生 Docker (不使用 docker compose)​

按照这些说明调试在 Docker 容器中运行的 Flask 应用程序。请注意，这将运行一个裸机 Superset Web 服务器，

首先，将以下内容添加到 ./docker-compose.yaml 文件中

superset:
    env_file: docker/.env
    image: *superset-image
    container_name: superset_app
    command: ["/app/docker/docker-bootstrap.sh", "app"]
    restart: unless-stopped
+   cap_add:
+     - SYS_PTRACE
    ports:
      - 8088:8088
+     - 5678:5678
    user: "root"
    depends_on: *superset-depends-on
    volumes: *superset-volumes
    environment:
      CYPRESS_CONFIG: "${CYPRESS_CONFIG}"

像往常一样启动 Superset

docker compose up --build

将所需的库和包安装到 docker 容器中

进入 superset_app 容器

docker exec -it superset_app /bin/bash
root@39ce8cf9d6ab:/app#

在容器内部运行以下命令

apt update
apt install -y gdb
apt install -y net-tools
pip install debugpy

找到 Flask 进程的 PID。请务必使用第一个 PID。每次更改任何 python 代码时，Flask 应用都会重新生成一个子进程。因此，使用第一个 PID 很重要。

ps -ef

UID        PID  PPID  C STIME TTY          TIME CMD
root         1     0  0 14:09 ?        00:00:00 bash /app/docker/docker-bootstrap.sh app
root         6     1  4 14:09 ?        00:00:04 /usr/local/bin/python /usr/bin/flask run -p 8088 --with-threads --reload --debugger --host=0.0.0.0
root        10     6  7 14:09 ?        00:00:07 /usr/local/bin/python /usr/bin/flask run -p 8088 --with-threads --reload --debugger --host=0.0.0.0

将 debugpy 注入到正在运行的 Flask 进程中。在本例中为 PID 6。

python3 -m debugpy --listen 0.0.0.0:5678 --pid 6

验证 debugpy 是否正在侦听 5678 端口

netstat -tunap

Active Internet connections (servers and established)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name
tcp        0      0 0.0.0.0:5678            0.0.0.0:*               LISTEN      462/python
tcp        0      0 0.0.0.0:8088            0.0.0.0:*               LISTEN      6/python

现在您已准备好将调试器附加到进程。使用 VSCode，您可以配置一个 .vscode/launch.json 启动配置文件，如下所示。

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to Superset App in Docker Container",
      "type": "python",
      "request": "attach",
      "connect": {
        "host": "127.0.0.1",
        "port": 5678
      },
      "pathMappings": [
        {
          "localRoot": "${workspaceFolder}",
          "remoteRoot": "/app"
        }
      ]
    }
  ]
}

VSCode 不会立即在断点处停止。我们已附加到 PID 6，但它尚不知道任何子进程。为了“唤醒”调试器，您需要修改一个 Python 文件。这将触发 Flask 重新加载代码并创建一个新的子进程。这个新的子进程将被 VSCode 检测到，并且断点将被激活。

在 Kubernetes 环境中调试服务器应用​

要在 Kubernetes 集群中的 POD 内调试 Flask，您需要确保 POD 以 root 身份运行并被授予 SYS_TRACE 功能。这些设置不应用于生产环境。

  securityContext:
    capabilities:
      add: ["SYS_PTRACE"]

有关更多详细信息，请参阅 为容器设置功能。

一旦 Pod 以 root 身份运行并具有 SYS_PTRACE 功能，它将能够调试 Flask 应用程序。

您可以遵循与 docker compose 中相同的说明。进入 Pod 并安装所需的库和软件包；gdb、netstat 和 debugpy。

通常在 Kubernetes 环境中，节点无法从集群外部寻址。因此，VSCode 将无法远程连接到 Kubernetes 节点上的 5678 端口。为此，您需要创建一个隧道，将 5678 端口转发到您的本地机器。

kubectl port-forward  pod/superset-<some random id> 5678:5678

现在，您可以使用与上述相同的配置启动 VSCode 调试器。VSCode 将连接到 127.0.0.1:5678，该地址由 kubectl 转发到您的远程 kubernetes POD。

Storybook​

Superset 包含一个 Storybook，用于预览各种 Superset 组件及其变体的布局/样式。要打开和查看 Storybook，请执行以下操作：

cd superset-frontend
npm run storybook

向 Superset 贡献新的 React 组件时，请尝试在组件的 jsx/tsx 文件旁边添加一个 Story。

提示​

添加新的数据源​

  1. 为数据源创建模型和视图，将它们添加到 Superset 文件夹下，例如一个新的 my_models.py，包含集群、数据源、列和指标的模型，以及一个 my_views.py，包含 clustermodelview 和 datasourcemodelview。

  2. 为新模型创建数据库迁移文件

  3. 在 config.py 中指定此变量以添加数据源模型及其来源模块

    例如

    ADDITIONAL_MODULE_DS_MAP = {'superset.my_models': ['MyDatasource', 'MyOtherDatasource']}

    这意味着它将在源注册表中注册 superset.my_models 模块中的 MyDatasource 和 MyOtherDatasource。

可视化插件​

关于编写新插件的主题，无论您是否愿意将其贡献回社区，都已在文档中以及这篇博客文章中得到了充分记录。

要将插件贡献给 Superset，您的插件必须满足以下标准：

  • 该插件应适用于整个社区，而非特别专业化的用例
  • 插件应使用 TypeScript 编写
  • 插件应包含足够的单元/端到端测试
  • 插件应使用适当的命名空间，例如文件夹名为 plugin-chart-whatever，包名为 @superset-ui/plugin-chart-whatever
  • 插件应通过 Emotion 使用主题变量，并由 ThemeProvider 传入
  • 插件应提供足够的错误处理（未返回数据、数据格式错误、控件无效等）
  • 插件应以填充完整的 README.md 文件形式包含文档
  • 插件应具有有意义且独特的图标
  • 最重要的是，插件应附带原作者对维护的承诺

提交的插件将根据具体情况考虑接受（或移除）。

添加数据库迁移​

  1. 修改您想要更改的模型。此示例将添加一个 Column Annotations 模型。

    提交示例

  2. 生成迁移文件

    superset db migrate -m 'add_metadata_column_to_annotation_model'

    这将在 migrations/version/{SHA}_this_will_be_in_the_migration_filename.py 中生成一个文件。

    提交示例

  3. 升级数据库

    superset db upgrade

    输出应如下所示：

    INFO  [alembic.runtime.migration] Context impl SQLiteImpl.
    INFO  [alembic.runtime.migration] Will assume transactional DDL.
    INFO  [alembic.runtime.migration] Running upgrade 1a1d627ebd8e -> 40a0a483dd12, add_metadata_column_to_annotation_model.py

  4. 将列添加到视图

    由于新增了一列，我们需要将其添加到 AppBuilder 模型视图中。

    提交示例

  5. 测试迁移的 down 方法

    superset db downgrade

    输出应如下所示：

    INFO  [alembic.runtime.migration] Context impl SQLiteImpl.
    INFO  [alembic.runtime.migration] Will assume transactional DDL.
    INFO  [alembic.runtime.migration] Running downgrade 40a0a483dd12 -> 1a1d627ebd8e, add_metadata_column_to_annotation_model.py

合并数据库迁移​

当两个数据库迁移发生冲突时，您会收到类似以下错误消息：

alembic.util.exc.CommandError: Multiple head revisions are present for
given argument 'head'; please specify a specific target
revision, '<branchname>@head' to narrow to a specific head,
or 'heads' for all heads`

要解决它

  1. 获取迁移头

    superset db heads

    这应该列出两个或更多迁移哈希。例如：

    1412ec1e5a7b (head)
    67da9ef1ef9c (head)

  2. 选择其中一个作为父修订，打开另一个修订的脚本，并将 Revises 和 down_revision 更新为新的父修订。例如：

    --- a/67da9ef1ef9c_add_hide_left_bar_to_tabstate.py
    +++ b/67da9ef1ef9c_add_hide_left_bar_to_tabstate.py
    @@ -17,14 +17,14 @@
    """add hide_left_bar to tabstate

    Revision ID: 67da9ef1ef9c
    -Revises: c501b7c653a3
    +Revises: 1412ec1e5a7b
    Create Date: 2021-02-22 11:22:10.156942

    """

    # revision identifiers, used by Alembic.
    revision = "67da9ef1ef9c"
    -down_revision = "c501b7c653a3"
    +down_revision = "1412ec1e5a7b"

    import sqlalchemy as sa
    from alembic import op

    或者，您也可以运行 superset db merge 来创建专门用于合并头的迁移脚本。

    superset db merge {HASH1} {HASH2}

  3. 将数据库升级到新的检查点

    superset db upgrade