开源的现代数据探索和可视化平台：Apache Superset 使用 Docker Compose

文中内容仅限技术学习与代码实践参考，市场存在不确定性，技术分析需谨慎验证，不构成任何投资建议。

Apache Superset™ 是一个开源的现代数据探索和可视化平台。对于许多团队来说，Superset 可以取代或增强专有的商业智能工具。Superset 可以与各种数据源很好地集成。

使用 Docker Compose

由于 docker compose 主要设计用于在单台主机上运行一组容器，无法支持高可用需求，因此我们不支持也不推荐使用我们的 docker compose 构建来支撑生产级用例。对于单主机环境，建议结合 minikube 和我们的 在 k8s 上安装 文档。

如我们的快速入门指南中所述，在 Linux 或 Mac OSX 电脑上使用 Docker Compose 是在本地试用 Superset 最快的方式。Superset 官方不支持 Windows。这也是快速启动完整开发环境的最简单方式。

请注意，我们支持以 4 种主要方式运行 docker compose：

1. docker-compose.yml： 用于交互式开发，在此模式下我们会挂载本地文件夹，其中包含前端/后端文件，你可实时编辑并体验在应用中所做的更改
2. docker-compose-light.yml： 轻量级配置，仅包含最少量服务（数据库、Superset 应用和前端开发服务器），开发时使用。采用内存缓存而非 Redis，并设计为可同时运行多个实例
3. docker-compose-non-dev.yml 仅基于本地分支构建更不可变的镜像，并启动所有所需镜像。启动时本地分支的更改会体现，但在 up 期间对代码的更改不会反映到应用中
4. docker-compose-image-tag.yml 从 docker-hub 拉取镜像（例如 5.0.0 版本）并启动，以便体验。此时本地分支内容对运行中的内容无影响，我们只是拉取并运行 docker-hub 上的预构建镜像。为使 docker compose 能与随之启动的 Postgres 镜像协同工作，你需要指向一个带 -dev 后缀的 TAG，例如 export TAG=5.0.0-dev 或 export TAG=4.1.2-dev，默认使用 latest-dev。dev 构建包含连接 Postgres 数据库所需的 psycopg2-binary，该数据库作为 docker compose 构建的一部分启动。

在设置完上述任一方式所需的依赖后，下文将详细介绍这些方法。

要求

请注意，本文档假设你已安装 Docker 和 git。另请注意，我们过去使用 docker-compose，但该工具已处于弃用路径，因此我们现使用 docker compose。

1. 克隆 Superset 的 GitHub 仓库

在终端中使用以下命令克隆 Superset 仓库：

git clone --depth=1  https://github.com/apache/superset.git

命令成功完成后，你应在当前目录看到一个新文件夹 superset。

2. 通过 Docker Compose 启动 Superset

首先假设你熟悉 docker compose 机制。此处我们泛指 docker compose up，尽管在某些情况下你可能希望使用 docker compose pull 强制检查远程镜像更新、使用 docker compose build 强制构建，或使用 docker compose build --pull 强制基于最新基础镜像构建。不过大多数情况下，简单的 up 命令即可。有关此主题的更多信息，请参阅 docker compose 文档。

选项 #1 - 交互式开发环境

# --build 参数确保所有层均为最新
docker compose up --build

在开发模式下运行时，superset-node 容器需完成资源构建，UI 才能正确渲染。如果你只是试用 Superset 而不做任何代码更改，请按照下文“生产”或特定版本的步骤操作。

默认情况下，我们在此处挂载本地 superset-frontend 文件夹，并运行 npm install 以及 npm run dev，后者会触发 webpack 编译/打包前端代码。根据本地配置，特别是内存不足 16GB 时，这些操作可能非常缓慢。此时建议将环境变量 BUILD_SUPERSET_FRONTEND_IN_DOCKER 设为 false，并在本地终端中运行。只需触发 npm i && npm run dev，速度会快很多。

有时 npm 相关状态可能混乱，从 superset-frontend/ 文件夹运行 npm run prune 会删除各包下的 node_module/ 文件夹，帮助你重新开始。在 docker compose 上下文中，运行 docker compose up 前设置 export NPM_RUN_PRUNE=true 会在容器内触发该操作。这会减慢启动速度，但会修复各种 npm 相关问题。

选项 #2 - 轻量级开发，支持多实例

如需资源占用更少、支持多实例的轻量开发设置：

# 单个轻量实例（默认端口 9001）
docker compose -f docker-compose-light.yml up

# 不同端口的多个实例
NODE_PORT=9001 docker compose -p superset-1 -f docker-compose-light.yml up
NODE_PORT=9002 docker compose -p superset-2 -f docker-compose-light.yml up
NODE_PORT=9003 docker compose -p superset-3 -f docker-compose-light.yml up

此配置包含：

• PostgreSQL 数据库（仅限内部网络）
• Superset 应用服务器
• 带 webpack 热重载的前端开发服务器
• 内存缓存（无 Redis）
• 每个实例隔离的卷和网络

在 http://localhost:{NODE_PORT} 访问各实例（例如 http://localhost:9001）。

选项 #3 - 基于本地分支构建一组不可变镜像

docker compose -f docker-compose-non-dev.yml up

选项 #4 - 启动官方发布版本

# 设置要运行的版本
export TAG=5.0.0
# 获取你即将检出的标签（假设你做了浅克隆）
git fetch --depth=1 origin tag $TAG
# 若有带宽，也可获取所有标签
# git fetch --tags
# 检出对应 git 引用
git checkout $TAG
# 启动 docker compose
docker compose -f docker-compose-image-tag.yml up

此处可通过 TAG 环境变量引用各发布标签、github SHA 及最新 master。有关可从 Docker Hub 指向的现有标签的更多信息，请参阅 docker 相关文档。

对于选项 #2 和 #3，我们建议从 git 仓库检出发布标签（例如：git checkout 5.0.0）以获得更可靠的结果。这可确保 docker-compose.*.yml 配置及挂载的 docker/ 脚本与你希望启动的镜像同步。

docker compose 技巧与配置

Superset 实例的所有内容（图表、仪表盘、用户等）都存储在其元数据数据库中。生产环境中，应备份此数据库。使用 docker compose 的默认安装会将该数据存储在 Docker 卷 中的 PostgreSQL 数据库内，该卷未被备份。

再次强调，DOCKER-COMPOSE 安装默认并非生产就绪。

你应该会看到启动容器的日志输出流。输出变慢后，你将在本地拥有一套运行的 Superset 实例！为避免后续运行出现大量文本，可在 docker compose up 命令末尾添加 -d 选项。

进一步配置

以下内容面向希望配置 Docker Compose 中 Superset 运行方式的用户；否则可跳至下一节。

你可按照 docker/README.md 中的步骤安装额外 Python 包并应用配置覆盖。

请注意，docker/.env 为 docker compose 使用的所有 docker 镜像设置默认环境变量，docker/.env-local 可用于覆盖这些默认值。另请注意，docker/.env-local 已在我们 .gitignore 中引用，防止开发者将可能敏感的配置意外提交到仓库。

一个重要变量是 SUPERSET_LOAD_EXAMPLES，它决定 superset_init 容器是否将示例数据和可视化填充到元数据数据库。这些示例有助于学习和试用 Superset，但对有经验的用户和生产部署并非必需。加载过程有时需几分钟且占用较多 CPU，因此在资源受限设备上你可能希望禁用它。

对于通常在 PYTHONPATH 中的 superset_config.py 文件管理的更高级或动态配置，可通过提供 docker/pythonpath_dev/superset_config_docker.py 实现，该文件会被 git 忽略（防止你将本地配置提交/推送到仓库）。其机制在 docker/pythonpath_dev/superset_config.py 中，你可看到逻辑执行 from superset_config_docker import *

用户常希望从 Superset 连接其他数据库。目前最简单的方法是修改 docker-compose-non-dev.yml 文件，将你的数据库添加为其他服务依赖的服务（通过 x-superset-depends-on）。也有人尝试在 Superset 服务上设置 network_mode: host，但这通常会破坏安装，因为配置需要使用 Docker Compose DNS 解析器来解析服务名。如果你有好的解决方案，请告诉我们！

Superset 使用 Scarf Gateway 收集遥测数据。了解不同 Superset 版本的安装数量可帮助项目决策修补和长期支持。Scarf 会清除个人身份信息（PII），仅提供聚合统计。

要让你的基于 docker compose 的安装通过 Scarf Gateway 下载的包选择退出此数据收集，请编辑 docker-compose.yml 和 docker-compose-non-dev.yml 文件中的 x-superset-image: 行，将 apachesuperset.docker.scarf.sh/apache/superset 替换为 apache/superset，以便直接从 Docker Hub 拉取镜像。

要禁用 Scarf 遥测像素，请在终端和/或 docker/.env 文件中将 SCARF_ANALYTICS 环境变量设为 False。

3. 登录 Superset

你的本地 Superset 实例还包含一个 Postgres 服务器来存储数据，并已预加载 Superset 自带的一些示例数据集。你现在可通过 web 浏览器访问 Superset，地址为 http://localhost:8088。请注意，许多浏览器现在默认使用 https - 如果你的浏览器是其中之一，请确保使用 http。

使用默认用户名和密码登录：

username: admin

password: admin

4. 将 Superset 连接到你的本地数据库实例

使用 docker 或 docker compose 运行 Superset 时，它运行在自己的 docker 容器中，就好像 Superset 运行在完全独立的机器上。因此，尝试使用主机名 localhost 连接本地数据库将无法工作，因为 localhost 指的是 Superset 所在的 docker 容器，而非你的实际主机。幸运的是，docker 提供了一种简单方法，让容器内访问主机网络资源，我们将利用此功能连接到本地数据库实例。

此处说明用于从 Superset（运行在 docker 容器内）连接到 postgresql（运行在你的主机上）。其他数据库的配置可能略有不同，但核心相同，归结为 2 步：

1. （Mac 用户可跳过此步骤） 配置本地 postgresql/数据库实例以接受公共传入连接。默认情况下，postgresql 仅允许来自 localhost 的传入连接，在 Docker 下，除非使用 --network=host，localhost 在主机和 docker 容器中指向不同端点。允许 postgresql 接受来自 Docker 的连接，需在 postgresql.conf 和 pg_hba.conf 文件中各做一行更改；你可在网上轻松找到针对你的操作系统/PG 版本的有用链接。对于 Docker，只需将 IP 172.0.0.0/8 加入白名单即可，而非 *，但无论如何，警告在生产数据库上执行此操作可能带来灾难性后果，因为你正在向公共互联网开放数据库。
2. 连接数据库时，请使用 host.docker.internal（Mac 用户、Ubuntu）或 172.18.0.1（Linux 用户）而非 localhost 作为主机名。这是 Docker 内部细节——在 Mac 系统上，Docker Desktop 会为 host.docker.internal 主机名创建 dns 条目，解析到主机的正确地址；而在 Linux 上则不然（至少默认情况下）。如果这两个主机名均无效，你可能需要找到要使用的确切主机名，为此可执行 ifconfig 或 ip addr show 并查看 Docker 为你创建的 docker0 接口的 IP 地址。或者，如果你甚至看不到 docker0 接口，可尝试（必要时使用 sudo）docker network inspect bridge 并查看是否有 "Gateway" 条目，记下 IP 地址。

4. 构建与否

运行 docker compose up 时，docker 会在后台按需构建，但如果资产已存在，可能会使用 docker 缓存。在 docker compose up 前运行 docker compose build 或使用等效快捷方式 docker compose up --build 可确保你的 docker 镜像与仓库中的定义匹配。这应仅适用于主要的 docker-compose.yml 文件（默认），而不适用于上文定义的其他方法。

升级 Superset

Docker Compose

首先，务必关闭正在运行的 Docker Compose 容器：

docker compose down

接着，通过 git 更新与 superset 仓库同步的文件夹：

git pull origin master

然后，重新启动容器，任何已变更的 Docker 镜像将自动拉取：

docker compose up

手动更新 Superset

要在原生安装中升级 Superset，请运行以下命令：

pip install apache_superset --upgrade

升级元数据数据库

通过运行以下命令迁移元数据数据库：

superset db upgrade
superset init

升级 Superset 不应删除您的图表和仪表板，但我们建议遵循最佳实践，并在升级前备份元数据数据库。在升级生产环境之前，我们建议在测试环境中先进行升级，并最终在非高峰时段完成生产环境的升级。

风险提示与免责声明
本文内容基于公开信息研究整理，不构成任何形式的投资建议。历史表现不应作为未来收益保证，市场存在不可预见的波动风险。投资者需结合自身财务状况及风险承受能力独立决策，并自行承担交易结果。作者及发布方不对任何依据本文操作导致的损失承担法律责任。市场有风险，投资须谨慎。