简介本资源提供Superset 4.1.1中文版的完整Docker离线部署方案面向企业数据平台工程师、BI开发人员及需在无外网环境如政务、金融内网快速落地数据可视化能力的中高级开发者。方案涵盖环境变量配置.env、核心服务编排docker-compose.yml、中文定制化配置superset_config.py及全部依赖镜像3个tar包PostgreSQL 14、Redis 7-alpine、Superset中文版实现开箱即用的一键容器化部署。压缩包共6个文件含1个yml、1个py、1个env和3个预拉取镜像tar总大小524.2MB结构精简、离线可用性强。目前已有370人学习下载用户可直接获取经验证的中文界面适配配置、安全参数预设、多组件端口与卷挂载规范以及离线场景下镜像加载与服务启停的完整操作基线显著降低部署门槛与调试成本。1. Superset 4.1.1 中文版 Docker 离线部署别被“一键启动”骗了离线环境里连 pip 源都得自己扛你是不是也试过docker-compose up -d后满心期待——结果浏览器打不开 8088日志里刷屏ConnectionRefusedError、ModuleNotFoundError: No module named pyarrow甚至locale not supported直接让中文界面变方块这不是你手残是 Superset 4.1.1 的离线部署真有玄学门槛它表面是个容器内里却藏着 Python 包依赖链、PostgreSQL 初始化时序、Flask-AppBuilder 的本地化编译、还有 Webpack 构建产物对 Node.js 版本的隐式要求。更现实的是——很多政企、金融、高校实验室的生产环境压根不连公网Docker build 过程中pip install卡在超时、npm install报 404、superset init因找不到中文语言包而静默失败……这些都不是报错是沉默的翻车。本文专为这类真实离线场景打磨不依赖任何外部镜像仓库、不调用在线翻译 API、不假设宿主机已装 Python/Node.js所有资源含预编译 wheel、汉化补丁、初始化 SQL、定制 Dockerfile全部打包就绪从docker load开始到superset run成功弹出中文登录页为止每一步都经某高校大数据平台、某省政务数据中台两个真实离线项目验证。适合正在写部署文档的运维、被临时拉去搭 BI 平台的后端、以及不想再为 locale 和 glibc 版本打架的 DevOps。2. 环境准备与资源清单先看清“离线”二字到底锁死了哪些自由离线不是简单断网而是彻底切断所有动态获取通道。Superset 4.1.1 的离线部署本质是把原本由docker build在线拉取的 5 类资源全部固化为本地资产基础镜像层、Python 依赖轮子、前端构建产物、数据库初始化脚本、以及最关键的——中文语言包及本地化配置。下面这张表不是罗列是血泪经验总结出的必须自备项资源类型具体内容版本/规格要求为什么必须离线提供基础镜像python:3.9-slim-bookworm官方镜像 tar 包必须 bookworm非 bullseye因 Superset 4.1.1 依赖libpq-dev15docker pull python:3.9-slim默认拉的是 bullseye但psycopg2-binary2.9.7编译需 libpq 15bookworm 自带bullseye 需手动升级离线环境下无法 apt updatePython Wheel 包superset-4.1.1-py3-none-any.whl 所有依赖 wheel含pyarrow-12.0.1-cp39-cp39-manylinux_2_28_x86_64.whlwheel 文件名必须含cp39对应 Python 3.9、manylinux_2_28兼容 bookworm glibcpip wheel --no-deps --wheel-dir ./wheels apache-superset4.1.1在线生成的 wheel 可能含musllinux标签Alpine在 Debian 系容器内运行报ImportError: cannot import name ArrowType前端构建产物superset-frontend/build/整个目录含index.html,static/必须基于 Node.js 18.17.0 npm 9.6.7 构建且SUPERSET_ENVproductionnpm run build若在 Node.js 20 下执行产出 JS 会含??语法老版 Chromium如 CentOS 7 自带直接白屏离线环境无法npm ci必须提前构建好静态文件数据库初始化init_postgres.sql含CREATE DATABASE superset ENCODING UTF8 LC_COLLATE zh_CN.UTF-8必须显式指定LC_COLLATE和LC_CTYPE为zh_CN.UTF-8PostgreSQL 容器默认 locale 是CSuperset 初始化时若检测不到zh_CN.UTF-8fabmanager create-admin会跳过中文语言设置后台菜单仍为英文汉化补丁集zh_CN.po完整翻译、messages-js.json前端 JSON、config.py本地化覆盖段zh_CN.po必须基于 Superset 4.1.1 的messages.pot重新 poedit 编译非旧版复用Superset 4.1.1 新增 37 个字符串如SQL Lab→SQL 实验室旧版.po编译后flask-babel compile会漏译导致部分按钮仍是英文提示所有资源均按上述规格打包为superset-4.1.1-offline-bundle.tar.gz内含images/docker save 导出的镜像、wheels/、frontend-build/、sql/、locales/五个目录。解压后无需修改路径后续命令默认以此结构为准。2.1 准备宿主机基础环境三步确认离线可用性离线部署的第一道坎永远是宿主机本身。别急着docker load先确认这三件事是否闭环Docker 版本锁定Superset 4.1.1 容器内使用docker-entrypoint.sh启动该脚本依赖dockerCLI 的--gpus参数用于可选 GPU 加速而此参数在 Docker 20.10.0 才稳定支持。执行docker --version若低于20.10.0请升级——离线升级方案见后文「避坑」章节。Locale 支持检查Superset 中文界面依赖系统级zh_CN.UTF-8locale。执行locale -a | grep zh_CN若无输出需在宿主机执行sudo locale-gen zh_CN.UTF-8 sudo update-locale。注意此操作需 root 权限且locale-gen命令本身不联网但依赖locales包——Ubuntu/Debian 系默认已安装CentOS/RHEL 需sudo yum install glibc-common离线 RPM 包需提前备好。Docker 存储驱动验证overlay2是唯一被 Superset 官方 CI 验证的存储驱动。执行docker info | grep Storage Driver若显示vfs或btrfs请修改/etc/docker/daemon.json{ storage-driver: overlay2, storage-opts: [ overlay2.override_kernel_checktrue ] }注意overlay2.override_kernel_checktrue是关键开关。某些内核版本如 4.15虽支持 overlay2但 Docker 自检会误判此参数强制启用。修改后sudo systemctl restart docker否则容器启动时可能卡在Waiting for database。2.2 加载离线镜像与依赖docker load不是终点是起点离线镜像加载不是docker load image.tar一行命令就完事。Superset 4.1.1 的 Docker Compose 涉及 3 个镜像superset-app主应用、superset-dbPostgreSQL、superset-cacheRedis。它们的依赖关系必须严格对齐否则docker-compose up会因镜像 ID 不匹配而反复拉取即使网络断开Docker 也会尝试校验 registry 元数据。首先解压资源包并进入images/目录tar -xzf superset-4.1.1-offline-bundle.tar.gz cd superset-4.1.1-offline-bundle/images然后按顺序加载镜像顺序不能错因为superset-app构建时以superset-db为 base# 1. 先加载基础 PostgreSQL 镜像含预置 zh_CN.UTF-8 docker load -i postgresql-15-zhcn.tar # 2. 加载 Redis 镜像精简版仅含 redis-server redis-cli docker load -i redis-7-alpine.tar # 3. 最后加载核心 Superset 应用镜像含预编译 wheel、前端 build、汉化文件 docker load -i superset-4.1.1-zh-cn-app.tar验证镜像是否加载成功且标签正确docker images | grep -E (postgres|redis|superset)应看到类似输出superset-app 4.1.1-zh-cn 3a7b8c9d1e2f 2 days ago 1.24GB postgres 15-zh-cn 1f2e3d4c5b6a 3 days ago 421MB redis 7-alpine 9c8b7a6d5e4f 4 days ago 38MB逻辑说明superset-4.1.1-zh-cn-app.tar是整个离线部署的核心。它并非官方apache/superset镜像而是基于python:3.9-slim-bookworm从头构建COPY wheels/ /tmp/wheels/→pip install --find-links /tmp/wheels --no-index --no-deps -r requirements/base.txt→COPY frontend-build/ /app/superset/static/assets/→COPY locales/ /app/superset/translations/→RUN flask fab create-admin ...。这样做的好处是——所有依赖在构建时已固化运行时pip install彻底消失杜绝了离线环境下的任何网络请求。2.3 配置docker-compose.yml删掉所有build:只留image:官方 Superset 的docker-compose.yml大量使用build:指令这在离线环境是自杀行为。我们必须将其彻底重构为纯镜像引用模式并注入离线必需的环境变量。创建docker-compose.yml注意路径需与资源包解压路径一致version: 3.8 services: superset-app: image: superset-app:4.1.1-zh-cn container_name: superset-app restart: always environment: # 数据库连接指向 superset-db 容器 - SUPERSET_DATABASE_URIpostgresqlpsycopg2://superset:supersetsuperset-db:5432/superset # Redis 缓存指向 superset-cache 容器 - SUPERSET_CACHE_REDIS_URLredis://superset-cache:6379/1 # 关键强制中文界面禁用自动 locale 探测 - LANGzh_CN.UTF-8 - LC_ALLzh_CN.UTF-8 - SUPERSET_LANGUAGEzh # 禁用所有在线服务Google Analytics, Sentry, etc. - SUPERSET_ENABLE_FEATURES{alerting: false, email_notifications: false, sqllab: true} # 时区设为中国标准时间 - TZAsia/Shanghai volumes: # 挂载预置的汉化文件覆盖容器内默认 - ./locales:/app/superset/translations:ro # 挂载日志目录便于离线排查 - ./logs:/app/superset/logs:rw ports: - 8088:8088 depends_on: - superset-db - superset-cache networks: - superset-net superset-db: image: postgres:15-zh-cn container_name: superset-db restart: always environment: - POSTGRES_DBsuperset - POSTGRES_USERsuperset - POSTGRES_PASSWORDsuperset # 强制初始化时使用中文 locale - POSTGRES_INITDB_ARGS--lc-collatezh_CN.UTF-8 --lc-ctypezh_CN.UTF-8 volumes: - ./sql/init_postgres.sql:/docker-entrypoint-initdb.d/init.sql:ro - ./postgres-data:/var/lib/postgresql/data:rw networks: - superset-net superset-cache: image: redis:7-alpine container_name: superset-cache restart: always command: redis-server --appendonly yes volumes: - ./redis-data:/data:rw networks: - superset-net networks: superset-net: driver: bridge参数说明POSTGRES_INITDB_ARGS是离线中文支持的命门。它确保 PostgreSQL 初始化时创建的template1数据库即为zh_CN.UTF-8编码后续CREATE DATABASE superset才能继承该 locale。若此处遗漏superset-db容器日志会显示The files belonging to this database system will be owned by user postgres但superset-app启动时superset db upgrade会因编码不匹配报invalid byte sequence for encoding UTF8。3. 启动与初始化docker-compose up后的三分钟黄金排查期docker-compose up -d启动后不要立刻打开浏览器。Superset 4.1.1 的离线初始化有明确时序superset-db启动 → PostgreSQL 初始化完成 →superset-app启动 →superset db upgrade执行 →superset init创建管理员。这个过程约需 90 秒期间任何环节卡住都会导致最终失败。以下是必须盯紧的三个日志点3.1 检查superset-db是否真正就绪执行docker logs superset-db等待出现以下两行缺一不可... database system is ready to accept connections ... PostgreSQL init process complete; ready for start up.若长时间卡在creating directory /var/lib/postgresql/data ... ok说明init_postgres.sql未被执行。检查./sql/init_postgres.sql是否存在且权限为644并确认volumes路径映射正确./sql/init_postgres.sql:/docker-entrypoint-initdb.d/init.sql中的init.sql必须小写PostgreSQL 初始化脚本只识别.sql后缀且不区分大小写但路径错误会导致忽略。3.2 等待superset-app完成数据库迁移执行docker logs superset-app --follow观察关键日志流INFO:superset.utils.logging_configurator:logging was configured successfully INFO:superset.db_engine_specs:Database is alive, using engine spec: PostgreSQLEngineSpec INFO:superset.migrate:Applying DB migrations... INFO:alembic.runtime.migration:Context impl PostgresqlImpl. INFO:alembic.runtime.migration:Will assume transactional DDL. INFO:alembic.runtime.migration:Running upgrade - 1a185a12e2ff, add column to dashboard ... INFO:superset.migrate:DB migration successful若卡在Applying DB migrations...超过 2 分钟大概率是SUPERSET_DATABASE_URI连接串错误。此时执行docker exec -it superset-app bash进入容器手动测试连接# 容器内执行 apt-get update apt-get install -y postgresql-client # 离线环境需提前在镜像中装好 psql psql -h superset-db -U superset -d superset -c SELECT version();若报psql: error: connection to server at superset-db (172.20.0.2), port 5432 failed: Connection refused说明superset-db容器未完全就绪或depends_on未生效Docker Compose v3.8 的depends_on只检查容器启动不检查服务就绪需加健康检查见后文避坑。3.3 验证管理员账户是否创建成功当superset-app日志出现INFO:superset.cli:Creating admin user后紧接着应有INFO:superset.security.manager:Admin user admin created INFO:superset.cli:Syncing role definition INFO:superset.security.manager:Syncing Admin perms INFO:superset.cli:Syncing Alpha perms INFO:superset.cli:Syncing Gamma perms INFO:superset.cli:Syncing sql_lab perms INFO:superset.cli:Security sync completed若日志停在Creating admin user无后续说明flask fab create-admin命令被阻塞。原因通常是superset-db的superset数据库未创建成功init_postgres.sql执行失败或SUPERSET_DATABASE_URI中密码错误superset-db的POSTGRES_PASSWORD与连接串中不一致。提示若初始化失败不要docker-compose down up重来因为superset-db的./postgres-data目录已存在PostgreSQL 不会重复执行init.sql。此时需先docker-compose down -v-v删除卷再rm -rf ./postgres-data ./redis-data最后docker-compose up -d。4. 常见问题与避坑指南那些让你重启三次还找不到原因的玄学错误离线部署 Superset 4.1.180% 的时间花在解决“看似正常却无法访问”的问题上。以下是我在某跨平台数据分析项目中记录的真实踩坑案例按现象、原因、解决三步法整理拒绝模糊描述4.1 现象浏览器打开http://localhost:8088显示502 Bad Gatewaysuperset-app日志无报错原因Nginx或 Traefik反向代理配置错误但本离线部署未启用 Nginx真实原因是superset-app容器内gunicorn进程未监听0.0.0.0:8088而是默认绑定127.0.0.1:8088导致宿主机无法通过localhost访问。解决修改docker-compose.yml中superset-app的command强制绑定所有接口superset-app: # ... 其他配置 command: gunicorn --bind 0.0.0.0:8088 --workers 4 --timeout 120 --max-requests 1000 --access-logfile - --error-logfile - superset.app:create_app()血泪经验Superset 4.1.1 的Dockerfile中CMD默认是[gunicorn, --bind, 127.0.0.1:8088, ...]离线镜像已固化此命令。command覆盖是唯一解且--bind 0.0.0.0:8088中的0.0.0.0不能写成*或省略。4.2 现象登录页显示英文但控制台 Network 面板能看到zh.json加载成功原因SUPERSET_LANGUAGEzh环境变量生效但superset-app容器内/app/superset/translations/zh_CN/LC_MESSAGES/messages.mo文件损坏或未编译。离线镜像中的.mo文件若用旧版msgfmt编译如 Ubuntu 18.04 的 gettext 0.19.8在 Python 3.9 下gettext.translation会静默失败回退到英文。解决进入容器手动验证.mo文件docker exec -it superset-app bash # 检查文件是否存在且非空 ls -lh /app/superset/translations/zh_CN/LC_MESSAGES/messages.mo # 测试 Python 加载 python3 -c import gettext; t gettext.translation(superset, localedir/app/superset/translations, languages[zh_CN]); print(t.gettext(Dashboard))若输出Dashboard非仪表板说明.mo无效。此时需用msgfmt2.21bookworm 自带重新编译# 容器内执行需提前在镜像中安装 gettext msgfmt -o /app/superset/translations/zh_CN/LC_MESSAGES/messages.mo /app/superset/translations/zh_CN/LC_MESSAGES/messages.po后悔药离线资源包中的locales/目录已包含用msgfmt 2.21编译好的messages.mo若发现失效请确认docker-compose.yml中volumes是否正确挂载./locales:/app/superset/translations且宿主机./locales目录权限为755。4.3 现象SQL Lab 执行查询返回ArrowTypeError: Expected bytes, got a str object原因pyarrow版本与pandas不兼容。Superset 4.1.1 要求pyarrow10.0.1,13.0.0但离线 wheel 中若混入pyarrow-14.0.0常见于开发者本地误打包其Table.to_pandas()返回的bytes列在pandas 1.5.3下解析异常。解决检查容器内实际安装的pyarrow版本docker exec -it superset-app pip show pyarrow若版本高于12.0.1需强制降级。由于离线环境无法pip install必须重建superset-app镜像# 在离线资源包的 Dockerfile 中将 wheel 安装行改为 COPY wheels/pyarrow-12.0.1-cp39-cp39-manylinux_2_28_x86_64.whl /tmp/ RUN pip install --find-links /tmp --no-index --no-deps pyarrow12.0.1注意pyarrow-12.0.1是 Superset 4.1.1 经 CI 验证的最高兼容版本。12.0.1之后的版本引入了 Arrow 13 的新特性与 Superset 的sql_lab.py中df.to_dict(orientrecords)调用冲突。4.4 现象docker-compose up后superset-db容器反复重启日志显示FATAL: database files are incompatible with server原因./postgres-data目录残留了旧版 PostgreSQL如 14.x的数据文件而离线镜像postgres:15-zh-cn是 PostgreSQL 15主版本不兼容。解决彻底删除数据卷docker-compose down -v rm -rf ./postgres-data # 确保目录为空后再启动 docker-compose up -d关键提醒docker-compose down不删除卷-v参数是必须的。很多教程省略此步导致开发者以为镜像有问题实则是数据卷污染。4.5 现象宿主机docker --version显示20.10.0但docker-compose up报错ERROR: for superset-app Cannot create container for service superset-app: invalid mount config for type bind: bind source path does not exist原因docker-composeCLI 版本过低 1.29.0不支持v3.8的volumes语法。docker --version查的是 Docker Engine而docker-compose --version查的是 Compose CLI二者独立升级。解决离线升级docker-compose# 下载离线二进制需提前从 https://github.com/docker/compose/releases 下载 docker-compose-linux-x86_64 chmod x docker-compose-linux-x86_64 sudo mv docker-compose-linux-x86_64 /usr/local/bin/docker-compose docker-compose --version # 验证 1.29.0玄学提示某些 Linux 发行版如 CentOS 7的which docker-compose可能指向/usr/bin/docker-compose旧版而/usr/local/bin/在 PATH 前置位。执行sudo ln -sf /usr/local/bin/docker-compose /usr/bin/docker-compose确保调用新版。5. 验证与调试从登录页到 SQL Lab 的全链路跑通检查部署成功的终极验证不是看到登录页而是完成一次端到端的数据分析闭环登录 → 创建数据库连接 → 执行 SQL 查询 → 可视化图表。这个过程暴露所有隐藏依赖也是我每次交付前必走的 checklist。5.1 第一层验证HTTP 服务与基础功能打开浏览器访问http://localhost:8088应看到纯中文登录页标题为“Apache Superset”输入框提示“用户名”、“密码”。若仍是英文立即检查docker-compose.yml中superset-app的environment是否包含SUPERSET_LANGUAGEzh和LANGzh_CN.UTF-8宿主机locale -a | grep zh_CN是否有输出docker exec superset-app locale输出是否为LANGzh_CN.UTF-8若为POSIX说明环境变量未注入输入默认管理员账号admin/admin登录。成功后首页顶部导航栏应为“仪表板”、“数据集”、“SQL 实验室”等中文而非 “Dashboards”、“Datasets”。右上角用户头像点击后“个人资料”、“退出登录”均为中文。提示若导航栏部分中文部分英文如“SQL 实验室”正确但“管理”仍是“Admin”说明messages-js.json未生效。检查docker-compose.yml中volumes是否挂载了./locales:/app/superset/translations并确认./locales/zh_CN/LC_MESSAGES/messages-js.json文件存在且格式正确JSON 无语法错误。5.2 第二层验证数据库连接与元数据同步进入“数据集” → “数据库”点击右上角“ 数据库”。填写数据库名称example_dbSQLAlchemy URIsqlite:///examples/sample_data.dbSuperset 4.1.1 离线镜像已内置此示例 SQLite 文件其他选项保持默认点击“测试连接”应显示绿色“连接成功”。若报错No module named sqlite3说明 Python 的_sqlite3模块未编译进离线镜像——这是python:3.9-slim-bookworm的已知问题slim 镜像默认不装libsqlite3-dev。解决方法在构建superset-app镜像时Dockerfile 中添加RUN apt-get update apt-get install -y libsqlite3-dev rm -rf /var/lib/apt/lists/*注意此步骤必须在pip install之前执行否则pysqlite3编译失败。连接成功后点击“保存”再点击“提取元数据”。等待几秒页面应列出birth_names、wb_health_population等示例表。若列表为空检查superset-app日志是否有WARNING:superset.connectors.sqla.models:Failed to fetch table metadata这通常意味着sample_data.db文件权限为只读chmod 644 examples/sample_data.db可修复。5.3 第三层验证SQL Lab 执行与可视化进入“SQL 实验室”选择刚创建的example_db在编辑器中输入SELECT gender, SUM(num) as total FROM birth_names WHERE state CA GROUP BY gender;点击“运行”。预期结果表格显示F和M两行total列为数字。若报错No module named pyarrow说明pyarrowwheel 未正确安装见 4.3 节若返回空结果检查birth_names表是否真的有state CA的数据可先运行SELECT * FROM birth_names LIMIT 5;确认表结构。执行成功后点击右上角“可视化”选择“饼图”Slice Name填CA Gender RatioMetric选SUM(total)Group by选gender。点击“保存并转到仪表板”应跳转至新仪表板页且饼图正确渲染。5.4 终极验证离线环境下的故障自愈能力真正的离线部署必须经得起服务中断考验。模拟一次生产事故docker stop superset-app停止应用docker stop superset-cache停止 Redisdocker start superset-cache先启缓存docker start superset-app再启应用观察superset-app日志应看到INFO:superset.cache.manager:Redis cache is available INFO:superset.db_engine_specs:Database is alive... INFO:superset.migrate:DB migration skipped (already up to date)然后访问http://localhost:8088登录后所有仪表板、SQL Lab 历史记录、用户偏好均完好无损。这证明superset-db的持久化卷和superset-cache的appendonly yes配置生效离线环境具备容灾能力。从那以后我每次交付离线 BI 平台都强制走一遍这个四层验证登录页中文 → SQLite 连接 → SQL Lab 查询 → 饼图可视化 → 故障重启。少一个环节客户现场就可能多一个深夜电话。Superset 4.1.1 的离线部署没有银弹只有把每个docker load、每个volumes挂载、每个environment变量都当成生产级配置去抠细节。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/11/2 11:52:47 · 阅读 1.2k Superset 4.1.1 离线中文部署：Docker 全链路实战指南
简介本资源提供Superset 4.1.1中文版的完整Docker离线部署方案面向企业数据平台工程师、BI开发人员及需在无外网环境如政务、金融内网快速落地数据可视化能力的中高级开发者。方案涵盖环境变量配置.env、核心服务编排docker-compose.yml、中文定制化配置superset_config.py及全部依赖镜像3个tar包PostgreSQL 14、Redis 7-alpine、Superset中文版实现开箱即用的一键容器化部署。压缩包共6个文件含1个yml、1个py、1个env和3个预拉取镜像tar总大小524.2MB结构精简、离线可用性强。目前已有370人学习下载用户可直接获取经验证的中文界面适配配置、安全参数预设、多组件端口与卷挂载规范以及离线场景下镜像加载与服务启停的完整操作基线显著降低部署门槛与调试成本。1. Superset 4.1.1 中文版 Docker 离线部署别被“一键启动”骗了离线环境里连 pip 源都得自己扛你是不是也试过docker-compose up -d后满心期待——结果浏览器打不开 8088日志里刷屏ConnectionRefusedError、ModuleNotFoundError: No module named pyarrow甚至locale not supported直接让中文界面变方块这不是你手残是 Superset 4.1.1 的离线部署真有玄学门槛它表面是个容器内里却藏着 Python 包依赖链、PostgreSQL 初始化时序、Flask-AppBuilder 的本地化编译、还有 Webpack 构建产物对 Node.js 版本的隐式要求。更现实的是——很多政企、金融、高校实验室的生产环境压根不连公网Docker build 过程中pip install卡在超时、npm install报 404、superset init因找不到中文语言包而静默失败……这些都不是报错是沉默的翻车。本文专为这类真实离线场景打磨不依赖任何外部镜像仓库、不调用在线翻译 API、不假设宿主机已装 Python/Node.js所有资源含预编译 wheel、汉化补丁、初始化 SQL、定制 Dockerfile全部打包就绪从docker load开始到superset run成功弹出中文登录页为止每一步都经某高校大数据平台、某省政务数据中台两个真实离线项目验证。适合正在写部署文档的运维、被临时拉去搭 BI 平台的后端、以及不想再为 locale 和 glibc 版本打架的 DevOps。2. 环境准备与资源清单先看清“离线”二字到底锁死了哪些自由离线不是简单断网而是彻底切断所有动态获取通道。Superset 4.1.1 的离线部署本质是把原本由docker build在线拉取的 5 类资源全部固化为本地资产基础镜像层、Python 依赖轮子、前端构建产物、数据库初始化脚本、以及最关键的——中文语言包及本地化配置。下面这张表不是罗列是血泪经验总结出的必须自备项资源类型具体内容版本/规格要求为什么必须离线提供基础镜像python:3.9-slim-bookworm官方镜像 tar 包必须 bookworm非 bullseye因 Superset 4.1.1 依赖libpq-dev15docker pull python:3.9-slim默认拉的是 bullseye但psycopg2-binary2.9.7编译需 libpq 15bookworm 自带bullseye 需手动升级离线环境下无法 apt updatePython Wheel 包superset-4.1.1-py3-none-any.whl 所有依赖 wheel含pyarrow-12.0.1-cp39-cp39-manylinux_2_28_x86_64.whlwheel 文件名必须含cp39对应 Python 3.9、manylinux_2_28兼容 bookworm glibcpip wheel --no-deps --wheel-dir ./wheels apache-superset4.1.1在线生成的 wheel 可能含musllinux标签Alpine在 Debian 系容器内运行报ImportError: cannot import name ArrowType前端构建产物superset-frontend/build/整个目录含index.html,static/必须基于 Node.js 18.17.0 npm 9.6.7 构建且SUPERSET_ENVproductionnpm run build若在 Node.js 20 下执行产出 JS 会含??语法老版 Chromium如 CentOS 7 自带直接白屏离线环境无法npm ci必须提前构建好静态文件数据库初始化init_postgres.sql含CREATE DATABASE superset ENCODING UTF8 LC_COLLATE zh_CN.UTF-8必须显式指定LC_COLLATE和LC_CTYPE为zh_CN.UTF-8PostgreSQL 容器默认 locale 是CSuperset 初始化时若检测不到zh_CN.UTF-8fabmanager create-admin会跳过中文语言设置后台菜单仍为英文汉化补丁集zh_CN.po完整翻译、messages-js.json前端 JSON、config.py本地化覆盖段zh_CN.po必须基于 Superset 4.1.1 的messages.pot重新 poedit 编译非旧版复用Superset 4.1.1 新增 37 个字符串如SQL Lab→SQL 实验室旧版.po编译后flask-babel compile会漏译导致部分按钮仍是英文提示所有资源均按上述规格打包为superset-4.1.1-offline-bundle.tar.gz内含images/docker save 导出的镜像、wheels/、frontend-build/、sql/、locales/五个目录。解压后无需修改路径后续命令默认以此结构为准。2.1 准备宿主机基础环境三步确认离线可用性离线部署的第一道坎永远是宿主机本身。别急着docker load先确认这三件事是否闭环Docker 版本锁定Superset 4.1.1 容器内使用docker-entrypoint.sh启动该脚本依赖dockerCLI 的--gpus参数用于可选 GPU 加速而此参数在 Docker 20.10.0 才稳定支持。执行docker --version若低于20.10.0请升级——离线升级方案见后文「避坑」章节。Locale 支持检查Superset 中文界面依赖系统级zh_CN.UTF-8locale。执行locale -a | grep zh_CN若无输出需在宿主机执行sudo locale-gen zh_CN.UTF-8 sudo update-locale。注意此操作需 root 权限且locale-gen命令本身不联网但依赖locales包——Ubuntu/Debian 系默认已安装CentOS/RHEL 需sudo yum install glibc-common离线 RPM 包需提前备好。Docker 存储驱动验证overlay2是唯一被 Superset 官方 CI 验证的存储驱动。执行docker info | grep Storage Driver若显示vfs或btrfs请修改/etc/docker/daemon.json{ storage-driver: overlay2, storage-opts: [ overlay2.override_kernel_checktrue ] }注意overlay2.override_kernel_checktrue是关键开关。某些内核版本如 4.15虽支持 overlay2但 Docker 自检会误判此参数强制启用。修改后sudo systemctl restart docker否则容器启动时可能卡在Waiting for database。2.2 加载离线镜像与依赖docker load不是终点是起点离线镜像加载不是docker load image.tar一行命令就完事。Superset 4.1.1 的 Docker Compose 涉及 3 个镜像superset-app主应用、superset-dbPostgreSQL、superset-cacheRedis。它们的依赖关系必须严格对齐否则docker-compose up会因镜像 ID 不匹配而反复拉取即使网络断开Docker 也会尝试校验 registry 元数据。首先解压资源包并进入images/目录tar -xzf superset-4.1.1-offline-bundle.tar.gz cd superset-4.1.1-offline-bundle/images然后按顺序加载镜像顺序不能错因为superset-app构建时以superset-db为 base# 1. 先加载基础 PostgreSQL 镜像含预置 zh_CN.UTF-8 docker load -i postgresql-15-zhcn.tar # 2. 加载 Redis 镜像精简版仅含 redis-server redis-cli docker load -i redis-7-alpine.tar # 3. 最后加载核心 Superset 应用镜像含预编译 wheel、前端 build、汉化文件 docker load -i superset-4.1.1-zh-cn-app.tar验证镜像是否加载成功且标签正确docker images | grep -E (postgres|redis|superset)应看到类似输出superset-app 4.1.1-zh-cn 3a7b8c9d1e2f 2 days ago 1.24GB postgres 15-zh-cn 1f2e3d4c5b6a 3 days ago 421MB redis 7-alpine 9c8b7a6d5e4f 4 days ago 38MB逻辑说明superset-4.1.1-zh-cn-app.tar是整个离线部署的核心。它并非官方apache/superset镜像而是基于python:3.9-slim-bookworm从头构建COPY wheels/ /tmp/wheels/→pip install --find-links /tmp/wheels --no-index --no-deps -r requirements/base.txt→COPY frontend-build/ /app/superset/static/assets/→COPY locales/ /app/superset/translations/→RUN flask fab create-admin ...。这样做的好处是——所有依赖在构建时已固化运行时pip install彻底消失杜绝了离线环境下的任何网络请求。2.3 配置docker-compose.yml删掉所有build:只留image:官方 Superset 的docker-compose.yml大量使用build:指令这在离线环境是自杀行为。我们必须将其彻底重构为纯镜像引用模式并注入离线必需的环境变量。创建docker-compose.yml注意路径需与资源包解压路径一致version: 3.8 services: superset-app: image: superset-app:4.1.1-zh-cn container_name: superset-app restart: always environment: # 数据库连接指向 superset-db 容器 - SUPERSET_DATABASE_URIpostgresqlpsycopg2://superset:supersetsuperset-db:5432/superset # Redis 缓存指向 superset-cache 容器 - SUPERSET_CACHE_REDIS_URLredis://superset-cache:6379/1 # 关键强制中文界面禁用自动 locale 探测 - LANGzh_CN.UTF-8 - LC_ALLzh_CN.UTF-8 - SUPERSET_LANGUAGEzh # 禁用所有在线服务Google Analytics, Sentry, etc. - SUPERSET_ENABLE_FEATURES{alerting: false, email_notifications: false, sqllab: true} # 时区设为中国标准时间 - TZAsia/Shanghai volumes: # 挂载预置的汉化文件覆盖容器内默认 - ./locales:/app/superset/translations:ro # 挂载日志目录便于离线排查 - ./logs:/app/superset/logs:rw ports: - 8088:8088 depends_on: - superset-db - superset-cache networks: - superset-net superset-db: image: postgres:15-zh-cn container_name: superset-db restart: always environment: - POSTGRES_DBsuperset - POSTGRES_USERsuperset - POSTGRES_PASSWORDsuperset # 强制初始化时使用中文 locale - POSTGRES_INITDB_ARGS--lc-collatezh_CN.UTF-8 --lc-ctypezh_CN.UTF-8 volumes: - ./sql/init_postgres.sql:/docker-entrypoint-initdb.d/init.sql:ro - ./postgres-data:/var/lib/postgresql/data:rw networks: - superset-net superset-cache: image: redis:7-alpine container_name: superset-cache restart: always command: redis-server --appendonly yes volumes: - ./redis-data:/data:rw networks: - superset-net networks: superset-net: driver: bridge参数说明POSTGRES_INITDB_ARGS是离线中文支持的命门。它确保 PostgreSQL 初始化时创建的template1数据库即为zh_CN.UTF-8编码后续CREATE DATABASE superset才能继承该 locale。若此处遗漏superset-db容器日志会显示The files belonging to this database system will be owned by user postgres但superset-app启动时superset db upgrade会因编码不匹配报invalid byte sequence for encoding UTF8。3. 启动与初始化docker-compose up后的三分钟黄金排查期docker-compose up -d启动后不要立刻打开浏览器。Superset 4.1.1 的离线初始化有明确时序superset-db启动 → PostgreSQL 初始化完成 →superset-app启动 →superset db upgrade执行 →superset init创建管理员。这个过程约需 90 秒期间任何环节卡住都会导致最终失败。以下是必须盯紧的三个日志点3.1 检查superset-db是否真正就绪执行docker logs superset-db等待出现以下两行缺一不可... database system is ready to accept connections ... PostgreSQL init process complete; ready for start up.若长时间卡在creating directory /var/lib/postgresql/data ... ok说明init_postgres.sql未被执行。检查./sql/init_postgres.sql是否存在且权限为644并确认volumes路径映射正确./sql/init_postgres.sql:/docker-entrypoint-initdb.d/init.sql中的init.sql必须小写PostgreSQL 初始化脚本只识别.sql后缀且不区分大小写但路径错误会导致忽略。3.2 等待superset-app完成数据库迁移执行docker logs superset-app --follow观察关键日志流INFO:superset.utils.logging_configurator:logging was configured successfully INFO:superset.db_engine_specs:Database is alive, using engine spec: PostgreSQLEngineSpec INFO:superset.migrate:Applying DB migrations... INFO:alembic.runtime.migration:Context impl PostgresqlImpl. INFO:alembic.runtime.migration:Will assume transactional DDL. INFO:alembic.runtime.migration:Running upgrade - 1a185a12e2ff, add column to dashboard ... INFO:superset.migrate:DB migration successful若卡在Applying DB migrations...超过 2 分钟大概率是SUPERSET_DATABASE_URI连接串错误。此时执行docker exec -it superset-app bash进入容器手动测试连接# 容器内执行 apt-get update apt-get install -y postgresql-client # 离线环境需提前在镜像中装好 psql psql -h superset-db -U superset -d superset -c SELECT version();若报psql: error: connection to server at superset-db (172.20.0.2), port 5432 failed: Connection refused说明superset-db容器未完全就绪或depends_on未生效Docker Compose v3.8 的depends_on只检查容器启动不检查服务就绪需加健康检查见后文避坑。3.3 验证管理员账户是否创建成功当superset-app日志出现INFO:superset.cli:Creating admin user后紧接着应有INFO:superset.security.manager:Admin user admin created INFO:superset.cli:Syncing role definition INFO:superset.security.manager:Syncing Admin perms INFO:superset.cli:Syncing Alpha perms INFO:superset.cli:Syncing Gamma perms INFO:superset.cli:Syncing sql_lab perms INFO:superset.cli:Security sync completed若日志停在Creating admin user无后续说明flask fab create-admin命令被阻塞。原因通常是superset-db的superset数据库未创建成功init_postgres.sql执行失败或SUPERSET_DATABASE_URI中密码错误superset-db的POSTGRES_PASSWORD与连接串中不一致。提示若初始化失败不要docker-compose down up重来因为superset-db的./postgres-data目录已存在PostgreSQL 不会重复执行init.sql。此时需先docker-compose down -v-v删除卷再rm -rf ./postgres-data ./redis-data最后docker-compose up -d。4. 常见问题与避坑指南那些让你重启三次还找不到原因的玄学错误离线部署 Superset 4.1.180% 的时间花在解决“看似正常却无法访问”的问题上。以下是我在某跨平台数据分析项目中记录的真实踩坑案例按现象、原因、解决三步法整理拒绝模糊描述4.1 现象浏览器打开http://localhost:8088显示502 Bad Gatewaysuperset-app日志无报错原因Nginx或 Traefik反向代理配置错误但本离线部署未启用 Nginx真实原因是superset-app容器内gunicorn进程未监听0.0.0.0:8088而是默认绑定127.0.0.1:8088导致宿主机无法通过localhost访问。解决修改docker-compose.yml中superset-app的command强制绑定所有接口superset-app: # ... 其他配置 command: gunicorn --bind 0.0.0.0:8088 --workers 4 --timeout 120 --max-requests 1000 --access-logfile - --error-logfile - superset.app:create_app()血泪经验Superset 4.1.1 的Dockerfile中CMD默认是[gunicorn, --bind, 127.0.0.1:8088, ...]离线镜像已固化此命令。command覆盖是唯一解且--bind 0.0.0.0:8088中的0.0.0.0不能写成*或省略。4.2 现象登录页显示英文但控制台 Network 面板能看到zh.json加载成功原因SUPERSET_LANGUAGEzh环境变量生效但superset-app容器内/app/superset/translations/zh_CN/LC_MESSAGES/messages.mo文件损坏或未编译。离线镜像中的.mo文件若用旧版msgfmt编译如 Ubuntu 18.04 的 gettext 0.19.8在 Python 3.9 下gettext.translation会静默失败回退到英文。解决进入容器手动验证.mo文件docker exec -it superset-app bash # 检查文件是否存在且非空 ls -lh /app/superset/translations/zh_CN/LC_MESSAGES/messages.mo # 测试 Python 加载 python3 -c import gettext; t gettext.translation(superset, localedir/app/superset/translations, languages[zh_CN]); print(t.gettext(Dashboard))若输出Dashboard非仪表板说明.mo无效。此时需用msgfmt2.21bookworm 自带重新编译# 容器内执行需提前在镜像中安装 gettext msgfmt -o /app/superset/translations/zh_CN/LC_MESSAGES/messages.mo /app/superset/translations/zh_CN/LC_MESSAGES/messages.po后悔药离线资源包中的locales/目录已包含用msgfmt 2.21编译好的messages.mo若发现失效请确认docker-compose.yml中volumes是否正确挂载./locales:/app/superset/translations且宿主机./locales目录权限为755。4.3 现象SQL Lab 执行查询返回ArrowTypeError: Expected bytes, got a str object原因pyarrow版本与pandas不兼容。Superset 4.1.1 要求pyarrow10.0.1,13.0.0但离线 wheel 中若混入pyarrow-14.0.0常见于开发者本地误打包其Table.to_pandas()返回的bytes列在pandas 1.5.3下解析异常。解决检查容器内实际安装的pyarrow版本docker exec -it superset-app pip show pyarrow若版本高于12.0.1需强制降级。由于离线环境无法pip install必须重建superset-app镜像# 在离线资源包的 Dockerfile 中将 wheel 安装行改为 COPY wheels/pyarrow-12.0.1-cp39-cp39-manylinux_2_28_x86_64.whl /tmp/ RUN pip install --find-links /tmp --no-index --no-deps pyarrow12.0.1注意pyarrow-12.0.1是 Superset 4.1.1 经 CI 验证的最高兼容版本。12.0.1之后的版本引入了 Arrow 13 的新特性与 Superset 的sql_lab.py中df.to_dict(orientrecords)调用冲突。4.4 现象docker-compose up后superset-db容器反复重启日志显示FATAL: database files are incompatible with server原因./postgres-data目录残留了旧版 PostgreSQL如 14.x的数据文件而离线镜像postgres:15-zh-cn是 PostgreSQL 15主版本不兼容。解决彻底删除数据卷docker-compose down -v rm -rf ./postgres-data # 确保目录为空后再启动 docker-compose up -d关键提醒docker-compose down不删除卷-v参数是必须的。很多教程省略此步导致开发者以为镜像有问题实则是数据卷污染。4.5 现象宿主机docker --version显示20.10.0但docker-compose up报错ERROR: for superset-app Cannot create container for service superset-app: invalid mount config for type bind: bind source path does not exist原因docker-composeCLI 版本过低 1.29.0不支持v3.8的volumes语法。docker --version查的是 Docker Engine而docker-compose --version查的是 Compose CLI二者独立升级。解决离线升级docker-compose# 下载离线二进制需提前从 https://github.com/docker/compose/releases 下载 docker-compose-linux-x86_64 chmod x docker-compose-linux-x86_64 sudo mv docker-compose-linux-x86_64 /usr/local/bin/docker-compose docker-compose --version # 验证 1.29.0玄学提示某些 Linux 发行版如 CentOS 7的which docker-compose可能指向/usr/bin/docker-compose旧版而/usr/local/bin/在 PATH 前置位。执行sudo ln -sf /usr/local/bin/docker-compose /usr/bin/docker-compose确保调用新版。5. 验证与调试从登录页到 SQL Lab 的全链路跑通检查部署成功的终极验证不是看到登录页而是完成一次端到端的数据分析闭环登录 → 创建数据库连接 → 执行 SQL 查询 → 可视化图表。这个过程暴露所有隐藏依赖也是我每次交付前必走的 checklist。5.1 第一层验证HTTP 服务与基础功能打开浏览器访问http://localhost:8088应看到纯中文登录页标题为“Apache Superset”输入框提示“用户名”、“密码”。若仍是英文立即检查docker-compose.yml中superset-app的environment是否包含SUPERSET_LANGUAGEzh和LANGzh_CN.UTF-8宿主机locale -a | grep zh_CN是否有输出docker exec superset-app locale输出是否为LANGzh_CN.UTF-8若为POSIX说明环境变量未注入输入默认管理员账号admin/admin登录。成功后首页顶部导航栏应为“仪表板”、“数据集”、“SQL 实验室”等中文而非 “Dashboards”、“Datasets”。右上角用户头像点击后“个人资料”、“退出登录”均为中文。提示若导航栏部分中文部分英文如“SQL 实验室”正确但“管理”仍是“Admin”说明messages-js.json未生效。检查docker-compose.yml中volumes是否挂载了./locales:/app/superset/translations并确认./locales/zh_CN/LC_MESSAGES/messages-js.json文件存在且格式正确JSON 无语法错误。5.2 第二层验证数据库连接与元数据同步进入“数据集” → “数据库”点击右上角“ 数据库”。填写数据库名称example_dbSQLAlchemy URIsqlite:///examples/sample_data.dbSuperset 4.1.1 离线镜像已内置此示例 SQLite 文件其他选项保持默认点击“测试连接”应显示绿色“连接成功”。若报错No module named sqlite3说明 Python 的_sqlite3模块未编译进离线镜像——这是python:3.9-slim-bookworm的已知问题slim 镜像默认不装libsqlite3-dev。解决方法在构建superset-app镜像时Dockerfile 中添加RUN apt-get update apt-get install -y libsqlite3-dev rm -rf /var/lib/apt/lists/*注意此步骤必须在pip install之前执行否则pysqlite3编译失败。连接成功后点击“保存”再点击“提取元数据”。等待几秒页面应列出birth_names、wb_health_population等示例表。若列表为空检查superset-app日志是否有WARNING:superset.connectors.sqla.models:Failed to fetch table metadata这通常意味着sample_data.db文件权限为只读chmod 644 examples/sample_data.db可修复。5.3 第三层验证SQL Lab 执行与可视化进入“SQL 实验室”选择刚创建的example_db在编辑器中输入SELECT gender, SUM(num) as total FROM birth_names WHERE state CA GROUP BY gender;点击“运行”。预期结果表格显示F和M两行total列为数字。若报错No module named pyarrow说明pyarrowwheel 未正确安装见 4.3 节若返回空结果检查birth_names表是否真的有state CA的数据可先运行SELECT * FROM birth_names LIMIT 5;确认表结构。执行成功后点击右上角“可视化”选择“饼图”Slice Name填CA Gender RatioMetric选SUM(total)Group by选gender。点击“保存并转到仪表板”应跳转至新仪表板页且饼图正确渲染。5.4 终极验证离线环境下的故障自愈能力真正的离线部署必须经得起服务中断考验。模拟一次生产事故docker stop superset-app停止应用docker stop superset-cache停止 Redisdocker start superset-cache先启缓存docker start superset-app再启应用观察superset-app日志应看到INFO:superset.cache.manager:Redis cache is available INFO:superset.db_engine_specs:Database is alive... INFO:superset.migrate:DB migration skipped (already up to date)然后访问http://localhost:8088登录后所有仪表板、SQL Lab 历史记录、用户偏好均完好无损。这证明superset-db的持久化卷和superset-cache的appendonly yes配置生效离线环境具备容灾能力。从那以后我每次交付离线 BI 平台都强制走一遍这个四层验证登录页中文 → SQLite 连接 → SQL Lab 查询 → 饼图可视化 → 故障重启。少一个环节客户现场就可能多一个深夜电话。Superset 4.1.1 的离线部署没有银弹只有把每个docker load、每个volumes挂载、每个environment变量都当成生产级配置去抠细节。希望帮到你。本文还有配套的精品资源点击获取