简介这份资源面向需要在无外网环境中搭建数据可视化平台的企业运维与开发者提供 Superset 4.1.1 中文版的 Docker 离线部署方案解决内网环境下镜像拉取困难、部署流程繁琐的问题。压缩包共 6 个文件约 524.2MB包含 3 个 tar 镜像包Superset 中文版、PostgreSQL 14、Redis 7、1 个 docker-compose.yml 服务编排文件、1 个 superset_config.py 配置脚本和 1 个 .env 环境变量文件覆盖容器启动、数据库连接与安全认证等关键配置。目前已有 368 人学习。通过这套文件读者可一次性获取离线镜像与编排配置快速完成多容器协同部署并借助中文界面降低使用门槛适合具备基础 Docker 操作能力、希望在内网快速落地数据探索与可视化环境的技术人员参考。1. 内网环境下的 Superset 4.1.1 中文版离线部署为什么值得折腾很多做数据分析的团队都遇到过这种局面服务器在内网没有外网出口但业务方又需要一个能拖拽出图、能配看板、还能显示中文的数据可视化平台。Superset 4.1.1 中文版 Docker 离线部署这套资源解决的就是这个场景。它把镜像、依赖、汉化文件、初始化脚本全部打包好你只需要把文件拷进内网机器按顺序执行几条命令就能跑起一个带中文界面的 Superset。适合谁适合手里有 Docker 基础、需要在内网快速搭一套 BI 看板、又不想从零编译 Python 依赖的运维或数据工程师。这套东西不是官方发行版是社区在官方 4.1.1 基础上做了中文化和离线适配的版本用之前得清楚它的边界。2. 拆开离线包镜像分层、汉化注入与初始化逻辑2.1 离线包里的三样东西镜像、配置、脚本拿到这个资源别急着docker load。先看清楚里面有什么。通常离线包会分成三个目录images/放superset-4.1.1-zh.tar这类镜像归档文件config/放superset_config.py和docker-compose.ymlscripts/放初始化脚本和汉化补丁。镜像本身是基于官方apache/superset:4.1.1做的二次构建把中文语言包、字体、时区配置都塞进去了。配置目录里的superset_config.py是关键它决定了元数据库连哪里、缓存用什么、密钥怎么设。脚本目录一般有init.sh和start.sh前者负责建表、建管理员、导入示例数据后者负责拉起容器。我一般会先看docker-compose.yml里定义了哪些服务。典型的离线部署会包含superset、postgres或mysql、redis三个容器。Superset 自身不存元数据它依赖一个关系型数据库存仪表板、图表、用户信息依赖 Redis 做缓存和异步任务队列。离线包里如果已经把 Postgres 和 Redis 的镜像也打进去了那部署会省很多事如果没打你得自己准备这两个基础镜像的离线包。注意不同来源的离线包目录结构可能不一样但核心逻辑不变——镜像、配置、初始化脚本三件套。拿到包先tar -tf看一眼镜像归档里的镜像名和标签别直接 load 完发现标签对不上。2.2 汉化是怎么注入的语言包替换与前端编译产物Superset 的中文支持分两层。后端层面Flask-Babel 负责翻译 Python 端的提示信息离线包一般会把superset/translations/zh/LC_MESSAGES/messages.mo编译好放进去。前端层面React 组件的文案在构建时就已经打包进静态资源了所以汉化版镜像在docker build阶段就替换了前端源码里的语言文件重新编译了superset-frontend。这意味着你拿到的镜像里前端静态文件已经是中文的不需要在运行时再做什么。但这里有个坑Superset 的语言切换依赖用户配置里的locale字段。初始化管理员账号后你得手动进Settings - User Profile把语言改成Chinese (Simplified)或者直接在元数据库里改ab_user表的locale字段。离线包里的init.sh通常会带一条 SQL 或一个 Flask 命令来做这件事但不同版本脚本写法不一样得自己确认。2.3 元数据库初始化建表、迁移与管理员创建Superset 第一次启动前必须初始化元数据库。官方推荐用superset db upgrade做迁移用superset fab create-admin建管理员用superset init初始化角色和权限。离线部署时这些命令要在容器内执行。下面是一个典型的初始化脚本片段#!/bin/bash # 离线初始化 Superset 元数据库 set -e # 等待 Postgres 就绪离线环境没有外网只能轮询本地端口 until pg_isready -h postgres -p 5432 -U superset; do echo 等待 Postgres 启动... sleep 2 done # 执行数据库迁移创建所有元数据表 superset db upgrade # 创建管理员账号密码从环境变量读取 superset fab create-admin \ --username admin \ --firstname Superset \ --lastname Admin \ --email adminexample.com \ --password ${ADMIN_PASSWORD} # 初始化默认角色和权限 superset init # 可选导入示例数据离线环境建议跳过以节省时间 # superset load_examples这段脚本的逻辑很直白先等数据库可用再跑迁移。superset db upgrade会读取superset_config.py里的SQLALCHEMY_DATABASE_URI连到 Postgres 上建表。create-admin命令在 4.x 版本里已经换成fab子命令老教程里写的superset create-admin会报错。superset init负责把权限同步到角色上这一步不做的话管理员登录进去也看不到菜单。参数方面ADMIN_PASSWORD建议在docker-compose.yml里通过环境变量注入不要硬编码在脚本里。pg_isready的-h和-p要跟 compose 里 Postgres 服务的名称和端口一致。如果用的是 MySQL把等待命令换成mysqladmin ping就行。3. 离线部署实操从 load 镜像到看板可访问3.1 导入镜像与目录挂载第一步是把镜像归档 load 进本地 Docker。假设离线包放在/opt/superset-offline执行# 导入 Superset 主镜像 docker load -i /opt/superset-offline/images/superset-4.1.1-zh.tar # 如果离线包里带了 Postgres 和 Redis 镜像一并导入 docker load -i /opt/superset-offline/images/postgres-15.tar docker load -i /opt/superset-offline/images/redis-7.tar # 确认镜像已存在 docker images | grep -E superset|postgres|redisdocker load会把 tar 里的镜像层解压到本地镜像库。执行完用docker images确认标签。如果标签显示为none说明归档时没打标签需要手动docker tag一下。离线包里的docker-compose.yml通常会引用固定标签标签对不上 compose 会报image not found。接下来是目录挂载。Superset 容器需要把本地的superset_config.py挂进去覆盖镜像里的默认配置。compose 文件里一般这样写services: superset: image: superset:4.1.1-zh volumes: - ./config/superset_config.py:/app/pythonpath/superset_config.py - ./data:/app/superset_home environment: - SUPERSET_SECRET_KEYyour_secret_key_here - ADMIN_PASSWORDadmin123 ports: - 8088:8088/app/pythonpath/superset_config.py是 Superset 读取配置的固定路径挂载覆盖后容器启动就会用你的配置。/app/superset_home用来持久化上传的 CSV、生成的缩略图等。SUPERSET_SECRET_KEY必须设不设的话 Superset 启动会报错而且这个 key 一旦设定就不要改改了所有加密的数据库连接密码都会失效。3.2 配置 superset_config.py 的关键参数superset_config.py是离线部署里最需要动手改的文件。下面列出几个必须关注的参数# 元数据库连接串指向 compose 里的 postgres 服务 SQLALCHEMY_DATABASE_URI postgresql://superset:supersetpostgres:5432/superset # Redis 缓存配置用于看板查询缓存和异步任务 CACHE_CONFIG { CACHE_TYPE: RedisCache, CACHE_DEFAULT_TIMEOUT: 300, CACHE_KEY_PREFIX: superset_, CACHE_REDIS_URL: redis://redis:6379/0, } # 异步查询结果后端同样走 Redis RESULTS_BACKEND RedisCache( hostredis, port6379, key_prefixsuperset_results_, db1 ) # 关闭遥测离线环境没必要往外发数据 SUPERSET_ENV production FEATURE_FLAGS { ALERT_REPORTS: False, DASHBOARD_RBAC: True, } # 时区设置避免看板时间显示错乱 DEFAULT_TIMEZONE Asia/ShanghaiSQLALCHEMY_DATABASE_URI里的主机名postgres是 compose 服务名Docker 内部 DNS 会解析。如果你把数据库放在宿主机上这里要改成宿主机的内网 IP。CACHE_REDIS_URL同理。FEATURE_FLAGS里DASHBOARD_RBAC建议打开方便按角色控制看板权限。DEFAULT_TIMEZONE设成Asia/Shanghai后新建的图表默认用这个时区但已有图表不会自动改需要手动调整。提示SUPERSET_SECRET_KEY不要写在superset_config.py里通过环境变量注入更安全。如果离线包里的脚本已经写死了记得改掉。3.3 启动顺序与健康检查配置改好后启动顺序有讲究。先起 Postgres 和 Redis等它们健康了再起 Superset。compose 里可以用depends_on配合healthcheck来控制services: postgres: image: postgres:15 healthcheck: test: [CMD-SHELL, pg_isready -U superset] interval: 5s retries: 10 redis: image: redis:7 healthcheck: test: [CMD, redis-cli, ping] interval: 5s retries: 10 superset: depends_on: postgres: condition: service_healthy redis: condition: service_healthy启动命令cd /opt/superset-offline docker compose up -d # 查看容器状态 docker compose ps # 跟踪 Superset 日志确认没有报错 docker compose logs -f superset日志里看到Running on http://0.0.0.0:8088就说明 Web 服务起来了。但这时候还不能登录因为元数据库还没初始化。需要进容器执行初始化脚本docker compose exec superset bash /app/scripts/init.sh初始化完成后浏览器访问http://内网IP:8088用admin和ADMIN_PASSWORD登录。登录后第一件事是进Settings - User Profile确认语言是中文如果不是就手动切一下。4. 避坑与排查离线部署最容易翻车的五个点4.1 镜像标签丢失导致 compose 启动失败现象docker compose up -d报Error response from daemon: manifest for superset:4.1.1-zh not found。原因docker load导入的镜像没有标签或者标签跟 compose 里写的不一致。解决先docker images看实际标签然后用docker tag IMAGE_ID superset:4.1.1-zh手动打上再重新up。4.2 元数据库迁移卡住或报编码错误现象superset db upgrade执行到一半报UnicodeEncodeError或直接卡死。原因Postgres 初始化时没设 UTF-8 编码或者容器 locale 不对。解决在 compose 的 Postgres 服务里加POSTGRES_INITDB_ARGS: --encodingUTF8 --localeC然后删掉数据卷重新初始化。数据卷不删的话编码改不了。4.3 中文界面只显示一半现象菜单是中文但图表类型名称、提示信息还是英文。原因前端汉化只覆盖了部分模块或者浏览器缓存了旧的静态文件。解决强制刷新浏览器CtrlShiftR如果还不行检查镜像里的superset-frontend构建产物是否真的替换了语言文件。有些离线包只汉化了后端前端没重新编译这种情况只能自己改源码重新构建。4.4 Redis 连不上导致看板加载超时现象登录后打开看板一直转圈日志里报ConnectionError: Error 111 connecting to redis:6379。原因Redis 服务没起来或者superset_config.py里的 Redis 地址写错了。解决docker compose ps确认 Redis 容器状态docker compose exec redis redis-cli ping测试连通性。如果 Redis 正常检查配置里的主机名是不是 compose 服务名。4.5 管理员密码设了但登录失败现象create-admin命令执行成功但登录提示用户名或密码错误。原因ADMIN_PASSWORD环境变量没传进容器脚本用了默认空密码或者之前已经初始化过create-admin没覆盖旧账号。解决进容器用superset fab reset-password --username admin --password 新密码重置。如果元数据库里已经有 admincreate-admin会报User already exists不会自动改密码。5. 进阶技巧离线环境下的数据源接入与看板迁移Superset 跑起来只是第一步真正要用起来还得接数据源。离线环境接数据库有个前提Superset 容器能网络可达目标数据库。常见做法是把 Superset 容器和目标数据库放在同一个 Docker 网络里或者直接用宿主机网络模式。如果目标数据库在另一台内网机器上确保防火墙放行了对应端口。接数据源时驱动是个麻烦事。Superset 默认只带了 SQLite 和 Postgres 的驱动连 MySQL 需要额外装mysqlclient或pymysql。离线环境下没法pip install得提前把 wheel 文件下好在 Dockerfile 里COPY进去安装。我一般会在构建镜像阶段就把常用驱动打进去pip install pymysql mysqlclient psycopg2-binary。如果用的是现成离线包先确认里面有没有这些驱动没有的话自己补一个层。看板迁移是另一个高频需求。比如在测试环境配好了看板要导到生产环境。Superset 提供了superset export-dashboards和superset import-dashboards命令导出的是一个 zip 包里面包含看板定义、图表配置、数据集信息。但注意导出的包不包含数据源连接信息导入后需要手动重新配数据库连接。另外如果看板里用了自定义 SQL 或虚拟数据集导入时可能会因为 SQL 方言差异报错得逐条检查。# 导出看板-f 指定输出文件 superset export-dashboards -f /app/superset_home/dashboard_backup.zip # 导入看板-p 指定导入路径 superset import-dashboards -p /app/superset_home/dashboard_backup.zip导出前建议先superset init确保权限同步否则导入后可能看不到菜单。导入时如果报Dataset not found说明看板依赖的数据集没导进去需要先导数据集再导看板。从那以后我每次做离线部署都会在 load 镜像后先跑一遍docker compose config检查 compose 文件语法再docker compose up -d之前手动确认镜像标签和端口占用。这套流程走下来基本能避开八成以上的翻车点。希望帮到你。本文还有配套的精品资源点击获取