简介这份资源面向需要在无外网环境下搭建数据可视化平台的企业与开发者提供 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。我一般要求组件最低版本建议版本说明操作系统CentOS 7.9 / Ubuntu 20.04Ubuntu 22.04内核 4.x 以上即可Docker Engine20.1024.x低于 20.10 对 OCI 镜像支持不全Docker Composev2.0插件式v2.20用docker compose而非docker-compose内存4 GB8 GBSuperset 元数据库 Redis 缓存吃内存磁盘20 GB 空闲40 GB镜像层 元数据 日志内存这条别省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 brokerdocker-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.pydata/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换成你自己的随机串 # 必改否则启动报错 - TZAsia/Shanghai # 时区影响图表时间轴 depends_on: - postgres - redisSUPERSET_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 ( postgresqlpsycopg2://superset:你的密码postgres:5432/superset )这里postgres是 compose 里的服务名容器间通过 Docker 内置 DNS 解析不用写 IP。密码要和docker-compose.yml里 PG 服务的POSTGRES_PASSWORD一致我见过有人两处写不一样容器起来了但 Superset 连库超时日志里could not connect to server翻半天。另外psycopg2驱动镜像里已带离线环境不用额外装。4.3 缓存与 CeleryRedis 连接别写 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 adminexample.com --firstname Admin --lastname User # 初始化默认角色权限 docker compose run --rm superset superset initdb 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没设或设成了 UTCSuperset 按容器时区解释时间字段。解决编排文件environment里加TZAsia/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 功能层登录、建数据集、出图服务通了只是第一步真正的验证是走一遍完整链路浏览器访问http://宿主机IP:8088用第 4 章建的管理员账号登录确认界面是中文进「数据集」页面连一个测试数据源离线环境可以用 PG 里自建一张小表确认能预览数据基于该数据集建一个简单图表选时间轴类型确认时间显示正确、无 500 报错把图表加进仪表盘刷新页面确认持久化生效。这四步走完说明汉化、元数据库、缓存、权限四条链路都通了。任何一步卡住对应回看第 4 章的配置项。6.3 数据层重启后数据不丢离线部署最容易被忽略的是持久化验证。执行一次完整重启# 停掉所有容器但保留数据卷 docker compose down # 重新拉起 docker compose up -d # 等待就绪后再次检查健康 sleep 30 curl -s http://localhost:8088/health重启后重新登录确认之前建的数据集和仪表盘还在说明data/postgres挂载生效。如果数据没了检查编排文件里 PG 服务的volumes是否指向宿主机目录而非匿名卷。这一步我每次部署完都强制走一遍因为持久化配错在首次部署时完全看不出来等到容器重建才发现就晚了。从那以后我每次离线部署 Superset都先把/health和重启验证这两步写进交付清单不跑完不算完。希望帮到你。本文还有配套的精品资源点击获取