Superset 4.1.1 中文版离线部署：Docker镜像+内网环境完整指南

简介Superset 4.1.1 中文版 Docker 离线部署包面向需要在无外网环境下快速搭建数据可视化平台的企业运维与数据分析人员。资源将 Superset 与 PostgreSQL、Redis 等依赖组件封装为 Docker 镜像配合编排文件实现一键式容器化部署有效解决内网环境安装复杂、依赖冲突等问题。包体共 6 个文件涵盖 3 个离线镜像 tar 包应用、数据库、缓存、1 个 Compose 编排文件、1 个 Python 配置脚本及 1 个环境变量文件压缩后约 524.2MB。各文件分工明确镜像负责运行时环境编排与配置文件负责服务定义和参数调优用户只需按说明导入镜像并启动容器即可。已有 368 人学习下载。资源提供完整的中文配置说明与调试思路帮助用户理解 .env、superset_config.py 等核心文件的作用并在离线条件下完成从镜像加载到 Superset 访问的全流程适合正在规划内网 BI 工具的团队参考。1. 离线部署 Superset 4.1.1 中文版先想清楚要不要自己造镜像碰上没法连外网的数据平台环境又要上一套能画图表、能拖拽看板的 BI 工具Superset 是个高频选择。但「Superset 4.1.1 中文版 Docker 离线部署」这几个词拆开看每一截都有坑4.1.1 不是随便 pull 下来就能跑中文界面不是加个环境变量就能变出来离线更不是把镜像 docker save 带走就完事。很多团队卡在「镜像导进去了、容器起来了、页面是英文的图表里中文还全是方块」这个半成品状态进退两难。这篇我把从外网准备镜像到内网起服务、再解决中文显示和初始化数据库的完整流程拆出来适合要给内网搭 BI 环境、又不想在依赖树上反复折腾的开发者包括那些头一回接触 Superset 的运维同事。2. 环境准备与镜像前置把 4.1.1 从外网完整搬到内网2.1 选定镜像与宿主环境Superset 的部署方式基本分两派一是直接用 Python 虚拟环境跑二是用 Docker 跑。离线场景下我无脑选 Docker原因很务实——Superset 的依赖树太深Pandas、SQLAlchemy、Flask-AppBuilder 这些加起来上百个 Python 包在有网机器上装都可能撞版本冲突内网环境下 pip 装到一半断掉就是黑匣子。官方提供的 Superset 4.1.1 镜像里已经把核心依赖打包好了离线时只要把镜像导进去等于把一整棵依赖树搬了过去。宿主环境我这边的建议是Linux 内核 4.18 以上Docker 版本 20.10 以上docker compose v2 插件装上内存至少 8GB磁盘预留 30GB。Superset 本体镜像解压后大约 2GB再加上 PostgreSQL 和 Redis 的镜像以及日志和数据目录30GB 是比较稳的余量。Ubuuntu 22.04 和 CentOS 7.9 我都跑过CentOS 7 注意内核 3.10 的老版本要升级 docker 到新版否则 cgroup 和 iptables 会出怪问题。提示离线部署最忌讳「先拉镜像再看文档」。先把宿主机的 Docker 版本、磁盘 inode、防火墙规则确认完再动镜像导入能省掉一半的返工。2.2 在有网机器上拉取并打包镜像我一般先在能上网的工作机上用官方镜像 Superset 4.1.1 打底把后面章节要用的 PostgreSQL 和 Redis 一起拉下来。这里操作尽量一次做完减少来回拷文件的次数。先拉基础镜像docker pull superset:4.1.1 docker pull postgres:15-alpine docker pull redis:7-alpineSuperset 官方仓库对镜像的命名是supersettag 直接对应版本号。postgres 选 15-alpine 是因为内存占用比完整版小Redis 选 7-alpine 同理。这三个镜像在生产环境各司其职Superset 本身跑应用服务PostgreSQL 存元数据和看板定义Redis 做缓存和异步任务队列。如果内网报表并发不高PostgreSQL 也可以换成内置 SQLite但我不推荐后面初始化和管理员创建时 SQLite 在高版本下会有并发写入问题。镜像拉完用 docker save 把三个镜像打到同一个 tar 包里mkdir -p /opt/superset-offline docker save superset:4.1.1 postgres:15-alpine redis:7-alpine -o /opt/superset-offline/superset-images.tar gzip /opt/superset-offline/superset-images.tar ls -lh /opt/superset-offline/-o指定输出文件gzip压缩后通常能从 4GB 压到 2GB 左右。这里顺便解释一下为什么不直接拷整个 docker 目录Docker 的数据目录包含所有镜像的历史层和容器读写层拷过去体积大而且换一台机器容易出现权限错乱。tar 包方式是最稳定的搬运格式内网 U 盘拷或者 scp 都能传。如果内网还是 Debian 系也可以用docker save | ssh 内网机器 docker load这种管道直传方式省掉中间磁盘占用。2.3 传输、加载与第一次校验传输到内网机器之后先建立好目录再执行 docker loadmkdir -p /opt/superset/{config,data,logs} gunzip superset-images.tar.gz docker load -i superset-images.tardocker load 会把 tar 里的镜像层逐一展开到宿主机 Docker 目录。这一步的耗时长不长取决于磁盘性能机械盘可能需要十几分钟SSD 会快很多。加载完一定要做校验别急着往下走docker images | grep -E superset|postgres|redis校验重点有三个一是三个镜像的 tag 是否正确二是 IMAGE ID 是否和源机器一致三是 REPOSITORY 有没有被 docker load 改成none。镜像名变成none的情况我在离线导入时遇到过好几次尤其是多次 load 同版本镜像时旧镜像的 tag 会被剥离新的没有自动继承名字。遇到这种情况用 docker tag 手动补一下 tag 就行比如docker tag a1b2c3d4 superset:4.1.1否则后面 docker compose 拉镜像时会报找不到镜像。3. 构建中文语言环境二进制镜像之外还得处理汉字3.1 中文语言包怎么无网生效这是离线部署 4.1.1 最容易被低估的一环。Superset 4.x 本身内置了多语言翻译文件包括简体中文的 .po 编译结果但默认配置里没有把中文语言项开放出来。直接把官方镜像拉起来进去看设置界面语言下拉框里通常只有 English。要让中文选项出现需要给 Superset 挂一个自定义的 superset_config.py。我在内网机器上建配置文件的方式是这样的cat /opt/superset/config/superset_config.py EOF from superset.config import * LANGUAGES { en: {flag: us, name: English}, zh: {flag: cn, name: Chinese}, } BABEL_DEFAULT_LOCALE zh EOF这段配置的意思是定义一个字典类型的 LANGUAGES 变量包含 en 和 zh 两个条目结构是「语言代码——国旗标识——显示名称」。Superset 的界面语言机制允许你自定义可用语言列表只要语言代码在翻译资源目录里存在前端语言下拉框就会动态渲染出来。BABEL_DEFAULT_LOCALE 设置新用户默认使用中文如果想让老用户也默认中文需要他们手动切换一次。注意from superset.config import *这行的作用是把官方默认配置全部继承下来再覆盖其中需要改的部分。不要只写自定义变量否则 Superset 会因为缺少一大堆底层配置直接起不来。镜像内部代码在读取配置时有自己的优先级SUPERSET_CONFIG_PATH这个环境变量指向配置文件路径我们后续在 docker-compose 里把这个文件挂载到容器内并设置环境变量让它生效。3.2 中文字体安装导出 PDF 和图表渲染全靠它语言包解决的是「界面文字」字体解决的是「图表里的汉字渲染」。在浏览器里看图表的 SVG 文本字体是从浏览器本机取的不用服务器管。但 Superset 有一个功能是导出 PDF 报告、给图表截图这套逻辑是服务端用无头浏览器渲染页面如果系统里没有中文字体渲染出来的 PDF 里的汉字全是豆腐块数据看板上每个图表标题都是乱码方块。内网机器没有 apt 源装字体的方式也得前置到镜像构建阶段。在有网的工作机上我用一个自定义 Dockerfile 来打一个带中文字体的新镜像FROM superset:4.1.1 USER root RUN apt-get update \ apt-get install -y fonts-noto-cjk \ apt-get clean \ rm -rf /var/lib/apt/lists/* USER superset构建命令是docker build -t superset:4.1.1-font -f Dockerfile .构建完成后再docker save导出一次。这个 Dockerfile 做的事情不复杂切换到 root 用户安装 fonts-noto-cjk 字体包装完清掉 apt 缓存减小镜像体积最后切回 superset 用户保持官方镜像的权限体系。如果把 apt-get 这一步直接放在内网环境做会因为连不上软件源而失败所以必须在联网阶段构建完成。如果业务方对字体有额外要求比如指定用思源黑体可以在网易源或者 GitHub 上把 TTF 文件下到工作机Dockerfile 里用COPY指令把字体文件放进/usr/share/fonts/custom/再执行fc-cache -f刷新字体缓存。两者原理一样都是让容器内的 fontconfig 能识别中文字体。3.3 离线 Python 依赖为什么能避开很多第一次做离线部署的人拿到官方镜像之后还想往里面加 Python 库比如连 Oracle 数据库要装 cx_Oracle、连 SQL Server 要装 pyodbc。这里有个取舍问题在离线内网环境里直接docker exec -it superset bash进去 pip install百分之百会因为找不到 PyPI 镜像源而超时。如果确实要加依赖正确姿势还是在有网机器上操作。pip download cx_Oracle8.3.0 -d /opt/pip-wheels在 Dockerfile 里加上拷贝和安装的步骤COPY pip-wheels /tmp/pip-wheels RUN pip install --no-index --find-links/tmp/pip-wheels cx_Oracle--no-index强制 pip 不要访问 PyPI--find-links指定本地 wheel 目录。这里一个很重要的原则是能用官方镜像自带依赖解决的问题绝不新增包。Superset 4.1.1 已经内置了连接 PostgreSQL、MySQL、SQLite、Presto 等常用数据库的驱动只有碰到冷门数据库才需要走这条路。离线环境下每多一个外部依赖镜像的体积和故障面都会大一圈这不是折腾不起而是内网一旦缺一个 wheel整个部署进度就卡住了。4. Docker Compose 编排与初始化从宿主机到能登录的完整流程4.1 目录规划与编排文件镜像准备好之后就到了宿主机的编排环节。我的目录规划比较固定/opt/superset/config放配置文件/opt/superset/data放数据库持久化目录/opt/superset/logs放应用日志。这样做的目的很明确——容器重建不丢数据日志集中在一个地方方便排查。docker-compose.yml 是整套服务的编排核心我直接给出一个能跑通的最小可用版本services: superset: image: superset:4.1.1-font container_name: superset-app environment: - SUPERSET_SECRET_KEYyour-strong-secret-key - SUPERSET_CONFIG_PATH/app/superset_config.py - SQLALCHEMY_DATABASE_URIpostgresqlpsycopg2://superset:supersetpostgres:5432/superset - REDIS_URLredis://redis:6379/0 ports: - 8088:8088 volumes: - ./config/superset_config.py:/app/superset_config.py - ./data:/app/data - ./logs:/app/logs depends_on: - postgres - redis postgres: image: postgres:15-alpine container_name: superset-db environment: - POSTGRES_USERsuperset - POSTGRES_PASSWORDsuperset - POSTGRES_DBsuperset volumes: - ./data/postgres:/var/lib/postgresql/data redis: image: redis:7-alpine container_name: superset-redis volumes: - ./data/redis:/data这个 compose 文件里端口我映射为宿主机 8088这是 Superset 默认的 web 端口。SUPERSET_SECRET_KEY不能省这是 Flask 签名会话的密钥不设的话每次重启容器会话都会失效用户登录状态保存不住。数据库连接串里的postgres:5432是容器网络内的服务名解析Docker Compose 会自动建立内部 DNS。volumes 挂载的配置文件路径要和SUPERSET_CONFIG_PATH保持一致这里我挂到/app/superset_config.py是约定俗成的路径实际上容器内部任何可读路径都行只要环境变量指向同一个地方。提示your-strong-secret-key上线前一定要换掉最好用openssl rand -base64 42生成一串随机的。密钥泄露等于任何人可以伪造登录会话。4.2 让配置真正被容器读到compose 文件里环境变量SUPERSET_CONFIG_PATH的写法决定了自定义配置能不能加载。Superset 的启动脚本默认会读取/etc/superset/superset_config.py找不到才会去找环境变量指定的路径。我把它显式指向挂载的文件就是为了确保加载的是/opt/superset/config/superset_config.py而不是镜像内自带的那份。还需要注意配置文件的属主和权限chown -R 1000:1000 /opt/superset/config /opt/superset/data /opt/superset/logs chmod 640 /opt/superset/config/superset_config.py容器内 superset 用户的 UID 是 1000宿主机的文件属主如果不是 1000容器写入时会报 Permission denied。这种情况特别容易出现在从别的机器拷贝文件过来的时候tar 包里的文件属主还是原机器的 UID一挂载进去就翻车。chmod 640是防止配置文件里的数据库密码被同宿主机的其他用户读到内网环境同样要这条纪律。4.3 初始化数据库与管理员账号服务起起来之后先别急着访问页面Superset 还需要往 PostgreSQL 里建表和创建角色。官方镜像里带了一个 script但依赖顺序要靠我们手动控制。我是这样做的docker compose up -d docker compose exec superset superset db upgrade docker compose exec superset superset initdb upgrade会把 SQLAlchemy 模型同步到 PostgreSQL包括用户表、角色表、看板定义表。init会创建默认角色和权限。这两个命令执行完后数据库里才有一整套可用的元数据结构。接下来创建管理员账号docker compose exec -it superset superset fab create-admin \ --username admin \ --firstname admin \ --lastname admin \ --email adminlocal.local \ --password admin123456fab create-admin是 Flask-AppBuilder 提供的命令行工具--username和--password是必填项。这里我给的是初始密码正式环境第一次登录后要改掉。admin 账号是后文验证一切功能的基础如果这里漏执行打开页面登录时会一直报「invalid login」很多人到这里会怀疑是数据库没连上其实只是没建账号。5. 常见问题排查离线部署踩过的五个大坑5.1 docker load 报 no space left on device现象执行 docker load 时中途报错no space left on device但df -h看磁盘明明还有 20GB。原因Docker 的存储目录/var/lib/docker和根分区可能是两个挂载点df -h /看的空间并不代表 Docker 目录所在分区。镜像解压时还会先写临时目录需要的空间通常是 tar 包的 2 到 3 倍。解决先df -h /var/lib/docker确认 Docker 分区剩余空间不够就修改 Docker 的>healthcheck: test: [CMD, redis-cli, ping] interval: 5s timeout: 3s retries: 56. 验证跑通登录、切中文、导数据三步定生死环境装完最重要的不是马上接业务数据源而是先做一轮功能验证确认 Superset 本身的技术栈是通的。我每次离线部署完都强制走一遍下面的清单走完才敢交接给业务方。第一步浏览器访问http://内网IP:8088看到登录页后用 setup 时创建的 admin 账号登录。这一步主要验证 web 服务和 Flask 会话正常。如果登录成功但跳转回登录页看 SECRET_KEY 是否配置了持久值——容器每次重启生成的随机密钥会导致这个问题。第二步点右上角头像进入 Profile 设置在语言下拉框里选「中文」保存刷新。正常的话左侧菜单和数据集的表单都会变成中文。这一步是验证第 3 章配置是否真的被容器加载。第三步建立测试数据源做联调。Superset 自带一个 examples 数据库但离线环境里默认是没有的。更踏实的做法是直接用 PostgreSQL 自带的库先建一张测试表并塞几行数据docker compose exec postgres psql -U superset -d superset -c CREATE TABLE test_chart (id int, val int); INSERT INTO test_chart VALUES (1, 100), (2, 200);然后在 Superset 界面里通过 Data → Database 添加 PostgreSQL 数据源连接串填postgresqlpsycopg2://superset:supersetpostgres:5432/superset。建一个 Dataset点 Create Chart选一个 Table 图把 val 字段拖到 Metrics保存并跑一次查询。这一步能把后端 SQL 执行链路、数据库驱动、缓存 Redis 都串起来验证。如果在创建图表时秒报错八成是 Redis 缓存没通如果是查询超时则优先检查 PostgreSQL 连接池配置。最后跑一次docker compose logs -f superset | grep ERROR确认没有任何持续刷新的异常后把 admin 密码改掉清理初始化用的临时文件整个离线部署就算真正落地了。这套环境我从 4.0 一路装到 4.1.1每次离线部署都把「先拉镜像、再配中文、后连库」这个顺序钉死在心里少走很多弯路。希望这些踩过的坑和验证习惯能帮到你照着这套流程走完你的 Superset 4.1.1 中文离线环境应该也能在半天内跑起来。本文还有配套的精品资源点击获取