企业官网建设流程全解析

简介：Superset 4.1.1中文版Docker离线部署包，面向需要在内网或无互联网环境中快速搭建数据可视化平台的开发者、数据分析师与运维人员。该方案将开源可视化工具Superset与Docker容器技术结合，解决了离线环境下应用依赖与镜像获取困难的问题，提供了一套可移植、可重复使用的部署流程。压缩包共6个文件，包括3个tar格式的Docker镜像（如Superset中文镜像、PostgreSQL数据库镜像、Redis缓存镜像）、docker-compose.yml服务编排文件、superset_config.py配置文件及.env环境变量文件，总大小约524.2MB，涵盖了从基础设施到应用配置的完整闭环。已有364人学习下载。借助这套资源，使用者无需手动搜索并下载镜像，也无需从零编写配置，只需按编排文件启动容器即可完成部署；中文界面显著降低了操作门槛，尤其适合国内团队在离线或内网环境下快速开启数据探索与可视化工作，同时便于后续扩展和迁移。

1. 离线部署 Superset 4.1.1 中文版：先回答三个必须面对的问题

哪怕是 Superset 4.1.1 中文版这种打包好的离线部署包，装起来也不是 docker load 完就能跑通全流程。它的目录里塞着镜像 tar、编排文件、配置模板和汉化资源，拿到手第一件事不是惊讶于“怎么这么大”，而是问自己三个问题：本地 Docker 版本能不能解析这套 compose 语法、数据库到底落在 SQLite 还是独立库里、配置改完容器重建后数据还在不在。这三个问题在在线部署时靠拉镜像就能糊弄过去，换到断网环境就成了硬门槛。这套包要解决的就是在一台不能出网的机器上把 Superset 跑起来，省去拉镜像和手工汉化的功夫，适合刚接手 BI 平台的新手运维，也适合被各种容器问题折腾过的老手。

2. 离线包结构与 Docker 环境预检：拆包之后先清点，再动手

离线部署最容易翻车的地方不是 Superset 本身，而是环境与包不匹配。先把包拆开，逐个文件确认用途，再做 Docker 环境检查，最后再导入镜像。这一步省不得，后面所有报错都能在这里找到根源。

2.1 解压后拿到什么：镜像 tar、compose 文件、配置模板逐个说

一个标准的离线包解压后，目录结构通常长这样：

superset-4.1.1-cn-offline/ ├── docker-compose.yml ├── .env.example ├── README.md ├── bin/ │ ├── load_images.sh │ └── start.sh ├── images/ │ ├── superset-4.1.1-cn.tar │ └── postgres-15-alpine.tar ├── config/ │ ├── superset_config.py │ └── superset_init.yaml └── translations/ └── zh_CN.mo

镜像目录里放着两个 tar：superset-4.1.1-cn.tar 是主应用镜像，postgres-15-alpine.tar 是元数据库镜像。为什么捆数据库？因为 Superset 的元数据不能只靠内存，生产环境用 SQLite 并发不够看，所以包内直接备了一个 Postgres。docker-compose.yml 定义两个容器服务，一个跑 Postgres，一个跑 Superset，卷、健康检查、服务依赖全在里面。.env.example 是环境变量模板，实际使用时复制成 .env 再改，里面管的是数据库密码、管理员账号、时区这类变量，不列入 git 也不打包交付。config/superset_config.py 是 Superset 的核心配置入口，数据库连接串、汉化开关、默认时区都在这里，这是整个包最需要人工检查的文件。translations/zh_CN.mo 是已编译好的中文翻译资源，正常情况下只需要确认存在，不需要动。

文件清单里哪些需要改，一张表说清楚：

真正要动的文件只有两个：compose 里的端口和卷，以及 .env 里的密钥和密码。config 里的数据库连接串在切换到独立数据库时需要改，初次部署如果直接走默认 SQLite 也可以先不动。

提示：不要因为包里有 README 就跳过目录清点。先确认 translations 里 zh_CN.mo 在不在、config 里 superset_config.py 有没有内容，再谈部署，否则后面排查汉化问题时根本分不清是配置问题还是资源缺失。

2.2 Docker 与 Docker Compose 版本要求：先检查版本再解包

这套 compose 用到了 depends_on 的长语法 condition，以及服务健康检查的数组形式，对 Docker Compose 版本有硬性要求。Compose V1，也就是单独的 docker-compose 命令，对这两类语法支持不完整，启动时经常报“must be a string”之类的解析错误。建议引擎版本 Docker 20.10 以上，Compose 用 V2 插件，也就是 docker compose 命令。

检查环境，一套命令走完：

docker --version docker compose version uname -a df -h /var/lib/docker

docker --version 看引擎版本，低于 20.10 的 CentOS 7 机器需要走 rpm 仓库升级，不能只装一个 compose 就完事。docker compose version 如果提示 command not found，说明只有旧版 docker-compose，需要装 compose plugin，这个坑在第 5 章会细说。uname -a 确认内核架构，x86_64 下这套包通常没问题，ARM 机器上要确认镜像是不是对应平台构建的。最后 df -h /var/lib/docker 是重点，两个镜像 tar 解压进 Docker 后会占不少空间，建议给 docker 数据目录留出至少 10GB 可用空间，否则导入到一半报 no space left on device，又得从头折腾。

如果是在 Windows 上用 Docker Desktop 跑这套包，注意 Docker Desktop 依赖 WSL2 或 Hyper-V，机器虚拟化支持没开的话，服务启动时大概率会弹 virtualization support not detected 这一类的错误。服务端部署别在 Windows 上硬扛，直接换 Linux 机器顺得多。Ubuntu 20.04、CentOS 7.9 是目前遇到最多的部署环境，CentOS 7 上系统自带 python 版本偏低，但不影响容器运行，只要 Docker 装对，Superset 容器内部环境是自带的。

2.3 镜像导入的常用做法：docker load 与镜像命名核对

离线包里的 bin/load_images.sh 一般封装了镜像导入的完整流程，最常见实现是把 images 目录下所有 tar 包挨个 load 进本机 Docker 引擎：

#!/usr/bin/env bash set -e for image in images/*.tar; do echo "Loading ${image} ..." docker load -i "${image}" done docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

脚本逻辑不复杂：set -e 让任何一次 docker load 失败都中断脚本，避免后面 compose 启动时才发现镜像缺失，排查起来反而更费时间。for 循环遍历 images 目录里所有 tar 包，docker load -i 从本地 tar 文件把镜像层解压进 Docker 引擎，完全不依赖网络。最后用 docker images --format 做表格化输出，一次性看到仓库名、tag 和大小，方便核对 compose 里写的 image 名是否与本机一致。

实际执行时，直接跑：

cd superset-4.1.1-cn-offline chmod +x bin/*.sh ./bin/load_images.sh

chmod +x 给脚本加执行权限，这步在部分系统上容易漏，漏了就会报 Permission denied。执行完后重点看 docker images 输出里有没有 superset-4.1.1-cn:latest 和 postgres:15-alpine 这两个条目。镜像导入成功后，检查磁盘占用：

docker system df

这个命令统计镜像、容器、卷、构建缓存四个维度的磁盘占用。如果输出显示镜像的 size 比预期大很多，不用慌，镜像层复用导致的虚存空间是正常现象，只要真实使用量没超过磁盘阈值就行。如果空间紧张，可以顺手清掉悬空镜像：docker image prune -f，它只删那些没有 tag 的中间镜像，不影响刚导入的正式镜像。

镜像导入这个环节，最容易出现的错误是把 compose 里的 image 名写错，或者 .env 里覆盖了 IMAGE_TAG 变量，导致 docker compose up 时 Docker 找不到本地镜像，转而去远端仓库拉取，离线环境下一拉就报 manifest not found。这个问题在第 5 章里有完整的排查路径，但最省事的做法是在 load 完之后立刻核对 docker images 输出，把 compose 里的 image 字段一次性对齐到完全一致。

3. 执行部署：docker compose 编排、环境变量与首次初始化

镜像就位后，部署的核心就变成了编排文件与环境变量。这一章把 docker-compose.yml 逐段拆开讲，说清楚每个配置项为什么这么写，然后给出一套可以直接抄的 .env 模板，最后走一遍首次启动的完整流程。整个过程中你会发现，离线部署真正磨人的不是启动动作本身，而是编排方案和实际环境之间的适配。

3.1 docker-compose.yml 逐段解读：镜像、健康检查、卷挂载怎么配

离线包自带的 docker-compose.yml 结构通常比官方示例更收敛，因为它是为离线场景定制的，不需要处理在线拉镜像的逻辑。一份能直接跑的编排大致长这样：

services: db: image: postgres:15-alpine container_name: superset-db restart: unless-stopped environment: POSTGRES_DB: superset POSTGRES_USER: superset POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-superset} volumes: - db_data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U superset -d superset"] interval: 10s timeout: 5s retries: 12 superset: image: superset-4.1.1-cn:latest container_name: superset-app restart: unless-stopped ports: - "0.0.0.0:8088:8088" environment: SUPERSET_CONFIG_PATH: /etc/superset/superset_config.py TZ: ${TZ:-Asia/Shanghai} SUPERSET_ADMIN_USERNAME: ${SUPERSET_ADMIN_USERNAME:-admin} SUPERSET_ADMIN_PASSWORD: ${SUPERSET_ADMIN_PASSWORD:-admin} SUPERSET_ADMIN_EMAIL: ${SUPERSET_ADMIN_EMAIL:-admin@example.com} volumes: - ./config/superset_config.py:/etc/superset/superset_config.py:ro - superset_home:/var/lib/superset depends_on: db: condition: service_healthy healthcheck: test: ["CMD", "wget", "-q", "--spider", "http://localhost:8088/health"] interval: 30s timeout: 10s retries: 5 volumes: db_data: superset_home:

db 服务里 POSTGRES_DB、POSTGRES_USER、POSTGRES_PASSWORD 三个环境变量决定 Postgres 初始化时自动创建一个叫 superset 的库和同名用户。POSTGRES_PASSWORD 用了 ${POSTGRES_PASSWORD:-superset} 这种变量替换写法，意思是 .env 里配了就用 .env 的值，没配就回落成 superset，这个设计是让你改 .env 而不是改 compose。healthcheck 里的 pg_isready 是 Postgres 自带的探活命令，-U superset 指定检查用户，-d superset 指定检查数据库，这条命令跑通说明数据库已经能接受连接了。

superset 服务的 image 名必须和第 2 章里加载的镜像 tag 完全一致。ports 写成 0.0.0.0:8088:8088，含义是所有网卡上的 8088 都映射到容器 8088，如果只想本机访问，可以改成 127.0.0.1:8088:8088，但这样外部机器就访问不到，交付给用户前要想清楚。SUPERSET_CONFIG_PATH 环境变量告诉容器去 /etc/superset/superset_config.py 读配置，这个文件是从宿主机 config 目录只读挂载进去的，:ro 后缀避免容器内部误改，好处是配置始终以宿主机文件为准。superset_home 卷挂到 /var/lib/superset，这是 Superset 存放 SQLite 数据、上传文件、图片缓存的目录，没有这个卷，容器一删全没了。

depends_on 的 condition: service_healthy 是这套编排里最关键的一行。它的意思是，只有 db 服务的 healthcheck 返回健康之后，superset 服务才启动。不要小看这个顺序，Superset 启动时会立刻用 SQLAlchemy 连接元数据库，如果数据库没准备好，后面只能靠容器自身的重试机制去碰运气。healthcheck 里用 wget --spider 而不是 curl，是因为 superset 镜像里不一定带 curl，但 wget 基本都有。--spider 模式不发请求体，只看目标 URL 是否可达，适合做探活。

3.2 环境变量与参数：.env 模板只改四件事

与 compose 配套的 .env 文件，是从 .env.example 复制出来的。一份基础模板长这样：

POSTGRES_PASSWORD=superset SUPERSET_SECRET_KEY=please-change-me TZ=Asia/Shanghai SUPERSET_ADMIN_USERNAME=admin SUPERSET_ADMIN_PASSWORD=admin SUPERSET_ADMIN_EMAIL=admin@example.com

每个变量的用途一张表说清楚：

SUPERSET_SECRET_KEY 是 Flask 签名会话的密钥，不设置时 Superset 启动日志会警告，而且会话在容器重启后会失效。生成方式很简单：

openssl rand -base64 42

把输出的一长串字符填到 .env 的 SUPERSET_SECRET_KEY 里。注意这个值不能带 shell 特殊字符，如果 openssl 输出里出现 +、/、= 的组合，建议多生成几次，直到拿到一条纯 URL 安全的字符串。TZ 设成 Asia/Shanghai 是给图表时间显示的，后面 config 里还会配一个 BABEL_DEFAULT_TIMEZONE，两者要一致，否则前端展示时间和数据库存储时间会差 8 小时。

管理员账号是容器 entrypoint 根据 SUPERSET_ADMIN_USERNAME 自动创建的。换句话说，第一次启动时不用手动执行 fab create-admin 那种命令，用户名密码已经由环境变量注入。交付生产环境时，SUPERSET_ADMIN_PASSWORD 默认值 admin 必须改掉，否则任何知道端口的人都能用 admin/admin 登录进去翻看板数据。

3.3 首次启动顺序：up、db upgrade、init 与健康检查

首次启动建议按顺序执行，不要直接 up -d 就完事，至少要把日志和健康状态盯一遍：

docker compose up -d docker compose ps docker compose logs -f superset

docker compose up -d 以后台方式拉起所有服务，-d 参数让命令在容器启动后立即返回。docker compose ps 查看两个容器的当前状态，正常情况应该看到 db 是 healthy，superset 是 Up。如果 superset 一直卡在 starting 状态，日志里通常能找到原因。docker compose logs -f superset 持续跟踪应用日志，Ctrl+C 退出但不会停容器。

第一次启动时，Superset 会尝试连接元数据库。如果入口点的初始化逻辑没有自动建表，或者你改了数据库连接串想做二次迁移，手动执行：

docker compose exec superset superset db upgrade docker compose exec superset superset init docker compose restart superset

superset db upgrade 是 Alembic 迁移命令，负责把元数据库表结构建到当前版本。superset init 创建默认角色、权限、权限集，以及根据环境变量注入的管理员账号。这两个命令执行顺序不能反，先有表再有初始化逻辑。重复执行 init 不会破坏已有数据，它是幂等的，所以担心初始化没跑成功的话，再跑一遍无妨。最后 restart superset 让配置重新加载。

启动完成后，验证 Web 服务：

curl -I http://127.0.0.1:8088/login/

期望返回 302 跳转到登录页，或者直接 200。如果 curl 报连接拒绝，先回到第 5 章的端口排查思路去看防火墙和监听地址。到这里，一套默认配置的 Superset 已经能登录了，下一步是决定元数据库到底用自带 SQLite 还是切换成独立库，以及让中文界面真正生效。

4. 元数据库选型与中文配置：从 SQLite 到 PostgreSQL 迁移的正确姿势

很多第一次部署 Superset 的人，会把关注点全放在汉化上，结果忽略了一个更基础的问题：数据往哪存。这个包同时带了 SQLite 路径和 Postgres 镜像，就是希望你在部署阶段就想清楚生产环境到底走哪条路。这一章先讲为什么别在 SQLite 上将就，再给出切到 Postgres 的完整步骤，最后把中文和时区配置一起收尾。

4.1 SQLite 与 PostgreSQL 的取舍：生产环境别在默认库上省事

Superset 官方便于入门，默认元数据库是 SQLite，连接串指向一个本地文件。SQLite 在小数据量、单用户场景下确实很省事，备份就是拷走一个文件，部署环境里几乎零依赖。但 Superset 是多人协作的 BI 平台，一旦多个用户同时编辑看板、刷新图表，SQLite 的写锁机制会频繁抛 database is locked 错误，体验非常差。另外一个隐患是，SQLite 的 .db 文件如果存放在容器可写层，容器一升级数据就没了，除非在 compose 里挂卷且挂对路径。

PostgreSQL 作为独立服务，写并发、备份恢复、权限体系都比 SQLite 成熟得多。两者的差异一张表看完：

包内自带 postgres-15-alpine 镜像，用意很明显：直接上 Postgres。给到读者的建议是，除非只是在本机做个功能体验，否则从一开始就把元数据库指到 Postgres，别等 Dashboards 建了一堆再迁库，那是给自己挖坑。迁移本身不算难，但迁移前建好的数据源、图表、看板都要重新来一遍，这个成本比一开始选对库高得多。

4.2 元数据库初始化与连接串：先建库，再让 Superset 指向它

如果沿用 compose 里 db 服务那一套，Postgres 容器首次启动时已经根据 POSTGRES_DB、POSTGRES_USER 自动建好了 superset 库和 superset 用户。如果你是把自己已有的 Postgres 实例接进来，或者想换库名密码，可以手动执行一次建库：

docker compose exec db psql -U postgres -c " CREATE USER superset WITH PASSWORD 'superset' ; CREATE DATABASE superset OWNER superset ENCODING 'UTF8'; "

第一行 CREATE USER 创建账号并设置密码，密码要和你 .env 里 POSTGRES_PASSWORD 保持一致。第二行 CREATE DATABASE 创建名为 superset 的库，OWNER 指定为 superset，这样后续做数据迁移时权限归属统一，不容易出现某个表无法读写的问题。ENCODING 指定 UTF8，这一步必须显式写上，否则中文字段在部分环境下可能出现乱码。

注意：如果 compose 里的 POSTGRES_DB 已经设了 superset，Postgres 容器初始化时这个库会自动创建。重复执行 CREATE DATABASE 会报 already exists，那不是错误，说明库已经在。上面这段 SQL 是给独立 Postgres 实例或者想换库名的人准备的。

建好库之后，让 Superset 指向它。修改 config/superset_config.py 里的连接串：

SQLALCHEMY_DATABASE_URI = 'postgresql://superset:superset@db:5432/superset'

这段连接串由五部分组成：postgresql:// 是数据库方言，superset:superset 是用户名和密码，db 是主机名，这个 db 对应 compose 里的服务名，容器间通信走内部网络，不需要写宿主机 IP。5432 是 Postgres 默认端口，superset 是数据库名。如果 Postgres 在宿主机上而非容器里，把 db 换成宿主机内网 IP 即可，但前提是容器网络能访问到宿主机。

修改完成后，重新执行数据库初始化和管理员初始化：

docker compose exec superset superset db upgrade docker compose exec superset superset init docker compose restart superset

这次 db upgrade 会往 Postgres 里建一套完整的元数据表。跑完后可以验证：

docker compose exec db psql -U superset -d superset -c "\dt"

能看到一堆 superset 前缀的表，比如 ab_user、ab_permission、dashboards，说明连接串配置成功，Superset 已经正式运行在独立数据库上。

4.3 中文汉化与时区：翻译文件、语言配置、默认时区一起改

中文汉化不是装个语言包就能生效的，它由三件事共同决定：翻译文件存在、i18n 开关打开、语言配置里包含中文。先确认翻译文件在容器里的位置：

docker compose exec superset ls -l /app/superset/translations/zh/LC_MESSAGES/

正常情况下能看到 messages.mo 文件。这个 .mo 是编译好的二进制翻译资源，包内已预置，不需要你自己跑 pybabel compile。如果这个文件不存在，后边再怎么配置都不会出中文界面。

接下来改 config/superset_config.py，把语言相关的配置加进去：

ENABLE_I18N = True LANGUAGES = { 'en': {'name': 'English', 'flag': 'us'}, 'zh': {'name': 'Chinese', 'flag': 'cn'}, } DEFAULT_LOCALE = 'zh' BABEL_DEFAULT_TIMEZONE = 'Asia/Shanghai'

ENABLE_I18N 是总开关，设为 True 才启用 Flask-Babel 的国际化支持。LANGUAGES 这个字典决定界面右上角语言下拉框里有哪些选项，只留英文的话即使翻译文件在也切不到中文。DEFAULT_LOCALE 设为 zh，会让新用户默认走中文。BABEL_DEFAULT_TIMEZONE 和 .env 里的 TZ 配合，把图表的时间轴统一到北京时间，排查“时间差 8 小时”的问题就是这里的配置不全。

改完重启，让配置生效：

docker compose restart superset docker compose logs -f superset | grep -i babel

重启后日志里没有 Babel 相关报错，刷新浏览器页面。如果右上角语言下拉框已经出现中文选项，切换后界面就全部变成中文。如果没生效，先强制刷新浏览器清掉静态资源缓存，再不行就查第 5 章汉化避坑的具体点位。

5. Superset 离线部署避坑指南：镜像、端口、持久化五连坑

离线部署的坑和在线部署不一样，在线环境遇到问题还能临时拉个包救火，离线环境每一步都得预先想清楚。这一章整理五条真实出现频率最高的故障，按“现象 → 原因 → 解决”的顺序写，可以直接对照排查。

5.1 镜像明明 load 了，compose 却报 manifest not found

现象：docker load 显示镜像已导入，但 docker compose up 时反复报错，内容接近 error pulling image config: manifest not found 或者 manifest unknown。

原因：compose 文件里的 image 字段和本地镜像 tag 不一致。离线环境下 Docker 引擎在本地找不到这个镜像 tag，就会尝试去配置的远端仓库拉取，访问不到仓库自然报 manifest 相关错误。常见触发点是 .env 里设置了 IMAGE_TAG 之类变量覆盖了 compose 里的镜像名，或者 load 的 tar 包和 compose 里的镜像名不是同一个版本。

解决：先看本地镜像的真实 tag：

docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.ID}}"

输出里找 superset-4.1.1-cn 和 postgres-15-alpine。然后把 compose 里对应服务的 image 字段改成和输出完全一致。比如本地显示仓库名是 superset-4.1.1-cn、tag 是 latest，compose 里就应该写 image: superset-4.1.1-cn:latest。如果本地输出显示仓库名带了别的前缀，那就要改 compose 对齐到带前缀的全名。改完后 docker compose up -d 会重新解析镜像，不会因为之前拉取失败缓存而卡住。

5.2 Compose V1 与 V2 语法差异导致启动失败

现象：执行 docker compose up -d 后，报 services.superset.depends_on.0 must be a string 这类解析错误，或者提示对 depends_on condition 语法不支持。

原因：机器上装的是旧版 docker-compose，即 Compose V1，它不支持新版 YAML 里 depends_on 的长语法 condition 写法。这套离线包的编排文件是按 Compose V2 写的，V1 解析器读到这种结构会直接抛异常。

解决：升级到 Compose V2 插件。确认命令：

docker compose version

如果显示 not found，而 docker-compose --version 有输出，说明只有旧版。CentOS 7 上常见做法是安装 docker-compose-plugin 的 rpm 包然后重启 Docker 服务；Ubuntu 上可以用 apt 安装 docker-compose-plugin。装完确认 docker compose version 输出是 v2.x。如果实在装不上，临时方案是把 compose 里的 depends_on 整段删掉，靠 Superset 容器自身的数据库连接重试机制顶上，但这样会牺牲启动顺序确定性，生产环境不推荐这么干。

5.3 端口映射后宿主机仍不通：防火墙、SELinux 与监听地址

现象：docker compose ps 显示端口映射正常，比如 0.0.0.0:8088->8088/tcp，但外部浏览器访问 http://服务器IP:8088 就是超时或拒绝连接，在宿主机上本地 curl 却能通。

原因：分三层排查。第一层是宿主机的 firewalld 或 iptables 没有放行 8088 端口，转发规则被防火墙拦住。第二层是 SELinux 拦截了容器端口绑定，这在 RHEL/CentOS 系上比较常见。第三层是 compose 里 ports 写成了 127.0.0.1:8088:8088，只监听了本机回环地址，外部自然不通。

解决：先在宿主机上确认监听地址：

docker compose ps ss -tlnp | grep 8088

ss 输出里如果是 0.0.0.0:8088，说明监听没问题，接下来放行防火墙：

firewall-cmd --permanent --add-port=8088/tcp firewall-cmd --reload

RHEL 系还有 SELinux 一层，放行进容器的网络连接：

setsebool -P httpd_can_network_connect 1

-P 表示持久化，重启后仍然生效。如果 ss 输出显示 127.0.0.1:8088，说明 compose 文件里写死了本机监听，把 ports 改成 0.0.0.0:8088:8088 再重启容器。三层全部查完再让用户访问，避免一次报错就急着怪容器的坏习惯。

5.4 汉化不生效：语言开关、翻译资源、浏览器缓存三处一起查

现象：页面右上角没有中文选项，或者切到中文后界面仍是英文，控制台有一堆 404 找不到翻译文件的请求。

原因：汉化配置不是一个开关能解决的。第一，ENABLE_I18N 没设 True，翻译系统根本没加载。第二，LANGUAGES 字典里没有 zh 这条，语言下拉框里自然看不到中文。第三，翻译 .mo 文件位置不对或容器里不存在，即使配置全对也渲染不出中文。第四，浏览器缓存了旧的 JS 和静态资源，界面看起来没变。

解决：三个点一起查，先看配置和翻译文件：

docker compose exec superset sh -c "grep -E 'ENABLE_I18N|LANGUAGES|DEFAULT_LOCALE' /etc/superset/superset_config.py" docker compose exec superset ls -l /app/superset/translations/zh/LC_MESSAGES/

第一条命令确认配置已经挂载进容器且内容正确，第二条确认 .mo 文件存在。如果文件不存在，说明离线包里翻译资源没拷全，需要重新解压包并挂载到 config 卷。如果都存在，再验证当前语言环境：

docker compose exec superset python -c "from flask_babel import get_locale; print(get_locale())"

输出 zh 说明服务端已经认为当前语言是中文。此时界面如果还显示英文，就强制刷新浏览器，Ctrl+Shift+R 清掉缓存。这条排查链看着长，但五分钟能走完，别卡在“是不是没装语言包”这个怀疑上。

5.5 容器重建后看板丢光：没见过比这个更疼的教训

现象：docker compose down 之后再用 docker compose up -d 把服务拉起来，登录进去发现数据源、图表、看板全部变成空的，配置也没了。用户体验相当于整个平台被重置。

原因：数据库数据没有落到持久化卷。SQLite 文件或者 Postgres 数据目录都在容器可写层，容器一旦被移除，数据跟着容器一起消失。docker compose down 默认会停掉并移除容器，但不会删卷，如果当初根本没挂卷，那数据就彻底没了。

解决：在 compose 文件里给两个服务都加上持久化卷：

volumes: db_data: superset_home:

这是第 3 章 compose 方案里已经写好的部分。确认是否生效，用 docker volume ls 查看卷是否存在：

docker volume ls | grep superset

看到 superset_db_data 和 superset_superset_home 这两个卷存在，说明持久化层已经有了。验证数据是否真的能扛重建，可以做个测试：往 Superset 里随便建一个数据集，然后 docker compose down && docker compose up -d，再登录看数据集还在不在。这个操作不复杂，但能救命。从那以后每次交付前，我都会用你的身份强制走一遍 down/up 验证持久化，这一条是花钱买来的教训。

6. 验证部署与运维收尾：健康检查清单、备份恢复与交付习惯

部署完成不等于交付完成。Superset 这种 BI 平台，用户真正关心的是数据在不在、界面能不能开、登录正不正常。把一套检查清单和备份习惯固化下来，比临时翻文档有用得多。

验证清单按顺序走，缺一不可：

docker compose ps curl -I http://127.0.0.1:8088/login/

docker compose ps 里两个服务都应该显示 Up，db 应该是 healthy，superset 如果也带 healthy 状态说明健康检查通过。curl -I 返回 302 或 200 代表 Web 层正常。然后用 admin 账号登录，进到数据源页面，确认第 4 章配置的 Postgres 连接能正常读到元数据表。最后创建一个测试图表，刷新看是否渲染，这一步能顺带把数据库读写链路都验证到。

备份要覆盖两层：配置文件和数据库数据。配置文件是宿主机上的 docker-compose.yml、.env、config/superset_config.py，这些决定了能不能重新拉起一套一样的服务：

tar czf superset-config-$(date +%F).tar.gz docker-compose.yml .env config/

数据库数据备份，如果用 Postgres，走 pg_dump：

docker compose exec db pg_dump -U superset -d superset > superset-db-$(date +%F).sql

恢复时先 docker compose up -d，再执行：

cat superset-db-$(date +%F).sql | docker compose exec -T db psql -U superset -d superset

这套备份恢复的流程，值得每次版本升级前完整走一遍。我最早一次交付时犯过一个特别蠢的错，把数据存在容器可写层里，交付完第二天用户跟我说所有看板都没了，打脸打得很难看。从那以后我每次部署完都强制走一遍 down/up 验证持久化，再写一行配置文件的备份命令存档。希望帮到你。

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