简介对于需要在无互联网环境快速落地数据可视化平台的企业运维与数据分析人员Superset 4.1.1中文版Docker离线部署包提供了完整解决方案。压缩包共6个文件约524.2MB内含3个Docker镜像tar包Redis、PostgreSQL及Superset中文版以及分别用于服务编排、环境变量注入、数据库连接与安全配置的YAML、ENV与Python配置文件可支撑离线环境下的一次性容器编排。已有364人学习下载适合想借助Docker实现可移植、可重复部署Superset的团队。借助该包用户无需从公网拉取镜像即可完成容器启动中文界面显著降低非英文用户的使用门槛同时部署前核对这些配置项、定期关注Superset和容器安全更新可确保长期稳定运行。1. Superset 4.1.1 离线部署为什么你必须先搞定镜像方案Apache Superset 作为目前使用率最高的开源 BI 工具4.1.1 版本在图表渲染性能、缓存策略和数据源连接器上都做了不少优化。但你真正要面对的问题通常不是 Superset 本身而是「怎么在内网环境里把 Docker 镜像弄进去」。很多团队在离线部署 Superset 4.1.1 时翻车翻的不是 Superset 的配置文件而是 Docker 镜像下载慢、镜像依赖层级不清晰、宿主机架构不匹配这类「看似无关」的环节。这篇笔记面向的是需要在内网、生产环境或安全隔离区里把 Superset 4.1.1 跑起来的运维和开发。整体思路是先用一台能联网的机器把镜像准备好再打包传输到离线宿主机最后通过 docker-compose 把服务拉起来。整个过程我踩过不少坑特别是 4.1.1 版本相比旧版在初始化数据库和静态资源处理上有变化如果不注意启动后大概率会卡在「Superset 一直 500」或者「登录页样式全丢」这两个问题上。2. 离线部署前的镜像准备从 Docker Hub 拉取到 tar 打包2.1 先用 docker pull 锁定 Superset 4.1.1 的镜像版本在联网机器上我一般建议不要直接拉apache/superset:latest而是指定4.1.1这个明确版本。Superset 官方镜像的更新节奏较快latest 标签可能在某个时间点变成了 4.1.2 或者 4.2.0这样你离线环境里跑的和你测试环境里跑的就不是同一个东西。在联网机器上执行以下命令docker pull apache/superset:4.1.1拉取完成后用docker images确认镜像已经存在于本地。这里需要记住镜像的 IMAGE ID因为后面打包时用 IMAGE ID 比用repository:tag更保险不会因为标签覆盖导致导出错版本。2.2 导出镜像并检查依赖为什么不能只看一个镜像文件Superset 4.1.1 的官方镜像基于python:3.11-slim构建但如果你只执行docker save apache/superset:4.1.1导出的 tar 包里通常只包含 Superset 这一个层。这样看起来没什么问题但当你把它导入到离线主机后如果宿主机本地没有python:3.11-slim的底层层Docker 会在运行时尝试从网络拉取缺失的层——而这在离线环境里直接失败。我建议的做法是先把镜像跑起来然后查看它的实际依赖docker run --rm -d --name superset_check apache/superset:4.1.1 sleep 300 docker inspect superset_check --format{{.Image}} docker history apache/superset:4.1.1 --no-truncdocker history能看到每一层的构建记录但你要关注的不是构建内容而是运行依赖。更稳妥的方式是直接用docker image inspect查看 RootFS 的层数然后把所有底层镜像也一起保存。一个实际的打包命令组合docker save apache/superset:4.1.1 python:3.11-slim -o superset_offline.tar注意这里把python:3.11-slim也一起打包了。如果你不能确定 Superset 4.1.1 是基于哪个 Python 版本构建的可以先执行docker inspect apache/superset:4.1.1 | grep -i python看环境变量里的PYTHON_VERSION。2.3 内网传输与导入用 md5 校验文件完整性离线环境里通过 U 盘或者内网 FTP 传输 tar 包最怕的是文件传输了一半而你毫不知情。我遇到过一次导入后启动报错排查了半天发现是 tar 包损坏重新传输才解决。导入前做一次 md5 校验md5sum superset_offline.tar在联网机器上打包完成后记录这个 md5 值传输到离线主机后再次计算两值一致再执行导入docker load -i superset_offline.tar加载成功后会输出Loaded image: apache/superset:4.1.1和Loaded image: python:3.11-slim两行信息确认都出现后再继续。如果只出现了一行说明底层镜像没打进去需要回到联网机器重新执行docker save。3. 用 docker-compose 跑通 Superset 4.1.1 中文版配置文件与初始化流程拆解3.1 先解决中文问题4.1.1 的语言配置方式和历史坑4.1.1 版本在语言设置上与旧版有差异。旧版本可以直接通过环境变量LANGzh_CN.UTF-8或者修改 config.py 里的BABEL_DEFAULT_LOCALE来切换界面语言但 4.1.1 版本需要同时确保系统有中文字体和中文本地化翻译文件。在离线环境里最容易翻车的是缺字体。Superset 生成的图表如果包含中文而镜像里没有中文字体图表里的中文会显示成方块。解决方式有两种一种是在构建自定义镜像时把中文字体打进去另一种是用 docker-compose 挂载宿主机的字体目录。推荐在docker-compose.yml中这样配置services: superset: image: apache/superset:4.1.1 container_name: superset environment: - LANGzh_CN.UTF-8 - LC_ALLzh_CN.UTF-8 - SUPERSET_LANGUAGES{zh:{flag:cn,name:Chinese}} ports: - 8088:8088 volumes: - ./superset_home:/app/superset_home - /usr/share/fonts:/usr/share/fonts:ro这里的SUPERSET_LANGUAGES是 4.x 版本开始支持的语言配置方式指定了中文语言包。/usr/share/fonts的挂载是让容器直接使用宿主机字体这样图表中文不会乱码。3.2 数据库初始化和管理员账号创建一条命令搞定还是分三步走Superset 的数据库初始化在 4.1.1 里有两种做法。如果你使用默认的 SQLite可以执行docker exec -it superset superset db upgrade docker exec -it superset superset initsuperset db upgrade负责建表superset init负责初始化角色和权限。容易忽略的是superset init执行完后还需要手动创建管理员账号docker exec -it superset fab create-admin \ --username admin \ --firstname admin \ --lastname admin \ --email adminexample.com \ --password admin注意这里用的是fab create-admin不是旧版的superset create-admin。4.1.1 版本切换到了 Flask-AppBuilder 的命令行入口之前用旧命令会提示 command not found。如果你的环境要求使用 MySQL 或 PostgreSQL 作为后端数据库需要在docker-compose.yml里加一个数据库服务并在 Superset 的环境变量中指定数据库连接串environment: - SUPERSET__SQLALCHEMY_DATABASE_URImysql://superset:supersetdb:3306/superset其中SUPERSET__SQLALCHEMY_DATABASE_URI这个环境变量是 Superset 从 1.4 版本开始支持的配置覆盖机制双下划线表示配置文件里的层级关系。如果你直接从官方文档复制连接串注意 MySQL 驱动要写mysql://而不是mysqlpymysql://因为 4.1.1 默认已经内置了 PyMySQL不需要额外指定驱动。3.3 通过 SECRET_KEY 避免登录状态失效的玄学问题很多离线部署跑起来之后发现一重启容器所有用户的登录状态全部失效重新登录后过几分钟又失效。这个问题根源是SECRET_KEY在生产模式下没有稳定设置。在docker-compose.yml的 environment 中必须增加- SUPERSET_SECRET_KEYyour_random_secret_string_here这个SECRET_KEY是用来给 Flask 签名 session cookie 的如果没有显式指定Superset 会每次启动时随机生成一个重启后所有 session 自动失效。生成一个随机字符串的方法openssl rand -base64 32把输出结果填到上面环境变量里即可。这个值一旦在用户使用期间改变也会把所有用户踢下线所以不要随便更换最好写入部署文档里让运维团队知晓。3.4 执行顺序离线环境首次启动的全流程命令把上面步骤串起来在离线宿主机的docker-compose.yml所在目录执行docker-compose up -d docker-compose ps等容器状态变为 running 后第一次可能要等 1-2 分钟因为 Superset 要加载静态资源和初始化配置进入容器执行docker exec -it superset superset db upgrade docker exec -it superset fab create-admin --username admin --firstname admin --lastname admin --email adminexample.com --password admin docker exec -it superset superset init docker-compose restart superset执行完superset init后重启容器的原因是要让语言配置和权限配置彻底生效。如果你不重启大概率会出现登录后菜单还是英文、部分功能权限异常的情况。4. Superset 4.1.1 离线部署避坑常见问题与排查手段4.1 容器反复重启或直接退出先看日志里的数据库连接串现象执行docker-compose up -d后docker ps看到 superset 容器几秒钟就退出或者一直处于 restarting 状态。手动执行docker logs superset看到类似ModuleNotFoundError: No module named MySQLdb或者sqlalchemy.exc.OperationalError。原因分析绝大多数情况是SUPERSET__SQLALCHEMY_DATABASE_URI环境变量配置了 MySQL 连接串但容器内缺少相应的数据库驱动或者连接串里的 host 指向了不存在的服务。4.1.1 镜像内置了 PyMySQL但不包含 PostgreSQL 的 psycopg2 完整版也没包含 SQL Server 的驱动。如果你要接的是 PostgreSQL需要在环境变量里把它切换到postgresqlpsycopg2://并且用docker exec进入容器手动安装pip install psycopg2-binary或者干脆在离线环境里提前准备一个自定义镜像。解决路径docker logs superset 21 | grep -i error先看具体的报错信息确认是驱动缺失还是连接失败。如果是驱动缺失最省事的办法是在联网机器上基于apache/superset:4.1.1做一个新镜像在 Dockerfile 里加上RUN pip install psycopg2-binary然后推送到内网。如果是连接失败检查数据库服务是否先于 superset 容器启动或者在 compose 文件里加depends_on并设置healthcheck。4.2 登录页能打开但样式全部丢失静态资源加载失败现象浏览器访问http://ip:8088能弹出登录框但页面没有任何 CSS 样式只剩纯文本和按钮叠在一起。按 F12 打开开发者工具能看到大量静态资源请求报 404。原因分析Superset 的静态资源默认由 Nginx 或者 Flask 直接服务在 4.1.1 中如果之前执行过superset init没有完全成功static/assets目录下的文件可能没有被正确拷贝到指定位置。另一种常见情况是离线环境下没有执行superset db upgrade导致系统数据库里缺少存储静态资源配置的表。解决路径先执行一次完整的初始化流程。如果问题还在进入容器查看静态资源目录docker exec -it superset bash ls -la /app/superset/static/assets/如果目录不存在或者内容为空在容器内手动执行superset static这个命令会重建静态资源目录。执行完后再重启容器。注意如果你用的是自定义的 Nginx 反向代理还需要确认 Nginx 配置里的location /static/指向正确别把 Superset 自己的静态请求代理到别的服务上。4.3 图表中文乱码字体缓存和系统语言都没生效现象仪表盘标题、图例、坐标轴的中文显示正常但图表内部的中文文字全部变成方框或者乱码。原因分析Superset 4.1.1 用dominate和d3渲染图表浏览器端的中文字体来自操作系统或者容器内的 fontconfig 配置。虽然宿主机挂载了字体目录但如果容器内的 fontconfig 缓存没有更新即使有字体文件渲染引擎也识别不到。解决路径进入容器并重建字体缓存docker exec -it superset bash apt-get update apt-get install -y fontconfig fc-cache -f -v如果你的离线环境没有 apt 源这个方案行不通。我一般会在网联机器上做一个自定义镜像Dockerfile 里加上RUN apt-get update apt-get install -y fonts-wqy-zenhei fonts-wqy-microhei然后把fc-cache也放进构建过程。这样保证进入容器后中文字体一定可用。4.4 导入 tar 包时报磁盘空间不足镜像层解压会占用双倍空间现象在离线主机上执行docker load -i superset_offline.tar时进度条走到一半报no space left on device但用df -h看磁盘明明还有几十 GB。原因分析docker load在解压镜像时会将全部镜像层先写入磁盘临时目录再写入 Docker 的数据目录。如果 Docker 数据目录所在分区空间不足或者/var/lib/docker所在分区和临时目录所在分区空间都很紧张就会触发这个报错。常见的情况是 Docker 数据目录默认在根分区而根分区往往只有 20-30 GB。解决路径先看当前空间df -h /var/lib/docker df -h /tmp如果/tmp空间够可以把 Docker 的临时目录指过去。更直接的做法是把 Docker 数据目录迁移到大分区但迁移本身比较耗时。我之前在一个 40 GB 根分区的机器上连续踩两次这个坑最后把/var/lib/docker挂载到了单独的数据盘才彻底解决。如果临时迁移不方便可以直接把/var/lib/docker软链到有空间的位置但这仅限应急不建议长期使用。4.5 容器内时间与宿主机不一致影响定时任务和图表刷新现象Superset 的定时报表任务执行时间和预期不符图表缓存刷新也比设定时间晚了几个小时。原因分析容器默认使用 UTC 时区而宿主机可能已经设置了Asia/Shanghai容器内date命令看到的还是 UTC 时间。Superset 的定时任务schedule在计算执行时间时依据的是容器内的系统时间。解决路径在 docker-compose 的环境变量中加入environment: - TZAsia/Shanghai同时把宿主机的/etc/localtime挂载进容器volumes: - /etc/localtime:/etc/localtime:ro这样容器内外时间一致。需要注意的是如果你已经用 Superset 创建了定时任务改完时区后最好手工重启一次容器否则已经加载到内存里的调度器可能还是用旧时区计算。5. 离线部署后的数据源连接验证从「跑起来」到「可用」5.1 通过预配置数据源减少上手成本部署完成后有一个细节值得做提前在 Superset 的配置里声明目标数据库连接。虽然通过页面操作也能添加数据库但在离线环境里操作人员可能不是原来的实施工程师连接参数和特殊配置容易填错。修改superset_config.py或者通过环境变量注入SQLALCHEMY_CUSTOM_PASSWORD_STORE和SQLALCHEMY_DATABASE_URI。最常见的做法是在docker-compose.yml里增加environment: - SUPERSET__SQLALCHEMY_DATABASE_URImysql://superset:supersetdb:3306/superset这里只解决了 Superset 自己用的数据库你还需要在界面上配置业务数据源。如果有多个业务库建议在一开始就通过 REST API 或者 Python 脚本批量创建数据库记录避免后续手工录入的麻烦。5.2 验证部署成功三个关键检查点第一个检查点是登录浏览器访问http://ip:8088能出现登录页并且样式完整说明静态资源没问题。第二个检查点是数据源连通性在 Superset 的 Data 菜单里选择 Databases点击目标数据库右侧的 Test Connection能返回 Success 就说明网络和驱动都正常。第三个检查点是图表创建链路新建一个 Chart选择数据集拖拽维度生成一个简单图表并确认中文显示正常。下面是我比较常用的一组最小验证命令# 检查容器是否持续运行 docker ps --filter namesuperset --format {{.Status}} # 查看 Superset 是否完成数据库初始化 docker exec -it superset superset db check # 确认 Superset 内部运行时健康 docker exec -it superset superset healthsuperset health是 4.x 新增的命令直接返回服务状态不用再额外 curl 接口。5.3 日志持久化离线环境里排障的后悔药很多人部署成功后就把容器晾在那里直到某天图表不出数据才想起来查日志但容器已经重启过日志早就丢了。我在离线部署的经验是从第一天开始就把日志挂载到宿主机目录。在docker-compose.yml里增加logging: driver: json-file options: max-size: 50m max-file: 5同时把 Superset 的应用日志目录挂出来volumes: - ./superset_logs:/app/logs在容器里 Superset 的日志默认输出到控制台但某些子进程的日志写到了/app/logs目录如果不挂载重启后全丢。挂载之后即使容器崩了也可以到superset_logs目录下翻日志分析原因。5.4 关于升级路径的一个提醒离线部署最怕的是版本升级。如果后续要从 4.1.1 升级到 4.1.2 或者 4.2.x一定要先备份 Superset 的后端数据库尤其是slices、dashboards、databases这几张表然后拉取新镜像测试不能直接在生产上执行superset db upgrade。我见过升级后仪表盘图标全部错位的案例原因是前端静态资源缓存没清。升级完成后让用户强制刷新浏览器并清理缓存能规避大部分类似问题。6. 生产环境下的三个额外配置让你的 Superset 离线部署更靠谱6.1 配置反向代理不要直接把 Superset 的端口暴露给所有内网机器在实际的内网环境里我通常不建议直接访问ip:8088。通过 Nginx 加一层反向代理一方面是为了统一入口另一方面也方便后续加访问控制。一个最常见的配置是server { listen 80; server_name superset.example.local; location / { proxy_pass http://127.0.0.1:8088; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }注意 Superset 是 Flask 应用如果你在 Nginx 层开启了 HTTPS需要同时设置X-Forwarded-Proto否则 Superset 生成的一些内部链接会变成 http 协议导致页面跳转异常。6.2 关闭 Superset 的定时报表或显式配置时间对于大多数内网环境Superset 自带的定时报表功能依赖 Celery Beat默认并没有启动。如果你用不上这个功能就不要启动。启动的方式是在docker-compose.yml里新增一个 worker 服务需要指定SUPERSET__CELERY_BROKER_URL和SUPERSET__CELERY_RESULT_BACKEND为 Redis 连接串。如果事先没有准备 Redis不建议在生产环境上临时把 Celery 跑起来因为它会引入额外的调度依赖。我在一个项目里吃过这个亏以为加了一个 worker 服务就能按月发报表结果 Redis 配置错误整个 superset 服务也被带崩了。6.3 定期备份方案离线环境比在线环境更容易丢数据在线环境有各种云备份服务离线环境往往只依赖机器上的一块磁盘。Superset 里的核心数据是dashboards、slices和相关表。备份的最简方式是直接备份 SQLite 文件或者 MySQL 的库docker exec superset superset export-dashboards -f /app/superset_home/dashboards_export.zipexport-dashboards会把当前所有仪表盘导出为一个 zip 包放到挂载目录后拷贝到宿主机即可。数据库本身可以用sqlite3 .backup或者mysqldump备份。我在多个项目里坚持一个习惯每次修改配置或者升级前先导出一份仪表盘备份再动数据库。这个习惯让我避免过两次彻底返工。如果你做的是生产级的离线部署建议把备份脚本写到 cron 里每天把导出文件和数据库备份文件存到单独的数据盘。别看操作简单真到要恢复的时候你就知道这步有多值钱了。希望上面这些从镜像打包到日志排查的踩坑经验能帮到你让你的 Superset 离线部署少走弯路。本文还有配套的精品资源点击获取 Superset 4.1.1 离线部署全指南：镜像打包与容器配置
简介对于需要在无互联网环境快速落地数据可视化平台的企业运维与数据分析人员Superset 4.1.1中文版Docker离线部署包提供了完整解决方案。压缩包共6个文件约524.2MB内含3个Docker镜像tar包Redis、PostgreSQL及Superset中文版以及分别用于服务编排、环境变量注入、数据库连接与安全配置的YAML、ENV与Python配置文件可支撑离线环境下的一次性容器编排。已有364人学习下载适合想借助Docker实现可移植、可重复部署Superset的团队。借助该包用户无需从公网拉取镜像即可完成容器启动中文界面显著降低非英文用户的使用门槛同时部署前核对这些配置项、定期关注Superset和容器安全更新可确保长期稳定运行。1. Superset 4.1.1 离线部署为什么你必须先搞定镜像方案Apache Superset 作为目前使用率最高的开源 BI 工具4.1.1 版本在图表渲染性能、缓存策略和数据源连接器上都做了不少优化。但你真正要面对的问题通常不是 Superset 本身而是「怎么在内网环境里把 Docker 镜像弄进去」。很多团队在离线部署 Superset 4.1.1 时翻车翻的不是 Superset 的配置文件而是 Docker 镜像下载慢、镜像依赖层级不清晰、宿主机架构不匹配这类「看似无关」的环节。这篇笔记面向的是需要在内网、生产环境或安全隔离区里把 Superset 4.1.1 跑起来的运维和开发。整体思路是先用一台能联网的机器把镜像准备好再打包传输到离线宿主机最后通过 docker-compose 把服务拉起来。整个过程我踩过不少坑特别是 4.1.1 版本相比旧版在初始化数据库和静态资源处理上有变化如果不注意启动后大概率会卡在「Superset 一直 500」或者「登录页样式全丢」这两个问题上。2. 离线部署前的镜像准备从 Docker Hub 拉取到 tar 打包2.1 先用 docker pull 锁定 Superset 4.1.1 的镜像版本在联网机器上我一般建议不要直接拉apache/superset:latest而是指定4.1.1这个明确版本。Superset 官方镜像的更新节奏较快latest 标签可能在某个时间点变成了 4.1.2 或者 4.2.0这样你离线环境里跑的和你测试环境里跑的就不是同一个东西。在联网机器上执行以下命令docker pull apache/superset:4.1.1拉取完成后用docker images确认镜像已经存在于本地。这里需要记住镜像的 IMAGE ID因为后面打包时用 IMAGE ID 比用repository:tag更保险不会因为标签覆盖导致导出错版本。2.2 导出镜像并检查依赖为什么不能只看一个镜像文件Superset 4.1.1 的官方镜像基于python:3.11-slim构建但如果你只执行docker save apache/superset:4.1.1导出的 tar 包里通常只包含 Superset 这一个层。这样看起来没什么问题但当你把它导入到离线主机后如果宿主机本地没有python:3.11-slim的底层层Docker 会在运行时尝试从网络拉取缺失的层——而这在离线环境里直接失败。我建议的做法是先把镜像跑起来然后查看它的实际依赖docker run --rm -d --name superset_check apache/superset:4.1.1 sleep 300 docker inspect superset_check --format{{.Image}} docker history apache/superset:4.1.1 --no-truncdocker history能看到每一层的构建记录但你要关注的不是构建内容而是运行依赖。更稳妥的方式是直接用docker image inspect查看 RootFS 的层数然后把所有底层镜像也一起保存。一个实际的打包命令组合docker save apache/superset:4.1.1 python:3.11-slim -o superset_offline.tar注意这里把python:3.11-slim也一起打包了。如果你不能确定 Superset 4.1.1 是基于哪个 Python 版本构建的可以先执行docker inspect apache/superset:4.1.1 | grep -i python看环境变量里的PYTHON_VERSION。2.3 内网传输与导入用 md5 校验文件完整性离线环境里通过 U 盘或者内网 FTP 传输 tar 包最怕的是文件传输了一半而你毫不知情。我遇到过一次导入后启动报错排查了半天发现是 tar 包损坏重新传输才解决。导入前做一次 md5 校验md5sum superset_offline.tar在联网机器上打包完成后记录这个 md5 值传输到离线主机后再次计算两值一致再执行导入docker load -i superset_offline.tar加载成功后会输出Loaded image: apache/superset:4.1.1和Loaded image: python:3.11-slim两行信息确认都出现后再继续。如果只出现了一行说明底层镜像没打进去需要回到联网机器重新执行docker save。3. 用 docker-compose 跑通 Superset 4.1.1 中文版配置文件与初始化流程拆解3.1 先解决中文问题4.1.1 的语言配置方式和历史坑4.1.1 版本在语言设置上与旧版有差异。旧版本可以直接通过环境变量LANGzh_CN.UTF-8或者修改 config.py 里的BABEL_DEFAULT_LOCALE来切换界面语言但 4.1.1 版本需要同时确保系统有中文字体和中文本地化翻译文件。在离线环境里最容易翻车的是缺字体。Superset 生成的图表如果包含中文而镜像里没有中文字体图表里的中文会显示成方块。解决方式有两种一种是在构建自定义镜像时把中文字体打进去另一种是用 docker-compose 挂载宿主机的字体目录。推荐在docker-compose.yml中这样配置services: superset: image: apache/superset:4.1.1 container_name: superset environment: - LANGzh_CN.UTF-8 - LC_ALLzh_CN.UTF-8 - SUPERSET_LANGUAGES{zh:{flag:cn,name:Chinese}} ports: - 8088:8088 volumes: - ./superset_home:/app/superset_home - /usr/share/fonts:/usr/share/fonts:ro这里的SUPERSET_LANGUAGES是 4.x 版本开始支持的语言配置方式指定了中文语言包。/usr/share/fonts的挂载是让容器直接使用宿主机字体这样图表中文不会乱码。3.2 数据库初始化和管理员账号创建一条命令搞定还是分三步走Superset 的数据库初始化在 4.1.1 里有两种做法。如果你使用默认的 SQLite可以执行docker exec -it superset superset db upgrade docker exec -it superset superset initsuperset db upgrade负责建表superset init负责初始化角色和权限。容易忽略的是superset init执行完后还需要手动创建管理员账号docker exec -it superset fab create-admin \ --username admin \ --firstname admin \ --lastname admin \ --email adminexample.com \ --password admin注意这里用的是fab create-admin不是旧版的superset create-admin。4.1.1 版本切换到了 Flask-AppBuilder 的命令行入口之前用旧命令会提示 command not found。如果你的环境要求使用 MySQL 或 PostgreSQL 作为后端数据库需要在docker-compose.yml里加一个数据库服务并在 Superset 的环境变量中指定数据库连接串environment: - SUPERSET__SQLALCHEMY_DATABASE_URImysql://superset:supersetdb:3306/superset其中SUPERSET__SQLALCHEMY_DATABASE_URI这个环境变量是 Superset 从 1.4 版本开始支持的配置覆盖机制双下划线表示配置文件里的层级关系。如果你直接从官方文档复制连接串注意 MySQL 驱动要写mysql://而不是mysqlpymysql://因为 4.1.1 默认已经内置了 PyMySQL不需要额外指定驱动。3.3 通过 SECRET_KEY 避免登录状态失效的玄学问题很多离线部署跑起来之后发现一重启容器所有用户的登录状态全部失效重新登录后过几分钟又失效。这个问题根源是SECRET_KEY在生产模式下没有稳定设置。在docker-compose.yml的 environment 中必须增加- SUPERSET_SECRET_KEYyour_random_secret_string_here这个SECRET_KEY是用来给 Flask 签名 session cookie 的如果没有显式指定Superset 会每次启动时随机生成一个重启后所有 session 自动失效。生成一个随机字符串的方法openssl rand -base64 32把输出结果填到上面环境变量里即可。这个值一旦在用户使用期间改变也会把所有用户踢下线所以不要随便更换最好写入部署文档里让运维团队知晓。3.4 执行顺序离线环境首次启动的全流程命令把上面步骤串起来在离线宿主机的docker-compose.yml所在目录执行docker-compose up -d docker-compose ps等容器状态变为 running 后第一次可能要等 1-2 分钟因为 Superset 要加载静态资源和初始化配置进入容器执行docker exec -it superset superset db upgrade docker exec -it superset fab create-admin --username admin --firstname admin --lastname admin --email adminexample.com --password admin docker exec -it superset superset init docker-compose restart superset执行完superset init后重启容器的原因是要让语言配置和权限配置彻底生效。如果你不重启大概率会出现登录后菜单还是英文、部分功能权限异常的情况。4. Superset 4.1.1 离线部署避坑常见问题与排查手段4.1 容器反复重启或直接退出先看日志里的数据库连接串现象执行docker-compose up -d后docker ps看到 superset 容器几秒钟就退出或者一直处于 restarting 状态。手动执行docker logs superset看到类似ModuleNotFoundError: No module named MySQLdb或者sqlalchemy.exc.OperationalError。原因分析绝大多数情况是SUPERSET__SQLALCHEMY_DATABASE_URI环境变量配置了 MySQL 连接串但容器内缺少相应的数据库驱动或者连接串里的 host 指向了不存在的服务。4.1.1 镜像内置了 PyMySQL但不包含 PostgreSQL 的 psycopg2 完整版也没包含 SQL Server 的驱动。如果你要接的是 PostgreSQL需要在环境变量里把它切换到postgresqlpsycopg2://并且用docker exec进入容器手动安装pip install psycopg2-binary或者干脆在离线环境里提前准备一个自定义镜像。解决路径docker logs superset 21 | grep -i error先看具体的报错信息确认是驱动缺失还是连接失败。如果是驱动缺失最省事的办法是在联网机器上基于apache/superset:4.1.1做一个新镜像在 Dockerfile 里加上RUN pip install psycopg2-binary然后推送到内网。如果是连接失败检查数据库服务是否先于 superset 容器启动或者在 compose 文件里加depends_on并设置healthcheck。4.2 登录页能打开但样式全部丢失静态资源加载失败现象浏览器访问http://ip:8088能弹出登录框但页面没有任何 CSS 样式只剩纯文本和按钮叠在一起。按 F12 打开开发者工具能看到大量静态资源请求报 404。原因分析Superset 的静态资源默认由 Nginx 或者 Flask 直接服务在 4.1.1 中如果之前执行过superset init没有完全成功static/assets目录下的文件可能没有被正确拷贝到指定位置。另一种常见情况是离线环境下没有执行superset db upgrade导致系统数据库里缺少存储静态资源配置的表。解决路径先执行一次完整的初始化流程。如果问题还在进入容器查看静态资源目录docker exec -it superset bash ls -la /app/superset/static/assets/如果目录不存在或者内容为空在容器内手动执行superset static这个命令会重建静态资源目录。执行完后再重启容器。注意如果你用的是自定义的 Nginx 反向代理还需要确认 Nginx 配置里的location /static/指向正确别把 Superset 自己的静态请求代理到别的服务上。4.3 图表中文乱码字体缓存和系统语言都没生效现象仪表盘标题、图例、坐标轴的中文显示正常但图表内部的中文文字全部变成方框或者乱码。原因分析Superset 4.1.1 用dominate和d3渲染图表浏览器端的中文字体来自操作系统或者容器内的 fontconfig 配置。虽然宿主机挂载了字体目录但如果容器内的 fontconfig 缓存没有更新即使有字体文件渲染引擎也识别不到。解决路径进入容器并重建字体缓存docker exec -it superset bash apt-get update apt-get install -y fontconfig fc-cache -f -v如果你的离线环境没有 apt 源这个方案行不通。我一般会在网联机器上做一个自定义镜像Dockerfile 里加上RUN apt-get update apt-get install -y fonts-wqy-zenhei fonts-wqy-microhei然后把fc-cache也放进构建过程。这样保证进入容器后中文字体一定可用。4.4 导入 tar 包时报磁盘空间不足镜像层解压会占用双倍空间现象在离线主机上执行docker load -i superset_offline.tar时进度条走到一半报no space left on device但用df -h看磁盘明明还有几十 GB。原因分析docker load在解压镜像时会将全部镜像层先写入磁盘临时目录再写入 Docker 的数据目录。如果 Docker 数据目录所在分区空间不足或者/var/lib/docker所在分区和临时目录所在分区空间都很紧张就会触发这个报错。常见的情况是 Docker 数据目录默认在根分区而根分区往往只有 20-30 GB。解决路径先看当前空间df -h /var/lib/docker df -h /tmp如果/tmp空间够可以把 Docker 的临时目录指过去。更直接的做法是把 Docker 数据目录迁移到大分区但迁移本身比较耗时。我之前在一个 40 GB 根分区的机器上连续踩两次这个坑最后把/var/lib/docker挂载到了单独的数据盘才彻底解决。如果临时迁移不方便可以直接把/var/lib/docker软链到有空间的位置但这仅限应急不建议长期使用。4.5 容器内时间与宿主机不一致影响定时任务和图表刷新现象Superset 的定时报表任务执行时间和预期不符图表缓存刷新也比设定时间晚了几个小时。原因分析容器默认使用 UTC 时区而宿主机可能已经设置了Asia/Shanghai容器内date命令看到的还是 UTC 时间。Superset 的定时任务schedule在计算执行时间时依据的是容器内的系统时间。解决路径在 docker-compose 的环境变量中加入environment: - TZAsia/Shanghai同时把宿主机的/etc/localtime挂载进容器volumes: - /etc/localtime:/etc/localtime:ro这样容器内外时间一致。需要注意的是如果你已经用 Superset 创建了定时任务改完时区后最好手工重启一次容器否则已经加载到内存里的调度器可能还是用旧时区计算。5. 离线部署后的数据源连接验证从「跑起来」到「可用」5.1 通过预配置数据源减少上手成本部署完成后有一个细节值得做提前在 Superset 的配置里声明目标数据库连接。虽然通过页面操作也能添加数据库但在离线环境里操作人员可能不是原来的实施工程师连接参数和特殊配置容易填错。修改superset_config.py或者通过环境变量注入SQLALCHEMY_CUSTOM_PASSWORD_STORE和SQLALCHEMY_DATABASE_URI。最常见的做法是在docker-compose.yml里增加environment: - SUPERSET__SQLALCHEMY_DATABASE_URImysql://superset:supersetdb:3306/superset这里只解决了 Superset 自己用的数据库你还需要在界面上配置业务数据源。如果有多个业务库建议在一开始就通过 REST API 或者 Python 脚本批量创建数据库记录避免后续手工录入的麻烦。5.2 验证部署成功三个关键检查点第一个检查点是登录浏览器访问http://ip:8088能出现登录页并且样式完整说明静态资源没问题。第二个检查点是数据源连通性在 Superset 的 Data 菜单里选择 Databases点击目标数据库右侧的 Test Connection能返回 Success 就说明网络和驱动都正常。第三个检查点是图表创建链路新建一个 Chart选择数据集拖拽维度生成一个简单图表并确认中文显示正常。下面是我比较常用的一组最小验证命令# 检查容器是否持续运行 docker ps --filter namesuperset --format {{.Status}} # 查看 Superset 是否完成数据库初始化 docker exec -it superset superset db check # 确认 Superset 内部运行时健康 docker exec -it superset superset healthsuperset health是 4.x 新增的命令直接返回服务状态不用再额外 curl 接口。5.3 日志持久化离线环境里排障的后悔药很多人部署成功后就把容器晾在那里直到某天图表不出数据才想起来查日志但容器已经重启过日志早就丢了。我在离线部署的经验是从第一天开始就把日志挂载到宿主机目录。在docker-compose.yml里增加logging: driver: json-file options: max-size: 50m max-file: 5同时把 Superset 的应用日志目录挂出来volumes: - ./superset_logs:/app/logs在容器里 Superset 的日志默认输出到控制台但某些子进程的日志写到了/app/logs目录如果不挂载重启后全丢。挂载之后即使容器崩了也可以到superset_logs目录下翻日志分析原因。5.4 关于升级路径的一个提醒离线部署最怕的是版本升级。如果后续要从 4.1.1 升级到 4.1.2 或者 4.2.x一定要先备份 Superset 的后端数据库尤其是slices、dashboards、databases这几张表然后拉取新镜像测试不能直接在生产上执行superset db upgrade。我见过升级后仪表盘图标全部错位的案例原因是前端静态资源缓存没清。升级完成后让用户强制刷新浏览器并清理缓存能规避大部分类似问题。6. 生产环境下的三个额外配置让你的 Superset 离线部署更靠谱6.1 配置反向代理不要直接把 Superset 的端口暴露给所有内网机器在实际的内网环境里我通常不建议直接访问ip:8088。通过 Nginx 加一层反向代理一方面是为了统一入口另一方面也方便后续加访问控制。一个最常见的配置是server { listen 80; server_name superset.example.local; location / { proxy_pass http://127.0.0.1:8088; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }注意 Superset 是 Flask 应用如果你在 Nginx 层开启了 HTTPS需要同时设置X-Forwarded-Proto否则 Superset 生成的一些内部链接会变成 http 协议导致页面跳转异常。6.2 关闭 Superset 的定时报表或显式配置时间对于大多数内网环境Superset 自带的定时报表功能依赖 Celery Beat默认并没有启动。如果你用不上这个功能就不要启动。启动的方式是在docker-compose.yml里新增一个 worker 服务需要指定SUPERSET__CELERY_BROKER_URL和SUPERSET__CELERY_RESULT_BACKEND为 Redis 连接串。如果事先没有准备 Redis不建议在生产环境上临时把 Celery 跑起来因为它会引入额外的调度依赖。我在一个项目里吃过这个亏以为加了一个 worker 服务就能按月发报表结果 Redis 配置错误整个 superset 服务也被带崩了。6.3 定期备份方案离线环境比在线环境更容易丢数据在线环境有各种云备份服务离线环境往往只依赖机器上的一块磁盘。Superset 里的核心数据是dashboards、slices和相关表。备份的最简方式是直接备份 SQLite 文件或者 MySQL 的库docker exec superset superset export-dashboards -f /app/superset_home/dashboards_export.zipexport-dashboards会把当前所有仪表盘导出为一个 zip 包放到挂载目录后拷贝到宿主机即可。数据库本身可以用sqlite3 .backup或者mysqldump备份。我在多个项目里坚持一个习惯每次修改配置或者升级前先导出一份仪表盘备份再动数据库。这个习惯让我避免过两次彻底返工。如果你做的是生产级的离线部署建议把备份脚本写到 cron 里每天把导出文件和数据库备份文件存到单独的数据盘。别看操作简单真到要恢复的时候你就知道这步有多值钱了。希望上面这些从镜像打包到日志排查的踩坑经验能帮到你让你的 Superset 离线部署少走弯路。本文还有配套的精品资源点击获取