Superset 4.1.1中文版Docker离线部署与汉化排障

简介：Superset 4.1.1 中文版 Docker 离线部署包面向需要在无外网或受限网络环境中搭建数据探索与可视化平台的企业及开发者，也适合具备基础 Docker 使用经验、希望快速复现 BI 环境的中级读者。压缩包共 6 个文件，包含 3 个 tar 离线镜像、1 个 yml 服务编排文件、1 个 py 配置文件和 1 个 env 环境变量文件，整体约 524.2MB，覆盖镜像导入、容器编排与运行参数配置等部署要素。已有 370 人学习或下载，说明该离线方案在中文数据可视化部署场景中具有一定参考价值。读者可据此获得一套可重复使用的容器化部署材料，便于在隔离网络中完成 Superset 中文环境搭建，并围绕数据库连接、服务组件组织与安全参数进行调整，进而开展数据探索、分析与可视化展示。

1. 内网环境里装 Superset 4.1.1，真正麻烦的其实不是 Superset 本身

内网机器上落地 Superset 4.1.1 中文版，最耗时间的环节基本都出在环境隔离上——docker pull连不上、前端依赖装不下来、驱动缺一个包就卡上一整天。这套 Docker 离线部署包要解决的正是这件事：镜像、汉化后的前端产物、常用数据库驱动、初始化脚本全部打成 tar，拷进去docker load加一份 compose 就能跑起来。它适合三类人：隔离网里要做 BI 报表的、需要给客户现场交付一套能直接演示的中文看板的，以及在“半中半英”界面上反复踩坑、想一次把语言包搞定的。下面按我实际拆包、加载、初始化的顺序讲，能抄的地方直接抄。

2. 离线 Docker 包的选型账：为什么不是进去 pip 装一遍

先说明一个常见误区：很多人第一反应是“把源码拷进去，在目标机器上pip install apache-superset不就行了”。在内网里这条路基本走不通，不是你操作有问题，而是 Superset 的安装链路天生依赖大量外网资源。想明白它依赖什么，才知道离线包该做成什么样、该核对哪些版本号。

2.1 内网拉取失败的三个真实原因

第一个原因是镜像分层。Superset 的官方镜像从基础 Python 镜像开始，一层层叠上系统包、Python 依赖、前端构建产物，最终体积通常在 1GB 以上。docker save只打包被引用的层，所以离线 tar 的体积和层数强相关；如果你在目标机器上只拷了一个“精简版”镜像，运行时就可能因为缺某一层而报错退出。这块没有捷径，导出的必须是完整引用链。

第二个原因是构建期依赖。Superset 的前端是 React + TypeScript，npm ci要连 registry；后端 Python 依赖要连包索引；某些版本的可视化导出还依赖无头浏览器和字体包。这些在构建阶段就完成了，所以离线交付的正确形态是“拿来即用的成品镜像”，而不是“到现场再 build”。一旦你在内网机器上执行docker compose build，那些联网步骤会全部重演一遍，翻车几乎是必然的。

第三个原因是驱动和字符集。生产上大概率接 PostgreSQL、MySQL 或 OLAP 引擎，而镜像内置的驱动不会覆盖所有数据源。如果在容器里临时pip install，容器重启后一切归零——这是很多人第一次部署后“昨天还能连、今天连不上”的根源。常见做法是把驱动预先打进一层派生镜像，随离线包一起交付。

提示：先在你的构建机上把docker images和docker history都跑一遍，确认每一个FROM的上游镜像都已导出，再打包。漏一个基础层，内网加载时就会得到一堆悬空镜像（dangling image）。

2.2 一份能交付的离线包包含什么

我把这类包拆成四层来看，每层解决一个独立问题。判断一个 Superset 4.1.1 中文版离线包是否合格，对照这张表逐项核就行。

编排层最容易被忽略。官方 compose 文件里通常带有build:段和镜像名占位，离线环境必须把这些全改成固定的image:，否则 compose 会尝试现场构建。另外.env里的密钥、数据库口令、SUPERSET_SECRET_KEY一定要在交付前改成目标环境的独立值，直接沿用示例值属于典型的安全欠账——SECRET_KEY一旦泄露，会话和加密字段就等于公开了。

驱动层有个细节：Superset 4.x 对 SQLAlchemy 2.x 的驱动版本比较敏感，同一个数据库的新旧驱动行为差异很明显。我一般会在构建机上把pip download出来的 wheel 一起放进离线包的wheels/目录，容器内用--no-index --find-links离线安装，避免现场再碰网络。

2.3 4.1.1 的版本对齐表

版本错配是离线部署里最隐蔽的坑，因为报错信息往往指向别处。下面这张表对齐的是常见依赖，实际以镜像内python --version和pip list输出为准。

“以镜像内为准”不是敷衍，而是因为 Superset 镜像在不同小版本间升级过基础镜像。你在派生镜像里pip install时，如果 wheel 是按另一个 Python 小版本下载的，装上去会报 ABI 不兼容。稳妥做法是进容器跑一次python -V && pip -V，把结果写进交付文档。

另外提醒一句：不要在派生镜像里升级 Flask、Werkzeug、SQLAlchemy 这些核心依赖。Superset 对它们的版本有明确约束，你随手pip install -U一个，很可能换来一个启动时报 import 错误的黑匣子，而报错栈完全指不到你改的那行。

3. 从 tar 到 running：镜像搬运、编排改写与首次初始化

这一章是整篇的核心，按顺序做完就能看到登录页。我把流程拆成导出校验、导入改名、编排改写、初始化四段，每段都给了可直接执行的脚本和参数说明。中间任何一步跳过，后面排查成本都会翻倍。

3.1 导出与校验：先把完整性锁死

在能联网的构建机上执行下面的脚本，把三个镜像一次性导出并生成校验文件。这里用变量把仓库前缀抽出来，是因为不同团队的内网仓库命名规则不一样，硬编码进脚本后面改起来很烦。

#!/usr/bin/env bash set -euo pipefail REGISTRY="your-registry.local/library" # 换成内网仓库前缀或本地命名 VERSION="4.1.1" IMAGES=( "${REGISTRY}/superset:${VERSION}" # 主镜像，含中文前端产物 "postgres:16-alpine" # 元数据库 "redis:7-alpine" # 缓存与队列 ) mkdir -p offline/images offline/sha256 for img in "${IMAGES[@]}"; do docker pull "$img" # 文件名把 / 和 : 换成下划线，避免跨平台路径问题 name=$(echo "$img" | tr '/:' '__') docker save -o "offline/images/${name}.tar" "$img" echo "exported: $name" done cd offline/images sha256sum ./*.tar > ../sha256/images.sha256 sha256sum -c ../sha256/images.sha256

脚本的逻辑很直白：逐个拉取、逐个save、最后统一算摘要。几个参数要留意：set -euo pipefail保证任何一个镜像拉取失败就中断，避免生成一个“看起来完整、实际缺一块”的包；tr '/:' '__'是为了让镜像名可以直接当文件名；sha256sum -c是给你自己用的——拷贝到内网后第一件事就是重跑一次校验，U 盘、跳板机、文件传输都可能悄悄改掉字节。

注意：docker save默认保留镜像的标签信息，但如果你在目标机器上重命名过镜像，再导出时标签会变。交付包里最好附一份镜像清单文本，写清楚每个 tar 对应的原始标签。

3.2 导入、改名与 compose 改写

内网侧先校验再加载，加载完统一打个本地标签，这样 compose 里写死的image就不会因为仓库前缀不同而找不到。

#!/usr/bin/env bash set -euo pipefail cd offline sha256sum -c sha256/images.sha256 # 先校验，不通过直接退出 for f in images/*.tar; do docker load -i "$f" done docker images --format 'table {{.Repository}}\t{{.Tag}}\t{{.Size}}'

加载完成后，用docker tag把镜像统一成 compose 里使用的名字。比如主镜像统一成superset-local:4.1.1，元数据库统一成postgres-local:16。统一命名的好处是：不同批次的离线包可以互换，compose 文件不需要跟着改。

接着改编排文件，核心是三条：删掉所有build:段、把image:指向本地标签、给元数据库加健康检查。

services: postgres: image: postgres-local:16 environment: POSTGRES_USER: superset POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} POSTGRES_DB: superset volumes: - ./data/postgres:/var/lib/postgresql/data healthcheck: # 关键：让 superset 等它真的可连 test: ["CMD-SHELL", "pg_isready -U superset -d superset"] interval: 5s timeout: 5s retries: 20 superset: image: superset-local:4.1.1 depends_on: postgres: condition: service_healthy # 不要写 service_started redis: condition: service_started env_file: - .env ports: - "8088:8088" volumes: - ./superset_config.py:/app/pythonpath/superset_config.py:ro - ./data/uploads:/app/superset/static/assets/uploads

condition: service_healthy是这段的关键。很多“db upgrade 报连接拒绝”的问题，根源就是只写了depends_on的默认语义——容器启动了，但数据库还在初始化，连接自然被拒。加上pg_isready健康检查之后，Superset 会等到元数据库真正接受连接再启动。

superset_config.py挂载成只读是刻意的：避免容器内的进程误写配置，也提醒你所有改动都走宿主机文件。上传目录单独挂出来，是为了容器重建后不会丢掉用户上传的 CSV 和图片资源。

3.3 首次初始化：三条命令的顺序不能乱

镜像就位、编排改好之后，第一次启动要手动跑三条命令。顺序错了会得到各种奇怪的报错，所以我把它们单独抽出来。

# 1) 只起元数据库和缓存，等健康检查通过 docker compose up -d postgres redis docker compose ps # 2) 升级元数据库表结构 docker compose run --rm superset superset db upgrade # 3) 创建管理员账号，密码用引号包住避免特殊字符被 shell 吃掉 docker compose run --rm superset superset fab create-admin \ --username admin \ --firstname Admin \ --lastname User \ --email admin@example.com \ --password 'ChangeMe_2024!' # 4) 初始化默认角色、权限和示例数据 docker compose run --rm superset superset init # 5) 全部服务拉起 docker compose up -d

superset db upgrade做的是元数据库迁移，把表结构推到与当前版本匹配的状态；这一步在跨版本升级时尤其重要，直接跳过会导致后续写入字段不存在。fab create-admin创建的是内置角色体系里的管理员，用户名和邮箱在 4.x 中都是必填，邮箱不用真实可达，但格式要合法。superset init会补齐权限点、创建默认角色，并对示例数据做初始化——这一步跑完，登录页才有完整的菜单结构。

--rm的意思是命令容器执行完立刻删除，避免留下一堆退出状态的容器占空间。第一次跑的时候别加-d，你要看着日志输出，有报错当场就能看见。

启动后用下面这条命令做一次自检，返回200才算真的活了：

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8088/health

3.4 启动之后先看这四处

页面能打开不等于能干活。我一般会按下面四处逐一确认：登录后进“设置 → 关于”，确认版本号是 4.1.1；进“数据源 → 数据库”，看已配置的连接能不能点“测试连接”；随便建一个图表，确认前端渲染没有白屏；最后用管理员账号进“安全 → 列表用户”，确认权限点已初始化。这四步都过了，才敢说这套离线部署是完整的。

如果第 2 步测试连接失败，先别怀疑网络，八成是驱动缺失，翻到第 5 章对应条目按流程处理。

4. 中文化不是改一个环境变量：语言包、字符集与时区三条链路

“中文版”这个词很容易被误解成“改个配置就完事”。实际上界面语言、数据展示、时间显示是三条独立的链路，任何一条没打通，你看到的都是局部中文——菜单是中文的，图表标题却是英文；或者界面中文了，导出的 CSV 打开全是乱码。这一章把三条链路分别说透。

4.1 前端语言包与默认语言配置

Superset 的语言体系分两层：后端用 flask-babel 管理服务端文案，前端用 i18next 管理界面文案。前端翻译文件在构建阶段就被打进产物里，所以“中文版镜像”和“官方镜像”的差别，很大程度上就在这一步——官方产物里中文覆盖率可能不完整，中文版会在构建时补齐或更新语言资源。

运行时切换语言有两个入口：一是用户在个人设置里选语言，二是在superset_config.py里设默认值。

# superset_config.py BABEL_DEFAULT_LOCALE = "zh" # 服务端默认语言，影响邮件、错误提示 LANGUAGES = { "en": {"flag": "us", "name": "English"}, "zh": {"flag": "cn", "name": "Chinese"}, } DEFAULT_TIMEZONE = "Asia/Shanghai" # 按团队所在时区替换

BABEL_DEFAULT_LOCALE决定新用户的初始语言，已经登录过的用户不受影响——他们的选择存在用户配置里，优先级更高。这就是为什么有人改了配置、重启了容器，界面还是英文：得去个人设置里手动切一次，或者清掉浏览器本地存储。LANGUAGES决定语言下拉框里出现哪些选项，只留中英两项能让界面干净不少。

DEFAULT_TIMEZONE影响的是图表的时间轴解读，跟界面语言无关，但混在一起讲容易搞错。它决定服务端如何解释不带时区信息的时间字段，设错了会出现“图表上的数据比数据库里晚八小时”这种经典问题。

提示：改完superset_config.py必须重启 superset 容器才生效，docker compose restart superset就够，不用重建镜像。

4.2 元数据库字符集：乱码问题的源头

界面中文正常，但数据集里的中文列名显示成问号或方块，问题一定在元数据库。Superset 把数据集名称、图表标题、看板描述都存在元数据库里，字符集不对就会在这些位置丢字符。

PostgreSQL 建库时要显式指定编码，不要依赖默认值：

CREATE DATABASE superset WITH ENCODING 'UTF8' LC_COLLATE 'C' LC_CTYPE 'C' TEMPLATE template0;

TEMPLATE template0是为了绕开模板库的字符集约束，保证新库能按你指定编码创建。LC_COLLATE和LC_CTYPE用C是为了排序行为稳定，某些环境下用本地化 collation 会导致索引行为和预期不一致。MySQL 则是另一种情况，必须确认库、表、连接三处都是utf8mb4：

CREATE DATABASE superset CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

连接串也要带上字符集参数，否则客户端和服务器协商出的编码可能不是你想要的。用 PostgreSQL 时连接串里加?client_encoding=utf8；用 MySQL 时加?charset=utf8mb4。这两个参数漏了，元数据库本身没错，但写入路径上仍会出现乱码。

4.3 图表与导出里的中文方框

这一类问题最容易被误判成“汉化不完整”。现象是：界面文字全是中文，但导出的 PNG、PDF 里中文变成一排方框。原因很单纯——容器的精简基础镜像里没有中文字体，渲染引擎找不到字形就用方框代替。

解决方式是在派生镜像里装字体，而不是在运行中的容器里临时装：

FROM superset-local:4.1.1 USER root # 只装 CJK 字体，控制镜像体积 RUN apt-get update \ && apt-get install -y --no-install-recommends fonts-noto-cjk \ && rm -rf /var/lib/apt/lists/* USER superset

--no-install-recommends是必须的，否则一装就是几百兆的推荐包。rm -rf /var/lib/apt/lists/*清理包索引，是减小镜像层的常规做法。装完重建镜像并重新docker save，这个派生镜像要一起进离线包。字体装好之后，导出图片和截图里的中文就正常了，跟语言包没关系。

另外 CSV 导出乱码是另一个问题，通常出在导出文件的编码声明上。如果下游用 Excel 打开出现乱码，多半是文件没有 BOM 头。这个属于使用习惯层面的问题，一般在交付文档里写清楚“用支持 UTF-8 的工具打开”比改代码更实际。

5. 避坑与排查：离线部署里最容易翻车的五个点

下面这五条都是我在不同环境里真实遇到过的，按发生频率排序。每条都按“现象 → 原因 → 解决”写，遇到问题直接对号入座，不用从头排查。

5.1 容器反复退出，日志只有一行

现象：docker compose ps显示 superset 状态Restarting或Exited (1)，日志里只有一行启动失败信息，看不出所以然。

原因：九成是镜像标签没对上，或者架构不匹配。在 ARM 机器上加载了 amd64 的 tar，docker load会成功，但运行时报 exec format error，而且往往被 compose 的重启策略吞掉。另一种情况是 compose 里写的镜像名和你docker tag之后的名称差一个后缀。

解决：先docker inspect <image> --format '{{.Os}}/{{.Architecture}}'确认架构与宿主机uname -m一致；再docker compose config | grep image逐条比对镜像名。把 compose 的restart: always临时改成no，让容器退出后不再重启，错误信息才会留在docker compose logs superset里。

5.2 db upgrade 卡在连接拒绝

现象：执行superset db upgrade后报could not connect to server或连接超时，但docker compose ps里 postgres 明明是 up 状态。

原因：up只代表容器进程起来了，不代表数据库完成初始化并接受连接。PostgreSQL 首次启动要跑初始化脚本，这期间端口是通的但连接会被拒。只写depends_on而没有健康检查条件时，compose 不会等它。

解决：给 postgres 加pg_isready健康检查（见 3.2 的编排示例），并把依赖改成condition: service_healthy。已经很急的情况下，手动docker compose exec postgres pg_isready -U superset反复确认就绪，再跑 upgrade。根治靠编排，不靠sleep 30。

5.3 汉化只生效一半

现象：菜单是中文，但新建图表弹窗、错误提示、部分按钮还是英文；或者换台机器打开就变回英文。

原因：三种可能叠在一起。一是当前登录用户在个人设置里选过 English，用户级配置优先于BABEL_DEFAULT_LOCALE；二是浏览器本地存储里缓存了旧的语言选择；三是镜像里那部分前端文案本来就没有中文翻译，属于覆盖率问题，不是配置问题。

解决：先让用户去个人设置里把语言改成中文，再强刷页面。确认superset_config.py里BABEL_DEFAULT_LOCALE = "zh"且容器已重启。如果个别新版本菜单项仍然英文，那就是语言包覆盖率的问题，只能等对应版本的中文资源补齐，或者自己在语言文件里加条目后重新构建前端产物——这也是中文版镜像存在的意义。

5.4 数据源测试连接报 ModuleNotFoundError

现象：在“数据源 → 数据库”里填好连接串，点测试连接，报No module named 'xxx'，但同样的连接串在宿主机客户端里能连通。

原因：驱动没打进镜像。Superset 通过 SQLAlchemy 方言连接数据库，每种数据库对应一个独立的 Python 驱动包，官方镜像只内置常见几种。你在容器里临时pip install装的包，容器一重建就没了。

解决：在构建机上pip download出对应 wheel，放进离线包，用派生镜像离线安装：

FROM superset-local:4.1.1 USER root COPY wheels/ /tmp/wheels/ # --no-index 强制离线，--find-links 指向本地 wheel 目录 RUN pip install --no-index --find-links=/tmp/wheels \ clickhouse-connect==0.7.19 \ psycopg2-binary==2.9.9 USER superset

参数说明：--no-index会彻底禁用包索引，任何缺失的依赖都会直接失败而不是悄悄联网；--find-links指定本地目录，pip 会从中解析依赖树。装完一定要重建镜像并重新导出 tar，别只在运行中的容器里验证。

注意：驱动版本要跟 SQLAlchemy 2.x 匹配，装完在容器里跑一次python -c "import sqlalchemy; print(sqlalchemy.__version__)"和驱动的 import，确认没有 ABI 冲突再交付。

5.5 上传文件失败，日志里是 PermissionError

现象：上传 CSV、保存图表缩略图时提示失败，容器日志里出现PermissionError: [Errno 13]，指向挂载目录。

原因：Superset 镜像内的进程以非 root 用户运行（常见 uid 是 1000）。宿主机上创建的挂载目录属主是 root，容器内用户没有写权限。superset_config.py只读挂载同理，如果你把它挂成了可写又属主不对，某些初始化步骤会失败。

解决：在宿主机上把挂载目录的属主改成容器内用户的 uid：

# 先确认容器内实际 uid docker compose run --rm superset id # 按输出结果调整，常见是 1000 sudo chown -R 1000:1000 ./data/uploads ./data/postgres

目录权限用750就够，不要图省事chmod 777。另外注意：PostgreSQL 数据目录对权限非常敏感，属主或权限改错会导致数据库拒绝启动，改之前先停容器。

6. 把离线包做成可复用资产：校验脚本与升级路径

单次部署跑通只是及格线。真正省时间的是把这件事做成可复用资产：一份校验脚本、一条明确的升级路径、一套元数据库备份习惯。我的做法是把校验和备份合到一个脚本里，交付时随包附带，接手的人照着跑就行。

#!/usr/bin/env bash set -euo pipefail BACKUP_DIR="./backup/$(date +%Y%m%d_%H%M%S)" mkdir -p "$BACKUP_DIR" # 1) 校验离线包完整性 sha256sum -c sha256/images.sha256 # 2) 元数据库逻辑备份，升级前必做 docker compose exec -T postgres \ pg_dump -U superset -d superset -Fc > "${BACKUP_DIR}/superset.dump" # 3) 记录当前版本，出问题时能说清从哪来 docker compose exec -T superset superset version > "${BACKUP_DIR}/version.txt" # 4) 记录镜像摘要，便于回滚时定位 docker images --digests | grep superset > "${BACKUP_DIR}/images.txt"

pg_dump -Fc生成的是自定义格式备份，比纯 SQL 体积小、恢复快，配合pg_restore可以做单表恢复。-T关掉伪终端，否则在 CI 或定时任务里会因为 TTY 问题失败。版本号和镜像摘要这两份记录看似多余，等真要回滚时就是后悔药——你会清楚地知道当时跑的是哪个镜像、哪个版本。

升级路径建议固定成三步：旧版本环境先跑一遍上面的备份，新镜像加载后执行superset db upgrade，启动后走一遍第 3.4 节的四项目视检查。跨大版本时要注意元数据库迁移不可逆，备份不是可选项。

还有一个容易忽略的细节：离线包的目录结构最好固定下来，images/、sha256/、wheels/、compose/四个目录名不要随批次变化。从那以后我每次交付前都强制走一遍“校验脚本 + 备份脚本 + 四项目视检查”，哪怕这次只改了一个驱动版本。血泪经验是：跳过校验省下的五分钟，通常会在三天后以两小时的排查代价还回来。希望帮到你。

本文还有配套的精品资源，点击获取