企业官网建设流程全解析

简介：这份资源面向需要在无外网环境下搭建数据可视化平台的企业与开发者，提供 Superset 4.1.1 中文版的 Docker 离线部署方案，将容器化部署与中文界面结合，降低英文命令行使用门槛。压缩包共 6 个文件，约 524.2MB，以 3 个 tar 镜像包为主，另含 yml 服务编排、py 配置脚本与 env 环境变量文件，分别对应镜像导入、多容器编排、参数配置与连接信息设定。已有 370 人学习下载。资源覆盖离线部署所需的关键环节，读者可据此完成镜像加载、服务编排与配置调整，快速搭建可移植、可重复使用的分析环境，并借助中文界面开展数据探索与可视化展示，同时为后续版本更新与安全维护提供参考。

1. 内网离线装 Superset 4.1.1 中文版：先想清楚镜像怎么进去

上周帮一个做数据报表的团队在内网环境里装 Superset 4.1.1 中文版，机器连不上外网，Docker Hub 也拉不动，一开始想当然地在目标机上敲docker compose up -d，结果卡在拉镜像那一步，日志里全是超时。这种场景其实很常见：数据平台要部署在隔离网段，安全策略不允许出站，但 Superset 又必须跑起来给业务看板用。装不好会怎样？最典型的就是镜像拉一半失败、容器起来后中文乱码、元数据库连不上，最后卡在登录页进不去。这篇笔记面向的是要在离线或半离线环境里落地 Superset 4.1.1 中文版的开发者，从镜像准备、离线导入、compose 配置到验证跑通，一步步走完，中间踩过的坑也一并记下来。

Superset 4.1.1 这个版本对 Python 3.9/3.10、Node 18 有要求，官方镜像已经把这些依赖打进去了，所以离线部署的核心不是装 Python，而是把镜像和中文语言包一起搬进去。下面按「准备镜像 → 导入加载 → 配置 compose → 初始化元数据 → 验证」的顺序展开，每一步都给出可抄的命令和参数说明。

2. 离线镜像准备：把 superset 4.1.1 和依赖镜像一次打包

2.1 先确认要哪几个镜像

Superset 的 docker compose 部署不是单个镜像，至少涉及三个：apache/superset:4.1.1本体、postgres元数据库、redis缓存。中文版通常是在官方镜像基础上加了语言包和时区配置，所以镜像 tag 要认准带中文标识的那个，别直接拉官方 latest，版本对不上后面初始化会报 schema 不匹配。

我一般会在一台能出网的跳板机上先把镜像拉齐，再导出成 tar。先看 compose 文件里引用了哪些 image：

# 在跳板机上，进入项目目录后查看镜像引用 grep -E "image:" docker-compose.yml

输出里会看到类似apache/superset:4.1.1、postgres:15、redis:7这样的行。把这三个记下来，版本号以 compose 文件为准，不要自己猜。如果项目里带了中文版定制镜像，tag 可能是superset-cn:4.1.1这种，以实际文件为准。

2.2 拉取并导出镜像

确认镜像名后，在跳板机上逐个拉取并导出。这里用docker save而不是export，因为save保留镜像层和元数据，导入后能直接用：

# 拉取三个镜像，版本与 compose 文件保持一致 docker pull apache/superset:4.1.1 docker pull postgres:15 docker pull redis:7 # 分别导出为 tar，方便拷贝到内网 docker save -o superset-4.1.1.tar apache/superset:4.1.1 docker save -o postgres-15.tar postgres:15 docker save -o redis-7.tar redis:7 # 打包成一个压缩包，减少传输体积 tar -czvf superset-offline-images.tar.gz superset-4.1.1.tar postgres-15.tar redis-7.tar

docker save -o的-o指定输出文件，后面跟镜像名加 tag。三个 tar 加起来通常 1GB 出头，压缩后能小一些。注意别用docker export，那个导出的是容器文件系统，丢了镜像配置，导入后docker run会报找不到 entrypoint。

2.3 中文语言包的额外处理

Superset 4.1.1 的中文界面依赖 Flask-Babel 的翻译文件，官方镜像里其实已经带了 zh 的 po/mo 文件，但默认语言是 en。如果项目提供的是定制中文镜像，语言包已经内置；如果是官方镜像，需要在配置里把BABEL_DEFAULT_LOCALE设成zh。这一步在镜像准备阶段不用动，但要在心里有数：中文不是靠换镜像解决的，是靠配置项。后面 compose 配置那章会具体写。

提示：导出前用docker images核对一遍 tag，别把latest导进去，离线环境里 tag 漂移是排查噩梦。

3. 内网导入与 compose 配置：superset_config.py 里三个必改项

3.1 导入镜像并核对

把压缩包拷到内网目标机后，先解压再逐个导入：

# 解压并导入三个镜像 tar -xzvf superset-offline-images.tar.gz docker load -i superset-4.1.1.tar docker load -i postgres-15.tar docker load -i redis-7.tar # 核对导入结果，确认 tag 和跳板机一致 docker images | grep -E "superset|postgres|redis"

docker load -i的-i指定输入文件。导入后docker images里应该能看到和跳板机完全相同的 REPOSITORY 和 TAG。如果 tag 显示<none>，说明导出时镜像名写错了，回跳板机重新docker save并带上完整 tag。

3.2 compose 文件里的镜像名要对上

内网机器的 compose 文件里 image 字段必须和导入的 tag 一字不差。常见翻车是跳板机拉的是apache/superset:4.1.1，compose 里写的是superset:4.1.1，启动时 Docker 找不到本地镜像又去拉远程，直接超时。改法：

services: superset: image: apache/superset:4.1.1 # 必须与 docker images 输出一致 ... postgres: image: postgres:15 redis: image: redis:7

改完用docker compose config校验一遍语法，这个命令只解析不启动，能提前发现缩进和变量引用错误。

3.3 superset_config.py 的三个必改项

Superset 的配置集中在superset_config.py，离线部署里至少改三处：元数据库连接、Redis 地址、中文语言。先看元数据库：

# superset_config.py SQLALCHEMY_DATABASE_URI = "postgresql://superset:superset@postgres:5432/superset"

这里postgres是 compose 里的服务名，Docker 内部 DNS 会解析成容器 IP；用户名密码要和 postgres 服务的POSTGRES_USER/POSTGRES_PASSWORD环境变量一致，库名对应POSTGRES_DB。写成本机localhost是最常见的错，容器之间不通。

Redis 缓存配置：

# 缓存后端指向 redis 服务 CACHE_CONFIG = { "CACHE_TYPE": "RedisCache", "CACHE_DEFAULT_TIMEOUT": 300, "CACHE_KEY_PREFIX": "superset_", "CACHE_REDIS_URL": "redis://redis:6379/1", }

CACHE_REDIS_URL里的redis同样是服务名，/1表示用 1 号库，和默认的 0 号库隔开，避免和其他应用抢 key。CACHE_DEFAULT_TIMEOUT单位是秒，300 秒对看板场景够用，调太小会导致频繁回源查库。

中文语言配置：

# 默认语言设为中文，时区按业务需要调整 BABEL_DEFAULT_LOCALE = "zh" BABEL_DEFAULT_TIMEZONE = "Asia/Shanghai"

BABEL_DEFAULT_LOCALE设成zh后，登录页和菜单会走中文翻译；如果设了还是英文，检查镜像里/usr/local/lib/python3.10/site-packages/superset/translations/zh/LC_MESSAGES/messages.mo是否存在，官方镜像一般都有，定制镜像可能被裁掉。

注意：superset_config.py的路径要在 compose 里通过 volume 挂进容器，通常是./superset_config.py:/app/pythonpath/superset_config.py，挂载路径写错等于没配。

4. 初始化元数据与启动：superset db upgrade 和 admin 账号

4.1 先起依赖服务再初始化

Superset 启动前必须先有元数据库。compose 里通常用depends_on控制顺序，但depends_on只保证容器启动顺序，不保证 postgres 已经能接受连接。稳妥做法是先单独起 postgres 和 redis，等健康检查通过再初始化：

# 只启动依赖服务 docker compose up -d postgres redis # 查看 postgres 日志，等到 "database system is ready to accept connections" docker compose logs -f postgres

看到 ready 那行后 Ctrl+C 退出日志跟踪。如果 compose 里配了 healthcheck，也可以用docker compose ps看状态是否变成 healthy。

4.2 执行数据库迁移

元数据库就绪后，跑 Superset 的 schema 初始化：

# 在 superset 容器里执行迁移，注意用 run 而不是 exec，容器还没起 docker compose run --rm superset superset db upgrade

docker compose run --rm会临时起一个容器执行命令，跑完自动删除，--rm避免留下垃圾容器。superset db upgrade是 Alembic 迁移命令，把元数据库表结构升到 4.1.1 对应版本。如果报relation "ab_user" does not exist之类，说明迁移没跑完或连错了库，回头查SQLALCHEMY_DATABASE_URI。

4.3 创建管理员并初始化权限

迁移完成后创建 admin 账号：

# 创建管理员，用户名 admin，密码按需改 docker compose run --rm superset superset fab create-admin \ --username admin \ --firstname Admin \ --lastname User \ --email admin@example.com \ --password admin123

fab create-admin是 Flask-AppBuilder 的命令，四个必填参数里 email 不能重复。密码admin123只是示例，生产环境换成强密码，别照抄。接着初始化默认角色和权限：

# 初始化角色权限 docker compose run --rm superset superset init

superset init会同步权限表和默认角色，漏跑这步的典型现象是登录后菜单空白、报 403。

4.4 启动全部服务

初始化完成后起全部容器：

# 后台启动所有服务 docker compose up -d # 查看 superset 容器状态和日志 docker compose ps docker compose logs -f superset

日志里出现Running on http://0.0.0.0:8088说明 Web 服务起来了。默认端口 8088，compose 里通常映射成8088:8088，浏览器访问http://目标机IP:8088即可。

5. 避坑排查：离线部署 Superset 最常见的五个翻车点

5.1 镜像导入后 tag 变成 none

现象：docker load成功，但docker images里 REPOSITORY 和 TAG 都是<none>，compose 启动时报pull access denied。

原因：跳板机docker save时镜像名没带 tag，或者 save 的是镜像 ID 而不是name:tag。

解决：回跳板机用docker save -o xxx.tar apache/superset:4.1.1重新导出，导入前docker tag补 tag 也行，但不如重新导出干净。

5.2 容器起来但连不上元数据库

现象：superset 容器反复重启，日志报could not connect to server: Connection refused。

原因：SQLALCHEMY_DATABASE_URI里写的是localhost或127.0.0.1，容器内 localhost 指向自己，不是 postgres 容器。

解决：改成 compose 服务名postgres，并确认 postgres 容器的POSTGRES_DB和 URI 里的库名一致。

5.3 中文界面不生效

现象：BABEL_DEFAULT_LOCALE = "zh"配了，登录页还是英文。

原因：superset_config.py没挂进容器，或者挂载路径不是/app/pythonpath/superset_config.py；也可能是镜像里缺 zh 的 mo 文件。

解决：进容器docker compose exec superset ls /app/pythonpath/确认配置文件在；再查 translations 目录下 zh 的 mo 是否存在，缺了就换带中文包的镜像。

5.4 db upgrade 报版本冲突

现象：执行superset db upgrade报Can't locate revision identified by 'xxxx'。

原因：元数据库里残留了旧版本的 alembic 版本表，常见于复用旧库或从别的版本迁过来。

解决：确认是新库的前提下，清空元数据库重建；如果是迁移场景，先备份再按官方升级路径逐版本升，别跳版。

5.5 端口映射冲突

现象：docker compose up -d报port is already allocated。

原因：目标机 8088 已被其他服务占用。

解决：ss -lntp | grep 8088找到占用进程，或改 compose 里的端口映射为18088:8088，访问时用 18088。

6. 装完怎么验证：三条命令确认 Superset 4.1.1 真的跑通了

装完不等于跑通，我一般用三条命令加一次浏览器访问做闭环验证。第一条看容器状态：

# 三个容器都应是 Up 状态，superset 不应反复重启 docker compose ps

重点看 STATUS 列，如果 superset 显示Restarting或Exit，直接看日志，别急着往下走。第二条验证元数据库连接和版本：

# 进容器查 Superset 版本和数据库连通性 docker compose exec superset superset version docker compose exec superset python -c "from superset import db; print(db.engine.execute('select 1').scalar())"

superset version应输出4.1.1；第二条能打印1说明 SQLAlchemy 能连上元数据库。第三条验证 Web 端口：

# 本机 curl 健康检查，返回 200 即 Web 服务正常 curl -s -o /dev/null -w "%{http_code}" http://localhost:8088/health

返回200说明 Flask 应用活着。最后浏览器访问http://目标机IP:8088，用第 4 章创建的 admin 账号登录，进 Settings → 语言切到中文，刷新后菜单变中文，整个链路就算通了。

验证时有个容易忽略的点：/health返回 200 只代表进程活着，不代表元数据库和 Redis 都通。所以我把superset version和数据库查询放在前面，先确认后端依赖，再看 Web 层。这个顺序是从一次翻车里总结的——当时/health一直 200，但登录报 500，查了半天才发现是 Redis 连不上导致 session 写不进去。

从那以后我每次离线部署 Superset，都强制按「容器状态 → 版本与库连通 → 端口健康 → 浏览器登录切中文」四步走一遍，少一步都可能留个暗坑。希望帮到你。

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