简介面向需要在内网或无外网环境中落地数据可视化的运维与开发人员这份资源提供 Superset 4.1.1 中文版 Docker 离线部署的完整文件集。压缩包共6个文件内含3个 Docker 镜像 tar 包Superset 中文镜像、Redis 7、PostgreSQL 14以及 docker-compose.yml 服务编排文件、superset_config.py 配置文件和 .env 环境变量文件总大小约524.2MB。整套离线包将中文界面、服务编排、镜像文件与常用配置一并整理好部署时可减少从源码编译和插件安装的额外工作。借助这些文件用户无需逐个下载镜像或对照英文文档即可在离线环境下启动 Superset并通过中文界面完成数据探索与可视化。资源对不了解命令行的初学者也较友好配置项和启动方式均已梳理清楚已有 364 人学习下载适合企业数据分析团队和希望快速搭建可视化平台的开发者使用部署后可通过浏览器访问可视化看板并利用图表、仪表盘与 SQL 查询能力快速产出分析结果。1. 离线内网跑通 Superset 4.1.1 中文版先说说为什么这件事值得做做数据平台的人迟早会碰到一个绕不开的场景服务器在隔离网段数据库在内网连包管理器都够不着却要把一套能用的 BI 看板搭起来。Superset 4.1.1 中文版加 Docker 离线部署就是为这种环境准备的。它的核心思路不复杂在能联网的机器上把镜像和依赖打成离线包搬到内网用 docker load 导进去再做语言、数据库和账号的初始化。这篇笔记把这条路径一步步拆开包括哪些资源必须在联网机器上提前备好、启动参数怎么设、汉化和字体怎么处理以及离线环境里最容易让人翻车的几个坑。适合正在内网搭数据可视化平台、又不想让数据出网的工程师照着做。2. 离线部署前的资源盘点在联网机器上把三样东西备齐离线部署不是在内网机器上凭空变出东西九成工作其实发生在能联网的那台机器上。我一般会把准备阶段拆成三块Superset 镜像本身、元数据库镜像如果内网没有、以及一组配置文件和中文字体。这三样东西在联网机器上准备好和内网机器约定好目录和路径后面就顺了。2.1 版本锁定为什么是 4.1.1 而不是 latest用 latest 标签做离线部署是第一个坑。在联网机器上三个月前拉的 latest 和今天拉的 latest 不是同一个东西镜像 ID 不同底层依赖版本也不同。离线环境没有后悔药一旦内网机器上跑出问题没法重新拉一个来对比只能干瞪眼。所以我在准备阶段第一件事就是锁死版本标签明确写成 apache/superset:4.1.1。拉取命令很简单docker pull apache/superset:4.1.1 docker images | grep superset执行完 docker images 后记下对应的 IMAGE ID。这个 ID 在内网导入后要用来核对防止传输过程中镜像内容被改掉。为什么要用官方镜像而不是自己 pip 装一个因为官方镜像里已经带好了 superset 命令行工具、Python 环境和 gunicorn入口脚本也是现成的离线环境下自己用 pip 装很容易缺系统依赖比如编译需要的 gcc、libffi到时候连 pip 源都够不着局面很难收拾。2.2 镜像导出docker save 与 docker load 的完整对应镜像拉下来之后要打包带走。常见做法是直接用 docker save 配合 gzip 压缩而不是裸导出一个大 tar。Superset 镜像本身不小压缩一下能省不少传输时间尤其是要走跳板机或者移动硬盘的时候。docker save apache/superset:4.1.1 | gzip superset-4.1.1.tar.gz md5sum superset-4.1.1.tar.gz superset-4.1.1.md5 ls -lh superset-4.1.1.tar.gz第一条命令把镜像层打包并通过管道直接压缩成 tar.gz第二条命令生成校验文件这是离线传输最容易忽略的一步。内网环境往往要经过多手拷贝加一个 md5 校验能第一时间发现文件损坏省得在内网机器上 load 到一半报错才回头排查。如果内网元数据库也要一并带过去同样方式处理docker pull postgres:15-alpine docker save postgres:15-alpine | gzip postgres-15-alpine.tar.gz这里要特别注意docker save 和 docker export 是两回事。save 打包的是镜像的完整层结构load 之后能直接跑export 导出的是容器文件系统导回来没有镜像元信息不能用于部署。离线部署必须用 save/load 这条路。2.3 元数据库与初始化依赖离线环境的一次性准备Superset 默认的元数据库是 SQLite试玩没问题但内网正式用我建议换 PostgreSQL 或 MySQL。元数据库只存用户、看板、数据源连接信息这些配置数据不存业务数据业务数据还是在你自己的数仓和 OLAP 里。如果内网已经有现成的 PostgreSQL直接建一个库给 Superset 用就行没有的话就把 postgres:15-alpine 镜像一并离线带过去这是最省事的方案。需要准备的远不止镜像下面是文件清单文件用途是否必须superset-4.1.1.tar.gzSuperset 镜像必须postgres-15-alpine.tar.gz元数据库镜像内网无库时必带superset_config.py覆盖默认配置写入密钥和语言必须NotoSansCJK-Regular.ttc图表中文渲染字体必须clickhouse-connect 等 whl额外数据源驱动按需superset_config.py 和字体文件都在联网机器上提前写好、放好后面章节会给出具体内容。另外如果业务上需要连 ClickHouse、MySQL 这些数据源官方镜像未必自带对应驱动离线环境下 pip 装不了所以要在联网机器上把 whl 包和依赖一起下载好拷进内网。这一步很容易被漏掉等你在内网建数据源的时候才发现驱动缺失又要折腾一轮。3. 从 docker load 到容器跑起来内网机器上的启动全流程资源备齐之后内网机器上的操作反而比准备阶段简单但每一步都要看准。整个流程可以分成四段导入镜像、起容器、初始化元数据库、验证登录。中间任何一步报错都先回头看前一步的输入对不对。3.1 导入镜像并校验 tag别让容器跑成未知版本把打包好的 tar.gz 和 md5 文件拷到内网机器后先做校验再导入。md5sum -c superset-4.1.1.md5 docker load -i superset-4.1.1.tar.gz docker images | grep superset第一条命令比对 md5输出 OK 表示文件完整。第二条命令导入镜像。第三条命令确认镜像是否出现这里重点看仓库名和 TAG如果显示的是 apache/superset:4.1.1 那最好如果 IMAGE ID 对上但 TAG 是空的说明打包来源本身没带 tag这时候要手动补一个docker tag IMAGE_ID apache/superset:4.1.1这一步不做后面 docker run 用 apache/superset:4.1.1 作为镜像名会直接报找不到镜像。离线环境里这种 tag 漂移很常见尤其是当 tar 包来自另一台机器的 load 结果镜像层是完整的tag 元信息却丢了。统一的做法是不管显示成什么样都以 IMAGE ID 为准手动把 tag 固定好。3.2 配置文件与启动命令密钥、语言和挂载一次配齐起容器之前先准备 superset_config.py这一步直接决定后面汉化和安全状态。在宿主机上建一个目录比如 /data/superset把文件放在里面# superset_config.py import os # 离线环境固定密钥避免每次重启 session 失效 SECRET_KEY 内网专用的长随机字符串至少32位不要用默认值 # 显式声明语言集合保证登录页能切到中文 LANGUAGES { zh: {flag: cn, name: Chinese}, en: {flag: us, name: English}, }SECRET_KEY 是 Flask 签名 session 和 CSRF 用的不设的话每次重启容器会话都会失效日志也会报警告。LANGUAGES 里的 zh 就是中文入口默认配置里其实也带中文但一旦用自定义配置覆盖原有的语言声明就不再生效所以必须显式写进去。接下来启动容器docker run -d \ --name superset \ -p 8088:8088 \ -e TZAsia/Shanghai \ -e SUPERSET_CONFIG_PATH/app/superset/superset_config.py \ -v /data/superset/superset_config.py:/app/superset/superset_config.py \ -v /data/superset/data:/app/superset_home \ --restartalways \ apache/superset:4.1.1逐个说参数-d 后台运行--name 固定容器名后面 exec 的时候不用查容器 ID-p 映射 8088 端口-e TZ 把容器时区设成上海解决后面图表时间差 8 小时的问题-e SUPERSET_CONFIG_PATH 告诉 Superset 去读哪个配置文件两个 -v 分别是挂载配置文件和持久化目录--restartalways 让内网机器重启后容器自动起来。这里必须提醒一句/app/superset 是 Python 包的安装目录整个目录挂载上去会把安装好的源码遮住容器直接起不来。只能挂载单文件到 superset_config.py数据目录单独挂到 /app/superset_home这个路径才是 Superset 留给持久化用的。3.3 初始化元数据库与管理员账号容器起来后不要急着访问先做初始化。三条命令按顺序执行docker exec -it superset superset db upgrade docker exec -it superset superset init docker exec -it superset fab create-admin \ --username admin \ --firstname admin \ --lastname admin \ --email adminexample.com \ --password Admin123456第一条 db upgrade 会在元数据库里建表Superset 的所有表结构都由它创建。第二条 init 做角色、权限、默认视图的初始化这一步依赖表已经存在所以顺序不能反。第三条 fab create-admin 创建管理员账号username 和 password 是登录凭证email 可以改成内网实际邮箱。如果后面密码忘了重跑这条命令就能重置不用动数据库。这里建议手动分步执行而不是把三条命令串成一长行。离线环境里一旦中间某条失败分步执行能一眼看出是哪条的问题串在一起只会多花排查时间。3.4 健康检查与登录验证初始化完成后先做基础检查再开浏览器。docker ps | grep superset curl -I http://127.0.0.1:8088/health docker logs superset --tail 50docker ps 确认容器处于 Up 状态curl 请求 /health 端点返回 HTTP/1.1 200 OK 说明服务在响应docker logs 看有没有异常堆栈。如果 curl 通但浏览器访问 http://内网IP:8088 打不开常见原因是宿主防火墙没放行 8088 端口先查防火墙规则别急着怀疑容器。登录页路径是 /login用刚才创建的 admin 账号登录能进首页就算跑通了。4. 中文版汉化与图表字体界面和看板都别再有方块字很多人一开始会去找Superset 中文版的特殊安装包其实官方镜像里已经内置了中文翻译。所谓中文版就是官方镜像加上正确的语言配置再补齐图表渲染需要的中文字体。前者负责界面菜单后者负责看板标题和图例。两步都做到才能算真正的中文环境。4.1 语言配置把 zh 显式写进 LANGUAGES在 3.2 节的 superset_config.py 里LANGUAGES 字典已经写出了 zh 和 en。这里再解释一下为什么必须显式写Superset 的默认配置里虽然有中文但一旦你通过 SUPERSET_CONFIG_PATH 指向自定义配置文件默认配置里的语言集合会被整体覆盖只保留你写进去的内容。如果只写了英文汉化入口就没了。配置做完后重启容器让配置生效docker restart superset重启后打开登录页右上角或右下角会有语言切换入口选择中文后界面立即切换。这个选择会被浏览器记住下次登录还是中文。如果页面上找不到切换入口检查配置里的 LANGUAGES 是否真的生效用 docker exec 进容器看配置加载路径docker exec -it superset python -c from superset import conf; print(conf.get(LANGUAGES))输出里能看到 zh 说明配置已生效看不到就回去查挂载路径和环境变量别急着怀疑镜像有问题。4.2 中文字体缺失导致方块字字体安装与缓存刷新界面汉化完成只是第一步。实际做看板时图表标题、坐标轴、图例很可能渲染成一个个方块。如果是浏览器里这样多半是客户端系统缺字体如果是导出 PNG 图片时方块问题一定在容器里。Superset 的图片导出功能在容器内渲染图表底层用的字体库找不到中文字体就只能画方块。解决办法是在容器内安装一套中文字体。先准备 NotoSansCJK-Regular.ttc 文件放到宿主机 /data/superset 目录下然后进容器操作docker exec -u root -it superset bash mkdir -p /usr/share/fonts/chinese cp /app/superset_home/NotoSansCJK-Regular.ttc /usr/share/fonts/chinese/ fc-cache -fv exit docker restart superset为什么用 -u root 进容器Superset 容器默认用户不是 root没有 /usr/share/fonts 的写权限。为什么先把字体拷到 /app/superset_home 再复制因为这个目录是挂载卷从宿主机放进去立刻可见不用 docker cp 绕一圈。更干净的做法是直接做一个带字体和配置的自定义镜像把环境固化成镜像再往后任何机器上 load 都能用FROM apache/superset:4.1.1 USER root COPY NotoSansCJK-Regular.ttc /usr/share/fonts/chinese/ RUN fc-cache -fv COPY superset_config.py /app/superset/superset_config.py USER superset在内网机器上构建这个镜像不需要联网基础镜像已经在本地了。构建完成后直接跑 docker build -t superset-zh:4.1.1 .后面 run 的时候用这个新镜像名。这种方式的好处是容器重建后所有环境配置一次性恢复不用再进容器手动折腾。4.3 验证汉化效果从登录页到导出图片汉化验证分三步走。登录页切换中文后逐一点开菜单看数据源、仪表板、图表这些核心菜单项是否都是中文。第二步新建一张图表输入中文标题加一个中文图例确认浏览器渲染正常。第三步用 Superset 的导出图片功能导出一张 PNG看导出的图片里中文是否正常。导出图片这一步最容易被忽略也最容易返工。因为导出走的是容器内的渲染流程字体没装进容器的话浏览器里看是好的导出的图却还是方块。凡是用到邮件报告、定时导出场景的必须把 4.2 节的字体安装做完再验收。5. 离线部署避坑五条能省一天的血泪经验离线部署和在线部署的差别在于出了问题没地方查。镜像拉不了文档看不了连对比实验都做不了。下面五条是我实际踩过的坑每一条都能让新手折腾半天以上。5.1 镜像 tag 丢失容器跑成未知版本现象docker load 成功后docker images 里看不到 apache/superset:4.1.1 这个 tagdocker run 报找不到镜像。原因tar 包里的镜像在源机器上就不是标准名字打出来的可能是从另一台机器 load 后没有重新 tagtag 元信息在打包时就是空的。save 只保存镜像层和当前 tag不会自动补全名字。解决load 之后立刻用 docker tag IMAGE_ID apache/superset:4.1.1 固定名字后续所有命令都用这个名字引用。在准备阶段也养成习惯在联网机器上先确认 docker images 里 tag 完整再打包。5.2 配置文件挂载成目录容器秒退现象docker run 后容器状态一直 Exiteddocker logs 里出现 ModuleNotFoundError 或者找不到 superset 可执行命令的错误。原因把 /data/superset 整个目录挂载到了 /app/superset这个目录是 Superset 安装包所在位置整个目录被宿主机内容遮住源码和命令行入口全部消失。解决删掉错误容器改成单文件挂载 /data/superset/superset_config.py:/app/superset/superset_config.py。挂载卷只是运行时的覆盖镜像本身没坏重新 run 一次就恢复。记住一点持久化配置挂载到具体的文件路径不要挂安装目录。5.3 内网 docker daemon 权限报错permission denied while trying to connect to the docker api现象内网机器上执行 docker ps直接报 permission denied while trying to connect to the docker api。原因当前用户不在 docker 用户组docker.sock 的访问被拒绝。另外也可能 docker daemon 根本没启动尤其是内网机器新装 Docker 之后没有设开机自启。解决先确认 daemon 状态再处理用户组权限sudo systemctl enable --now docker sudo usermod -aG docker 你的用户名 newgrp docker docker pssystemctl enable --now 同时完成开机自启和立即启动usermod 把用户加进 docker 组newgrp 让当前会话立即生效。这一步做完再执行 docker 命令就不会报权限错了。5.4 数据目录权限导致初始化写库失败现象容器起来后日志里出现 PermissionError [Errno 13]位置在 /app/superset_home初始化命令执行到一半中断。原因宿主机上的 /data/superset/data 目录属主是 root容器内进程以 uid 1000 的 superset 用户运行没有写权限。解决直接调整宿主目录属主为容器用户sudo chown -R 1000:1000 /data/superset/data如果自定义镜像改过用户先查容器内实际 uid 再改。这个权限问题在在线部署时一样会遇到但离线环境里日志不好翻很多人会误判成镜像问题白白浪费时间。5.5 时区差 8 小时看板时间轴对不上现象图表横轴时间比服务器本地时间晚 8 小时导出报告里的时间戳也对不上。原因容器默认时区是 UTCSuperset 从容器环境变量读时区而不是宿主机时区。解决docker run 时加 -e TZAsia/Shanghai或者挂载 /etc/localtime。已经跑起来的容器改完环境变量后要 docker rm 重新 run 才能生效docker restart 不会重读 -e 参数。另一种做法是在自定义配置里把时区写死但前提是容器里要有对应的 tzdata 数据环境变量是最直接的方式。6. 进阶把离线部署固化成一条初始化脚本到这一步Superset 4.1.1 中文版在内网已经能跑起来剩下的问题是可复制性。内网往往不止一台机器测试环境一台、生产环境一台每台都手动执行第四节和第五节的命令效率太低还容易漏步骤。我习惯把整个流程写成一个离线部署脚本放在和 tar 包同一个目录里新机器上跑一次就完成部署。脚本的核心逻辑分四段导入镜像、固定 tag、起容器、初始化。下面是一个可以直接套用的骨架#!/usr/bin/env bash set -euo pipefail # 离线部署 Superset 4.1.1 中文版 # 用法: ./deploy_offline.sh IMAGE_NAMEapache/superset:4.1.1 CONFIG_SRC/data/superset/superset_config.py DATA_DIR/data/superset/data docker load -i superset-4.1.1.tar.gz docker tag $(docker images -q apache/superset:4.1.1 | head -n1) $IMAGE_NAME docker rm -f superset 2/dev/null || true docker run -d \ --name superset \ -p 8088:8088 \ -e TZAsia/Shanghai \ -e SUPERSET_CONFIG_PATH/app/superset/superset_config.py \ -v $CONFIG_SRC:/app/superset/superset_config.py \ -v $DATA_DIR:/app/superset_home \ --restartalways \ $IMAGE_NAME sleep 10 docker exec superset superset db upgrade docker exec superset superset init docker exec superset fab create-admin \ --username admin \ --firstname admin \ --lastname admin \ --email adminexample.com \ --password Admin123456 echo 部署完成访问 http://内网IP:8088脚本里 set -euo pipefail 的作用是任何一步失败立即停止防止带着错误状态往下跑docker rm -f 那行保证重复执行时不冲突。初始化命令里如果账号已经存在fab create-admin 会提示已存在不影响后续使用。实际使用时把密码和路径改成自己环境的不需要额外安装任何工具脚本本身就在离线包目录里。部署完之后的验收我一般按这个顺序做先 curl /health 确认服务在线再登录页切换中文确认汉化生效然后建一张测试图表、导出一张 PNG 确认字体正常。这三关过了这套离线环境就具备了交付条件。我第一次做这类离线部署时在配置文件挂载目录这个坑上浪费了半天容器起不来日志翻来翻去才明白是 -v 挂错了路径。后来把流程固化成脚本新环境十分钟就能跑通。内网部署这种事一次做对比做得快更重要希望这份笔记能帮你在 Superset 4.1.1 离线部署上少走几段弯路。本文还有配套的精品资源点击获取
Superset 4.1.1中文版离线部署指南：Docker内网环境汉化与避坑
简介面向需要在内网或无外网环境中落地数据可视化的运维与开发人员这份资源提供 Superset 4.1.1 中文版 Docker 离线部署的完整文件集。压缩包共6个文件内含3个 Docker 镜像 tar 包Superset 中文镜像、Redis 7、PostgreSQL 14以及 docker-compose.yml 服务编排文件、superset_config.py 配置文件和 .env 环境变量文件总大小约524.2MB。整套离线包将中文界面、服务编排、镜像文件与常用配置一并整理好部署时可减少从源码编译和插件安装的额外工作。借助这些文件用户无需逐个下载镜像或对照英文文档即可在离线环境下启动 Superset并通过中文界面完成数据探索与可视化。资源对不了解命令行的初学者也较友好配置项和启动方式均已梳理清楚已有 364 人学习下载适合企业数据分析团队和希望快速搭建可视化平台的开发者使用部署后可通过浏览器访问可视化看板并利用图表、仪表盘与 SQL 查询能力快速产出分析结果。1. 离线内网跑通 Superset 4.1.1 中文版先说说为什么这件事值得做做数据平台的人迟早会碰到一个绕不开的场景服务器在隔离网段数据库在内网连包管理器都够不着却要把一套能用的 BI 看板搭起来。Superset 4.1.1 中文版加 Docker 离线部署就是为这种环境准备的。它的核心思路不复杂在能联网的机器上把镜像和依赖打成离线包搬到内网用 docker load 导进去再做语言、数据库和账号的初始化。这篇笔记把这条路径一步步拆开包括哪些资源必须在联网机器上提前备好、启动参数怎么设、汉化和字体怎么处理以及离线环境里最容易让人翻车的几个坑。适合正在内网搭数据可视化平台、又不想让数据出网的工程师照着做。2. 离线部署前的资源盘点在联网机器上把三样东西备齐离线部署不是在内网机器上凭空变出东西九成工作其实发生在能联网的那台机器上。我一般会把准备阶段拆成三块Superset 镜像本身、元数据库镜像如果内网没有、以及一组配置文件和中文字体。这三样东西在联网机器上准备好和内网机器约定好目录和路径后面就顺了。2.1 版本锁定为什么是 4.1.1 而不是 latest用 latest 标签做离线部署是第一个坑。在联网机器上三个月前拉的 latest 和今天拉的 latest 不是同一个东西镜像 ID 不同底层依赖版本也不同。离线环境没有后悔药一旦内网机器上跑出问题没法重新拉一个来对比只能干瞪眼。所以我在准备阶段第一件事就是锁死版本标签明确写成 apache/superset:4.1.1。拉取命令很简单docker pull apache/superset:4.1.1 docker images | grep superset执行完 docker images 后记下对应的 IMAGE ID。这个 ID 在内网导入后要用来核对防止传输过程中镜像内容被改掉。为什么要用官方镜像而不是自己 pip 装一个因为官方镜像里已经带好了 superset 命令行工具、Python 环境和 gunicorn入口脚本也是现成的离线环境下自己用 pip 装很容易缺系统依赖比如编译需要的 gcc、libffi到时候连 pip 源都够不着局面很难收拾。2.2 镜像导出docker save 与 docker load 的完整对应镜像拉下来之后要打包带走。常见做法是直接用 docker save 配合 gzip 压缩而不是裸导出一个大 tar。Superset 镜像本身不小压缩一下能省不少传输时间尤其是要走跳板机或者移动硬盘的时候。docker save apache/superset:4.1.1 | gzip superset-4.1.1.tar.gz md5sum superset-4.1.1.tar.gz superset-4.1.1.md5 ls -lh superset-4.1.1.tar.gz第一条命令把镜像层打包并通过管道直接压缩成 tar.gz第二条命令生成校验文件这是离线传输最容易忽略的一步。内网环境往往要经过多手拷贝加一个 md5 校验能第一时间发现文件损坏省得在内网机器上 load 到一半报错才回头排查。如果内网元数据库也要一并带过去同样方式处理docker pull postgres:15-alpine docker save postgres:15-alpine | gzip postgres-15-alpine.tar.gz这里要特别注意docker save 和 docker export 是两回事。save 打包的是镜像的完整层结构load 之后能直接跑export 导出的是容器文件系统导回来没有镜像元信息不能用于部署。离线部署必须用 save/load 这条路。2.3 元数据库与初始化依赖离线环境的一次性准备Superset 默认的元数据库是 SQLite试玩没问题但内网正式用我建议换 PostgreSQL 或 MySQL。元数据库只存用户、看板、数据源连接信息这些配置数据不存业务数据业务数据还是在你自己的数仓和 OLAP 里。如果内网已经有现成的 PostgreSQL直接建一个库给 Superset 用就行没有的话就把 postgres:15-alpine 镜像一并离线带过去这是最省事的方案。需要准备的远不止镜像下面是文件清单文件用途是否必须superset-4.1.1.tar.gzSuperset 镜像必须postgres-15-alpine.tar.gz元数据库镜像内网无库时必带superset_config.py覆盖默认配置写入密钥和语言必须NotoSansCJK-Regular.ttc图表中文渲染字体必须clickhouse-connect 等 whl额外数据源驱动按需superset_config.py 和字体文件都在联网机器上提前写好、放好后面章节会给出具体内容。另外如果业务上需要连 ClickHouse、MySQL 这些数据源官方镜像未必自带对应驱动离线环境下 pip 装不了所以要在联网机器上把 whl 包和依赖一起下载好拷进内网。这一步很容易被漏掉等你在内网建数据源的时候才发现驱动缺失又要折腾一轮。3. 从 docker load 到容器跑起来内网机器上的启动全流程资源备齐之后内网机器上的操作反而比准备阶段简单但每一步都要看准。整个流程可以分成四段导入镜像、起容器、初始化元数据库、验证登录。中间任何一步报错都先回头看前一步的输入对不对。3.1 导入镜像并校验 tag别让容器跑成未知版本把打包好的 tar.gz 和 md5 文件拷到内网机器后先做校验再导入。md5sum -c superset-4.1.1.md5 docker load -i superset-4.1.1.tar.gz docker images | grep superset第一条命令比对 md5输出 OK 表示文件完整。第二条命令导入镜像。第三条命令确认镜像是否出现这里重点看仓库名和 TAG如果显示的是 apache/superset:4.1.1 那最好如果 IMAGE ID 对上但 TAG 是空的说明打包来源本身没带 tag这时候要手动补一个docker tag IMAGE_ID apache/superset:4.1.1这一步不做后面 docker run 用 apache/superset:4.1.1 作为镜像名会直接报找不到镜像。离线环境里这种 tag 漂移很常见尤其是当 tar 包来自另一台机器的 load 结果镜像层是完整的tag 元信息却丢了。统一的做法是不管显示成什么样都以 IMAGE ID 为准手动把 tag 固定好。3.2 配置文件与启动命令密钥、语言和挂载一次配齐起容器之前先准备 superset_config.py这一步直接决定后面汉化和安全状态。在宿主机上建一个目录比如 /data/superset把文件放在里面# superset_config.py import os # 离线环境固定密钥避免每次重启 session 失效 SECRET_KEY 内网专用的长随机字符串至少32位不要用默认值 # 显式声明语言集合保证登录页能切到中文 LANGUAGES { zh: {flag: cn, name: Chinese}, en: {flag: us, name: English}, }SECRET_KEY 是 Flask 签名 session 和 CSRF 用的不设的话每次重启容器会话都会失效日志也会报警告。LANGUAGES 里的 zh 就是中文入口默认配置里其实也带中文但一旦用自定义配置覆盖原有的语言声明就不再生效所以必须显式写进去。接下来启动容器docker run -d \ --name superset \ -p 8088:8088 \ -e TZAsia/Shanghai \ -e SUPERSET_CONFIG_PATH/app/superset/superset_config.py \ -v /data/superset/superset_config.py:/app/superset/superset_config.py \ -v /data/superset/data:/app/superset_home \ --restartalways \ apache/superset:4.1.1逐个说参数-d 后台运行--name 固定容器名后面 exec 的时候不用查容器 ID-p 映射 8088 端口-e TZ 把容器时区设成上海解决后面图表时间差 8 小时的问题-e SUPERSET_CONFIG_PATH 告诉 Superset 去读哪个配置文件两个 -v 分别是挂载配置文件和持久化目录--restartalways 让内网机器重启后容器自动起来。这里必须提醒一句/app/superset 是 Python 包的安装目录整个目录挂载上去会把安装好的源码遮住容器直接起不来。只能挂载单文件到 superset_config.py数据目录单独挂到 /app/superset_home这个路径才是 Superset 留给持久化用的。3.3 初始化元数据库与管理员账号容器起来后不要急着访问先做初始化。三条命令按顺序执行docker exec -it superset superset db upgrade docker exec -it superset superset init docker exec -it superset fab create-admin \ --username admin \ --firstname admin \ --lastname admin \ --email adminexample.com \ --password Admin123456第一条 db upgrade 会在元数据库里建表Superset 的所有表结构都由它创建。第二条 init 做角色、权限、默认视图的初始化这一步依赖表已经存在所以顺序不能反。第三条 fab create-admin 创建管理员账号username 和 password 是登录凭证email 可以改成内网实际邮箱。如果后面密码忘了重跑这条命令就能重置不用动数据库。这里建议手动分步执行而不是把三条命令串成一长行。离线环境里一旦中间某条失败分步执行能一眼看出是哪条的问题串在一起只会多花排查时间。3.4 健康检查与登录验证初始化完成后先做基础检查再开浏览器。docker ps | grep superset curl -I http://127.0.0.1:8088/health docker logs superset --tail 50docker ps 确认容器处于 Up 状态curl 请求 /health 端点返回 HTTP/1.1 200 OK 说明服务在响应docker logs 看有没有异常堆栈。如果 curl 通但浏览器访问 http://内网IP:8088 打不开常见原因是宿主防火墙没放行 8088 端口先查防火墙规则别急着怀疑容器。登录页路径是 /login用刚才创建的 admin 账号登录能进首页就算跑通了。4. 中文版汉化与图表字体界面和看板都别再有方块字很多人一开始会去找Superset 中文版的特殊安装包其实官方镜像里已经内置了中文翻译。所谓中文版就是官方镜像加上正确的语言配置再补齐图表渲染需要的中文字体。前者负责界面菜单后者负责看板标题和图例。两步都做到才能算真正的中文环境。4.1 语言配置把 zh 显式写进 LANGUAGES在 3.2 节的 superset_config.py 里LANGUAGES 字典已经写出了 zh 和 en。这里再解释一下为什么必须显式写Superset 的默认配置里虽然有中文但一旦你通过 SUPERSET_CONFIG_PATH 指向自定义配置文件默认配置里的语言集合会被整体覆盖只保留你写进去的内容。如果只写了英文汉化入口就没了。配置做完后重启容器让配置生效docker restart superset重启后打开登录页右上角或右下角会有语言切换入口选择中文后界面立即切换。这个选择会被浏览器记住下次登录还是中文。如果页面上找不到切换入口检查配置里的 LANGUAGES 是否真的生效用 docker exec 进容器看配置加载路径docker exec -it superset python -c from superset import conf; print(conf.get(LANGUAGES))输出里能看到 zh 说明配置已生效看不到就回去查挂载路径和环境变量别急着怀疑镜像有问题。4.2 中文字体缺失导致方块字字体安装与缓存刷新界面汉化完成只是第一步。实际做看板时图表标题、坐标轴、图例很可能渲染成一个个方块。如果是浏览器里这样多半是客户端系统缺字体如果是导出 PNG 图片时方块问题一定在容器里。Superset 的图片导出功能在容器内渲染图表底层用的字体库找不到中文字体就只能画方块。解决办法是在容器内安装一套中文字体。先准备 NotoSansCJK-Regular.ttc 文件放到宿主机 /data/superset 目录下然后进容器操作docker exec -u root -it superset bash mkdir -p /usr/share/fonts/chinese cp /app/superset_home/NotoSansCJK-Regular.ttc /usr/share/fonts/chinese/ fc-cache -fv exit docker restart superset为什么用 -u root 进容器Superset 容器默认用户不是 root没有 /usr/share/fonts 的写权限。为什么先把字体拷到 /app/superset_home 再复制因为这个目录是挂载卷从宿主机放进去立刻可见不用 docker cp 绕一圈。更干净的做法是直接做一个带字体和配置的自定义镜像把环境固化成镜像再往后任何机器上 load 都能用FROM apache/superset:4.1.1 USER root COPY NotoSansCJK-Regular.ttc /usr/share/fonts/chinese/ RUN fc-cache -fv COPY superset_config.py /app/superset/superset_config.py USER superset在内网机器上构建这个镜像不需要联网基础镜像已经在本地了。构建完成后直接跑 docker build -t superset-zh:4.1.1 .后面 run 的时候用这个新镜像名。这种方式的好处是容器重建后所有环境配置一次性恢复不用再进容器手动折腾。4.3 验证汉化效果从登录页到导出图片汉化验证分三步走。登录页切换中文后逐一点开菜单看数据源、仪表板、图表这些核心菜单项是否都是中文。第二步新建一张图表输入中文标题加一个中文图例确认浏览器渲染正常。第三步用 Superset 的导出图片功能导出一张 PNG看导出的图片里中文是否正常。导出图片这一步最容易被忽略也最容易返工。因为导出走的是容器内的渲染流程字体没装进容器的话浏览器里看是好的导出的图却还是方块。凡是用到邮件报告、定时导出场景的必须把 4.2 节的字体安装做完再验收。5. 离线部署避坑五条能省一天的血泪经验离线部署和在线部署的差别在于出了问题没地方查。镜像拉不了文档看不了连对比实验都做不了。下面五条是我实际踩过的坑每一条都能让新手折腾半天以上。5.1 镜像 tag 丢失容器跑成未知版本现象docker load 成功后docker images 里看不到 apache/superset:4.1.1 这个 tagdocker run 报找不到镜像。原因tar 包里的镜像在源机器上就不是标准名字打出来的可能是从另一台机器 load 后没有重新 tagtag 元信息在打包时就是空的。save 只保存镜像层和当前 tag不会自动补全名字。解决load 之后立刻用 docker tag IMAGE_ID apache/superset:4.1.1 固定名字后续所有命令都用这个名字引用。在准备阶段也养成习惯在联网机器上先确认 docker images 里 tag 完整再打包。5.2 配置文件挂载成目录容器秒退现象docker run 后容器状态一直 Exiteddocker logs 里出现 ModuleNotFoundError 或者找不到 superset 可执行命令的错误。原因把 /data/superset 整个目录挂载到了 /app/superset这个目录是 Superset 安装包所在位置整个目录被宿主机内容遮住源码和命令行入口全部消失。解决删掉错误容器改成单文件挂载 /data/superset/superset_config.py:/app/superset/superset_config.py。挂载卷只是运行时的覆盖镜像本身没坏重新 run 一次就恢复。记住一点持久化配置挂载到具体的文件路径不要挂安装目录。5.3 内网 docker daemon 权限报错permission denied while trying to connect to the docker api现象内网机器上执行 docker ps直接报 permission denied while trying to connect to the docker api。原因当前用户不在 docker 用户组docker.sock 的访问被拒绝。另外也可能 docker daemon 根本没启动尤其是内网机器新装 Docker 之后没有设开机自启。解决先确认 daemon 状态再处理用户组权限sudo systemctl enable --now docker sudo usermod -aG docker 你的用户名 newgrp docker docker pssystemctl enable --now 同时完成开机自启和立即启动usermod 把用户加进 docker 组newgrp 让当前会话立即生效。这一步做完再执行 docker 命令就不会报权限错了。5.4 数据目录权限导致初始化写库失败现象容器起来后日志里出现 PermissionError [Errno 13]位置在 /app/superset_home初始化命令执行到一半中断。原因宿主机上的 /data/superset/data 目录属主是 root容器内进程以 uid 1000 的 superset 用户运行没有写权限。解决直接调整宿主目录属主为容器用户sudo chown -R 1000:1000 /data/superset/data如果自定义镜像改过用户先查容器内实际 uid 再改。这个权限问题在在线部署时一样会遇到但离线环境里日志不好翻很多人会误判成镜像问题白白浪费时间。5.5 时区差 8 小时看板时间轴对不上现象图表横轴时间比服务器本地时间晚 8 小时导出报告里的时间戳也对不上。原因容器默认时区是 UTCSuperset 从容器环境变量读时区而不是宿主机时区。解决docker run 时加 -e TZAsia/Shanghai或者挂载 /etc/localtime。已经跑起来的容器改完环境变量后要 docker rm 重新 run 才能生效docker restart 不会重读 -e 参数。另一种做法是在自定义配置里把时区写死但前提是容器里要有对应的 tzdata 数据环境变量是最直接的方式。6. 进阶把离线部署固化成一条初始化脚本到这一步Superset 4.1.1 中文版在内网已经能跑起来剩下的问题是可复制性。内网往往不止一台机器测试环境一台、生产环境一台每台都手动执行第四节和第五节的命令效率太低还容易漏步骤。我习惯把整个流程写成一个离线部署脚本放在和 tar 包同一个目录里新机器上跑一次就完成部署。脚本的核心逻辑分四段导入镜像、固定 tag、起容器、初始化。下面是一个可以直接套用的骨架#!/usr/bin/env bash set -euo pipefail # 离线部署 Superset 4.1.1 中文版 # 用法: ./deploy_offline.sh IMAGE_NAMEapache/superset:4.1.1 CONFIG_SRC/data/superset/superset_config.py DATA_DIR/data/superset/data docker load -i superset-4.1.1.tar.gz docker tag $(docker images -q apache/superset:4.1.1 | head -n1) $IMAGE_NAME docker rm -f superset 2/dev/null || true docker run -d \ --name superset \ -p 8088:8088 \ -e TZAsia/Shanghai \ -e SUPERSET_CONFIG_PATH/app/superset/superset_config.py \ -v $CONFIG_SRC:/app/superset/superset_config.py \ -v $DATA_DIR:/app/superset_home \ --restartalways \ $IMAGE_NAME sleep 10 docker exec superset superset db upgrade docker exec superset superset init docker exec superset fab create-admin \ --username admin \ --firstname admin \ --lastname admin \ --email adminexample.com \ --password Admin123456 echo 部署完成访问 http://内网IP:8088脚本里 set -euo pipefail 的作用是任何一步失败立即停止防止带着错误状态往下跑docker rm -f 那行保证重复执行时不冲突。初始化命令里如果账号已经存在fab create-admin 会提示已存在不影响后续使用。实际使用时把密码和路径改成自己环境的不需要额外安装任何工具脚本本身就在离线包目录里。部署完之后的验收我一般按这个顺序做先 curl /health 确认服务在线再登录页切换中文确认汉化生效然后建一张测试图表、导出一张 PNG 确认字体正常。这三关过了这套离线环境就具备了交付条件。我第一次做这类离线部署时在配置文件挂载目录这个坑上浪费了半天容器起不来日志翻来翻去才明白是 -v 挂错了路径。后来把流程固化成脚本新环境十分钟就能跑通。内网部署这种事一次做对比做得快更重要希望这份笔记能帮你在 Superset 4.1.1 离线部署上少走几段弯路。本文还有配套的精品资源点击获取