简介面向需要在 Windows 环境部署 Superset 的数据分析初学者、BI 实施人员及运维人员这份文档围绕 Airbnb 开源的数据分析与可视化平台展开帮助读者完成本地安装、初始化与中文界面配置降低上手自助分析和仪表盘搭建的门槛。压缩包仅含 1 个 docx 文档大小约 16KB以步骤说明和命令示例为主便于按顺序查阅。已有 1478 人学习说明其在同类安装资料中具有一定参考价值。内容覆盖前置依赖准备、Superset 安装、管理员账户创建、数据库升级、示例数据加载、角色权限初始化及服务启动并整理汉化目录创建、语言包放置、config.py 参数调整和重启验证等关键环节同时结合 Superset 支持多种关系型数据库与大数据框架的特点读者可据此搭建可查询、可可视化、可做权限控制的分析环境并掌握常见配置与排错思路。1. Windows 下装 Superset先别急着敲 pipPython 版本选错后面全是白工有人在 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 依赖的若干包根本没有对应轮子直接装不上。Python 版本装老版本 Superset 的可行性说明2.7能装上但依赖普遍停止更新不建议在新环境里用3.6.x 64 位推荐主流依赖都有 cp36 预编译轮子编译量最小3.7.x勉强个别包缺轮子必须提前装好编译工具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.exewhere 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-linksD:\wheels --no-indexwhere cl找不到结果说明编译工具没装好或者环境变量没刷新别急着往下走。--find-links指向的目录里放提前下载好的.whl文件--no-index表示完全不走网络这两条组合适合内网环境。我一般还会把--default-timeout调大到 120Windows 上 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-timeout120 :: 装完自检确认包能导入、确认版本、确认命令行入口落在虚拟环境里 python -c import superset; print(superset.__version__) where supersetimport 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-AppBuilderSuperset 只是把--app superset传进去。:: 老版本0.x 时代的写法 fabmanager create-admin --app superset执行后会连续问六个问题用户名、名、姓、邮箱、密码、确认密码。密码不能为空太短会被要求重输直接一次输对省事。邮箱随便填一个符合格式的即可本地环境不会真的发信。到了 1.x 之后这条入口换成了 Superset 自己的 CLI:: 1.x / 2.x 起的写法功能等价 superset fab create-admin版本段建管理员命令备注0.xfabmanager create-admin --app superset依赖 Flask-AppBuilder 注册的入口点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 initdb upgrade干的事是按迁移脚本把 SQLite 里的表建出来。默认数据库文件落在当前用户目录下的.superset\superset.db不在项目目录里很多人装完去安装目录找库文件找不到就是这个原因。想看文件在哪执行dir %USERPROFILE%\.superset就能看到。load_examples会下载一批示例数据集并灌进库用于开箱就有一张能画的图。这一步依赖网络慢或者失败都不影响主流程跳过它照样能登录、能连自己的库。init写的是角色权限表Admin、Alpha、Gamma、Public 这几个角色和对应的权限项都在这一步落库。顺序不能换先init后db upgrade权限表还不存在直接报no such table。这也是新手最常踩的一个顺序坑。注意三条命令都在 bin 目录下执行中途切走目录再回来python superset会报cant 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_MESSAGESmd是 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 编译成 momsgfmt 来自 gettext 工具包 msgfmt messages.po -o messages.moWindows 默认没有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 的改动不会热加载必须停服务重启。CtrlC 结束当前进程重新执行启动命令控制台看到服务正常监听再打开浏览器。浏览器这边多半有缓存直接刷新可能还是旧界面用 CtrlF5 强刷一次。还是英文的话按顺序排查config.py改的是不是当前虚拟环境里那份多环境并存时最容易改错、messages.mo是否真的在LC_MESSAGES目录里、BABEL_DEFAULT_FOLDER的值和实际路径是否对得上。这三处排完基本都能正常显示中文菜单。5. 常见问题排查五个把安装卡死的坑下面这几条都是实际装的过程中反复出现的按「现象 → 原因 → 解决」记遇到时对着现象找比从头翻日志快得多。5.1 安装阶段的两个高频报错现象一pip install superset跑到一半红字报Microsoft Visual C 14.0 is required。原因是某个依赖包在当前 Python 版本下没有预编译 wheelpip 退回源码编译而机器上没有 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报cant 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:passhost:3306/dbname前提是对应驱动已经pip install进这个虚拟环境。第三层是出图。拿刚才的查询结果点 Create Chart选个表格或柱状图保存后加进一张 Dashboard再点导出 CSV。走完这一圈才算这套 Windows 环境真的能交付。验证项检查位置通过标准进程与端口命令行控制台打印监听地址浏览器能打开登录页管理员账号右上角用户菜单能登录菜单完整角色权限左侧导航Sources / Charts / Dashboards / SQL Lab 齐全数据库连接SQL Lab查询能返回结果无驱动报错出图与导出Chart / Dashboard图表能保存、仪表盘能展示、CSV 能下载汉化右上角语言切换中文菜单正常显示可切回英文顺手记一条命令备查出问题时报版本比描述现象有用得多:: 确认当前虚拟环境里的 Superset 版本与依赖清单 python -c import superset; print(superset.__version__) pip list | findstr -i flask sqlalchemy werkzeug版本号和报错信息一起贴出来定位问题的速度完全不一样。从那以后我每次装完 Superset都先把 SQL Lab 跑通一条查询再往下交付光能登录不算装完。汉化不生效、示例数据没加载、端口改了没记住这些小毛病最后都是靠这一圈验证暴露出来的。希望帮到你。本文还有配套的精品资源点击获取
简介面向需要在 Windows 环境部署 Superset 的数据分析初学者、BI 实施人员及运维人员这份文档围绕 Airbnb 开源的数据分析与可视化平台展开帮助读者完成本地安装、初始化与中文界面配置降低上手自助分析和仪表盘搭建的门槛。压缩包仅含 1 个 docx 文档大小约 16KB以步骤说明和命令示例为主便于按顺序查阅。已有 1478 人学习说明其在同类安装资料中具有一定参考价值。内容覆盖前置依赖准备、Superset 安装、管理员账户创建、数据库升级、示例数据加载、角色权限初始化及服务启动并整理汉化目录创建、语言包放置、config.py 参数调整和重启验证等关键环节同时结合 Superset 支持多种关系型数据库与大数据框架的特点读者可据此搭建可查询、可可视化、可做权限控制的分析环境并掌握常见配置与排错思路。1. Windows 下装 Superset先别急着敲 pipPython 版本选错后面全是白工有人在 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 依赖的若干包根本没有对应轮子直接装不上。Python 版本装老版本 Superset 的可行性说明2.7能装上但依赖普遍停止更新不建议在新环境里用3.6.x 64 位推荐主流依赖都有 cp36 预编译轮子编译量最小3.7.x勉强个别包缺轮子必须提前装好编译工具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.exewhere 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-linksD:\wheels --no-indexwhere cl找不到结果说明编译工具没装好或者环境变量没刷新别急着往下走。--find-links指向的目录里放提前下载好的.whl文件--no-index表示完全不走网络这两条组合适合内网环境。我一般还会把--default-timeout调大到 120Windows 上 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-timeout120 :: 装完自检确认包能导入、确认版本、确认命令行入口落在虚拟环境里 python -c import superset; print(superset.__version__) where supersetimport 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-AppBuilderSuperset 只是把--app superset传进去。:: 老版本0.x 时代的写法 fabmanager create-admin --app superset执行后会连续问六个问题用户名、名、姓、邮箱、密码、确认密码。密码不能为空太短会被要求重输直接一次输对省事。邮箱随便填一个符合格式的即可本地环境不会真的发信。到了 1.x 之后这条入口换成了 Superset 自己的 CLI:: 1.x / 2.x 起的写法功能等价 superset fab create-admin版本段建管理员命令备注0.xfabmanager create-admin --app superset依赖 Flask-AppBuilder 注册的入口点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 initdb upgrade干的事是按迁移脚本把 SQLite 里的表建出来。默认数据库文件落在当前用户目录下的.superset\superset.db不在项目目录里很多人装完去安装目录找库文件找不到就是这个原因。想看文件在哪执行dir %USERPROFILE%\.superset就能看到。load_examples会下载一批示例数据集并灌进库用于开箱就有一张能画的图。这一步依赖网络慢或者失败都不影响主流程跳过它照样能登录、能连自己的库。init写的是角色权限表Admin、Alpha、Gamma、Public 这几个角色和对应的权限项都在这一步落库。顺序不能换先init后db upgrade权限表还不存在直接报no such table。这也是新手最常踩的一个顺序坑。注意三条命令都在 bin 目录下执行中途切走目录再回来python superset会报cant 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_MESSAGESmd是 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 编译成 momsgfmt 来自 gettext 工具包 msgfmt messages.po -o messages.moWindows 默认没有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 的改动不会热加载必须停服务重启。CtrlC 结束当前进程重新执行启动命令控制台看到服务正常监听再打开浏览器。浏览器这边多半有缓存直接刷新可能还是旧界面用 CtrlF5 强刷一次。还是英文的话按顺序排查config.py改的是不是当前虚拟环境里那份多环境并存时最容易改错、messages.mo是否真的在LC_MESSAGES目录里、BABEL_DEFAULT_FOLDER的值和实际路径是否对得上。这三处排完基本都能正常显示中文菜单。5. 常见问题排查五个把安装卡死的坑下面这几条都是实际装的过程中反复出现的按「现象 → 原因 → 解决」记遇到时对着现象找比从头翻日志快得多。5.1 安装阶段的两个高频报错现象一pip install superset跑到一半红字报Microsoft Visual C 14.0 is required。原因是某个依赖包在当前 Python 版本下没有预编译 wheelpip 退回源码编译而机器上没有 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报cant 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:passhost:3306/dbname前提是对应驱动已经pip install进这个虚拟环境。第三层是出图。拿刚才的查询结果点 Create Chart选个表格或柱状图保存后加进一张 Dashboard再点导出 CSV。走完这一圈才算这套 Windows 环境真的能交付。验证项检查位置通过标准进程与端口命令行控制台打印监听地址浏览器能打开登录页管理员账号右上角用户菜单能登录菜单完整角色权限左侧导航Sources / Charts / Dashboards / SQL Lab 齐全数据库连接SQL Lab查询能返回结果无驱动报错出图与导出Chart / Dashboard图表能保存、仪表盘能展示、CSV 能下载汉化右上角语言切换中文菜单正常显示可切回英文顺手记一条命令备查出问题时报版本比描述现象有用得多:: 确认当前虚拟环境里的 Superset 版本与依赖清单 python -c import superset; print(superset.__version__) pip list | findstr -i flask sqlalchemy werkzeug版本号和报错信息一起贴出来定位问题的速度完全不一样。从那以后我每次装完 Superset都先把 SQL Lab 跑通一条查询再往下交付光能登录不算装完。汉化不生效、示例数据没加载、端口改了没记住这些小毛病最后都是靠这一圈验证暴露出来的。希望帮到你。本文还有配套的精品资源点击获取
