简介：这份资源面向需要在无外网环境下搭建数据可视化平台的企业与开发者，提供 Superset 4.1.1 中文版的 Docker 离线部署方案，将容器化部署与中文界面结合，降低英文命令行使用门槛。压缩包共 6 个文件，约 524.2MB，以 3 个 tar 镜像包为主，另含 yml 服务编排、py 配置脚本与 env 环境变量文件，分别对应镜像导入、多容器编排、参数配置与连接信息设定。已有 370 人学习下载。资源覆盖离线部署所需的关键环节，读者可据此完成镜像加载、服务启动与配置调整，快速获得可移植、可重复使用的 Superset 运行环境，并在此基础上开展数据探索与可视化分析。

1. 从一台没有外网的机器说起：Superset 4.1.1 中文版离线部署到底难在哪

上周接手一台内网服务器，要求把 Superset 4.1.1 中文版跑起来，机器不通外网，连 pip 源都摸不到。我第一反应是拉个官方镜像完事，结果docker pull直接卡在解析域名那一步，这才意识到离线部署和在线部署根本是两套打法。Superset 这套 BI 环境依赖重、镜像层多、初始化脚本还带数据库迁移，装不好就是容器起来了但页面 500，或者中文乱码、时区错位。这篇记录写给两类人：一是手里只有离线包、要在隔离环境里把 Superset 4.1.1 中文版 Docker 部署跑通的人；二是装过一次但卡在初始化或汉化上、想搞清楚参数取舍的人。下面按「环境清单 → 镜像导入 → 配置编排 → 初始化 → 排错 → 验证」走一遍，命令都能直接抄。

2. 环境清单与版本选型：Superset 4.1.1 离线包该准备什么

离线部署最怕的不是装不上，是装到一半发现少了个依赖包，又没法联网补。所以动手前先把清单列死，版本对齐，后面每一步才有底。

2.1 宿主机与 Docker 版本的最低要求

Superset 4.1.1 官方镜像基于 Python 3.10 构建，对宿主机的要求不算高，但 Docker 版本别太老，否则docker load导入多架构镜像清单时会报invalid manifest。我一般要求：

内存这条别省，4 GB 能跑起来但导入数据集时容易 OOM，我踩过一次，容器被内核直接 kill，日志里只有一行Killed，查了半天才定位到内存。

2.2 离线包到底包含哪几样东西

在线部署一条docker compose up就完事，离线部署得把这几样提前备齐，缺一样都跑不通：

• Superset 4.1.1 中文版镜像 tar 包（superset-4.1.1-zh.tar），这是核心，通常由能联网的机器docker save出来；
• PostgreSQL 镜像 tar 包（元数据库，Superset 官方推荐 PG，别用 SQLite 上生产）；
• Redis 镜像 tar 包（缓存与 Celery broker）；
• docker-compose.yml编排文件；
• superset_config.py配置文件（汉化、时区、密钥都在这）；
• 初始化 SQL 或迁移脚本（首次启动时跑superset db upgrade用）。

提示：镜像 tar 包在导出机器上要和导入机器的架构一致，docker save默认只存当前架构，跨架构（比如 x86 导出、ARM 导入）会失败，导出前用docker inspect确认Architecture字段。

2.3 版本对齐：为什么不能混用 4.0 和 4.1 的配置

Superset 4.x 小版本之间配置项有增删，4.1.1 里FEATURE_FLAGS的默认值和 4.0 不一样，直接拿旧superset_config.py套过来，轻则功能开关不生效，重则启动时报KeyError。我一般做法是：以 4.1.1 镜像内自带的config.py为基准，只覆盖需要改的项，不整份替换。镜像里这个文件路径是/app/superset/config.py，进容器cat一下就能对照，这是离线环境里最靠谱的参照物。

3. 镜像导入与目录规划：把离线包落到正确位置

清单齐了，接下来是把 tar 包变成能用的镜像，再把目录结构搭好。这一步顺序错了，后面编排文件里的挂载路径全对不上。

3.1 docker load 导入镜像并核对标签

把三个 tar 包传到宿主机某个目录，比如/opt/superset-offline/images/，然后逐个导入：

# 进入离线包目录 cd /opt/superset-offline/images/ # 依次导入三个镜像，-i 指定输入文件 docker load -i superset-4.1.1-zh.tar docker load -i postgres-15.tar docker load -i redis-7.tar # 核对导入结果，确认标签和架构 docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

docker load会把 tar 里的镜像层和标签一起还原，导入后docker images应该能看到superset:4.1.1-zh、postgres:15、redis:7三个条目。如果标签显示<none>，说明导出时没打 tag，得用docker tag <IMAGE_ID> superset:4.1.1-zh手动补，否则编排文件里image:字段匹配不上，up的时候会去联网拉，离线环境直接失败。

3.2 目录结构：挂载点提前规划好

Superset 容器里需要持久化的东西不多，但位置要对。我习惯在宿主机建这么一套：

mkdir -p /opt/superset-offline/{config,data/postgres,data/redis,logs}

对应关系是：config/放superset_config.py，data/postgres挂 PG 的数据目录，data/redis挂 Redis 持久化，logs/挂 Superset 日志。这样容器重建时数据不丢，出问题也能直接在宿主机翻日志，不用docker exec进去找。目录权限注意一下，PG 容器里跑的是postgres用户（UID 999），宿主机目录如果权限太严会报Permission denied，我一般chown -R 999:999 data/postgres先放开。

3.3 编排文件的关键字段

docker-compose.yml是离线部署的中枢，几个字段必须改对：

services: superset: image: superset:4.1.1-zh # 必须和 load 进来的标签一致 container_name: superset ports: - "8088:8088" # 宿主机端口:容器端口 volumes: - ./config/superset_config.py:/app/pythonpath/superset_config.py - ./logs:/app/superset/logs environment: - SUPERSET_SECRET_KEY=换成你自己的随机串 # 必改，否则启动报错 - TZ=Asia/Shanghai # 时区，影响图表时间轴 depends_on: - postgres - redis

SUPERSET_SECRET_KEY是硬性要求，4.1.1 启动时如果检测到默认值会直接拒绝启动，生成方式用openssl rand -base64 42。TZ不设的话容器默认 UTC，中文环境下图表时间会差 8 小时，这个坑很隐蔽，页面能开但数据对不上。volumes里配置文件挂到/app/pythonpath/是 Superset 约定的加载路径，挂错位置等于没配。

4. 配置汉化与元数据库初始化：superset_config.py 怎么写

镜像和编排就位，真正决定「中文版能不能用」的是配置文件。这一章把汉化、元数据库连接、缓存三块拆开讲，每块都给可抄的配置。

4.1 汉化配置：语言包和默认语言

Superset 4.1.1 自带多语言支持，中文包在镜像里已经包含，配置里要做的是把默认语言设成简体中文，并确保语言列表里有zh：

# superset_config.py 片段 BABEL_DEFAULT_LOCALE = "zh" LANGUAGES = { "en": {"flag": "us", "name": "English"}, "zh": {"flag": "cn", "name": "简体中文"}, }

BABEL_DEFAULT_LOCALE控制未登录页和默认界面语言，设成zh后首次访问就是中文。LANGUAGES字典决定右上角语言切换下拉里有哪些选项，只留中英文够用，加多了反而让用户困惑。改完重启容器生效，如果页面还是英文，先清浏览器缓存，再看容器日志里有没有Unable to load locale之类的报错，多半是配置文件没挂进去。

4.2 元数据库连接：指向离线 PG 容器

元数据库连接串写在配置里，指向编排文件里的 PG 服务名：

# 元数据库连接，host 用 compose 服务名 postgres SQLALCHEMY_DATABASE_URI = ( "postgresql+psycopg2://superset:你的密码@postgres:5432/superset" )

这里postgres是 compose 里的服务名，容器间通过 Docker 内置 DNS 解析，不用写 IP。密码要和docker-compose.yml里 PG 服务的POSTGRES_PASSWORD一致，我见过有人两处写不一样，容器起来了但 Superset 连库超时，日志里could not connect to server翻半天。另外psycopg2驱动镜像里已带，离线环境不用额外装。

4.3 缓存与 Celery：Redis 连接别写 localhost

异步查询和缓存都走 Redis，连接串同样用服务名：

# 缓存配置 CACHE_CONFIG = { "CACHE_TYPE": "RedisCache", "CACHE_DEFAULT_TIMEOUT": 300, "CACHE_KEY_PREFIX": "superset_", "CACHE_REDIS_URL": "redis://redis:6379/1", } # Celery broker，异步 SQL 实验室用 CELERY_CONFIG = {"broker_url": "redis://redis:6379/0"}

CACHE_REDIS_URL里的redis是服务名，写成localhost在容器里指向容器自己，必然连不上，这是新手最常翻的车。/1和/0是 Redis 的逻辑库编号，缓存和 broker 分库避免键冲突，这个细节官方文档提得少但实际部署很有用。

4.4 首次初始化：db upgrade 与创建管理员

配置挂好后，第一次启动前要跑数据库迁移和建管理员账号，这两步在离线环境里必须手动执行：

# 启动依赖服务，先不启 superset docker compose up -d postgres redis # 等 PG 就绪后，进 superset 容器跑迁移 docker compose run --rm superset superset db upgrade # 创建管理员，-u 用户名 -p 密码 -e 邮箱 -f 名 -l 姓 docker compose run --rm superset superset fab create-admin \ --username admin --password 你的密码 \ --email admin@example.com --firstname Admin --lastname User # 初始化默认角色权限 docker compose run --rm superset superset init

db upgrade建表，create-admin建账号，init同步权限，三步顺序不能乱，少了init管理员登录后看不到任何菜单。--rm让临时容器跑完即删，不留垃圾。迁移过程中如果报relation already exists，说明之前跑过一半，加--force不推荐，我一般直接清空 PG 数据目录重来，离线环境数据本来就可重建。

5. 离线部署避坑：五条血泪排查记录

离线环境没有搜索引擎兜底，出问题只能靠日志和现象反推。下面五条是我和同事实际踩过的，按「现象 → 原因 → 解决」记下来。

5.1 容器反复重启，日志只有 Killed

现象：docker compose up后 superset 容器状态在Restarting和Exited之间循环，docker logs只有一行Killed。原因：宿主机内存不足，Superset 启动时加载元数据和缓存峰值超过可用内存，被内核 OOM killer 干掉。解决：free -h确认可用内存，低于 4 GB 就加内存或调小CACHE_DEFAULT_TIMEOUT，也可以在 compose 里给 superset 服务加mem_limit: 3g限制，让它自己报错而不是被系统杀。

5.2 页面能开但图表全报 500

现象：登录正常，仪表盘能打开，但任何图表都显示500 Internal Server Error。原因：元数据库连接串里的密码和 PG 容器实际密码不一致，或者 PG 容器还没就绪 superset 就启动了。解决：先docker compose logs postgres确认 PG 正常监听，再核对两处密码；编排文件里depends_on只保证启动顺序不保证就绪，稳妥做法是给 superset 加restart: on-failure，让它连不上时重试。

5.3 中文界面部分菜单仍是英文

现象：大部分界面汉化了，但某些菜单项还是英文。原因：Superset 4.1.1 的中文翻译覆盖率不是 100%，部分新增功能词条没有对应翻译，这是语言包本身的缺口，不是配置问题。解决：接受现状，或者自己维护一份messages.po补翻译后重新编译，离线环境里我一般不动它，够用就行，别在这上面耗时间。

5.4 docker load 后镜像标签是 none

现象：docker load成功，但docker images里 superset 那行REPOSITORY和TAG都是<none>。原因：导出机器上docker save时镜像本身就没打 tag，或者用了docker save <IMAGE_ID>而非docker save repo:tag。解决：docker tag <IMAGE_ID> superset:4.1.1-zh手动补标签，再改编排文件里的image字段对齐。根治办法是导出时就用docker save -o xxx.tar superset:4.1.1-zh带标签导出。

5.5 时区错位导致时间轴图表偏移

现象：图表数据正确，但时间轴上的点整体偏移 8 小时。原因：容器TZ没设或设成了 UTC，Superset 按容器时区解释时间字段。解决：编排文件environment里加TZ=Asia/Shanghai，同时确认元数据库里存的时间戳类型，timestamp without time zone和timestamp with time zone处理方式不同，前者依赖应用层时区，后者依赖数据库时区，两边要统一。

6. 装完怎么验证：三步确认 Superset 4.1.1 真的跑通了

容器Up不等于部署成功，我见过太多「状态正常但用不了」的情况。验证要分三层：服务层、功能层、数据层，每层都有明确的通过标准。

6.1 服务层：健康检查与端口连通

先确认三个容器都在跑且健康：

# 查看容器状态，STATUS 列应为 Up (healthy) 或 Up docker compose ps # 直接请求健康检查端点，返回 {"status": "OK"} 才算通 curl -s http://localhost:8088/health

/health是 Superset 内置的健康检查端点，返回{"status": "OK"}说明 Flask 应用和元数据库连接都正常。如果返回 502 或超时，回看第 5 章的排查记录。端口方面8088是默认端口，改过的话以编排文件为准。

6.2 功能层：登录、建数据集、出图

服务通了只是第一步，真正的验证是走一遍完整链路：

1. 浏览器访问http://宿主机IP:8088，用第 4 章建的管理员账号登录，确认界面是中文；
2. 进「数据集」页面，连一个测试数据源（离线环境可以用 PG 里自建一张小表），确认能预览数据；
3. 基于该数据集建一个简单图表，选时间轴类型，确认时间显示正确、无 500 报错；
4. 把图表加进仪表盘，刷新页面确认持久化生效。

这四步走完，说明汉化、元数据库、缓存、权限四条链路都通了。任何一步卡住，对应回看第 4 章的配置项。

6.3 数据层：重启后数据不丢

离线部署最容易被忽略的是持久化验证。执行一次完整重启：

# 停掉所有容器但保留数据卷 docker compose down # 重新拉起 docker compose up -d # 等待就绪后再次检查健康 sleep 30 && curl -s http://localhost:8088/health

重启后重新登录，确认之前建的数据集和仪表盘还在，说明data/postgres挂载生效。如果数据没了，检查编排文件里 PG 服务的volumes是否指向宿主机目录而非匿名卷。这一步我每次部署完都强制走一遍，因为持久化配错在首次部署时完全看不出来，等到容器重建才发现就晚了。

从那以后我每次离线部署 Superset，都先把/health和重启验证这两步写进交付清单，不跑完不算完。希望帮到你。

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