Superset 4.1.1 中文版内网离线部署实战：从镜像到中文生效

简介：本资源面向需要在无外网环境下搭建数据可视化平台的企业运维与开发者，提供 Superset 4.1.1 中文版的 Docker 离线部署方案，解决内网环境无法拉取镜像、部署流程繁琐的问题。压缩包共 6 个文件，以 3 个 tar 镜像包为主，涵盖 Superset 中文版、PostgreSQL 与 Redis 运行所需镜像，另含 1 个 yml 服务编排文件、1 个 py 配置文件和 1 个 env 环境变量文件，整体约 524.2MB，导入后即可离线启动。资源将环境变量、应用配置与服务编排分层组织，便于按需修改数据库连接、端口映射与认证参数，同时预置镜像省去联网下载环节，适合具备基础 Docker 使用经验、希望快速在内网落地中文数据探索平台的读者。目前已有 368 人学习下载，可作为离线部署与后续版本维护的参考。

1. 从一次内网部署翻车说起：Superset 4.1.1 中文版离线装法

上个月帮一个做数据报表的团队在内网环境里部署 Superset 4.1.1 中文版，原以为拉个镜像、跑个docker compose up就完事，结果卡了整整两天。内网没有外网出口，pip install全部超时，前端静态资源加载不出来，中文语言包也没生效，登录进去还是满屏英文。这套环境在数据团队里其实很常见——Superset 做 BI 看板、接 ClickHouse 或 MySQL 出图，但一旦落到离线内网，Docker 镜像怎么带进去、Python 依赖怎么预装、中文怎么配，每一步都是坑。这篇记录的是我实际走通的一套离线部署流程，从镜像准备到中文生效再到验证跑通，适合需要在无外网环境落地 Superset 的运维和开发照着复现。

2. 环境准备：离线包里到底要装哪些东西

2.1 版本组合与依赖清单

Superset 4.1.1 这个版本对 Python 和数据库驱动比较敏感，我一般会先把版本钉死，避免装到一半发现依赖冲突。下面这套组合是我在内网跑通的基线：

离线环境的核心难点是：Superset 镜像本身可以docker save带进去，但它运行时还会去拉 Python 包和前端资源。所以离线包必须包含三部分——基础镜像 tar 包、Python wheel 离线包、以及中文语言包。

2.2 在有网机器上准备离线镜像

先在一台能联网的机器上把镜像拉下来并导出。我习惯用官方镜像做基底，再叠加中文语言包：

# 拉取 Superset 4.1.1 官方镜像 docker pull apache/superset:4.1.1 # 导出为 tar 包，方便拷贝进内网 docker save apache/superset:4.1.1 -o superset-4.1.1.tar # 同时把 PostgreSQL 和 Redis 镜像也导出 docker pull postgres:14 docker pull redis:7 docker save postgres:14 -o postgres-14.tar docker save redis:7 -o redis-7.tar

docker save会把镜像所有层打包成一个 tar，体积通常在 1GB 左右。参数-o指定输出文件名，拷贝时用移动硬盘或内网文件服务器传进去。注意不要用docker export，那个导出的是容器文件系统，会丢失镜像元数据，导入后跑不起来。

2.3 Python 依赖离线包的制作

Superset 启动时会检查 Python 依赖，离线环境必须提前把 wheel 包下好。这一步最容易翻车，因为有些包需要编译，纯pip download拿到的可能是源码包：

# 在联网机器上创建依赖目录 mkdir -p /opt/superset-offline/wheels cd /opt/superset-offline # 下载 Superset 4.1.1 及其依赖的 wheel 包 pip download apache-superset==4.1.1 \ --dest ./wheels \ --platform manylinux2014_x86_64 \ --python-version 310 \ --only-binary=:all: # 补充数据库驱动，按实际用的库选 pip download psycopg2-binary==2.9.9 \ --dest ./wheels \ --platform manylinux2014_x86_64 \ --python-version 310 \ --only-binary=:all:

--platform和--python-version必须和目标环境一致，否则下下来的 wheel 装不上。--only-binary=:all:强制只下二进制包，避免拿到需要现场编译的源码包。如果某个包没有对应平台的 wheel，就得在联网机器上先编译好再打包，这一步没有捷径。

3. 离线导入与容器启动：把镜像和依赖搬进内网

3.1 导入镜像并验证

把 tar 包拷进内网机器后，逐个导入：

# 导入三个镜像 docker load -i superset-4.1.1.tar docker load -i postgres-14.tar docker load -i redis-7.tar # 验证镜像是否导入成功 docker images | grep -E "superset|postgres|redis"

docker load会还原镜像的所有层和标签，导入后docker images应该能看到apache/superset:4.1.1、postgres:14、redis:7三个条目。如果标签显示为<none>，说明导出时镜像被重新 tag 过，需要手动docker tag补上。

3.2 编写 docker-compose 编排文件

离线环境不能用官方 compose 文件里那些在线拉取的配置，我一般会自己写一份精简版，把依赖挂载进去：

# docker-compose.yml version: "3.8" services: superset: image: apache/superset:4.1.1 container_name: superset ports: - "8088:8088" volumes: - ./wheels:/opt/wheels # 挂载离线 wheel 包 - ./superset_config.py:/app/superset_config.py - ./translations:/app/translations # 中文语言包 environment: - SUPERSET_SECRET_KEY=your_secret_key_here - PYTHONPATH=/app depends_on: - postgres - redis command: > /bin/bash -c " pip install --no-index --find-links=/opt/wheels apache-superset==4.1.1 && superset db upgrade && superset fab create-admin --username admin --firstname Admin --lastname User --email admin@example.com --password admin && superset init && superset run -h 0.0.0.0 -p 8088 " postgres: image: postgres:14 container_name: superset-db environment: - POSTGRES_USER=superset - POSTGRES_PASSWORD=superset - POSTGRES_DB=superset volumes: - ./pgdata:/var/lib/postgresql/data redis: image: redis:7 container_name: superset-redis ports: - "6379:6379"

这里的关键是pip install --no-index --find-links=/opt/wheels，--no-index禁止联网索引，--find-links指定本地 wheel 目录。superset db upgrade初始化元数据库表结构，superset fab create-admin建管理员账号，superset init初始化权限和角色。这几步顺序不能乱，否则会报表不存在或权限错误。

3.3 中文语言包挂载与配置

中文版的核心是语言包和配置。superset_config.py里要显式指定语言：

# superset_config.py import os # 数据库连接，指向 compose 里的 postgres 服务 SQLALCHEMY_DATABASE_URI = "postgresql://superset:superset@postgres:5432/superset" # 密钥，必须设置且不能泄露 SECRET_KEY = os.environ.get("SUPERSET_SECRET_KEY", "your_secret_key_here") # 默认语言设为中文 BABEL_DEFAULT_LOCALE = "zh" LANGUAGES = { "zh": {"flag": "cn", "name": "Chinese"}, "en": {"flag": "us", "name": "English"}, } # 关闭在线地图等需要外网的功能 FEATURE_FLAGS = { "ENABLE_TEMPLATE_PROCESSING": True, }

BABEL_DEFAULT_LOCALE设为zh后，新登录用户默认中文。LANGUAGES字典决定语言切换菜单里有哪些选项。如果中文没生效，先检查translations目录是否挂载正确，再确认superset init是否在语言包挂载后执行——顺序反了的话，Babel 编译时读不到中文翻译。

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

4.1 现象：pip install 报 Could not find a version

原因：--find-links目录里缺少某个依赖的 wheel，或者 wheel 的平台标签不匹配。离线环境 pip 不会去 PyPI 找，找不到就直接报错。

解决：在联网机器上用pip download时加--platform manylinux2014_x86_64 --python-version 310，确保和目标环境一致。如果某个包确实没有对应 wheel，就在联网机器上pip wheel编译好再拷进去。我一般会多下一个pip和setuptools的 wheel 备用，因为容器内 pip 版本可能过旧。

4.2 现象：superset db upgrade 卡住或报连接超时

原因：compose 里depends_on只保证容器启动顺序，不保证 PostgreSQL 已经 ready。Superset 启动时数据库还没初始化完，连接就失败了。

解决：在 command 里加等待逻辑，或者用healthcheck。我一般会在superset db upgrade前加一段循环检测：

until pg_isready -h postgres -p 5432 -U superset; do echo "waiting for postgres..." sleep 2 done

pg_isready是 PostgreSQL 自带的检测命令，返回 0 表示可以接受连接。这段逻辑放在 compose 的 command 里，确保数据库就绪后再执行升级。

4.3 现象：登录后界面还是英文

原因：BABEL_DEFAULT_LOCALE设了但没生效，或者superset init在语言包挂载前执行了，Babel 没编译到中文翻译。

解决：确认translations目录挂载到了/app/translations，然后重新执行superset init。如果还不行，进容器手动跑pybabel compile -d /app/translations强制编译。另外检查浏览器语言设置，Superset 会优先读用户 profile 里的语言偏好，新用户才用BABEL_DEFAULT_LOCALE。

4.4 现象：前端静态资源 404，页面样式全乱

原因：Superset 4.x 的前端资源在镜像里是预构建的，但如果挂载覆盖了/app/superset/static目录，或者superset init没跑完，资源就没生成。

解决：不要挂载覆盖/app/superset/static，只挂载配置和语言包。如果确实需要自定义前端，得在联网机器上npm run build后把dist目录拷进去。离线环境我一般直接用官方镜像的预构建资源，不动前端。

4.5 现象：容器启动后自动退出，日志显示 SECRET_KEY 未设置

原因：SUPERSET_SECRET_KEY环境变量没传进去，或者superset_config.py里SECRET_KEY为空。Superset 4.1.1 强制要求设置密钥，否则拒绝启动。

解决：在 compose 的environment里显式传SUPERSET_SECRET_KEY，并在superset_config.py里用os.environ.get读取。密钥用openssl rand -base64 42生成，不要用默认值。这个密钥一旦设定不要随意更改，否则已加密的数据库连接密码会解不开。

5. 装完怎么验证：三步确认中文版真的跑通了

5.1 容器状态与日志检查

启动后先看容器是否稳定运行：

# 查看容器状态 docker compose ps # 跟踪 superset 日志，确认没有报错 docker compose logs -f superset | head -50

docker compose ps里三个服务都应该是Up状态。日志里看到superset run启动、Listening on 0.0.0.0:8088就说明主进程起来了。如果看到Error或Traceback，按第 4 章的排查点逐个对。

5.2 登录验证与中文界面确认

浏览器打开http://内网IP:8088，用superset fab create-admin建的账号登录。登录后重点看三处：

如果登录页还是英文，先别急着改配置，用无痕窗口再试一次——浏览器可能缓存了旧的 locale。确认中文生效后，随便建一个数据库连接测试一下元数据库读写是否正常。

5.3 一个我每次都会跑的习惯

从那以后我每次离线部署 Superset，都会在superset init之后强制走一遍superset db upgrade的幂等检查，再手动pybabel compile -d /app/translations编译一次语言包。这两个动作看起来多余，但能挡住九成的「装完看着正常、用两天就报错」的玄学问题。离线环境没有后悔药，镜像和依赖一旦带错，重新传一遍就是半天。希望帮到你。

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