Superset 4.1.1 离线部署：Docker 镜像准备与中文汉化避坑指南

简介：面向需要离线部署Superset 4.1.1中文版的企业运维、数据分析人员及Docker学习者，该资源将Superset数据可视化工具与容器化部署方式结合，解决内网无互联网环境或需要标准化交付场景下的快速搭建问题。压缩包共6个文件，包含三个Docker镜像tar包（Superset中文版主镜像、PostgreSQL数据库镜像、Redis缓存镜像）、docker-compose.yml服务编排、superset_config.py配置以及.env环境变量文件，总大小约524.2MB，各文件职责明确，便于离线导入与二次调整。已有364人学习下载。借助这套离线包，无需再手动逐一下载镜像或从零编写编排与配置，按docker-compose启动容器即可完成部署；同时提供环境变量和配置样例，可快速适配数据库连接、端口映射、认证方式等参数。对于希望在内网快速启用Superset进行数据探索与可视化展示的团队，这是一份可直接落地的实用方案，也能帮助初学者理解容器化部署中各文件的实际作用。

1. 离线网络里跑 BI：Superset 4.1.1 的 Docker 离线部署为什么绕不开镜像准备

在完全断网的内网服务器上交付一个可用的 Apache Superset 4.1.1 中文版 BI 平台，难点往往不在 Superset 本身，而在离线环境对镜像和依赖的管理方式。没有公网，docker pull 用不了，apt 装不了，pip 也拉不了，想把平台做成“开箱即用的中文版”，就必须先在一台联网机器上把镜像、配置、语言资源整体梳理好，再带进内网。这篇文章会从镜像准备、docker-compose 编排、中文语言包配置到初始化踩坑记录，把整个离线部署链路讲完，适合正在做内网 BI 交付、信创或政企数据平台的同学参考。

2. 离线部署前的准备：选型对比与镜像打包的三条命令

2.1 先定部署形态：单容器只适合试跑，交付要上 compose

如果你的目标只是本地把 Superset 4.1.1 拉起来看一眼界面，docker run -p 8088:8088 apache/superset:4.1.1就够了。但离线交付不一样，它要解决三件事：重启策略、配置管理、依赖服务。单容器方案里，重启策略得靠--restart参数，配置要么烧进镜像、要么逐个用-e传，外部依赖（Redis、元数据库 MySQL）还要你自己额外管理。这套东西写进交付文档，接收方很难复现，后面排障也没有凭据。

我通常建议把离线部署直接做成 docker-compose 编排，原因是 compose 文件本身就是交付文档。团队拿到文件后，一条docker compose up -d能把 Superset、Redis、MySQL 按网络关系起好，配置挂载、数据卷、健康检查都写在同一个 YAML 里，比单独跑一堆 docker run 命令可靠得多。

这里还有一个前置判断：内网里有没有已经存在的 MySQL 或 Redis。如果有现成的，compose 里就只编排 Superset 一个服务，连接串直接指向现成实例；如果没有，就把这两个依赖一起放进编排文件，保证整个栈离线自洽。这个判断结果直接决定后续镜像列表长什么样，所以别急着写 compose，先把数据库和缓存的情况问清楚。

2.2 在联网机器上准备镜像：三条命令完成离线 tar 包

离线部署的第一个动作不是部署，而是准备镜像。常见做法是找一台可以访问公网的机器，用 docker pull 拉取需要的镜像，再用 docker save 导出成 tar 文件，最后通过 U 盘或内网传输工具拷进目标机器。准备端可以是个人电脑上的 Docker Desktop（Windows 或 macOS 都行），但如果目标是 Linux/amd64 服务器，注意用--platform linux/amd64拉对应架构的镜像，避免在 Apple Silicon 的电脑上拉了 arm64 版本，导致内网机器跑不起来。

需要准备的镜像一般至少有三个：Superset 本体、Redis（做缓存）、MySQL（元数据库）。如果内网已经有现成的 MySQL 或 Redis，只需要拉 apache/superset 一个即可。

# 在有公网的机器上执行 docker pull apache/superset:4.1.1 docker pull redis:7.2-alpine docker pull mysql:8.0 # 导出为单文件 tar，便于内网拷贝 docker save apache/superset:4.1.1 -o superset-4.1.1.tar docker save redis:7.2-alpine -o redis-7.2.tar docker save mysql:8.0 -o mysql-8.0.tar

docker save导出的是镜像的完整分层结构和 manifest，包含所有历史层、环境变量、入口点信息；常见的错误是用docker export去导容器，那个命令只导出容器文件系统，会丢掉镜像的层历史和运行元数据，加载后起容器往往直接报错，这是离线部署里很典型的坑。

导出后不要直接把 tar 拷走，先记录一下镜像的摘要，方便在离线机器上校验。用docker images --digests查看镜像 ID 和 RepoDigest，把摘要记录下来；或者直接在两台机器上对 tar 包做sha256sum，保证拷贝过程没有损坏。离线机器上硬盘空间也要提前预留，镜像 tar 解包后实际占用会大于 tar 本身，通常建议留出 tar 大小两倍以上的临时空间。

2.3 先把 superset_config.py 写对：密钥、语言、数据库、缓存四个配置

镜像本身不自带生产配置，Superset 启动时会去/app/pythonpath/superset_config.py读取自定义配置。离线部署前，这个文件在联网准备阶段就要写清楚，不然进内网后再改，还得反复重建容器。

我一般在宿主机上放一份superset_config.py，用 volume 挂进容器，而不是把配置烧进镜像。原因是：以后升级镜像不用重新构建，配置单点维护，且交付给下一任运维也看得懂。

# superset_config.py # 生产模式必须固定 SECRET_KEY，否则每次重启会话和签名都会失效 SECRET_KEY = "please-change-to-a-very-long-random-string" # 语言选项：只保留英文和简体中文 LANGUAGES = { "en": {"flag": "us", "name": "English"}, "zh": {"flag": "cn", "name": "简体中文"}, } BABEL_DEFAULT_LOCALE = "zh" # 元数据库连接串：使用内置 MySQL 服务时，主机名写 compose 里的服务名 SQLALCHEMY_DATABASE_URI = "mysql+pymysql://superset:superset_pwd@mysql:3306/superset?charset=utf8mb4" # 结果缓存走 Redis CACHE_CONFIG = { "CACHE_TYPE": "RedisCache", "CACHE_KEY_PREFIX": "superset_cache", "CACHE_REDIS_URL": "redis://redis:6379/1", }

SECRET_KEY的坑主要在首次初始化前：如果启动时没设置，Superset 会用随机值初始化，Flask 的会话 cookie 和 CSRF 令牌都基于它，重启后已登录用户的会话全部失效。运维日志里经常出现“登录后马上被登出”的假象，其实只是密钥没固定。

LANGUAGES决定界面里可选的语言，只有加进去“简体中文”，用户切换语言时下拉里才找得到；BABEL_DEFAULT_LOCALE则是未登录时默认界面语言，把它设成zh，内网用户打开页面第一眼就是中文菜单。SQLALCHEMY_DATABASE_URI这里我用的是mysql+pymysql驱动，镜像内置了 PyMySQL，不需要额外装系统库；如果用 PostgreSQL，镜像里也自带 psycopg2，连接串换成postgresql+psycopg2://...即可。

另外注意charset=utf8mb4不能省。Superset 的元数据里会存中文标签、图表名称、数据集描述，如果连接串没指定 utf8mb4，MySQL 端默认字符集可能与客户端不一致，写入中文时容易出现Incorrect string value一类的报错，后面再排查很被动。

3. 用 docker-compose 离线启动 Superset：编排、初始化与 MySQL 后端切换

3.1 compose 文件怎么组织：app、Redis、MySQL 三个服务的依赖关系

在离线机器上，先把之前准备好的 tar 包docker load -i进去，然后写 compose。这里给出一个内置 MySQL 和 Redis 的完整编排，适用于内网没有任何现成依赖的场景。

version: "3.8" services: mysql: image: mysql:8.0 container_name: superset-mysql restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: root_pwd MYSQL_DATABASE: superset MYSQL_USER: superset MYSQL_PASSWORD: superset_pwd command: - --character-set-server=utf8mb4 - --collation-server=utf8mb4_unicode_ci volumes: - mysql_data:/var/lib/mysql networks: - superset-net healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost"] interval: 10s retries: 12 redis: image: redis:7.2-alpine container_name: superset-redis restart: unless-stopped command: redis-server --appendonly yes volumes: - redis_data:/data networks: - superset-net superset: image: apache/superset:4.1.1 container_name: superset restart: unless-stopped ports: - "8088:8088" environment: SUPERSET_SECRET_KEY: please-change-to-a-very-long-random-string volumes: - ./superset_config.py:/app/pythonpath/superset_config.py depends_on: mysql: condition: service_healthy redis: condition: service_started networks: - superset-net networks: superset-net: volumes: mysql_data: redis_data:

这里有两个细节值得说明。第一，depends_on我特意用了condition: service_healthy，否则 MySQL 容器刚起来其实还在初始化，Superset 如果先启动，第一次db upgrade大概率会碰到“访问数据库连接被拒”的报错，日志堆一片，新人容易误判成镜像问题。第二，compose 默认会给三个服务建一个自定义网络，服务名mysql、redis在这个网络里可以被 Superset 容器直接解析，所以连接串的主机名写mysql和redis而不是localhost，这一点和内网连外部数据库完全不同。

镜像加载完成后，启动这一步就简单了：

docker compose up -d docker compose ps

docker compose ps要看三个容器状态都是 Up。如果 MySQL 容器反复 restart，大概率是初始化 SQL 执行失败或数据卷权限不对，先docker logs superset-mysql看 MySQL 自身输出，不要急着处理 Superset。

3.2 首次初始化必跑的三条命令：db upgrade、create-admin、init

容器起来后，Superset 的元数据库还是空的。官方镜像的入口脚本会在首次启动时尝试初始化一部分基础结构，但管理员账号和角色权限仍需要手动执行。离线环境下没有网络加载示例数据集，所以load_examples这一步可以直接跳过，否则它会去访问外部资源，报一堆超时错误。

# 把数据库结构升级到当前版本 docker exec -it superset superset db upgrade # 创建管理员账号 docker exec -it superset superset fab create-admin \ --username admin \ --firstname Admin \ --lastname User \ --email admin@example.com \ --password "Admin_123456" # 初始化角色、权限和默认配置 docker exec -it superset superset init # 重启一次让配置完整生效 docker restart superset

superset db upgrade底层走的是 Alembic 迁移脚本，它会在 MySQL 里维护一张alembic_version表，记录当前迁移版本。只要这条命令执行成功，后面重启容器不会重复迁移。fab create-admin创建的是 Flask-AppBuilder 的管理员，也就是登录 Superset 后的超级管理员，--password参数如果省略，会进入交互模式，在自动化脚本里就没法用了。

superset init负责初始化权限、采集元数据并构建权限映射。跑完这三条，浏览器访问http://内网服务器IP:8088，用 admin 账号登录，正常情况下已经能进主界面。如果登录后提示CSRF token missing或类似错误，多半是 SECRET_KEY 没设或前后配置不一致，回 2.3 检查。

3.3 为什么离线部署要把元数据库从 SQLite 切到 MySQL

官方镜像默认的元数据库连接串是 SQLite，文件落在容器内路径/app/superset_home/superset.db。如果只是单机试用，SQLite 完全够用，但离线部署一旦交给业务方，就会遇到几个实际痛点。

SQLite 的写锁是库级别的。Superset 的仪表板加载、切片器状态、操作日志都会写元数据库，五六个人同时使用，很快就会出现database is locked错误。还有备份维度：MySQL 可以用mysqldump做逻辑备份，也可以在运维侧做主从；SQLite 只能靠落盘文件快照，在容器环境里很容易备份到容器还在写的那一瞬间而产生坏文件。

从升级迁移的角度看，SQLite 的坑更明显。以后版本升级，Superset 官方只保证 PostgreSQL 和 MySQL 的迁移路径可靠，本地文件库经常会碰到 Alembic 迁移卡住的问题。我一直坚持，标签为“生产”或“交付”的离线环境，一开始就把元数据库放在 MySQL；上面的 compose 里保留了 MySQL 容器，连接串对应章节 2.3，已经提前切好，不会出现“部署完才发现要换库”的翻车事故。

如果是用已有外部 MySQL，那连接串要改成宿主机能解析的主机名或 IP，不能写mysql，因为外部实例不在 compose 网络里；第五节专门讲这个网络问题的排查。

4. Superset 中文汉化落地：语言包、默认语言与字段名映射

4.1 语言资源在哪：先确认容器里的 translations 目录

很多用户看到“中文版”第一反应是找汉化补丁。实际上 Superset 的官方镜像在 4.x 版本中已经内置一套简体中文翻译文件，只是默认没被启用。语言资源放在/app/superset/translations/，其中中文的编译产物是zh/LC_MESSAGES/messages.mo，Flask-Babel 在启动时按这个文件加载翻译字符串。

离线环境没有网，验证镜像里有没有中文资源，只有一条路：直接在容器内找文件。

docker exec -it superset ls /app/superset/translations/ docker exec -it superset find /app/superset/translations/zh -name "*.mo"

如果第二条命令有输出，说明翻译文件存在。此时只要superset_config.py里加上了LANGUAGES里的zh，界面就能切到中文。如果zh目录缺失或.mo文件不存在，常见做法是找一台有网机器，拉同一个官方镜像，把容器里的 translations 完整拷出来。注意：这里拉的是同一个 tag 的镜像，不要随意下载第三方整理包。

# 在有网机器上执行 docker cp superset:/app/superset/translations ./translations

把translations放进离线环境的部署目录，再在 compose 里加一条 volume 挂载，覆盖镜像内默认路径，汉化资源就补上了。

# docker-compose.yml 的 superset 服务 volume 里追加 - ./translations:/app/superset/translations

这里补一句提醒：所谓“中文版”，不能只依赖一个 .mo 文件。它至少包含三层：语言资源文件（.mo）、界面默认语言（BABEL_DEFAULT_LOCALE）、图表与数据集的中文显示名。前两层能在部署阶段解决，第三层属于数据建模的日常工作，下面两节分开讲。

4.2 把默认语言钉死在中文：BABEL_DEFAULT_LOCALE 与用户级偏好

有了语言资源，还要确保用户打开页面时看到的就是中文。这个控制点在两个地方：

• 未登录用户看到语言的默认值，由superset_config.py里的BABEL_DEFAULT_LOCALE = "zh"决定；
• 登录用户的语言偏好存在用户 profile 里，打开页面时会优先读它，而不是每次都用配置文件里的默认值。

所以在部署阶段要做的其实是两步：配置文件里把默认语言设为zh，然后管理员登录后，在右上角头像菜单里把语言切到“简体中文”。如果用户是在英文模式下创建的，他看到的还会是英文；新用户在注册时语言偏好会继承当前的界面语言，所以部署时先切中文再建业务账号，顺序上有讲究。

BABEL_DEFAULT_LOCALE字段在旧版 Superset 也支持，但有些版本对zh的解析依赖语言代码是否存在于LANGUAGES字典。配置里LANGUAGES和BABEL_DEFAULT_LOCALE要同时出现，只写一个，另一个不会自动生效。改完配置后记得docker restart superset，因为 Flask-Babel 的初始化发生在进程启动时，不是运行中热加载。

时区方面也建议一并处理。Superset 默认使用 UTC，中文用户看 “昨天 / 今天” 会差 8 小时。可以在superset_config.py里追加：

# 让界面和图表时间显示跟随本地时区 TALISMAN_ENABLED = False SUPERSET_WEBSERVER_TIMEOUT = 120

时区的关键修正不在配置文件，而是在创建数据源时，在数据集属性里选择对应的时区。否则配置了也只会影响服务端日志时间，图表横轴时间的偏移要靠数据源时区字段去纠正，这一点经常被人忽略。

4.3 数据集字段和图表名称：中文版的最后一公里

部署做完，界面是中文了，但数据表里的列名还是英文，比如created_at、status、user_id。这个阶段的中文化已经从“部署”进入“数据建模”。

Superset 里有一个字段叫 verbose_name，可以覆盖原始列名。配置入口是数据集编辑页面的 Columns 标签：把每个列的 verbose_name 写成中文，图表构建时下拉框里、维度名、指标名全部显示中文。如果表只有十几列，手工改就行；如果是几十张表、上百个字段，手工就是体力活，用 API 批量更新更稳。

REST API 调用的基本步骤是：先登录拿 access_token，再按数据集 ID 拉取当前列定义，修改 verbose_name 后 PUT 回去。一个最小脚本如下：

# scripts/update_verbose_name.py import requests base_url = "http://localhost:8088" # 1. 登录拿 token login_resp = requests.post(f"{base_url}/api/v1/security/login", json={ "username": "admin", "password": "Admin_123456", "provider": "db", "refresh": True, }).json() token = login_resp["access_token"] headers = {"Authorization": f"Bearer {token}"} # 2. 读取数据集定义（ID 从 /api/v1/dataset/ 列表里确认） ds_id = 1 resp = requests.get(f"{base_url}/api/v1/dataset/{ds_id}", headers=headers).json() columns = resp["result"]["columns"] # 3. 构造中文字典，只改目标字段 name_dict = { "created_at": "创建时间", "updated_at": "更新时间", "user_id": "用户ID", "status": "状态", } for col in columns: col_name = col["column_name"] if col_name in name_dict: col["verbose_name"] = name_dict[col_name] # 4. 写回 requests.put(f"{base_url}/api/v1/dataset/{ds_id}", json={"columns": columns}, headers=headers)

这段脚本的注意点有两个：接口返回的columns结构在不同小版本里可能字段名有差异，比如 4.x 里列对象的 key 是column_name，而 3.x 部分版本是column，跑之前先print(columns[0])看一眼结构；另外 PUT 请求会把整组列定义覆盖写回去，所以脚本里一定要基于 GET 出来的结果修改，不能只传想改的那几个字段，否则会把其它列的配置冲掉。

字段名这种工作可以提前到离线准备阶段做。Superset 的元数据在数据库里，提前修改元数据不会影响目标数据源。很多团队把“中文版”做成交付物，其实就是把迁移脚本和这份 column 映射表一起放进部署包，落地时一次性执行。

5. 离线部署避坑记录：镜像导入、初始化失败、汉化失效与网络不通

5.1 docker load 后镜像显示为 <none>，或 tag 对不上

现象：离线机器上执行docker load -i superset-4.1.1.tar，输出 Loaded，但docker images里看到的 tag 是<none>，compose 启动时报 “pull access denied for apache/superset”。

原因：save 时镜像 tag 在 tar 包里其实保留了；出现<none>，往往是在有网机器上先改了 tag，或者 tar 包传到一半损坏。损坏的 tar 在 load 阶段可能只解出了一部分层，完整 tag 没有被覆盖到。

解决：先校验文件完整性。拷贝前后各执行一次sha256sum superset-4.1.1.tar，两边值一样再 load；load 完成后用docker images --digests apache/superset核对 digest，而不是只看 tag。如果已经是<none>状态，不需要重新拉镜像，直接给镜像打个 tag 即可：

docker tag <镜像ID> apache/superset:4.1.1

另外，离线机器上如果 docker 服务本身权限不对，docker load也会失败或读到不完整内容。内网服务器经常是多人共用的，当前用户没加进 docker 组时，所有 docker 命令都要加sudo；更稳妥的方式是把部署用户加进 docker 组并重新登录一次会话，省得后面每条命令都带 sudo，也避免 sudo 环境下 volume 路径权限不一致。

5.2 初始化命令报错：create-admin 用户名已存在，或 db upgrade 卡住

现象：按章节 3.2 执行superset fab create-admin，提示Username already exists；或者superset db upgrade跑一半报table already exists。常见于同一个 MySQL 库被反复初始化过的场景。

原因：Superset 的初始化不是完全幂等的。fab create-admin在用户已存在时会直接拒绝，不是覆盖密码；db upgrade则依赖 Alembic 的 version 表，如果之前有人手动建过表但没正确记录版本，迁移就会和现存结构冲突。

解决：内网测试环境，最干脆的做法是把元数据库清掉重来，比手工修补快得多。用 root 登录 MySQL 容器：

DROP DATABASE IF EXISTS superset; CREATE DATABASE superset CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; GRANT ALL PRIVILEGES ON superset.* TO 'superset'@'%'; FLUSH PRIVILEGES;

然后重新执行docker restart superset-mysql，再依次跑superset db upgrade、superset fab create-admin、superset init。这样做之前先确认库里没有业务配置，别把仪表板配了半天再清库。

如果是生产环境不想清库，就要进 MySQL 查看alembic_version表里的 version_num 和 Superset 期望的迁移版本差在哪，手工插入或回滚迁移版本，但这一步风险较高。我的经验是：生产库在第一次初始化前就要定好连接串，不要先用 SQLite 跑通再用 MySQL，那等于让 Alembic 在同一套迁移脚本上换个数据库重跑，很容易踩到已存在表的边界。

5.3 界面切到中文后仍有大量英文残留，或语言下拉里没有中文

现象：登录后右上角语言下拉找不到“简体中文”；或者切到中文后，菜单、设置页仍然大量英文。

原因：前者说明LANGUAGES字典里根本没把zh加进去；后者说明翻译文件缺失，或者浏览器缓存了旧的静态资源。还有一个隐蔽原因：用户 profile 里的语言偏好在切换后其实已经写入，但前端静态资源被本地缓存挡住，看起来像“没生效”。

解决：按顺序排查。先确认配置文件里同时有LANGUAGES和BABEL_DEFAULT_LOCALE，然后进入容器确认.mo文件存在：

docker exec -it superset find /app/superset/translations/zh -name "*.mo" | head -5

文件在的话，重启 superset 并清掉 Redis 里的缓存，避免旧的翻译缓存影响加载：

docker exec -it superset-redis redis-cli FLUSHDB docker restart superset

浏览器侧强制刷新一次，绕过静态资源缓存。如果某几个角落页面仍是英文，这多半是该版本的翻译覆盖度问题，不属于部署失败，可以接受；真实生产中没必要为个位数未翻译字符串去改源码重新编译镜像。

5.4 容器内连不上同网段 MySQL：连接被拒、host 解析不了

现象：Superset 里配置一个外部 MySQL 数据源，测试连接报Can't connect to MySQL server on '192.168.x.x' (111 Connection refused)，或者报Unknown host 'mysql'。如果数据源是宿主机同网段的 MySQL，这类问题在离线环境尤其多。

原因：两个层面。一是 Superset 容器默认在 compose 网络里，容器内的localhost指向它自己，不是宿主机；连接串写成localhost:3306肯定连不上业务库。二是不管你想连哪个 MySQL，那个服务得允许来自容器 IP 的连接，MySQL 用户表里 localhost 权限默认只放行回环地址。

解决：先确认要连的是 compose 网络内的 MySQL，还是宿主机所在物理网络的 MySQL，连接串按场景区分：

• 同一 compose 栈里的 MySQL：主机名写mysql，端口 3306；
• 宿主机上的 MySQL：主机名写宿主机局域网 IP，而不是localhost；
• 其它网段服务器上的 MySQL：先在宿主机上用telnet IP 3306验证宿主机到目标库的网络通不通，再进容器验证，分两步缩小范围。

对于外部数据库，还要检查目标 MySQL 的bind-address是不是127.0.0.1，如果是就要改成0.0.0.0；以及 MySQL 用户授权里的 host 段是不是只写了localhost，需要改成%或指定内网网段。内网 CentOS 机器如果开了防火墙，3306 端口会被 drop，现象也是连接超时。

还有一个常见误区：宿主机上能连库，不代表容器里能连。容器网络经过 bridge 和 iptables，直接在容器里做连通性测试最直接：

docker exec -it superset python -c "import socket; socket.create_connection(('目标IP', 3306), 5)"

能连上 socket，但 Superset 测试连接仍报错，那才轮到检查认证和 PyMySQL 驱动层面。

6. 部署完先做这三件事：健康检查、数据接入验证与配置固化

6.1 用健康接口和登录接口验证服务状态

离线环境里没有外部技术支持，部署完是不是真的能用，不能靠“页面出来了”判断，要按接口、登录、数据源三层验证。

第一层是 Web 健康检查。Superset 暴露了/health接口，它只反映 Web 进程是否存活，这个返回 200 不代表元数据库和 Redis 都正常：

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8088/health

第二层是真实登录与 API 认证。用管理员的账号调/api/v1/security/login拿 token，能拿 token 说明配置的 SECRET_KEY、数据库和用户体系都已经可用：

curl -s -X POST http://localhost:8088/api/v1/security/login \ -H "Content-Type: application/json" \ -d '{"username":"admin","password":"Admin_123456","provider":"db","refresh":true}'

返回 JSON 里带有access_token，这步过了，登录链路基本没问题。

6.2 数据接入与一个真实图表的冒烟自测

API 验证完，进界面创建一条真实的数据源，接一张业务表，跑一个汇总图表。别跳过这步直接交付，数据源连接是最容易在离线环境里翻车的环节，尤其是 5.4 提到的权限和网络问题。

我会固定用两类数据源做冒烟测试：一类是接入同一个 MySQL 的元数据库，验证驱动和基础查询；另一类是业务方真实库，验证权限、时区和字段映射。后者通常要请业务方提供账号，尽量在交付前完成，别等到上线当天再碰。

6.3 把部署目录固化下来，备份元数据库

第三层是把部署配置固化下来，形成可复现的交付物。我习惯在部署目录里固定放四样东西：compose 文件、superset_config.py、translations目录、一份初始化 SQL 和命令的 README。以后升级版本、换机器，照着这套流程重新走一遍，比到时候从记忆里拼命令可靠得多。

升级前记得用 mysqldump 先把元数据库备份出来，容器里执行：

docker exec -i superset-mysql mysqldump -usuperset -psuperset_pwd superset > superset_backup_$(date +%F).sql

备份文件放在部署目录之外，另一台机器再放一份。这套“先备份、再 load、再比对 digest、最后才跑迁移”的流程，是从一次真实教训换来的。有一次我在升级时图快，直接在旧库上跑了新版的superset db upgrade，中途连接断掉，Alembic 停在中间版本，之后怎么迁移都报错，最后还是靠之前的 mysqldump 把库还原才救了回来。

整个离线部署链路里，镜像校验、初始化顺序和汉化配置是最容易出问题的三处，也是投入时间最值得的三处。先把这三块按顺序落地，再处理数据源的网络连通，离线上交付 Superset 4.1.1 中文版就不会有大坑了。希望这些记录能帮到你。

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