企业官网建设流程全解析

简介：面向内网或离线环境中需要快速搭建数据可视化平台的企业与开发者，这一压缩包提供了 Superset 4.1.1 中文版的 Docker 离线部署方案。它将开源数据探索工具与容器化优势相结合，省去联网拉取镜像和英文文档查阅成本，中文界面也明显降低了使用门槛。整包共 6 个文件，以 tar 镜像文件为主体，覆盖 Superset 中文应用、Redis 缓存与 PostgreSQL 数据库三个离线镜像；同时包含 docker-compose.yml 容器编排文件、superset_config.py 配置文件和 .env 环境变量文件，分别用于服务定义、数据库连接与安全参数设置。压缩包约 524.2MB，结构简明，适合直接导入部署。目前已有 364 人学习下载。按编排文件启动容器后即可获得可用的中文 Superset 实例，可用于企业数据探索、可视化看板搭建与内部 BI 场景，也有助于运维人员在无外网环境下理解镜像、编排和配置之间的配合关系。

1. Superset 4.1.1 中文版 Docker 离线部署：内网 BI 的最后一公里，卡在镜像和语言上

一个没有外网的数据中心里，业务方急着要看板，服务器不能连公网，手上只有一台能上网的办公电脑。这时候 Apache Superset 4.1.1 的 Docker 离线部署就成了刚需：把官方镜像打包运进内网，再配好中文界面和数据库驱动，整套 BI 环境就能在内网跑起来。这件事难倒过不少人，但拆开看只有三个核心问题：镜像怎么运进去、中文怎么真正生效、额外的数据库驱动怎么装。本方案就是解决这三个问题的，适合做数据平台、数据仓库交付、或者在企业内网搭自助分析环境的工程师。按下面步骤走，一到两天内能出一个稳定跑在 4.1.1 上的中文版 Superset。

2. 离线部署先从镜像说起：save/load 与内网镜像分发的三种做法

2.1 有网机器上拉取镜像并固化：先核对 tag 再动手

离线部署第一步不是写配置，而是把 Docker 镜像做成一个可以搬运的文件。我一般会在有网的机器上先拉取apache/superset:4.1.1，注意 tag 一定要写全。很多人在这步就翻车，拉了个latest回来，进内网之后发现行为和预期不一致，想排查都没法复现。

# 在有网机器上执行 docker pull apache/superset:4.1.1 # 确认镜像存在且架构正确 docker images | grep superset

这里docker pull之后用docker images看一眼，确认 REPOSITORY 列是apache/superset，TAG 列是4.1.1。如果目标服务器是 ARM 架构（比如鲲鹏、飞腾），还需要在拉取时指定平台参数，否则运过去装上也跑不起来。常见做法是加--platform linux/amd64或--platform linux/arm64，取决于你内网服务器的 CPU 架构。

确认无误后，把镜像固化成本地文件：

docker save -o superset_4.1.1.tar apache/superset:4.1.1 # 传输前检查文件完整性 ls -lh superset_4.1.1.tar

docker save做的事情是把镜像的所有层打包成一个 tar 文件，这个文件可以拷贝到 U 盘、通过 scp 或内网文件服务器传进隔离网络。我习惯在 save 完之后立刻记录一下文件大小和 SHA256 值，传输完成后比对，避免内网传输工具丢数据。镜像本身很大是正常的，别因为文件大就怀疑打包失败。如果你用的内网文件服务器经常断点续传失败，建议分割传输或者用 rsync 这类带校验的工具。

2.2 进内网的通道：docker save / docker load 与私有仓库怎么选

镜像文件进来之后，目标服务器上执行docker load就能把镜像导进本地 Docker。这是最直接的通道，适合只有一两台服务器的场景。但如果内网里有十台机器都要部署 Superset，每台都docker load一次虽然可行，却不是最高效的办法。

# 目标服务器执行 docker load -i superset_4.1.1.tar # 验证镜像已经导入 docker images | grep superset

另一种更工程化的做法是在内网搭一个私有 registry（比如 Harbor 或 Docker Registry），把 tar 包 load 到一台机器上之后docker tag再docker push到内网 registry，其他机器直接docker pull。这样做的优点在于后续升级镜像版本、分发其他组件时，整套流程都能复用，不用每次拿 U 盘跑来跑去。

如果内网环境规划里有 Kubernetes，那更要把镜像放进私有仓库，因为 K8s 节点本身是不允许随意从外网拉镜像的。这块没有绝对的对错，我的判断标准很简单：两到三台机器，用 save/load 就够了；超过三台，直接上私有 registry 更省事。国内很多团队在内网里同时跑 Hadoop、人大金仓数据库、Kodbox 这类私有化组件，镜像管理早晚要做，不如一开始就选好。

2.3 你自己写还是用官方 Compose：离线场景下我推荐哪种

Superset 官方发布时带了一份 Docker Compose 编排文件（分 dev 和 non-dev 两个版本）。但离线环境里直接用官方非 dev 版有一个很实际的问题：它里面定义的初始化容器和 worker 容器，在离线场景下依赖的镜像 tag 比较多，搬运起来麻烦，而且启动顺序对新手不友好。

我一般会在离线部署时写一个精简版 docker-compose.yml，只保留 superset 主服务，把 worker 和 beat 先砍掉。对于中小团队的分析场景，单容器跑 Superset 完全够用，后续要扩展再补 worker 也不迟。

services: superset: image: apache/superset:4.1.1 container_name: superset restart: always ports: - "8088:8088" environment: - SUPERSET_SECRET_KEY=please_change_this_to_your_own_key - TZ=Asia/Shanghai volumes: - ./superset_config.py:/app/pythonpath/superset_config.py:ro - superset_home:/app/superset_home volumes: superset_home:

这段编排里重点说明三个地方。第一，SUPERSET_SECRET_KEY必须改成你自己的随机字符串，否则每次重启容器时 session 失效，用户会被频繁踢下线。第二，./superset_config.py以只读方式挂载到/app/pythonpath/目录，这是 Superset 镜像约定的配置目录，只要这个文件存在，容器启动时就会自动加载。第三，superset_home这个命名卷用来持久化 SQLite 数据库和上传的文件资源，不挂的话容器一删全没了。这个文件要随镜像一起拷贝进内网，我习惯把它和 config 文件放在同一个目录里，方便维护。

3. 把 4.1.1 调成中文版：语言、时区与初始化一个都不能少

3.1 中文不生效的真正原因：浏览器语言判断与 config.py 的优先级

很多人以为 Superset 支持中文就是在界面上选一下语言，实际进去后发现只有登录框旁边的语言下拉菜单里能看到中文选项，选完也确实是中文。但默认情况下，Superset 的界面语言是跟随浏览器 Accept-Language 走的。如果你的内网用户用的是 Chrome 默认英文环境，或者公司统一推送了英文版浏览器配置，打开 Superset 依然是英文界面。

要让 Superset 4.1.1 默认就是中文，需要在挂载的superset_config.py里显式指定默认语言，而不是依赖用户手工去切。下面这一段是我实际用的配置：

# -*- coding: utf-8 -*- # superset_config.py 挂载到 /app/pythonpath/ 后自动生效 # 语言配置：把中文放在第一位并设置默认 LANGUAGES = { "zh": {"flag": "cn", "name": "Chinese"}, "en": {"flag": "us", "name": "English"}, } # 默认界面语言设置为中文 BABEL_DEFAULT_LOCALE = "zh" BABEL_DEFAULT_FOLDER = "superset/translations"

配置里的关键是BABEL_DEFAULT_LOCALE，这一项决定了用户在未登录和没有显式设置语言偏好时，界面默认用哪种语言。LANGUAGES字典则控制语言下拉菜单里能选哪些语言。这里要提醒一句，不要只设LANGUAGES不设BABEL_DEFAULT_LOCALE，那样下拉菜单里有中文，但默认还是英文，等于没配。BABEL_DEFAULT_FOLDER保持默认路径不要动，指向的是镜像内翻译文件的位置。

挂载方式在上一章的 docker-compose.yml 里已经写了，把这份文件保存为superset_config.py，和 compose 文件放在同一个目录。修改配置后需要重启容器才能生效，docker compose restart superset即可，不需要重新导入镜像。

3.2 第一次启动的初始化顺序：db upgrade、create-admin 与 init 连着做

镜像导入、容器启动之后，Superset 还不能直接用。4.1.1 的镜像默认带了一个空数据库结构，需要执行三条初始化命令，顺序不能乱。先说结论，再解释为什么。

# 进入容器执行初始化 docker compose exec superset superset db upgrade docker compose exec superset superset fab create-admin \ --username admin \ --firstname admin \ --lastname admin \ --email admin@example.com \ --password admin123456 docker compose exec superset superset init

superset db upgrade负责把数据库表结构升级到当前版本对应的 schema。如果你是新建部署，这一步就是建表；如果你是从旧版本升级上来的，这一步会自动跑迁移脚本。第二步superset fab create-admin创建管理员账号，这里用的fab命令是 Flask-AppBuilder 的命令行工具，Superset 的权限体系构建在它之上。第三步superset init会写入基础角色、权限和默认配置数据，不执行这一步的话，就算有管理员账号也看不到菜单项。

这三条命令我见过很多人跳步骤。有人忘了跑init，结果登录进去侧边栏只有空壳；有人顺序颠倒先建账号再 upgrade，结果账号写进去又被迁移脚本重置。稳妥做法是第一条命令执行完看到日志输出 no problem 或迁移成功字样，再执行下一条。整个初始化过程在离线环境里不需要联网，所有依赖都在镜像内部。

3.3 时区、连接串与编码：让图表里的时间不差八小时

中文界面搞定之后，通常紧跟着的问题是时区。Superset 默认用 UTC 时间，国内团队看到的图表时间永远比北京时间慢八小时。这个不是 bug，是设计使然，需要在两个层面同时处理。

第一层是操作系统和运行时的时区，在 docker-compose.yml 的 environment 里加TZ=Asia/Shanghai，这样容器内日志时间和执行计划都走北京时间。第二层是在superset_config.py里加一段配置，让 Superset 在渲染图表时也按指定时区处理时间字段：

# 时区配置：影响图表时间展示 TIMEZONE = "Asia/Shanghai"

但真正隐藏的坑在数据库连接串上。如果你的数据源是 MySQL 或 PostgreSQL，连接串里建议显式指定时区和字符集，否则数据库返回的 DATETIME 会被 Superset 当作 UTC 处理。常见做法是在连接串后面追加参数：

mysql://user:password@mysql_host:3306/your_db?charset=utf8mb4

这里charset=utf8mb4是为了让中文数据正常显示不变成乱码。PostgreSQL 的驱动一般在连接串里用options=-c%20timezone%3DAsia%2FShanghai的方式指定。这些细节如果不提前处理，做出来的图表时间对不上，业务方第一反应就是平台有问题，解释成本很高。

4. 离线装数据库驱动：用自定义镜像而不是进容器 pip install

4.1 为什么容器内 pip install 是伪需求

Superset 产品本身支持连接主流数据库，但镜像内置的驱动并不全。默认镜像里带了 PostgreSQL 和 MySQL 的基础驱动，可当你需要连接国产数据库或者新版本的 MySQL 8.0 时，进容器执行pip install是很多人的第一反应。这在有网环境没问题，重启容器后镜像一重建就全没了。

离线环境下，容器内根本没有网，pip install直接报错。更麻烦的是 Superset 镜像的底层是基于特定版本 Python 编译的，你在宿主机上手动下载的 wheel 包很可能因为 manylinux 标签不匹配装不上。所以唯一可靠的方式是：在有网环境里构建一个包含额外驱动的自定义镜像，再把这个镜像 save 进内网分发。这本质上是把“装驱动”这件事提前到打包阶段解决。

4.2 在有网机器上用 pip download 攒离线 wheels，再 Dockerfile 构建

具体做法分两步。第一步，拉一个和线上环境一致的 Superset 4.1.1 镜像，用容器内的 pip 把需要的驱动下载成 wheel 文件：

# 在有网机器执行：下载驱动到本地 wheels 目录 docker run --rm -v "$PWD/wheels":/wheels apache/superset:4.1.1 \ pip download pymysql cryptography -d /wheels

这里把当前目录的wheels文件夹挂载到容器里，在容器内执行pip download的好处是，下载的 wheel 包和 Superset 镜像里的 Python 版本、系统库完全匹配。pymysql是纯 Python 的 MySQL 驱动，兼容性最好；cryptography是连接 MySQL 8.0 时做认证加密的依赖，很多人漏掉它导致连库时报错。下载完成后，wheels目录里会有一堆.whl文件。

第二步，写一个 Dockerfile 把这些 wheel 打进新镜像：

# 以官方镜像为基础 FROM apache/superset:4.1.1 # 拷贝离线 wheel 包进镜像 COPY wheels /tmp/wheels # 离线安装驱动，装完清理临时目录 RUN pip install --no-index --find-links=/tmp/wheels \ pymysql cryptography \ && rm -rf /tmp/wheels

构建命令是docker build -t superset-custom:4.1.1 .。之后流程回到第二章，把superset-custom:4.1.1这个新镜像 save 成 tar 包，传进内网再 load。构建自定义镜像这个能力，后面接人大金仓数据库、达梦数据库时也用得上，原理一样，只是换驱动包名。

4.3 替换镜像后重启：config 与驱动生效的验证

自定义镜像导入内网后，把之前 docker-compose.yml 里的image字段改成新镜像名，然后重新创建容器：

# 目标服务器上执行 docker compose up -d # 看启动日志确认没有报错 docker compose logs superset | tail -n 50

判断驱动是否生效，最直接的方式是在 Superset 的“数据”菜单里新建数据库连接。填完 MySQL 连接串后，Superset 有个测试连接按钮。如果你点了测试依然报Can't connect to MySQL server，先看报错是网络层还是认证层。网络层的问题大概率是两台机器不在同一个 Docker 网络里，可以用docker network inspect排查；认证层的报错通常比网络层多一行caching_sha2_password关键字，那就是驱动兼容问题。

我见过不少团队在这一步卡两三天，最后发现只是 compose 文件里忘了把数据库地址写成容器网络内可达的主机名。记住一个原则：Superset 容器访问 MySQL，不要写localhost，要写 MySQL 容器名或宿主机内网 IP。

5. Superset 4.1.1 离线部署避坑：五个高频问题的现象与处理

5.1 镜像 load 成功 Compose 却找不到镜像：tag 对不上

现象：docker load -i superset_4.1.1.tar执行完没有任何报错，docker images也能看到记录，但执行docker compose up -d时提示image not found。

原因：compose 文件里写的镜像名带了:latest后缀，比如写成apache/superset:latest，而 save 的时候保存的是apache/superset:4.1.1。Docker 不会自动把 4.1.1 当成 latest。

解决：save 之前先明确 tag，或者在 compose 里严格写apache/superset:4.1.1。我习惯把镜像 tag 写进 compose 文件，不依赖latest这种可变标签。内网环境里一旦有两个版本的镜像，latest指向谁完全不可控。

5.2 容器起来但页面一直 loading：资源没起来和内存不够是两码事

现象：浏览器打开 8088 端口，登录页能出来，但登录之后页面转圈，菜单和图表一直不出来。docker compose ps看到容器状态是 Up，日志里也没有 fatal 错误。

原因：这个报错在 4.x 版本里常见。一种情况是superset init没执行，权限数据没生成，前端请求接口 403 导致白屏；另一种情况是容器内存太小，Superset 渲染页面时前端资源加载超时。这两者的表现几乎一样，但处理方式完全不同。

解决：先执行docker compose exec superset superset init，完成后刷新页面。如果还白屏，看宿主机内存和容器日志；我一般会给 Superset 容器留至少 2GB 内存，在 compose 里用mem_limit: 2g限制。多数 4.1.1 部署的现场问题都是内存不够而不是程序坏了。

5.3 切了中文还是英文：Accept-Language 与 LANGUAGES 的配合

现象：config.py 里 LANGUAGES 和 BABEL_DEFAULT_LOCALE 都写了，重启后界面还是英文。

原因：Superset 的语言选择逻辑是先看用户偏好，再看浏览器 Accept-Language 头，最后才落到默认配置。公司统一安装的浏览器如果默认发en-US，且用户在 Superset 用户信息里已经设置过语言偏好，那 config 里的默认值就不生效。还有一种情况是挂载的 config.py 没有真正加载，容器的/app/pythonpath/路径挂载失败。

解决：进入容器验证 config 有没有加载：docker compose exec superset python -c "from superset_config import *; print(BABEL_DEFAULT_LOCALE)"，能输出zh就是加载了。确认加载后，让用户点右上角头像，在用户信息里把语言切到中文，这是一次性的。想彻底解决就要求内网统一浏览器策略，或者干脆接受第一次登录手动切语言。

5.4 连接 MySQL 卡在认证插件：caching_sha2_password 的兼容处理

现象：数据库连接测试报错，日志里有Authentication plugin 'caching_sha2_password' cannot be loaded或类似字样。

原因：MySQL 8.0 默认认证插件是caching_sha2_password，而 Superset 4.1.1 镜像里自带的 MySQL 客户端驱动对这个插件的支持不完整。这个问题在有网环境也常见，离线环境里因为没法顺手升级驱动，更容易卡住。

解决：按第四章方式构建自定义镜像，把pymysql和cryptography打进镜像；同时把数据库连接串的驱动一层写成mysql+pymysql。我一般建议不要为了图省事把 MySQL 用户的认证插件改成mysql_native_password，那是拿数据库安全性妥协，不值得。

5.5 重启后数据全丢：SQLite 与挂载卷的关系

现象：容器重建之后，登录页能打开，但之前建的看板、数据源、用户全没了，像是新装的一样。

原因：Superset 默认使用 SQLite 数据库，文件存放在容器内部的/app/superset_home目录。这个目录如果没挂载到宿主机，容器一删数据就跟着没了。docker-compose.yml 里没写 volumes 的人十有八九踩这个坑。

解决：在 compose 里配置 volumes，把/app/superset_home映射到宿主机目录，比如./superset_home_data:/app/superset_home。如果内网已经规划了 MySQL 作为元数据库，那就提前在 config.py 里把 SQLAlchemy URI 指过去，生产环境更稳。记住，SQLite 适合验证和轻量使用，多人协作的团队直接上 MySQL 或 PostgreSQL。

6. 部署完成后的验证清单与一条保命习惯

部署完成不是看一眼页面能打开就结束了，我每次交付后都会走一遍固定验证流程。先把服务状态和健康检查跑一遍：

# 目标服务器上执行验证 docker compose ps # 健康检查接口，返回 OK 代表服务正常 curl -s http://localhost:8088/health

健康检查通过后，用管理员账号登录，新建一个测试数据源，随便跑一个 Table 类型的图表，确认查询、渲染、导出三个路径都通。很多人只验证到图表能出来就收工了，导出 Excel 这个功能经常在离线环境里因为字体缺失导出乱码或者直接失败。既然业务方会用到导出，就顺手验证掉。

这里我想说一个自己吃亏换来的保命习惯：每次改 config.py 或 docker-compose.yml 之前，先备份当前能用的版本，用cp加时间戳就行，或者干脆把这个目录纳入 git 管理。离线环境里没有外网，出了问题想查资料都费劲，唯一可靠的办法就是随时能回滚到上一个能跑的状态。我见过同事手滑把系统自带的 superset_config.py 覆盖了，整个平台的登录和权限全部失控，最后花了一天才从镜像里扒出原始文件。所以我现在任何配置改动前都留一个备份，这个习惯在离线环境里救了我很多次。

希望这篇部署笔记能让你少走弯路，按这个流程来的话，Superset 4.1.1 中文版在内网跑起来只是时间问题。部署完成之后，再研究一下自定义图表插件和定时报表，这套平台就能真正承担起团队的自助分析需求了。

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