企业官网建设流程全解析

简介：面向需要在内网或无外网环境中落地数据可视化的运维与开发人员，这份资源提供 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_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 TZ=Asia/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 \ --restart=always \ apache/superset:4.1.1

逐个说参数：-d 后台运行；--name 固定容器名，后面 exec 的时候不用查容器 ID；-p 映射 8088 端口；-e TZ 把容器时区设成上海，解决后面图表时间差 8 小时的问题；-e SUPERSET_CONFIG_PATH 告诉 Superset 去读哪个配置文件；两个 -v 分别是挂载配置文件和持久化目录；--restart=always 让内网机器重启后容器自动起来。

这里必须提醒一句：/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 admin@example.com \ --password Admin@123456

第一条 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 50

docker 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 这个 tag，docker run 报找不到镜像。

原因：tar 包里的镜像在源机器上就不是标准名字打出来的，可能是从另一台机器 load 后没有重新 tag，tag 元信息在打包时就是空的。save 只保存镜像层和当前 tag，不会自动补全名字。

解决：load 之后立刻用 docker tag <IMAGE_ID> apache/superset:4.1.1 固定名字，后续所有命令都用这个名字引用。在准备阶段也养成习惯，在联网机器上先确认 docker images 里 tag 完整再打包。

5.2 配置文件挂载成目录，容器秒退

现象：docker run 后容器状态一直 Exited，docker 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 ps

systemctl 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 小时，导出报告里的时间戳也对不上。

原因：容器默认时区是 UTC，Superset 从容器环境变量读时区，而不是宿主机时区。

解决：docker run 时加 -e TZ=Asia/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_NAME="apache/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 TZ=Asia/Shanghai \ -e SUPERSET_CONFIG_PATH=/app/superset/superset_config.py \ -v "$CONFIG_SRC":/app/superset/superset_config.py \ -v "$DATA_DIR":/app/superset_home \ --restart=always \ "$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 admin@example.com \ --password Admin@123456 echo "部署完成，访问 http://<内网IP>:8088"

脚本里 set -euo pipefail 的作用是任何一步失败立即停止，防止带着错误状态往下跑；docker rm -f 那行保证重复执行时不冲突。初始化命令里如果账号已经存在，fab create-admin 会提示已存在，不影响后续使用。实际使用时，把密码和路径改成自己环境的，不需要额外安装任何工具，脚本本身就在离线包目录里。

部署完之后的验收，我一般按这个顺序做：先 curl /health 确认服务在线，再登录页切换中文确认汉化生效，然后建一张测试图表、导出一张 PNG 确认字体正常。这三关过了，这套离线环境就具备了交付条件。

我第一次做这类离线部署时，在配置文件挂载目录这个坑上浪费了半天，容器起不来，日志翻来翻去才明白是 -v 挂错了路径。后来把流程固化成脚本，新环境十分钟就能跑通。内网部署这种事，一次做对比做得快更重要，希望这份笔记能帮你在 Superset 4.1.1 离线部署上少走几段弯路。

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