简介为需要离线部署数据可视化平台的企业运维与开发人员提供Superset 4.1.1中文版的完整Docker镜像与编排配置可在无外网环境下快速搭建起可用的中文数据探索与图表分析环境。压缩包共6个文件大小约524.2MB核心为3个tar镜像文件含Superset中文版、PostgreSQL与Redis配合docker-compose.yml定义多容器启动方式superset_config.py用于调整数据库连接与认证安全参数.env存放环境变量部署时按需修改即可。已有363人学习下载。借助这套离线安装包使用者无需逐一解决基础镜像拉取和版本兼容问题也免去手工配置各组件依赖的繁琐步骤内置中文支持对不熟悉英文界面的用户尤其友好内置丰富可视化组件可对数据库中的数据进行探索、分析与看板展示适合企业内部数据看板、教学实验及安全隔离场景下的快速落地与后续二次开发。 在公司内部的国产化服务器、私有云环境甚至部分政务网里做数据可视化最头疼的一件事就是机器不能访问外网却还要求能跑起最新版本的数据分析平台。我最近就在一台完全离线的服务器上完成了 Apache Superset 4.1.1 的中文版 Docker 部署。整个过程踩了不少坑从镜像拉取、离线传输、中文本地化到数据库初始化和常见故障排查前前后后整理出了一套可以直接照抄的流程。如果你也正在面临 Superset 离线部署的需求或者手里正好有一台“裸奔”的内网机器这篇内容应该能帮你少走不少弯路。先说重点这个需求的核心不是 Superset 本身有多难装而是“离线”两个字带来的连锁问题——镜像怎么来、依赖怎么解决、中文 locale 怎么处理、容器怎么在无网状态下正常初始化。下面我会按照实际操作的顺序把每一步的原理和命令都展开讲清楚。1. 部署思路拆解离线容器化的三个关键决策1.1 为什么要用 Docker 做离线部署Superset 是一个典型的 Python Web 应用依赖的 Python 包少说几十个还有 Node 前端构建产物、数据库迁移脚本、静态资源文件。如果直接在离线服务器上用源码方式部署你需要先把全套 Python 依赖、Node 依赖、编译工具链全部准备好光 pip 和 npm 的离线包就能把人折腾到崩溃。Docker 的价值在于把环境和应用打包成镜像。这样离线服务器上唯一需要的东西就是 Docker 运行时本身剩下的都可以通过镜像文件导入。你只需要在一台能联网的机器上把镜像拉下来导出成 tar 包拷到离线机器上 load 进去一个完好的运行环境就就位了。1.2 三种离线方案对比我在做技术选型时实际对比过三种方式方案优点缺点结论源码 离线 Python 依赖不依赖 Docker依赖梳理极难编译依赖难解决升级麻烦不推荐Docker 镜像导出导入环境一致、交付简单、回滚容易需要联网机器作为转换跳板推荐Docker Registry 仓库中转支持多机器分发离线环境还得额外部署一个镜像仓库环境复杂时可用最终我选择了第二种用一台能联网的工作机拉取官方镜像完成中文化和必要配置再导出 tar 包送到离线目标服务器上导入启动。这也是目前业界做内网容器化交付最主流的方式。1.3 离线部署完整流程规划整个流程可以规划成下面几个阶段环境与版本确认确认离线机器的 CPU 架构、Docker 版本、磁盘空间。镜像准备联网机拉取 apache/superset:4.1.1做中文化配置导出镜像包。镜像传输使用压缩后的 tar 包通过 U 盘/内网传输工具拷入离线机。部署启动离线机加载镜像编写 docker-compose 配置完成数据库初始化和账号创建。验证访问登录界面确认中文语言和时区设置。这个路径看起来简单但每一步都有细节尤其是中文化配置和数据库初始化最容易出问题。下面我会一步步拆开讲。2. 部署前准备版本选型与资料清单2.1 版本选型为什么选 4.1.1Superset 的版本迭代速度不算慢我选 4.1.1 主要看中三点4.1.x 属于稳定版本线核心功能SQL Lab、Dashboard、Charts已经非常成熟没有太多破坏性变更。4.1.1 修复了 4.1.0 里的一些权限和图表渲染问题相对于 4.0.x它在前端交互和加载性能上也有明显提升。Docker Hub 上有对应的官方镜像 tag可以直接拉取apache/superset:4.1.1。这里要提醒一句不要图新鲜直接用 latest 或者 dev 标签。离线环境没有网络一旦镜像有问题你甚至没法临时 pull 一个补丁版本所以必须用一个明确、稳定的版本号。2.2 离线机器环境要求在执行部署前先到目标服务器上用命令确认这几项# 查看系统架构x86_64 还是 arm64 uname -m # 查看系统发行版 cat /etc/os-release # 查看 Docker 版本 docker --version # 查看磁盘空间镜像解压后至少预留 10GB df -h /var/lib/docker我这次部署的机器是 x86_64 架构的离线服务器Docker 版本为 24.0.x满足要求。如果是 ARM 架构需要在联网机器上拉取对应的 ARM 镜像导出方式一样但是 tag 前缀需要留意。Superset 官方镜像对多架构支持得比较好拉取时会自动匹配这一步通常不会出问题。2.3 需要提前准备的资料清单离线部署讲究“一次备齐”我整理了一个检查清单你在开始前对着打勾Superset 镜像 tar 包联网机导出建议压缩大约 1.5GB 左右。docker-compose.yml 文件可以现场写但我建议提前准备好并测试过。superset_config.py 中文化配置文件后续会细讲。Docker 离线安装包rpm/deb如果离线机器连 Docker 都没装需要提前准备。外部数据库驱动包可选如果要连 MySQL、PostgreSQL 等外部数据源需要提前把驱动打包进镜像。注意第 4 点。很多离线服务器真的就是“裸机”Docker 都没有。如果你的目标机器还没有 Docker需要到能联网的机器上把 Docker 的安装包和依赖包全部下载好再一起拷进去。3. 联网机器上准备 Superset 4.1.1 镜像3.1 拉取官方镜像在能联网的机器上先拉取官方镜像docker pull apache/superset:4.1.1拉取完成后用docker images确认docker images | grep superset正常情况下会看到类似信息apache/superset 4.1.1 b2b1e2b2c8a6 2 weeks ago 1.32GB3.2 给镜像打一个本地标签打完标签之后可以避免后续导入时 REPOSITORY 字段太冗长。我一般习惯打一个简短的 tagdocker tag apache/superset:4.1.1 superset-local:4.1.1这里解释一下原因docker save 导出时会保留镜像的 repo 和 tag 信息如果你使用了很长的原始 tag在离线机器上 load 之后也要用同样的名字才能引用。打一个简短 tag后面写 compose 文件时更清爽。3.3 中文化镜像的构建关键步骤官方镜像默认虽然支持多语言但有几个问题默认 locale 是英文、时区是 UTC、部分翻译资源需要额外处理。为了做到真正的“中文版”我们需要在联网机器上基于官方镜像构建一个新的自定义镜像。这里我写了一个 DockerfileFROM apache/superset:4.1.1 # 切换到 root 用户安装额外依赖 USER root # 设置时区 RUN apt-get update \ apt-get install -y --no-install-recommends tzdata \ cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \ echo Asia/Shanghai /etc/timezone # 如果后续需要连接外部数据库在这里加入 python 驱动 RUN pip install --no-cache-dir pymysql psycopg2-binary # 切换回 superset 用户 USER superset # 设置环境变量 ENV SUPERSET_HOME/app/superset \ TZAsia/Shanghai \ LANGC.UTF-8 \ LC_ALLC.UTF-8构建并导出docker build -t superset-local:4.1.1 .需要说明的是Superset 语言本身是通过前端 i18n 机制管理的官方镜像已包含中文翻译资源。这里的“中文化”主要体现在时区默认设为东八区避免图表时间显示差 8 小时。通过环境变量和配置文件把默认语言设置为 zh。确保系统 locale 不会导致中文乱码。3.4 导出镜像并压缩传输镜像构建好后开始导出。这里有两个方案方案一直接导出不压缩docker save -o superset-4.1.1.tar superset-local:4.1.1方案二导出后压缩推荐docker save superset-local:4.1.1 | gzip superset-4.1.1.tar.gz压缩后的镜像体积能小 30%~40%在通过内网传输工具或 U 盘拷贝时能省不少时间。拷贝到离线机器后建议先用md5sum或sha256sum校验一下文件完整性防止传输过程中损坏。这一步看起来多余但实际工作中很管用——我就碰到过镜像包拷贝到一半断了结果 load 时报错找不到 manifest 的情况。4. 中文本地化的完整配置4.1 Superset 多语言机制说明Superset 的界面语言是运行时动态加载的。默认情况下它会根据浏览器的Accept-Language来显示语言。最要命的是如果你的浏览器或操作系统是英文环境Superset 就显示英文如果浏览器是中文环境它可能显示中文但部分翻译不完整。要做到不管用户浏览器设置如何打开就是中文需要从服务端指定默认语言。Superset 读取语言配置的顺序是环境变量 -superset_config.py- 数据库用户偏好设置。也就是说即使你在配置里改了默认语言用户未单独设置时也能生效但用户如果自己改过语言偏好则会覆盖默认配置。4.2 创建 superset_config.py我们需要准备一个中文化配置并把它挂载到容器里。先创建配置文件# superset_config.py import os from typing import Optional # 用于 Flask 签名和会话加密务必修改成随机字符串 SECRET_KEY os.environ.get(SUPERSET_SECRET_KEY, please-change-me) # 默认语言设为中文 BABEL_DEFAULT_LOCALE zh LANGUAGES { zh: {flag: cn, name: Chinese}, en: {flag: us, name: English}, } # 时区 TZ Asia/Shanghai SUPERSET_TIMEZONE Asia/Shanghai # 使用 SQLite 时不需要额外配置如果生产环境使用 MySQL请配置下面的内容 SQLALCHEMY_DATABASE_URI os.environ.get( DATABASE_URL, sqlite:////app/superset/superset.db ) # 允许跨域请求按需开启 ENABLE_CORS True将这个配置文件挂载进容器有两种方式方式一通过 volume 挂载在 docker-compose.yml 中挂载volumes: - ./superset_config.py:/app/superset/superset_config.py:ro方式二直接打进镜像将配置文件复制进镜像COPY superset_config.py /app/superset/superset_config.py我两种都试过。如果是给多个环境复用建议打进镜像交付物更完整如果只是单台机器调试挂载更方便改配置重启容器即可。4.3 启动时指定配置文件路径Superset 官方镜像的启动脚本默认会寻找SUPERSET_CONFIG_PATH环境变量。如果你没有显式设置它会按默认路径加载。为了保险建议在环境变量中显式指定SUPERSET_CONFIG_PATH/app/superset/superset_config.py如果挂载或复制路径不对Superset 会静默使用默认配置导致中文化不生效。这里最容易出的问题就是路径写错但服务又能正常启动让你很难排查。建议启动容器后执行下面命令确认配置已加载docker exec -it superset sh -c python -c from superset import app; print(app.config.get(\BABEL_DEFAULT_LOCALE\))如果输出是zh说明配置生效了。5. 离线服务器上的完整部署实操5.1 安装 Docker如果离线机上没有如果目标服务器已经装好 Docker直接跳过这一步。如果没装这块是离线部署里最恼人的环节。以 CentOS 7 / openEuler / 麒麟等 rpm 系系统为例需要在联网机器上下载 Docker 和相关依赖。最简单的做法是在联网机器上使用yumdownloader或dnf download命令把需要的 rpm 全部拉下来# 在联网的相同系统版本机器上执行 mkdir -p /tmp/docker-rpm cd /tmp/docker-rpm yum install --downloadonly --downloaddir/tmp/docker-rpm docker-ce docker-ce-cli containerd.io docker-compose-plugin然后把整个/tmp/docker-rpm目录拷贝到离线机器上rpm -Uvh *.rpm装完后启动服务systemctl enable docker systemctl start docker如果是 Ubuntu/Debian 系思路一样用apt-get download或apt download把 deb 包拉下来再dpkg -i安装。这块细节比较多每家公司的离线环境情况差异大建议在实施前先摸清系统版本和依赖情况。5.2 导入镜像先创建部署目录并导入镜像mkdir -p /opt/superset cd /opt/superset # 将 tar.gz 包放到 /opt/superset 后执行 gzip -dc superset-4.1.1.tar.gz | docker load加载完成后检查镜像docker images | grep superset正常情况下你会看到superset-local和4.1.1的镜像信息。如果发现 REPOSITORY 显示为none说明镜像在保存时 tag 信息丢了可以用docker tag重新打标签例如docker tag IMAGE_ID superset-local:4.1.15.3 编写 docker-compose.yml在离线机器上创建docker-compose.ymlversion: 3.8 services: superset: image: superset-local:4.1.1 container_name: superset restart: always ports: - 8088:8088 environment: - TZAsia/Shanghai - SUPERSET_CONFIG_PATH/app/superset/superset_config.py - SUPERSET_SECRET_KEYyour-random-secret-key-change-me volumes: - ./superset_config.py:/app/superset/superset_config.py:ro - superset-data:/app/superset command: sh -c superset db upgrade superset init superset run -h 0.0.0.0 -p 8088 --with-threads --reload --debugger volumes: superset-data:这里有一点要特别说明我用的 command 是先执行db upgrade再启动服务。如果你前期把配置文件放错了位置容器启动就会卡在数据库初始化的环节。所以挂载进去的配置文件一定要保证路径正确。5.4 初始化数据库与管理账号容器启动后如果命令里没有自动创建管理员账号需要手动执行# 进入容器 docker exec -it superset bash # 创建管理员按提示输入用户名、邮箱、密码 superset fab create-admin # 初始化权限和角色数据 superset init # 如果希望加载示例数据可选 superset load_examples这里需要注意创建管理员时首次输入的密码不要太简单Superset 对密码策略有一定要求太弱会直接拒绝而且不给你明确的密码规则提示很容易反复报错。我当时的密码设置为Admin123456这种强度一次通过。5.5 验证部署初始化完成后在浏览器里访问http://服务器IP:8088如果部署成功你会看到登录页面并且界面语言已经是中文。用刚创建的管理员账号登录就能看到完整的控制台、仪表盘列表和数据源管理菜单。6. 常见问题与排坑记录6.1 问题速查表下面这些问题是离线部署 Superset 时最常遇到的我按照“症状 - 原因 - 解决方案”整理成一张速查表建议保存。症状原因解决方案docker load失败报invalid tartar 包损坏或未完整传输重新传输拷贝前比对 md5镜像加载成功但启动容器报image not found没有短 tag启动时引用了不存在的 tag用docker images查看准确 tag登录后白屏或反复跳登录页SECRET_KEY未设置或变化在环境变量中固定 SECRET_KEY中文不生效配置文件路径不对或挂载失败检查容器内配置文件是否存在图表时间显示偏差 8 小时容器时区未设置设置TZAsia/Shanghai连接 MySQL 数据源失败缺少 pymysql 驱动构建镜像时安装 pymysql登录时报 CSRF 错误反向代理或端口映射导致请求地址异常在配置中设置ENABLE_PROXY_FIX True浏览器访问 8088 不通防火墙拦截或端口未开放systemctl status firewalld检查并开放端口6.2 我踩过的三个大坑坑一数据库迁移卡死或超时第一次启动时superset db upgrade在 SQLite 上跑得还算快但如果数据卷比较大迁移可能需要两三分钟。如果容器日志长时间没有更新不要急着重启先观察。可以在另一个终端执行docker logs -f superset等待完成。如果反复失败建议清掉数据卷重新开始docker compose down -v docker compose up -d坑二登录页面中文但仪表盘里的日期格式还是英文即使界面语言改成了中文默认的日期格式可能还是YYYY-MM-DD这种通用格式符合国内需求就不用管如果你需要切换到YYYY年MM月DD日需要在配置中自定义DATE_FORMAT YYYY年MM月DD日不过这个格式在国际化环境下容易引起歧义我一般不建议随意改除非是纯内部使用。坑三连接外部数据库时驱动缺失Superset 本身不带所有数据库驱动。我们最常见的需求是连 MySQL 和 PostgreSQL所以构建镜像时一定要提前装好pymysql和psycopg2-binary。连接串示例# MySQL SQLALCHEMY_DATABASE_URI mysqlpymysql://user:passwordhost:3306/dbname # PostgreSQL SQLALCHEMY_DATABASE_URI postgresqlpsycopg2://user:passwordhost:5432/dbname如果忘了装驱动在界面上新建数据库连接时会报No module named pymysql而且日志里不会提示你怎么装。这也是为什么我在前面的 Dockerfile 里特意加了这两行 pip 安装。6.3 日常运维补充部署完成并不是终点。我现在在离线服务器上还保留了一套简单的运维习惯每天备份superset-data卷里的superset.db文件。定期使用docker compose pull联网机构建新版本复制到离线机升级。所有重要变更先改配置再重启容器尽量不直接进容器改文件因为容器重建后文件会丢失。写在最后关于离线交付的一点体会这次 Superset 4.1.1 离线部署最大的收获其实是让我对“交付物思维”有了更深的理解。在线环境可以随意调试离线环境里所有东西都必须提前准备、反复验证没有试错的余地。镜像、配置文件、初始化命令、数据卷备份每一项都要想清楚它会在哪个环节被用到。根据我个人的经验第一次做离线部署时一定要在联网环境里完整跑一遍流程把能踩的坑都踩完再固化到离线交付清单中。比如 Dockerfile 里驱动装没装、superset_config.py 路径对不对、SECRET_KEY 有没有固定这些问题在联网环境下有提示容易发现在离线环境里一个小错误可能导致整个交付卡住几天。最后再分享一个小技巧如果后期有多台离线机器需要部署建议把构建好的中文化镜像上传到内网的 Docker Registry 中比如 Harbor。这样每台新机器只需要docker pull内网镜像即可不用每次拷贝几个 G 的压缩包。离线部署的本质从来不是“能不能装”而是“怎么把一次的成功经验可靠地复制到每一台机器上”——把流程固定下来比单次跑通重要得多。本文还有配套的精品资源点击获取
Apache Superset 4.1.1离线Docker部署与中文化实践
简介为需要离线部署数据可视化平台的企业运维与开发人员提供Superset 4.1.1中文版的完整Docker镜像与编排配置可在无外网环境下快速搭建起可用的中文数据探索与图表分析环境。压缩包共6个文件大小约524.2MB核心为3个tar镜像文件含Superset中文版、PostgreSQL与Redis配合docker-compose.yml定义多容器启动方式superset_config.py用于调整数据库连接与认证安全参数.env存放环境变量部署时按需修改即可。已有363人学习下载。借助这套离线安装包使用者无需逐一解决基础镜像拉取和版本兼容问题也免去手工配置各组件依赖的繁琐步骤内置中文支持对不熟悉英文界面的用户尤其友好内置丰富可视化组件可对数据库中的数据进行探索、分析与看板展示适合企业内部数据看板、教学实验及安全隔离场景下的快速落地与后续二次开发。 在公司内部的国产化服务器、私有云环境甚至部分政务网里做数据可视化最头疼的一件事就是机器不能访问外网却还要求能跑起最新版本的数据分析平台。我最近就在一台完全离线的服务器上完成了 Apache Superset 4.1.1 的中文版 Docker 部署。整个过程踩了不少坑从镜像拉取、离线传输、中文本地化到数据库初始化和常见故障排查前前后后整理出了一套可以直接照抄的流程。如果你也正在面临 Superset 离线部署的需求或者手里正好有一台“裸奔”的内网机器这篇内容应该能帮你少走不少弯路。先说重点这个需求的核心不是 Superset 本身有多难装而是“离线”两个字带来的连锁问题——镜像怎么来、依赖怎么解决、中文 locale 怎么处理、容器怎么在无网状态下正常初始化。下面我会按照实际操作的顺序把每一步的原理和命令都展开讲清楚。1. 部署思路拆解离线容器化的三个关键决策1.1 为什么要用 Docker 做离线部署Superset 是一个典型的 Python Web 应用依赖的 Python 包少说几十个还有 Node 前端构建产物、数据库迁移脚本、静态资源文件。如果直接在离线服务器上用源码方式部署你需要先把全套 Python 依赖、Node 依赖、编译工具链全部准备好光 pip 和 npm 的离线包就能把人折腾到崩溃。Docker 的价值在于把环境和应用打包成镜像。这样离线服务器上唯一需要的东西就是 Docker 运行时本身剩下的都可以通过镜像文件导入。你只需要在一台能联网的机器上把镜像拉下来导出成 tar 包拷到离线机器上 load 进去一个完好的运行环境就就位了。1.2 三种离线方案对比我在做技术选型时实际对比过三种方式方案优点缺点结论源码 离线 Python 依赖不依赖 Docker依赖梳理极难编译依赖难解决升级麻烦不推荐Docker 镜像导出导入环境一致、交付简单、回滚容易需要联网机器作为转换跳板推荐Docker Registry 仓库中转支持多机器分发离线环境还得额外部署一个镜像仓库环境复杂时可用最终我选择了第二种用一台能联网的工作机拉取官方镜像完成中文化和必要配置再导出 tar 包送到离线目标服务器上导入启动。这也是目前业界做内网容器化交付最主流的方式。1.3 离线部署完整流程规划整个流程可以规划成下面几个阶段环境与版本确认确认离线机器的 CPU 架构、Docker 版本、磁盘空间。镜像准备联网机拉取 apache/superset:4.1.1做中文化配置导出镜像包。镜像传输使用压缩后的 tar 包通过 U 盘/内网传输工具拷入离线机。部署启动离线机加载镜像编写 docker-compose 配置完成数据库初始化和账号创建。验证访问登录界面确认中文语言和时区设置。这个路径看起来简单但每一步都有细节尤其是中文化配置和数据库初始化最容易出问题。下面我会一步步拆开讲。2. 部署前准备版本选型与资料清单2.1 版本选型为什么选 4.1.1Superset 的版本迭代速度不算慢我选 4.1.1 主要看中三点4.1.x 属于稳定版本线核心功能SQL Lab、Dashboard、Charts已经非常成熟没有太多破坏性变更。4.1.1 修复了 4.1.0 里的一些权限和图表渲染问题相对于 4.0.x它在前端交互和加载性能上也有明显提升。Docker Hub 上有对应的官方镜像 tag可以直接拉取apache/superset:4.1.1。这里要提醒一句不要图新鲜直接用 latest 或者 dev 标签。离线环境没有网络一旦镜像有问题你甚至没法临时 pull 一个补丁版本所以必须用一个明确、稳定的版本号。2.2 离线机器环境要求在执行部署前先到目标服务器上用命令确认这几项# 查看系统架构x86_64 还是 arm64 uname -m # 查看系统发行版 cat /etc/os-release # 查看 Docker 版本 docker --version # 查看磁盘空间镜像解压后至少预留 10GB df -h /var/lib/docker我这次部署的机器是 x86_64 架构的离线服务器Docker 版本为 24.0.x满足要求。如果是 ARM 架构需要在联网机器上拉取对应的 ARM 镜像导出方式一样但是 tag 前缀需要留意。Superset 官方镜像对多架构支持得比较好拉取时会自动匹配这一步通常不会出问题。2.3 需要提前准备的资料清单离线部署讲究“一次备齐”我整理了一个检查清单你在开始前对着打勾Superset 镜像 tar 包联网机导出建议压缩大约 1.5GB 左右。docker-compose.yml 文件可以现场写但我建议提前准备好并测试过。superset_config.py 中文化配置文件后续会细讲。Docker 离线安装包rpm/deb如果离线机器连 Docker 都没装需要提前准备。外部数据库驱动包可选如果要连 MySQL、PostgreSQL 等外部数据源需要提前把驱动打包进镜像。注意第 4 点。很多离线服务器真的就是“裸机”Docker 都没有。如果你的目标机器还没有 Docker需要到能联网的机器上把 Docker 的安装包和依赖包全部下载好再一起拷进去。3. 联网机器上准备 Superset 4.1.1 镜像3.1 拉取官方镜像在能联网的机器上先拉取官方镜像docker pull apache/superset:4.1.1拉取完成后用docker images确认docker images | grep superset正常情况下会看到类似信息apache/superset 4.1.1 b2b1e2b2c8a6 2 weeks ago 1.32GB3.2 给镜像打一个本地标签打完标签之后可以避免后续导入时 REPOSITORY 字段太冗长。我一般习惯打一个简短的 tagdocker tag apache/superset:4.1.1 superset-local:4.1.1这里解释一下原因docker save 导出时会保留镜像的 repo 和 tag 信息如果你使用了很长的原始 tag在离线机器上 load 之后也要用同样的名字才能引用。打一个简短 tag后面写 compose 文件时更清爽。3.3 中文化镜像的构建关键步骤官方镜像默认虽然支持多语言但有几个问题默认 locale 是英文、时区是 UTC、部分翻译资源需要额外处理。为了做到真正的“中文版”我们需要在联网机器上基于官方镜像构建一个新的自定义镜像。这里我写了一个 DockerfileFROM apache/superset:4.1.1 # 切换到 root 用户安装额外依赖 USER root # 设置时区 RUN apt-get update \ apt-get install -y --no-install-recommends tzdata \ cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \ echo Asia/Shanghai /etc/timezone # 如果后续需要连接外部数据库在这里加入 python 驱动 RUN pip install --no-cache-dir pymysql psycopg2-binary # 切换回 superset 用户 USER superset # 设置环境变量 ENV SUPERSET_HOME/app/superset \ TZAsia/Shanghai \ LANGC.UTF-8 \ LC_ALLC.UTF-8构建并导出docker build -t superset-local:4.1.1 .需要说明的是Superset 语言本身是通过前端 i18n 机制管理的官方镜像已包含中文翻译资源。这里的“中文化”主要体现在时区默认设为东八区避免图表时间显示差 8 小时。通过环境变量和配置文件把默认语言设置为 zh。确保系统 locale 不会导致中文乱码。3.4 导出镜像并压缩传输镜像构建好后开始导出。这里有两个方案方案一直接导出不压缩docker save -o superset-4.1.1.tar superset-local:4.1.1方案二导出后压缩推荐docker save superset-local:4.1.1 | gzip superset-4.1.1.tar.gz压缩后的镜像体积能小 30%~40%在通过内网传输工具或 U 盘拷贝时能省不少时间。拷贝到离线机器后建议先用md5sum或sha256sum校验一下文件完整性防止传输过程中损坏。这一步看起来多余但实际工作中很管用——我就碰到过镜像包拷贝到一半断了结果 load 时报错找不到 manifest 的情况。4. 中文本地化的完整配置4.1 Superset 多语言机制说明Superset 的界面语言是运行时动态加载的。默认情况下它会根据浏览器的Accept-Language来显示语言。最要命的是如果你的浏览器或操作系统是英文环境Superset 就显示英文如果浏览器是中文环境它可能显示中文但部分翻译不完整。要做到不管用户浏览器设置如何打开就是中文需要从服务端指定默认语言。Superset 读取语言配置的顺序是环境变量 -superset_config.py- 数据库用户偏好设置。也就是说即使你在配置里改了默认语言用户未单独设置时也能生效但用户如果自己改过语言偏好则会覆盖默认配置。4.2 创建 superset_config.py我们需要准备一个中文化配置并把它挂载到容器里。先创建配置文件# superset_config.py import os from typing import Optional # 用于 Flask 签名和会话加密务必修改成随机字符串 SECRET_KEY os.environ.get(SUPERSET_SECRET_KEY, please-change-me) # 默认语言设为中文 BABEL_DEFAULT_LOCALE zh LANGUAGES { zh: {flag: cn, name: Chinese}, en: {flag: us, name: English}, } # 时区 TZ Asia/Shanghai SUPERSET_TIMEZONE Asia/Shanghai # 使用 SQLite 时不需要额外配置如果生产环境使用 MySQL请配置下面的内容 SQLALCHEMY_DATABASE_URI os.environ.get( DATABASE_URL, sqlite:////app/superset/superset.db ) # 允许跨域请求按需开启 ENABLE_CORS True将这个配置文件挂载进容器有两种方式方式一通过 volume 挂载在 docker-compose.yml 中挂载volumes: - ./superset_config.py:/app/superset/superset_config.py:ro方式二直接打进镜像将配置文件复制进镜像COPY superset_config.py /app/superset/superset_config.py我两种都试过。如果是给多个环境复用建议打进镜像交付物更完整如果只是单台机器调试挂载更方便改配置重启容器即可。4.3 启动时指定配置文件路径Superset 官方镜像的启动脚本默认会寻找SUPERSET_CONFIG_PATH环境变量。如果你没有显式设置它会按默认路径加载。为了保险建议在环境变量中显式指定SUPERSET_CONFIG_PATH/app/superset/superset_config.py如果挂载或复制路径不对Superset 会静默使用默认配置导致中文化不生效。这里最容易出的问题就是路径写错但服务又能正常启动让你很难排查。建议启动容器后执行下面命令确认配置已加载docker exec -it superset sh -c python -c from superset import app; print(app.config.get(\BABEL_DEFAULT_LOCALE\))如果输出是zh说明配置生效了。5. 离线服务器上的完整部署实操5.1 安装 Docker如果离线机上没有如果目标服务器已经装好 Docker直接跳过这一步。如果没装这块是离线部署里最恼人的环节。以 CentOS 7 / openEuler / 麒麟等 rpm 系系统为例需要在联网机器上下载 Docker 和相关依赖。最简单的做法是在联网机器上使用yumdownloader或dnf download命令把需要的 rpm 全部拉下来# 在联网的相同系统版本机器上执行 mkdir -p /tmp/docker-rpm cd /tmp/docker-rpm yum install --downloadonly --downloaddir/tmp/docker-rpm docker-ce docker-ce-cli containerd.io docker-compose-plugin然后把整个/tmp/docker-rpm目录拷贝到离线机器上rpm -Uvh *.rpm装完后启动服务systemctl enable docker systemctl start docker如果是 Ubuntu/Debian 系思路一样用apt-get download或apt download把 deb 包拉下来再dpkg -i安装。这块细节比较多每家公司的离线环境情况差异大建议在实施前先摸清系统版本和依赖情况。5.2 导入镜像先创建部署目录并导入镜像mkdir -p /opt/superset cd /opt/superset # 将 tar.gz 包放到 /opt/superset 后执行 gzip -dc superset-4.1.1.tar.gz | docker load加载完成后检查镜像docker images | grep superset正常情况下你会看到superset-local和4.1.1的镜像信息。如果发现 REPOSITORY 显示为none说明镜像在保存时 tag 信息丢了可以用docker tag重新打标签例如docker tag IMAGE_ID superset-local:4.1.15.3 编写 docker-compose.yml在离线机器上创建docker-compose.ymlversion: 3.8 services: superset: image: superset-local:4.1.1 container_name: superset restart: always ports: - 8088:8088 environment: - TZAsia/Shanghai - SUPERSET_CONFIG_PATH/app/superset/superset_config.py - SUPERSET_SECRET_KEYyour-random-secret-key-change-me volumes: - ./superset_config.py:/app/superset/superset_config.py:ro - superset-data:/app/superset command: sh -c superset db upgrade superset init superset run -h 0.0.0.0 -p 8088 --with-threads --reload --debugger volumes: superset-data:这里有一点要特别说明我用的 command 是先执行db upgrade再启动服务。如果你前期把配置文件放错了位置容器启动就会卡在数据库初始化的环节。所以挂载进去的配置文件一定要保证路径正确。5.4 初始化数据库与管理账号容器启动后如果命令里没有自动创建管理员账号需要手动执行# 进入容器 docker exec -it superset bash # 创建管理员按提示输入用户名、邮箱、密码 superset fab create-admin # 初始化权限和角色数据 superset init # 如果希望加载示例数据可选 superset load_examples这里需要注意创建管理员时首次输入的密码不要太简单Superset 对密码策略有一定要求太弱会直接拒绝而且不给你明确的密码规则提示很容易反复报错。我当时的密码设置为Admin123456这种强度一次通过。5.5 验证部署初始化完成后在浏览器里访问http://服务器IP:8088如果部署成功你会看到登录页面并且界面语言已经是中文。用刚创建的管理员账号登录就能看到完整的控制台、仪表盘列表和数据源管理菜单。6. 常见问题与排坑记录6.1 问题速查表下面这些问题是离线部署 Superset 时最常遇到的我按照“症状 - 原因 - 解决方案”整理成一张速查表建议保存。症状原因解决方案docker load失败报invalid tartar 包损坏或未完整传输重新传输拷贝前比对 md5镜像加载成功但启动容器报image not found没有短 tag启动时引用了不存在的 tag用docker images查看准确 tag登录后白屏或反复跳登录页SECRET_KEY未设置或变化在环境变量中固定 SECRET_KEY中文不生效配置文件路径不对或挂载失败检查容器内配置文件是否存在图表时间显示偏差 8 小时容器时区未设置设置TZAsia/Shanghai连接 MySQL 数据源失败缺少 pymysql 驱动构建镜像时安装 pymysql登录时报 CSRF 错误反向代理或端口映射导致请求地址异常在配置中设置ENABLE_PROXY_FIX True浏览器访问 8088 不通防火墙拦截或端口未开放systemctl status firewalld检查并开放端口6.2 我踩过的三个大坑坑一数据库迁移卡死或超时第一次启动时superset db upgrade在 SQLite 上跑得还算快但如果数据卷比较大迁移可能需要两三分钟。如果容器日志长时间没有更新不要急着重启先观察。可以在另一个终端执行docker logs -f superset等待完成。如果反复失败建议清掉数据卷重新开始docker compose down -v docker compose up -d坑二登录页面中文但仪表盘里的日期格式还是英文即使界面语言改成了中文默认的日期格式可能还是YYYY-MM-DD这种通用格式符合国内需求就不用管如果你需要切换到YYYY年MM月DD日需要在配置中自定义DATE_FORMAT YYYY年MM月DD日不过这个格式在国际化环境下容易引起歧义我一般不建议随意改除非是纯内部使用。坑三连接外部数据库时驱动缺失Superset 本身不带所有数据库驱动。我们最常见的需求是连 MySQL 和 PostgreSQL所以构建镜像时一定要提前装好pymysql和psycopg2-binary。连接串示例# MySQL SQLALCHEMY_DATABASE_URI mysqlpymysql://user:passwordhost:3306/dbname # PostgreSQL SQLALCHEMY_DATABASE_URI postgresqlpsycopg2://user:passwordhost:5432/dbname如果忘了装驱动在界面上新建数据库连接时会报No module named pymysql而且日志里不会提示你怎么装。这也是为什么我在前面的 Dockerfile 里特意加了这两行 pip 安装。6.3 日常运维补充部署完成并不是终点。我现在在离线服务器上还保留了一套简单的运维习惯每天备份superset-data卷里的superset.db文件。定期使用docker compose pull联网机构建新版本复制到离线机升级。所有重要变更先改配置再重启容器尽量不直接进容器改文件因为容器重建后文件会丢失。写在最后关于离线交付的一点体会这次 Superset 4.1.1 离线部署最大的收获其实是让我对“交付物思维”有了更深的理解。在线环境可以随意调试离线环境里所有东西都必须提前准备、反复验证没有试错的余地。镜像、配置文件、初始化命令、数据卷备份每一项都要想清楚它会在哪个环节被用到。根据我个人的经验第一次做离线部署时一定要在联网环境里完整跑一遍流程把能踩的坑都踩完再固化到离线交付清单中。比如 Dockerfile 里驱动装没装、superset_config.py 路径对不对、SECRET_KEY 有没有固定这些问题在联网环境下有提示容易发现在离线环境里一个小错误可能导致整个交付卡住几天。最后再分享一个小技巧如果后期有多台离线机器需要部署建议把构建好的中文化镜像上传到内网的 Docker Registry 中比如 Harbor。这样每台新机器只需要docker pull内网镜像即可不用每次拷贝几个 G 的压缩包。离线部署的本质从来不是“能不能装”而是“怎么把一次的成功经验可靠地复制到每一台机器上”——把流程固定下来比单次跑通重要得多。本文还有配套的精品资源点击获取