企业官网建设流程全解析

简介：《superset在Windows下安装说明》面向需要在Windows环境搭建开源BI平台SuperSet的开发者与数据分析人员，聚焦安装配置与界面汉化两个核心问题，适合具备Python基础、希望快速完成本地部署的初中级用户参考。资源包仅含1个docx文档，压缩包约16KB，体量轻便，便于离线查阅和随装随看。目前已有1475人学习下载，说明其在SuperSet Windows部署场景中具有一定参考价值。文档围绕环境准备、依赖与管理账户、数据库初始化、示例数据与权限初始化、服务启动和浏览器访问等环节展开，并补充汉化目录创建、语言包放置及config.py语言配置等要点，可帮助读者理清安装顺序、减少配置遗漏，并作为排查部署问题的对照材料。

1. SuperSet 在 Windows 下安装：先分清 fabmanager 和 superset 两套命令

第一次在 Windows 机器上装 SuperSet，我照着一份流传很广的笔记往下敲，前面pip install superset顺利得像什么都没装，到第五步fabmanager create-admin --app superset，命令行直接回我一句「不是内部或外部命令」。当时第一反应是命令敲错了，反复核对了三遍拼写才反应过来，是版本对不上——笔记记的是 SuperSet 0.x 时期的写法，而我 pip 装到的是把 fabmanager 收进superset fab子命令之后的版本。Windows 上装这套 BI 平台的翻车点几乎都集中在三处：Python 解释器选错、命令的代际差异、以及那个必须在Lib\site-packages\superset\bin目录下才能跑起来的初始化。这篇就把这套环境从头走一遍，装什么、按什么顺序、坏了看哪里，都落到具体命令上。写给要在 Windows 本机或测试机上把 SuperSet 跑起来做看板的人。

2. 装前把环境钉死：Python 3.x、pip、编译工具三件套

Windows 装 SuperSet 最容易犯的错，是把「装 Python」当成「装完 Python 就行」。这套东西背后拖着 Flask、SQLAlchemy、pandas、cryptography 一串包，其中好几个带 C 扩展，pip 一旦找不到预编译 wheel，就会退化成源码编译，然后在你面前堆几百行红色报错。前置项没钉死，后面每一步都是玄学。

2.1 Python 版本与虚拟环境：别用系统里那个装了一堆东西的解释器

我一般不会用系统全局那个 Python。原因很实在：你机器上可能已经装着别的项目依赖，pip install superset会把它依赖的 Flask、SQLAlchemy 版本一起拽动，装完 SuperSet 跑起来了，别的项目挂了。用虚拟环境隔离，出问题直接删目录重来，这是最便宜的后悔药。

Windows 上创建虚拟环境，官方启动器py比裸python靠谱，因为它能明确指定大版本：

# 用 py 启动器指定 3.x 建虚拟环境，路径不要带空格和中文 py -3 -m venv C:\superset-venv # 激活，激活后命令行前面会出现 (superset-venv) C:\superset-venv\Scripts\activate # 确认当前用的是虚拟环境里的解释器，不是系统那个 where python python -V

where python这一句是关键。正常情况下第一条输出应该是C:\superset-venv\Scripts\python.exe，如果第一条指向的是C:\Program Files\PythonXX\python.exe，说明激活没生效，后面所有安装都会装到全局去。激活失败最常见的原因是用了 PowerShell 但没执行策略权限，换个 cmd 窗口重来就行，不用去改系统策略。

路径这条我要单独说：不要把虚拟环境建在Program Files、桌面、或者任何含中文的目录下。SuperSet 的静态资源路径、模板路径都是拼出来的字符串，遇到空格和中文会在某个你意想不到的环节炸掉，报错信息还跟路径毫无关系。放在C:\superset-venv这种干净路径下，能省掉一半排查时间。

版本选择上，别闭眼装最新的大版本。SuperSet 0.x 这条线对 Python 3.6 上下的兼容性最好，新版本对 Python 版本的下限要求会跟着走。判断方法很简单：装完之后如果pip check一堆冲突，或者 import 就报语法错误，那就是版本选高了，退回一个小版本重来，比在原地修依赖快得多。

2.2 编译依赖与 pip 源：Windows 上最容易被跳过的一步

先把 pip 自身升上去，老版本 pip 对 wheel 的识别能力差，明明有预编译包也会去下源码包：

# 三个基础工具先升到最新，顺序别反 python -m pip install --upgrade pip setuptools wheel # 配一个下载快的源，公司内网就填内网源地址 pip config set global.index-url https://<你的镜像源>/simple pip config set global.trusted-host <你的镜像源域名> # 看看配置落到哪个文件了，出问题好回滚 pip config list

pip config set会把配置写进用户目录下的 pip.ini，这是持久化的，比每次命令行加-i参数省事。trusted-host这一项在部分内网源上是必须的，不加会报 SSL 证书校验失败——这个报错看起来像网络问题，实际是证书问题，很容易往错误方向排查。

然后是编译工具。Windows 上最经典的一道墙是这个报错：

error: Microsoft Visual C++ 14.0 or greater is required.

看到它就说明 pip 在给某个包做源码编译，而机器上没有 C++ 构建工具。两条路：一是装 Visual C++ Build Tools，勾选「使用 C++ 的桌面开发」那一套；二是绕开编译，强制只用预编译包：

# 强制只装 wheel，装不上就直接报错，不会退化成源码编译 pip install --only-binary :all: superset # 或者单独给某个难缠的包指定版本，先装好再装主体 pip install --only-binary :all: cryptography pandas

--only-binary :all:的意义在于把问题提前暴露。默认行为是「编译失败才报错」，你会在滚了几百行日志之后才看到真正的错误；加上这个参数，缺 wheel 的包一秒就报出来，你能立刻判断是换源还是装编译器。我一般先用它试一次，装不动再回头补 Build Tools。

2.3 数据库驱动：先跑通 sqlite，再谈 mysql、oracle

SuperSet 自己需要一套元数据库来存用户、权限、看板定义、图表配置，默认用 sqlite 文件，开箱即用。但它的价值在于连你的业务库——MySQL、Oracle、PostgreSQL、Presto、Impala、SparkSQL、Greenplum、MSSQL 这些都在支持列表里。

我的建议是分两步：第一次装，先用默认 sqlite 把服务跑起来，确认登录页能打开、示例数据能加载；跑通之后再换元数据库、再装业务库驱动。一次性把驱动全装上，出问题时你分不清是 SuperSet 装坏了还是驱动版本不对。

业务库驱动按需装，注意区分驱动包名和连接串前缀：

# MySQL：pymysql 是纯 Python 实现，不需要编译，Windows 上最省事 pip install pymysql # 连接串写成 mysql+pymysql://user:pass@host:3306/dbname # PostgreSQL pip install psycopg2-binary # MSSQL pip install pymssql

pymysql这类纯 Python 驱动在 Windows 上几乎是零成本，优先选它。mysqlclient性能更好但要编译，没有 Build Tools 时不要碰。驱动装完不是立刻生效的，要在 SuperSet 的「数据库」页面新增连接时填对 SQLAlchemy URI，前缀写错会报No module named xxx，看着像没装，其实是连接串里的驱动名和包名对不上。

3. 安装 SuperSet 本体：pip install superset 之后的四步初始化

前置项齐了，主体安装其实只有一行命令，真正耗时的是后面四步初始化。这四步顺序错了、目录错了，表现出来都是「服务起不来」，但原因完全不同。

3.1 一条 pip 命令装了什么，装完先确认版本代际

# 装主体，网络不稳就加超时和重试 pip install superset --timeout 120 --retries 5 # 装完先看版本和安装位置，两个信息决定了后面用哪套命令 pip show superset

pip show输出的Version和Location要记住。Location就是包的实际落盘位置，后面db upgrade、汉化目录都要基于它来拼路径。很多人后面找不到bin目录，就是因为没看这一行，凭感觉去虚拟环境根目录下翻。

然后确认命令代际，这是决定后面所有操作的分水岭：

# 老版本（0.x 线）由 Flask-AppBuilder 提供管理命令 fabmanager --help # 新版本把管理命令收进了 superset 自己的子命令里 superset fab --help

两条命令哪条有输出，就走哪条路。原文笔记里全部用的是fabmanager，说明它对应的是 0.x 那套。如果你的环境里fabmanager不存在而superset fab在，那不是装坏了，是版本新了，把后面所有fabmanager xxx换成superset fab xxx即可。这个差异是 Windows 上新手最容易被劝退的地方，命令报「不是内部或外部命令」时，先想版本，别急着重装。

3.2 创建管理员账号：create-admin 的交互项怎么填

# 老版本写法 fabmanager create-admin --app superset # 新版本等价写法 superset fab create-admin

执行后会连续问你六项：用户名、名、姓、邮箱、密码、确认密码。这里有两个坑。

第一，密码有强度要求，太短或者纯数字会被拒，报错信息不长，容易以为是程序崩了。第二，邮箱虽然是必填，但不做真实性校验，随便填一个格式合法的就行，它只用于账号标识。

还有一个隐性问题：如果这一步报「no such table」或者直接抛数据库异常，说明元数据库的表还没建，得先把下一步的db upgrade提前跑一遍。原文的顺序是先 create-admin 再 db upgrade，在部分版本上能过，在部分版本上会卡住——遇到卡住，把顺序调过来就行，不是笔记写错了，是版本行为变了。

创建成功会打印一行类似Admin User xxx created.的提示。没看到这行就别往下走，后面登录会一直失败。

3.3 db upgrade：为什么一定要先进 bin 目录

这一步是 Windows 上最容易翻车的地方。Linux 下装完superset可执行文件直接进 PATH，敲superset db upgrade就行；Windows 下这个入口脚本不一定被加进 PATH，所以原文用了python superset db upgrade这种写法——让 Python 去执行bin目录下那个没有扩展名的superset脚本文件。

# 先切到包安装目录下的 bin，路径按 pip show 的 Location 拼 cd C:\superset-venv\Lib\site-packages\superset\bin # 确认目录里有 superset 这个文件 dir superset # 执行数据库升级 python superset db upgrade

路径这里有个细节要纠正：原文写的是libs\site-packages，Windows 上实际的目录名是Lib（大写 L，无 s），这是笔记里的笔误，照着libs找会一直提示路径不存在。用pip show superset输出的Location拼出来的路径最准。

db upgrade做的事是建表加版本迁移，它会创建用户表、切片表、看板表、日志表，还有一张 alembic 的版本表。执行过程中会刷一批Running upgrade ...的日志，只要最后没有 Traceback 就算成功。如果中途断了，重新执行一遍是安全的，它按版本号增量走，不会重复建表。

4. 初始化与汉化：load_examples、init 和中文语言包三件事

服务能起来不等于能用。这一步的三件事分别解决「有数据可看」「权限体系完整」「界面看得懂」，少一件体验都会打折。

4.1 load_examples 和 init：一个灌数据，一个建权限

# 仍然在 bin 目录下，加载官方示例数据 python superset load_examples # 初始化角色和权限 python superset init

load_examples会创建一批示例数据源、图表和看板，数据量不小，第一次跑几分钟很正常，中途没有任何输出也属于正常现象——别以为卡死了就去 Ctrl+C，中断之后可能留下半套数据，后面图表打开报错，只能删库重来。这一步的价值在于：装完之后你手里立刻有一批能点的图表，可以拿来验证「查询能不能跑通、图表能不能渲染」这条完整链路，比对着空界面自己造数据快得多。

init负责把权限点、默认角色（Admin、Alpha、Beta、Gamma、Public）和它们之间的映射关系写进元数据库。这一步如果跳过，用管理员账号登录后打开某些页面会报权限错误，看起来像 bug，其实是权限表是空的。init可以重复执行，不会产生重复数据。

顺序上我建议：db upgrade→create-admin→load_examples→init。原文把 create-admin 放在最前面，如果你的版本能过就按原文走；过不了就把db upgrade提到最前面，这是最稳的排列。

4.2 汉化目录：translations/zh/LC_MESSAGES 三层结构不能少一层

汉化不生效，九成是目录建错了位置。这三个目录必须在superset 包目录下，不是虚拟环境根目录，也不是项目目录：

# 切到 superset 包目录，注意是包目录不是虚拟环境根目录 cd C:\superset-venv\Lib\site-packages\superset # 逐层建目录，Windows 的 md 一次只能建一层 md translations cd translations md zh cd zh md LC_MESSAGES

建完的完整路径应该是C:\superset-venv\Lib\site-packages\superset\translations\zh\LC_MESSAGES。差一层，比如少了LC_MESSAGES，或者把translations建到了site-packages下面而不是superset下面，程序都找不到翻译文件，而且不会报错，只是界面继续显示英文——这种「静默失败」最难查。

接下来把messages.mo放进LC_MESSAGES目录。这个文件是编译好的二进制翻译包，从官方仓库的superset/translations/zh/LC_MESSAGES路径下取。如果你要自己改词条，就下messages.po，改完编译成 mo。

提示：messages.mo是二进制文件，不要用文本编辑器打开另存，保存一次文件就损坏了，表现为汉化全部失效。

4.3 config.py 三个配置项：改完必须重启才生效

配置文件在C:\superset-venv\Lib\site-packages\superset\config.py。改之前先复制一份config.py.bak，因为pip install --upgrade会把这个文件覆盖掉，你的汉化配置会一起没——我吃过这个亏，升级完界面又变回英文，一度以为是翻译包丢了。

# superset/config.py 中找到并修改这三处 # 默认语言设为中文 BABEL_DEFAULT_LOCALE = 'zh' # 翻译文件根目录，保持默认即可，不要改成绝对路径 BABEL_DEFAULT_FOLDER = 'babel/translations' # 语言列表，只留中文就把 en 那行注释掉 LANGUAGES = { # 'en': {'flag': 'us', 'name': 'English'}, 'zh': {'flag': 'cn', 'name': 'Chinese'}, }

三个参数的作用分别是：BABEL_DEFAULT_LOCALE决定没登录时登录页用什么语言；BABEL_DEFAULT_FOLDER是翻译文件的查找根，这个值是相对包目录的，改成绝对路径反而找不到；LANGUAGES控制右上角语言下拉里有几个选项。

把en注释掉的效果是语言下拉里只剩中文，用户没法切回英文。如果你的团队里有人习惯英文界面，就别注释，两个都留着。改完保存，回命令行Ctrl+C停掉服务，重新python superset runserver -d，然后关掉浏览器再重新打开——只刷新页面有时候拿的还是缓存的语言包。

自编译 mo 文件的话，需要机器上有 gettext 工具：

# 在 messages.po 所在目录执行，输出到同目录 msgfmt messages.po -o messages.mo

msgfmt不在 PATH 里会报「不是内部或外部命令」，装一个 Windows 版 gettext 就行。这条命令本身很少出错，出错基本是 po 文件里有语法错误，报错会带行号，按行号改。

5. 常见问题排查：8088 打不开、汉化不生效、初始化报错的对照表

装完到能用之间，平均要踩三到五个坑。这一章把最常见的几条按「现象 → 原因 → 解决」列出来，遇到了直接对照。

5.1 启动阶段：runserver -d 之后该看到什么才算成功

# 默认 8088 端口，-d 是 debug 模式 python superset runserver -d # 端口被占用时换一个 python superset runserver -d -p 8089

-d打开调试模式，好处是报错会直接显示在浏览器页面上，坏处是它会启动自动重载，日志里出现两次启动信息，看着像起了两个进程，其实是一个。端口参数-p要写在后面，顺序反了会被忽略。

判断是否真正启动成功，看最后几行有没有类似Running on http://0.0.0.0:8088的输出。有这行再去开浏览器；没有这行，浏览器里看到什么都是假的。另外这个窗口不能关，关了服务就停——要后台跑就得另想办法，别指望它自己常驻。

新版本把runserver换成了run，参数也变了，如果runserver报未知命令，换成superset run -p 8088 --with-threads试试。

5.2 五条踩坑记录：现象、原因、解决

第一条：fabmanager提示不是内部或外部命令。现象是敲完命令立刻报错，连 Python 都没启动。原因是装的 SuperSet 版本已经把管理命令收进superset fab子命令，或者Scripts目录没在 PATH 里。解决分两步：先where fabmanager确认文件在不在，在的话就是 PATH 问题，用完整路径调用；不在的话直接用superset fab create-admin替代，功能一样。

第二条：db upgrade报No module named superset或者找不到文件。现象是在任意目录下执行都报模块不存在，但pip show superset明明显示装了。原因是当前工作目录不对，python superset这种写法要求superset脚本文件就在当前目录下。解决是先cd到Lib\site-packages\superset\bin，dir确认文件存在，再执行。还有一个变种是路径里Lib写成了libs，照着笔记抄最容易中这个。

第三条：浏览器打开localhost:8088一片空白或者 404。现象是端口通了但页面出不来。三种原因：一是服务其实没起成功，回去看命令行有没有Running on那行；二是端口被别的程序占了，netstat -ano | findstr 8088查一下占用进程；三是用了https://前缀访问，本地服务是 http，浏览器自动补 https 就会失败，手动把地址改成http://localhost:8088。

第四条：汉化改了 config.py，界面还是英文。现象是配置项明明改了，重启也做了，界面纹丝不动。原因通常是三个：messages.mo放错目录（最常见是少了LC_MESSAGES这一层）、浏览器缓存了旧语言包、或者 pip 升级把 config.py 覆盖回去了。解决顺序是：先dir逐层确认 mo 文件路径，再清浏览器缓存或用无痕窗口打开，最后检查 config.py 里的三行还在不在。

第五条：load_examples跑了很久没反应，或者中途报错。现象是命令行停在那里十几分钟不动。原因是示例数据要建表、灌数据、生成图表定义，本身耗时；中途报错一般是元数据库被上一次中断污染了。解决是先等够十分钟再判断；真报错了就删掉 sqlite 元数据库文件（默认在用户目录下的.superset目录里），重新走一遍db upgrade和load_examples。这一步别硬修，重来更快。

6. 装完怎么验证：从登录页走到一张能出图的图表

服务起来只是第一步，真正的验收标准是「一条数据链路能走通」。我一般按下面这张表逐项过，全绿才算装完：

SQL Lab 那一步是关键，它是唯一能同时验证「元数据库正常」和「业务数据源可连」的动作。在示例库上跑一句最简单的：

-- 在 SQL Lab 里选示例数据源，跑一条聚合，验证查询和结果渲染链路 SELECT status, COUNT(*) AS cnt FROM main.flights GROUP BY status ORDER BY cnt DESC;

这条语句走通了，说明 SQLAlchemy 连接、查询执行、结果序列化、前端表格渲染四段都是通的。任何一段断了，报错都会停在这一步，比在图表页面报错好定位得多。

把这些都过完之后，我还会做一件事：把config.py的改动单独记一份到虚拟环境外面，再把messages.mo也复制一份出来。原因很单纯——升级一次 SuperSet 覆盖一次配置，重装一次丢一次翻译包，这两件事我都经历过，第二次开始就老实了。从那以后我每次装完 SuperSet，都会在虚拟环境同级的目录下放一个superset-keep文件夹，里面只放三样东西：改过的config.py、messages.mo、还有一份记录当前版本的说明。重装的时候三个文件一拷，五分钟恢复原样。希望帮到你。

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