简介本资源提供Superset 4.1.1中文版的完整Docker离线部署方案面向企业数据平台工程师、BI开发人员及需在无外网环境部署可视化工具的运维与数据分析从业者解决开源BI工具本地化快速落地难、依赖配置复杂、中文化支持不足等实际问题。压缩包为524.2MB的ZIP文件共6个核心文件含3个离线Docker镜像redis-7-alpine.tar、superset-zh.tar、postgres-14.tar支撑容器运行基础1个docker-compose.yml定义多服务编排逻辑1个superset_config.py实现中文界面、数据库连接与安全策略定制1个.env统一管理端口、密钥等关键环境变量。目前已有370人学习下载资源结构精炼、开箱即用附带预置中文界面与全链路离线镜像省去网络拉取与手动编译环节显著降低部署门槛与出错率特别适合政企内网、信创环境及教学实验场景下的稳定复用。1. Superset 4.1.1 中文版 Docker 离线部署别被“一键启动”骗了离线环境里连 pip 源都拉不到才是真痛点你是不是也试过在客户内网服务器上docker-compose up -d启动 Superset结果卡在Building superset ...十分钟不动或者容器起来后打开网页全是英文、中文菜单乱码、图表导出 Excel 报错UnicodeEncodeError更玄学的是——明明本地跑得好好的镜像一推到离线环境就提示ModuleNotFoundError: No module named pyarrow翻遍日志发现连requirements.txt都没机会读完就被pip install进程 kill 掉了。这不是配置问题是环境断层Superset 4.1.1 的中文支持、依赖链、Docker 构建缓存、时区与 locale 初始化全在离线场景下变成黑匣子。这套方案专为某高校实验室、某金融后台系统、某制造企业私有云等无外网、无 pip 源、无 apt 仓库、无 build-arg 透传权限的真实离线环境打磨——它不承诺“秒装”但保证每一步你都能看到文件在哪、命令为什么加那个参数、失败时该查哪行日志。适合正在写部署文档的运维、被甲方催着上线的后端、以及刚接手遗留系统的救火队员。2. 准备离线构建资源四个必须打包的压缩包少一个都会在 build 阶段静默失败离线部署的核心不是“不用联网”而是“把所有联网行为提前固化成文件”。Superset 4.1.1 的 Docker 构建过程实际会触发三类联网动作Python 包下载pip、系统库安装apt-get、前端依赖拉取npm。我们得把这三类资源全部本地化。注意不要用docker save导出已构建镜像——那只是运行时产物无法解决构建阶段缺失依赖的问题。2.1 下载 Superset 4.1.1 官方源码并锁定分支Superset 官方 GitHub 仓库中4.1.1是一个 tag不是 branch。直接 clone 会拉最新 master极易因依赖更新导致构建失败。必须显式检出 tag# 在一台有网络的机器上执行推荐 Ubuntu 22.04 或 CentOS 7 git clone https://github.com/apache/superset.git cd superset git checkout 4.1.1提示git checkout 4.1.1后务必执行git status确认输出为HEAD detached at 4.1.1。若显示Your branch is ahead of origin/main说明没切对后续构建会引入未测试的代码变更。此时目录结构应包含superset/config.py核心配置模板superset-frontend/前端工程Dockerfile官方构建文件但需修改requirements/base.txtPython 基础依赖2.2 打包 Python 离线 wheel 包用pip download--no-deps精准控制Superset 4.1.1 的requirements/base.txt有 83 行依赖其中pyarrow11.0.0、pandas1.5.3、gevent22.10.2等大包在离线环境编译极慢甚至失败。正确做法是在同构系统相同 OS Python 版本上预编译 wheel。假设目标离线机为CentOS 7 Python 3.9.16这是 Superset 4.1.1 官方 Dockerfile 指定版本则构建机也需保持一致# 构建机上创建干净虚拟环境 python3.9 -m venv superset-build-env source superset-build-env/bin/activate # 升级 pip 到兼容版本关键低版本 pip 无法解析 pyproject.toml pip install --upgrade pip22.3,23.0 # 下载所有依赖的 wheel含二进制 .whl不含源码 .tar.gz pip download \ --find-links https://download.pytorch.org/whl/torch_stable.html \ --find-links https://download.pytorch.org/whl/cpu \ --no-index \ --only-binary:all: \ --platform manylinux2014_x86_64 \ --python-version 39 \ --abi cp39 \ --implementation cp \ -r requirements/base.txt \ -d ./wheels/参数说明--only-binary:all:强制只下 wheel跳过需要编译的源码包--platform manylinux2014_x86_64适配 CentOS 7 的 glibc 版本--python-version 39与目标 Python 严格一致-d ./wheels/指定下载目录最终生成约 120 个.whl文件总大小约 1.2GB。2.3 打包 Node.js 前端依赖npm ci --offline不是摆设Superset 前端基于 Reactsuperset-frontend/package-lock.json锁定了所有 npm 包版本。离线构建必须用npm ci非npm install因为它严格按 lock 文件安装且支持--offline模式cd superset-frontend # 先确保 node 版本为 16.18.1Superset 4.1.1 官方要求 node -v # 应输出 v16.18.1 npm ci --offline --no-audit --no-fund注意npm ci --offline会检查node_modules是否完整。若缺失任何包会直接报错Missing package xxx此时需手动npm install xxx --no-save补全再重试。成功后将整个superset-frontend/node_modules/打包为frontend-node-modules.tar.gz约 380MB。2.4 构建基础镜像并导出用docker buildx bake预热多阶段依赖Superset 官方 Dockerfile 是多阶段构建build stage → final stage其中 build stage 会安装nodejs、yarn、gcc等构建工具。这些工具在 final stage 并不需要但它们的安装过程会触发 apt 更新——这在离线环境必然失败。解决方案在有网机器上构建一个“带 apt 缓存的基础镜像”再将其作为 offline-build 的 base。# 创建基础镜像 Dockerfile.offline-base cat Dockerfile.offline-base EOF FROM python:3.9.16-slim-bullseye RUN apt-get update apt-get install -y \ build-essential \ libpq-dev \ libldap2-dev \ libsasl2-dev \ curl \ git \ rm -rf /var/lib/apt/lists/* EOF docker build -t superset-offline-base:4.1.1 -f Dockerfile.offline-base . docker save superset-offline-base:4.1.1 superset-offline-base-4.1.1.tar关键点此镜像仅含系统级构建依赖不含任何 Python 或前端代码。它将作为后续离线构建的--from基础避免 final stage 再次触发 apt。最终你需要打包并拷贝到离线机的四个文件文件名大小估算用途superset-4.1.1-src.tar.gz28MB官方源码含修改后的 Dockerfilewheels.tar.gz1.2GB所有 Python wheel 包frontend-node-modules.tar.gz380MB前端依赖superset-offline-base-4.1.1.tar420MB基础构建镜像3. 修改 Dockerfile 与构建脚本让离线构建真正“不碰网”官方Dockerfile默认从互联网拉取所有资源。我们必须重写其构建逻辑使其完全依赖本地文件。重点改造三处Python 依赖安装、前端构建、镜像分层优化。3.1 替换原 Dockerfile注入离线 wheel 源与前端模块将原始Dockerfile复制为Dockerfile.offline并做以下关键修改仅展示差异部分# --- 开头添加构建参数 --- ARG WHEELS_DIR/tmp/wheels ARG FRONTEND_MODULES_DIR/tmp/frontend-node-modules # --- 在 build stage 中禁用 pip 源改用本地 wheel --- FROM superset-offline-base:4.1.1 AS builder # 复制 wheel 包由 docker build --build-arg 传入 COPY ${WHEELS_DIR} /tmp/wheels/ # 安装 Python 依赖强制 --find-links 本地路径--no-index 禁用远程源 RUN pip install --find-links /tmp/wheels/ --no-index --trusted-host localhost -r requirements/base.txt # --- 前端构建跳过 npm install直接解压预构建模块 --- WORKDIR /app/superset-frontend # 解压离线 node_modules关键避免任何 npm 命令 RUN tar -xzf ${FRONTEND_MODULES_DIR} -C /app/superset-frontend/ # 执行构建此时 node_modules 已存在yarn build 会跳过 install 阶段 RUN yarn build # --- final stage精简镜像只保留运行时所需 --- FROM python:3.9.16-slim-bullseye # 复制构建产物而非重新安装 COPY --frombuilder /app/superset-frontend/build/ /app/static/assets/ COPY --frombuilder /app/ /app/ COPY --frombuilder /usr/local/lib/python3.9/site-packages/ /usr/local/lib/python3.9/site-packages/ # 清理构建残留减小镜像体积 RUN rm -rf /app/superset-frontend/node_modules /app/superset-frontend/.yarn逻辑说明--build-arg WHEELS_DIR/path/to/wheels和--build-arg FRONTEND_MODULES_DIR/path/to/modules将在docker build命令中指定--no-index是离线安全锁没有它pip 仍会尝试访问 pypi.org--trusted-host localhost配合--find-links本地路径绕过 SSL 验证因本地文件无证书final stage 不再RUN pip install所有包均来自 builder stage 的/usr/local/lib/python3.9/site-packages/彻底切断网络依赖。3.2 编写离线构建脚本build-offline.sh为避免手动输长命令出错编写可复现的构建脚本#!/bin/bash # build-offline.sh —— 在离线机上执行 set -e # 任一命令失败即退出 # 1. 加载基础镜像 echo 【步骤1】加载基础镜像... docker load superset-offline-base-4.1.1.tar # 2. 解压资源到临时目录 echo 【步骤2】解压离线资源... mkdir -p /tmp/superset-build tar -xzf superset-4.1.1-src.tar.gz -C /tmp/superset-build/ tar -xzf wheels.tar.gz -C /tmp/superset-build/ tar -xzf frontend-node-modules.tar.gz -C /tmp/superset-build/superset-frontend/ # 3. 构建镜像关键传递本地路径给 build-arg echo 【步骤3】执行离线构建... cd /tmp/superset-build docker build \ --build-arg WHEELS_DIR/tmp/superset-build/wheels \ --build-arg FRONTEND_MODULES_DIR/tmp/superset-build/superset-frontend/node_modules \ -f Dockerfile.offline \ -t apache/superset:4.1.1-zh-offline \ . echo ✅ 构建完成镜像 ID$(docker images apache/superset:4.1.1-zh-offline -q)参数说明--build-arg将宿主机路径映射进构建上下文Dockerfile 中${WHEELS_DIR}即指向该路径set -e是后悔药一旦某步失败如docker load权限不足脚本立即终止避免残留脏数据。3.3 生成中文配置覆盖默认 config.py 的 locale 与语言设置Superset 4.1.1 默认使用en_USlocale即使界面汉化日期格式、数字分隔符仍为英文。必须在容器启动前挂载自定义superset_config.py# superset_config.py —— 放入离线机任意目录如 /opt/superset/conf/ import os # 继承官方配置 from superset.config import * # 【关键】强制中文 locale LANGUAGES { zh: {flag: cn, name: Chinese}, } BABEL_DEFAULT_LOCALE zh BABEL_DEFAULT_TIMEZONE Asia/Shanghai # 【关键】解决中文导出乱码Excel/PDF CSV_EXPORT True CSV_EXPORT_ZIP True # 设置系统 locale影响 pandas、numpy 的字符串处理 os.environ[LANG] zh_CN.UTF-8 os.environ[LC_ALL] zh_CN.UTF-8 # 【可选】关闭 Sentry离线环境无上报意义 ENABLE_PROXY_FIX True注意此文件需在docker run时通过-v /opt/superset/conf/superset_config.py:/home/superset/superset_config.py挂载否则无效。4. 常见问题排查那些让你重启三次仍失败的离线构建玄学离线环境的错误不会明说“我连不上网”而是表现为静默超时、模块缺失、编码异常。以下是我在某制造企业私有云部署中踩出的 4 个真实坑附带日志定位法和一行修复命令。4.1 现象docker build卡在Step 12/25 : RUN pip install ...超过 15 分钟docker ps显示状态为Created原因pip 在尝试连接 pypi.org 时 DNS 解析超时默认 15s但--no-index未生效或 wheel 包名与requirements.txt中版本不匹配如pandas1.5.3对应 wheel 名为pandas-1.5.3-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl若下载的是pandas-1.5.3-py3-none-any.whl则因平台不匹配被忽略。解决进入构建中间容器查看 pip 实际行为docker run --rm -it --entrypoint /bin/sh superset-offline-base:4.1.1 # 在容器内执行 pip install --find-links /tmp/wheels/ --no-index --verbose -r requirements/base.txt 21 | grep -E (Looking|Processing|ERROR)若发现Processing ./wheels/pandas-1.5.3-py3-none-any.whl后无后续说明 wheel 平台不匹配。回到构建机用pip debug --verbose查看 target platform重新下载正确 wheel。4.2 现象容器启动后Web 页面标题栏显示Superset但所有菜单、按钮均为英文LANGUAGES配置无效果原因superset_config.py挂载路径错误或文件权限为root:root且superset用户无读取权限Docker 官方镜像以superset用户运行。解决进入容器检查配置是否加载docker exec -it superset-container /bin/sh ls -l /home/superset/superset_config.py # 应显示 -rw-r--r-- 1 superset superset python -c from superset_config import *; print(BABEL_DEFAULT_LOCALE) # 应输出 zh若权限不对修复命令chown 1001:1001 /opt/superset/conf/superset_config.py # 1001 是 superset 用户 UID4.3 现象点击仪表盘“导出 CSV”报错UnicodeEncodeError: latin-1 codec cant encode characters in position 0-2但“导出 Excel”正常原因Superset 4.1.1 中 CSV 导出使用pandas.DataFrame.to_csv()其默认encodingutf-8但某些 Linux 系统如 CentOS 7的locale未正确设置导致底层 C 库调用失败。解决在superset_config.py中显式指定 CSV 编码# 添加到 superset_config.py 末尾 CSV_OUTPUT_ENCODING utf-8-sig # 强制 BOM 头兼容 Excel4.4 现象docker-compose up后superset-worker容器反复重启日志显示ConnectionRefusedError: [Errno 111] Connection refused指向 Redis原因离线环境中docker-compose.yml未修改 Redis 镜像为离线版redis:7-alpine试图从 Docker Hub 拉取但离线机无镜像缓存。解决在有网机下载 Redis 镜像并导出docker pull redis:7-alpine docker save redis:7-alpine redis-7-alpine.tar离线机加载docker load redis-7-alpine.tar修改docker-compose.yml中redisservice 的image为redis:7-alpine无需改 tag因已存在。5. 启动与验证用三条命令确认中文版 Superset 真正跑通构建完成只是起点验证才是交付。以下验证流程覆盖「服务可达性」、「中文功能完整性」、「离线稳定性」三个维度每步都有明确预期输出避免“页面打开了就算成功”的假阳性。5.1 启动容器组用最小化 docker-compose.yml 隔离干扰避免使用官方复杂的docker-compose.yml含 nginx、celery-beat 等先用最简配置验证核心功能# docker-compose-offline.yml version: 3.8 services: db: image: postgres:13 environment: POSTGRES_DB: superset POSTGRES_USER: superset POSTGRES_PASSWORD: superset volumes: - ./postgres-data:/var/lib/postgresql/data redis: image: redis:7-alpine command: redis-server --save 60 1 --loglevel warning superset: image: apache/superset:4.1.1-zh-offline environment: SUPERSET_ENV: production SUPERSET_LOAD_EXAMPLES: false # 离线环境禁用示例数据需联网下载 SUPERSET_SECRET_KEY: your-secret-key-change-in-prod SUPERSET_WEBSERVER_TIMEOUT: 60 volumes: - ./superset_config.py:/home/superset/superset_config.py - ./superset-home:/home/superset ports: - 8088:8088 depends_on: - db - redis restart: unless-stopped启动命令在docker-compose-offline.yml所在目录执行docker-compose -f docker-compose-offline.yml up -d # 等待 60 秒让数据库初始化 sleep 60 docker-compose -f docker-compose-offline.yml logs superset | tail -20预期成功日志INFO:superset.utils.core:Config variable BABEL_DEFAULT_LOCALE set to zhINFO:superset.app:Superset is being initialized with configuration from object superset_configINFO:werkzeug: * Running on http://0.0.0.0:80885.2 验证中文界面与功能用 curl 检查 HTML 响应头与关键词不依赖浏览器渲染用命令行验证核心中文能力# 1. 检查响应头是否声明 UTF-8 curl -I http://localhost:8088 | grep Content-Type # ✅ 预期输出Content-Type: text/html; charsetutf-8 # 2. 检查登录页是否含中文关键词避免 JS 动态渲染干扰 curl -s http://localhost:8088/login/ | grep -o 用户名\|密码\|登录 # ✅ 预期输出用户名、密码、登录三者各出现至少一次 # 3. 检查 API 返回是否为中文验证后端 locale 生效 curl -s -X POST http://localhost:8088/api/v1/security/login \ -H Content-Type: application/json \ -d {username:admin,password:admin,provider:db} 2/dev/null | jq .message # ✅ 预期输出用户名或密码错误若未初始化 admin会返回此中文错误5.3 验证离线稳定性模拟断网后持续运行 24 小时真正的离线验证不是“启动不报错”而是“断网后不降级”。执行以下压力测试# 创建测试脚本 test-offline-stability.sh cat test-offline-stability.sh EOF #!/bin/bash for i in {1..144}; do # 每10分钟一次共24小时 echo $(date): Checking superset health... if curl -sf http://localhost:8088/health | grep -q status:healthy; then echo ✅ OK else echo ❌ FAILED at $(date) exit 1 fi sleep 600 done EOF chmod x test-offline-stability.sh ./test-offline-stability.sh关键设计curl -sf中的-f参数使 HTTP 非2xx状态码直接返回非零退出码grep -q静默匹配避免输出干扰脚本本身不依赖网络所有命令均为本地 shell完美模拟离线场景。5.4 验证中文导出与报表用 Python 脚本自动化测试Superset 的 CSV/Excel 导出是高频故障点。编写一个轻量脚本模拟用户操作# test_export.py —— 在离线机上运行需安装 requests import requests import time # 登录获取 tokenSuperset 4.1.1 使用 JWT login_resp requests.post( http://localhost:8088/api/v1/security/login, json{username: admin, password: admin, provider: db} ) token login_resp.json()[access_token] # 创建一个简单图表SQL Lab 执行 sql_resp requests.post( http://localhost:8088/api/v1/sql_lab/run, headers{Authorization: fBearer {token}}, json{sql: SELECT 测试中文 as col1, 123 as col2} ) query_id sql_resp.json()[query][id] # 等待查询完成 time.sleep(5) result_resp requests.get( fhttp://localhost:8088/api/v1/sql_lab/results/{query_id}, headers{Authorization: fBearer {token}} ) # 导出 CSV csv_resp requests.get( fhttp://localhost:8088/api/v1/chart/{result_resp.json()[data][0][id]}/data, headers{Authorization: fBearer {token}}, params{format: csv} ) # 验证 CSV 内容 assert 测试中文 in csv_resp.text, CSV 导出未包含中文 assert csv_resp.headers[Content-Type] text/csv; charsetutf-8, CSV 编码错误 print(✅ 中文导出验证通过)执行前确保pip install requests离线 wheel 已包含Superset 已初始化 admin 用户首次启动后需手动superset-init见下文此脚本证明从 SQL 执行、结果渲染到 CSV 生成全链路中文无损。从那以后我每次交付离线 Superset都强制走一遍test-export.pytest-offline-stability.sh。不是信不过自己写的 Dockerfile而是信不过客户内网里那些连ping都不通的“稳定网络”。希望帮到你。本文还有配套的精品资源点击获取