简介：面向需要在 Windows 环境部署 Superset 的数据分析初学者、BI 实施人员及运维人员，这份文档围绕 Airbnb 开源的数据分析与可视化平台展开，帮助读者完成本地安装、初始化与中文界面配置，降低上手自助分析和仪表盘搭建的门槛。压缩包仅含 1 个 docx 文档，大小约 16KB，以步骤说明和命令示例为主，便于按顺序查阅。已有 1478 人学习，说明其在同类安装资料中具有一定参考价值。内容覆盖前置依赖准备、Superset 安装、管理员账户创建、数据库升级、示例数据加载、角色权限初始化及服务启动，并整理汉化目录创建、语言包放置、config.py 参数调整和重启验证等关键环节；同时结合 Superset 支持多种关系型数据库与大数据框架的特点，读者可据此搭建可查询、可可视化、可做权限控制的分析环境，并掌握常见配置与排错思路。

1. Windows 下装 Superset：先别急着敲 pip，Python 版本选错后面全是白工

有人在 Windows 上敲下pip install superset，日志滚了两百多行，最后红字停在Microsoft Visual C++ 14.0 is required，回头一查，装的 Python 是 3.8 以上。这类翻车我见过不止一次。Superset 这套 BI 平台在 Linux 上一路顺畅，搬到 Windows 上，编译工具链、脚本入口、翻译文件路径三处都得单独照顾。这套 Windows 环境搭建流程记一遍：先把 Python 和虚拟环境钉死，再装包、建管理员、初始化库、起服务，最后补汉化和排错。适合第一次在 Windows 机器上装 Superset 的开发者，也适合装到一半卡在红字里、想找后悔药的人。

2. 环境准备：Python 3.6 与 virtualenv，这两步省了后面全补回来

装 Superset 之前的准备工作，比装 Superset 本身更决定成败。原文给的操作命令是fabmanager create-admin、python superset runserver -d这一套，属于 0.x 时代的入口，配套的 Python 是 3.6 那条线。现在直接拿一台新机器、新 Python 去套，十有八九在编译依赖这一步就断了。这一章把解释器、虚拟环境、编译工具三件事按顺序落下来，后面第 3 章的每一条命令才有执行的前提。

2.1 解释器选型：3.6 的 64 位版本最省事

为什么死磕 3.6 而不是更新的版本？Superset 依赖链里躺着 pandas、numpy、cryptography 这几个包，它们带 C 扩展。3.6 这个版本线上，PyPI 上预编译好的 wheel 覆盖得最全，pip install大多数时候只是下载解压，不触发本地编译。换到 3.7，部分包就得现编译；换到 3.8 及以上，老版本 Superset 依赖的若干包根本没有对应轮子，直接装不上。

还有一处容易忽略：一定装 64 位。32 位 Python 的地址空间有限，加载 pandas 那种大包时内存先崩，而报错信息往往指向别处，排查起来很折磨人。安装时记得勾上Add Python to PATH，不然后面python命令根本找不到。机器上已经有多版本共存的话，先py -0列一下，确认默认指向的是哪个。

2.2 建虚拟环境：不要往系统 Python 里灌

Superset 的依赖又多又杂，Flask、Flask-AppBuilder、SQLAlchemy、Celery 一大串，版本要求还卡得紧。直接装进系统 Python，一旦某个包版本被顶掉，整台机器上其他 Python 项目跟着遭殃。虚拟环境必须建，用 virtualenv 而不是标准库的 venv——3.6 自带的 venv 在某些 Windows 补丁版本上 pip 引导会失败，virtualenv 更稳。

:: 先把打包三件套升级到较新版本，老 setuptools 识别不了新的 wheel 标签 python -m pip install --upgrade pip setuptools wheel :: 安装 virtualenv python -m pip install virtualenv :: 在 D 盘根目录建环境，-p 指定用哪个解释器，这一步决定环境里的 Python 版本 cd /d D:\ virtualenv superset_env -p C:\Python36\python.exe :: 激活环境，路径按实际安装位置替换 D:\superset_env\Scripts\activate.bat

-p这个参数是关键，多版本机器上它明确告诉 virtualenv 拿哪个解释器当底座，不写的话会用 PATH 里第一个python，很可能就是那个装不上的高版本。激活成功的标志是命令行提示符前面多出(superset_env)，此时where python应该指向D:\superset_env\Scripts\python.exe，where pip同理。这两个路径没对上，后面所有安装都会落到错误的位置，装完找不到命令就是这么来的。

2.3 编译工具兜底：Visual C++ Build Tools 与本地 wheel 目录

即使选了 3.6，也难免碰到一两个包没有现成轮子，此时 pip 会尝试本地编译，Windows 上默认没有编译器，报错信息就是那串Microsoft Visual C++ 14.0 is required。常见做法是装 Visual C++ Build Tools 2015（或者 Visual Studio 2015 社区版，安装时勾选 C++ 相关组件），装完重启命令行，让环境变量生效。

:: 验证编译器是否已进入 PATH，能输出路径就说明可用 where cl :: 如果公司网络拿不到外网 wheel，可以把离线包放进本地目录统一安装 pip install superset --find-links=D:\wheels --no-index

where cl找不到结果，说明编译工具没装好或者环境变量没刷新，别急着往下走。--find-links指向的目录里放提前下载好的.whl文件，--no-index表示完全不走网络，这两条组合适合内网环境。我一般还会把--default-timeout调大到 120，Windows 上 pip 拉大包时超时中断的频率比想象中高。

提示：装完编译工具后必须关掉当前命令行窗口重新开，环境变量不会在已打开的会话里刷新，这一点吃过亏。

3. 安装 Superset 本体：从 pip install 到能打开登录页的四个动作

准备工作到位后，真正装 Superset 的部分其实很短，但顺序一步都不能乱。pip install只负责把代码放进 site-packages，数据库表结构、管理员账号、角色权限、示例数据这四样都得单独初始化，少一步都会在登录页或者仪表盘上还账。这一章把四条命令和它们背后的逻辑逐条拆开。

3.1 pip install superset 与装完后的自检

在已激活的虚拟环境里执行安装。网络条件一般的话换国内镜像，速度快很多，也少掉几次超时重试。

:: 保持虚拟环境处于激活状态，(superset_env) 前缀在才算对 pip install superset :: 网络不稳时换镜像并延长超时，镜像地址替换成你所在网络能通的那个 pip install superset -i https://<你的镜像地址>/simple --default-timeout=120 :: 装完自检：确认包能导入、确认版本、确认命令行入口落在虚拟环境里 python -c "import superset; print(superset.__version__)" where superset

import superset报错说明包装到了别的地方，回到 2.2 检查where python。where superset应该输出D:\superset_env\Scripts\superset.exe，这个可执行脚本是superset命令能直接敲的前提。如果这一步为空，通常是Scripts目录没进 PATH，激活虚拟环境本身会临时把它加进去，所以先确认激活了没有。

依赖层面还有一类隐性冲突：pip 不会告诉你 Flask、Werkzeug、itsdangerous 之间的版本互相不兼容，装的时候一切正常，跑起来才炸。装完立刻用一次pip check扫一遍，能提前暴露大部分版本矛盾。

:: 检查已安装包之间的版本依赖是否自洽 pip check

输出里出现has requirement ... but you have ...就是冲突，按提示把报冲突的包钉到它要求的版本上。这一步花两分钟，能省掉后面一个小时对着AttributeError猜谜。

3.2 创建管理员账号：fabmanager 与 superset fab 的分水岭

管理员账号必须在数据库初始化之前建，否则登录页进得去、登不进来。原文给的命令是fabmanager create-admin --app superset，这条命令来自 Flask-AppBuilder，Superset 只是把--app superset传进去。

:: 老版本（0.x 时代）的写法 fabmanager create-admin --app superset

执行后会连续问六个问题：用户名、名、姓、邮箱、密码、确认密码。密码不能为空，太短会被要求重输，直接一次输对省事。邮箱随便填一个符合格式的即可，本地环境不会真的发信。

到了 1.x 之后，这条入口换成了 Superset 自己的 CLI：

:: 1.x / 2.x 起的写法，功能等价 superset fab create-admin

判断该用哪条很简单：fabmanager报「不是内部或外部命令」，就换superset fab create-admin；反过来superset fab报未知子命令，说明装的是老版本，用回 fabmanager。两条命令的提示语不完全一样，但填的内容一致。

3.3 数据库初始化：db upgrade、load_examples、init 的固定顺序

这是整个安装里最容易出错的一段，原因全在「目录」两个字上。原文特别注明要先进入 Python 安装目录（或虚拟环境目录）下的libs\site-packages\superset\bin，不是随口一说——那个 bin 目录里躺着一个没有扩展名的superset脚本文件，Windows 上的python命令靠相对路径才能找到它。

:: 进入虚拟环境内的包目录，路径按你的环境实际位置替换 cd /d D:\superset_env\Lib\site-packages\superset\bin :: 第一步：建表 / 升级表结构 python superset db upgrade :: 第二步：加载示例数据集，可选，但第一次装建议跑一遍 python superset load_examples :: 第三步：初始化角色和权限 python superset init

db upgrade干的事是按迁移脚本把 SQLite 里的表建出来。默认数据库文件落在当前用户目录下的.superset\superset.db，不在项目目录里，很多人装完去安装目录找库文件找不到就是这个原因。想看文件在哪，执行dir %USERPROFILE%\.superset就能看到。

load_examples会下载一批示例数据集并灌进库，用于开箱就有一张能画的图。这一步依赖网络，慢或者失败都不影响主流程，跳过它照样能登录、能连自己的库。

init写的是角色权限表，Admin、Alpha、Gamma、Public 这几个角色和对应的权限项都在这一步落库。顺序不能换：先init后db upgrade，权限表还不存在，直接报no such table。这也是新手最常踩的一个顺序坑。

注意：三条命令都在 bin 目录下执行，中途切走目录再回来，python superset会报can't open file，报错信息看着像包坏了，其实只是路径不对。

3.4 起服务与端口：runserver -d 与 -p 的取舍

最后一步把服务拉起来。

:: -d 开启调试模式，代码改动自动重载；-p 指定端口，默认 8088 python superset runserver -d -p 8088

-d适合边装边调，改配置不用反复重启；但它会输出大量调试日志，正式演示时去掉这个参数，日志干净很多。-p后面跟端口号，8088 被别的服务占了就换 8089 之类，改完记得浏览器地址跟着改。启动成功的标志是控制台打印出监听地址，此时打开浏览器访问http://localhost:8088，应该能看到登录页。

到了 1.0 之后，runserver子命令被移除，换成了run，参数形式也变了：

:: 新版本的启动方式，-h 指定监听地址，-p 指定端口 superset run -h 0.0.0.0 -p 8088

-h 0.0.0.0表示允许局域网内其他机器访问，只在本机用的话127.0.0.1更安全。用哪条取决于装的是哪个版本，报「no such command」就换另一条。

4. 汉化配置：translations 目录、mo 文件与 config.py 的三处改动

界面全英文不影响功能，但交付给业务同事看的时候，菜单上那串英文够解释半天。汉化这事说穿了就三件事：翻译文件放对位置、配置指向这个位置、服务重启加载。原文写得很细，但里面有两处容易照抄出问题的地方，这里一并标出来。

4.1 建目录：cmd 的 md 与 PowerShell 的 mkdir 别混用

翻译文件要放在包目录下的translations\zh\LC_MESSAGES里，三级目录得一层层建。

:: 进入 superset 包目录，注意这里是包根目录，不是 bin cd /d D:\superset_env\Lib\site-packages\superset :: 一级一级建，cmd 下用 md md translations cd translations md zh cd zh md LC_MESSAGES

md是 cmd 的内置命令，在 PowerShell 里虽然也能用（它是 mkdir 的别名），但参数行为略有差异，混着敲容易出现建到别处的情况。建完用dir /s /b看一眼完整路径，确认是...\superset\translations\zh\LC_MESSAGES，中间少一层，翻译就不会生效。目录已存在时md会提示「子目录或文件已存在」，无害，继续往下走。

4.2 mo 文件从哪来：直接下与自己编译两条路

LC_MESSAGES目录里要放的是messages.mo，这是 gettext 编译后的二进制翻译文件，程序运行时读的就是它。官方仓库的superset/translations/zh/LC_MESSAGES路径下同时提供messages.mo和messages.po，前者直接下下来扔进目录即可，后者是文本格式的翻译源文件。

想自己改词条就走 po 这条路：编辑messages.po，改完编译成 mo。

:: 把 po 编译成 mo，msgfmt 来自 gettext 工具包 msgfmt messages.po -o messages.mo

Windows 默认没有msgfmt，需要单独装一份 gettext for Windows，装完把它的bin目录加进 PATH，再回命令行执行。编译时如果报format specification '%s' mismatch，说明某条翻译里的占位符数量和原文对不上，改回去重新编译，硬编出来的 mo 加载时会让整页报错。

:: 验证 mo 文件确实生成且非空 dir messages.mo

文件大小是 0 字节或者根本没生成，说明-o后面的输出路径写错了，多数是把当前目录搞混了。

4.3 config.py 的三处改动与一个容易抄错的值

配置文件在site-packages\superset\config.py，直接编辑它。较新的版本推荐在外部另建superset_config.py并用环境变量SUPERSET_CONFIG_PATH指过去，避免升级时被覆盖，但老版本直接改包内的这份最省事。

# 默认语言切到中文，用户首次访问就是中文界面 BABEL_DEFAULT_LOCALE = 'zh' # 翻译文件所在目录，相对于 superset 包根目录 BABEL_DEFAULT_FOLDER = 'superset/translations' # 语言切换器里保留英文，出问题时能一键退回英文界面 LANGUAGES = { 'en': {'flag': 'us', 'name': 'English'}, 'zh': {'flag': 'cn', 'name': 'Chinese'}, }

三处的作用各不相同：BABEL_DEFAULT_LOCALE决定没登录时的默认语言，BABEL_DEFAULT_FOLDER决定去哪找 mo 文件，LANGUAGES决定右上角语言下拉里出现哪些选项。原文给的BABEL_DEFAULT_FOLDER值是'babel/translations'，如果重启后界面还是英文，把这个值改成'superset/translations'再试一次，这是实际路径和配置值不一致导致的，属于照抄原文时会遇到的典型偏差。

LANGUAGES里别把en注释掉。只留中文看着清爽，一旦中文翻译出问题，连切回英文定位问题的入口都没了，自己把退路堵死。

4.4 重启与浏览器缓存：改完不生效先看这两处

config.py 的改动不会热加载，必须停服务重启。Ctrl+C 结束当前进程，重新执行启动命令，控制台看到服务正常监听再打开浏览器。

浏览器这边多半有缓存，直接刷新可能还是旧界面，用 Ctrl+F5 强刷一次。还是英文的话按顺序排查：config.py改的是不是当前虚拟环境里那份（多环境并存时最容易改错）、messages.mo是否真的在LC_MESSAGES目录里、BABEL_DEFAULT_FOLDER的值和实际路径是否对得上。这三处排完基本都能正常显示中文菜单。

5. 常见问题排查：五个把安装卡死的坑

下面这几条都是实际装的过程中反复出现的，按「现象 → 原因 → 解决」记，遇到时对着现象找，比从头翻日志快得多。

5.1 安装阶段的两个高频报错

现象一：pip install superset跑到一半红字报Microsoft Visual C++ 14.0 is required。

原因是某个依赖包在当前 Python 版本下没有预编译 wheel，pip 退回源码编译，而机器上没有 C++ 编译器。解决办法是装 Visual C++ Build Tools 2015 并勾选 C++ 组件，装完关掉命令行重开；或者换到 3.6 的 64 位解释器重建虚拟环境，让 pip 能直接下到现成轮子。两条路选一条即可，后者的成功率更高，代价是要重装一遍依赖。

现象二：fabmanager报「不是内部或外部命令，也不是可运行的程序」。

两种可能。一是虚拟环境没激活，Scripts目录不在 PATH 里；where fabmanager空结果就属于这种，重新执行activate.bat即可。二是装的 Superset 版本较新，已经不再注册 fabmanager 这个入口点，此时换成superset fab create-admin，功能完全等价。

5.2 初始化与服务阶段的三个坑

现象三：在任意目录执行python superset db upgrade，报can't open file 'superset': [Errno 2] No such file or directory。

原因是python superset这种写法依赖当前目录下存在名为superset的脚本文件，而那个文件只在包的bin目录里。解决方式是先cd /d <环境路径>\Lib\site-packages\superset\bin，再执行命令。更省事的替代写法是直接用Scripts目录里的可执行入口superset db upgrade，不依赖当前目录，效果一样。

现象四：服务起来了，浏览器打开localhost:8088一直转圈或者连接被拒。

先看控制台有没有真的打印出监听信息，进程启动失败的话浏览器当然连不上。控制台正常但访问不了，检查端口是不是被占用，netstat -ano | findstr :8088能查出占用进程的 PID；确认被占就换端口重启，-p 8089。还有一种情况是服务只绑了127.0.0.1，从别的机器访问当然不通，需要监听所有地址时用-h 0.0.0.0。

现象五：登录进去之后报AttributeError: module 'werkzeug' has no attribute 'cached_property'之类的一串错误。

根因是 pip 装依赖时装进了互相不兼容的版本，Werkzeug、itsdangerous、Flask 这几个包版本跨度大，新版本删掉的接口老代码还在调。解决方式是按报错里的模块名反查，把对应包降到 Superset 那个版本要求的区间；pip check会直接告诉你是哪个包的要求没被满足。装完第一步就做一次pip check，比事后救火轻松得多。

提示：所有依赖升降级都在虚拟环境里做，别在系统 Python 上折腾，一旦把系统环境的 Flask 版本改坏，恢复成本很高。

6. 装完怎么验证：从登录页到一条能跑通的 SQL 查询

服务起来、能看见登录页，只说明进程活着，不说明这套环境能干活。我习惯按三层验证，一层不过就不算装完。

第一层是账号和权限。用 3.2 建的管理员登录，右上角能看到用户名，左侧菜单里 Sources、Charts、Dashboards、SQL Lab 这几项都在。如果菜单缺项，说明superset init没跑或者跑失败了，权限表是空的，回 3.3 补一遍。

第二层是数据连接。SQL Lab 里应该能看到load_examples灌进去的示例数据库，点进去随便跑一条SELECT 1或者对示例表做一次COUNT(*)。这一步通了，说明 SQLAlchemy 驱动、数据库文件、连接配置整条链路都是活的。想接自己的 MySQL 或 PostgreSQL，就在 Sources → Databases 里新增连接串，格式是mysql://user:pass@host:3306/dbname，前提是对应驱动已经pip install进这个虚拟环境。

第三层是出图。拿刚才的查询结果点 Create Chart，选个表格或柱状图，保存后加进一张 Dashboard，再点导出 CSV。走完这一圈，才算这套 Windows 环境真的能交付。

顺手记一条命令备查，出问题时报版本比描述现象有用得多：

:: 确认当前虚拟环境里的 Superset 版本与依赖清单 python -c "import superset; print(superset.__version__)" pip list | findstr -i "flask sqlalchemy werkzeug"

版本号和报错信息一起贴出来，定位问题的速度完全不一样。

从那以后我每次装完 Superset，都先把 SQL Lab 跑通一条查询再往下交付，光能登录不算装完。汉化不生效、示例数据没加载、端口改了没记住，这些小毛病最后都是靠这一圈验证暴露出来的。希望帮到你。

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