superset的安装和启动流程参考于腾讯云开发者社区的一篇博客和superset的官网和帮助文档中的本地开发环境搭建部分,解决问题部分的参考链接都附在文章当中。

问题背景

最近在做iotdb和superset的一个连接工作，本以为安装superset不过上官网下载一下，走个安装流程即可，但是实际操作起来属于是一言难尽。真的是没想到一款知名的开源软件的安装和启动的报错竟然如此之多，读者可以在网上搜索superset，前几条信息除了superset的官网之外就是错误解决博客，甚至有博客专门列了个二十余项的报错清单讲解决之法。不过作者安装花费了这么长的时间，更多的还是因为前期对于这个安装工作的没有足够的重视，资料没有收集阅读全面就草草上手，以至于前后经历了安装生产环境版本、使用本地环境安装、使用虚拟环境安装、使用虚拟机安装和使用docker安装等曲折的历程，属实是比较痛苦。不过经历这些试错的环节，作者也是学习到了更丰富的知识，最后还是推荐使用虚拟环境或者docker实现superset的安装和启动。作者这里会分享一下包含生产环境与开发环境两个版本在内的superset的安装启动流程与错误解决。

虚拟环境下的安装启动流程

先注明一下作者这里使用的python版本是3.8.9，电脑系统是windows,iotdb版本为1.1.1, node.js版本为16, npm的版本为8

安装前言

  • 对于生产环境和开发环境的两个版本的superset的安装流程大体上是一样的，但是在部分指令使用与错误处理上会有所不同。

  • 读者需要注意，这里的流程不包含后续的数据库连接工作，如果需要连接数据库，自行在superset官网的安装数据库驱动中，找到自己想要使用的数据库驱动包(pypi packet)去pip，pip时机在初始化superset之前都可以，当然，数据库驱动包很可能会带来更多的报错，这部分的报错需要结合具体的数据库和报错去分析。

  • 第一次安装的流程概述如下

    • 版本选择(开发环境)
    • 虚拟环境的创建与启动
    • 安装superset依赖
    • 构建前端资源(开发环境)
    • 初始化superset的元数据数据库
    • 创建管理员用户/初始化Superset的应用程序环境
    • 启动superset

  • 对于已经启动过的读者来说，关掉虚拟环境后再次启动的流程概述如下

    • 虚拟环境的启动
    • 初始化superset的元数据数据库
    • 初始化Superset的应用程序环境
    • 启动superset

版本选择(开发环境)

  • 首先对于开发环境下，源代码是必不可少的，直接从github上拉取superset的源代码
  • 因为作者是第一次参与开源社区的开发，不太清楚github里面哪些是稳定的分支可以pull，最开始是直接选用了master进行开发，后来遇到了一些bug，也是顺利解决。同时作者通过网络博客的学习，也参考了一些其他博主的版本去安装与启动，尝试了2.1,2.0,1.3,0.36等分支，这些分支出现的依赖问题、显示问题相较于master略多(这里讲述的是作者设备的情况，当然也可能是superset在最新的版本中解决了前面版本的部分问题)。
  • 对于新入坑的读者，可以去superset的github主页找他们的联系方式，咨询一下最新的稳定版本

下面介绍可能遇到的问题：

  • 报错1：克隆时候报错 Cloning into ‘superset’… error: RPC failed; curl 92 HTTP/2 stream 3 was not closed cleanly before end of the underlying stream fatal: expected flush after ref listing
    • 这个说明在尝试克隆 Git 仓库时发生了问题。这可能是由于网络问题、服务器问题或 Git 配置问题引起的。
    • 解决方法：再clone一次即可

构建前端资源(开发环境)

  • 这里官网要求node.js需要达到版本16，npm需要达到版本7

  • 假设当前的开发目录是superset目录，那么需要依次执行下面四个指令cd superset-frontend，npm ci，npm run build,cd ..

  • tips:

    • 视电脑性能的不同，构建过程需要等待几分钟到十几分钟不等
    • 前端资源构建的这个操作位置是比较自由的，只需要在启动superset之前执行这个部分的指令即可，如果在superset之前没有执行前端资源构建，将会导致网页无法显示，表现为前端页面处于一种崩溃状态
    • 如果读者的开发工作涉及到superset前端的样式修改可以采用如下的两种方式进行开发
      • 每次修改之后都重新输入构建前端资源的指令
      • 在前端资源构建和superset启动之后，执行npm run dev-server打开webpack的开发服务器，能够对前端资源进行热重载，可以实时反馈前端修改到网页上

  • 报错1：出现大量npm ERR!xxx格式的报错信息行

    • 解决方法：这个报错可以在superset的github issue中找到: fail to npm install on superset-frontend at 2.1 version,由于问题比较新，暂时还没有在2.1分支上解决这个问题的方法，作者是切换到master是可以顺利编译的，读者可以通过切换分支，选择一个不是2.1分支的版本继续下面的操作

  • 报错2：

    1
    2
    3
    4
    npm ERR! code 1
    npm ERR! path D:\supersetconnect\superset\superset-frontend\node_modules\@applitools\eyes-storybook
    npm ERR! command failed
    npm ERR! command C:\Windows\system32\cmd.exe /d /s /c ..\AppData\Local\Temp\postinstall6852635.cmd
    • 解决方法，这个报错表示在安装@applitools/eyes-storybook包时发生了错误。根据错误日志，是在执行postinstall脚本时出现了问题。解决方法是删除superset-frontend目录下的node_modules文件夹，然后重新执行npm ci或者npm install命令，更新依赖即可解决。

  • 警告：这里会出现很多的warning，大多数说superset选用的版本较老，可以不予理会

虚拟环境的创建与启动

这个部分我一开始是安装了python的virtualenv包来进行虚拟环境的创建，后来查阅资料了解到python3.3以上的版本自带了venv的虚拟环境，两者在这里拥有相似的效果，读者自行选择

  • 虚拟环境的创建

    • 对于virtualenv
      • 在终端使用pip install virtualenv指令安装virtualenv
      • 找个合适的位置，在终端输入virtualenv your_environment_name创建虚拟环境
    • 对于venv
      • 在终端使用python -m venv your_environment_name创建虚拟环境
    • 上面表述中的your_environment_name替换为你想要的环境名称，例如superset_venv,指令产生的效果就是会在当前文件夹下创建一个名为superset_venv的文件夹，其中为虚拟环境的文件存放区域。后面就以superset_venv为例继续阐述流程

  • 虚拟环境的启动(再次强调，作者用的是windows系统，不是windows系统的指令会略有不同)

    • 在终端输入superset_venv\Scripts\activate激活虚拟环境，效果为看到命令提示符前面有一个表示虚拟环境名称的前缀，例如(superset_venv)。

安装superset依赖

  • 推荐的先行操作:在终端当中输入superset_venv\scripts\python.exe -m pip install --upgrade pip将pip更新到最新版,注意这里的superset_venv\scripts\python.exe,这是在虚拟环境文件夹下有这么一个python.exe,如果执行报错,可以检查自己的终端路径或者将这里的相对路径superset_venv\scripts\python.exe改为绝对路径

  • 这里的安装指令在开发环境和生产环境两个版本之间会略有不同

    • 对于生产环境，输入pip install --upgrade apache-superset
    • 对于开发环境，输入pip install -r requirements/testing.txt
      • 这里之所以和生产环境不同，是因为生产环境使用的是稳定发布的apache-superset的python依赖包，和我们使用的apache-superset版本很可能不一致，直接安装apache-superset源码中的需求文件即可

  • 等待依赖安装，如果这个过程没有报错，确实是值得恭喜的，可以进入第三步。下面是介绍作者在这里遇到的报错和解决方法

  • 报错1：ERROR: Could not build wheels for python-geohash, which is required to install pyproject.toml-based projects

    • 解决方法：在Unofficial Windows Binaries for Python Extension Packages网站上下载对应版本的预编译包。这里作者使用的python是3.8，且为x64的windows系统，所以需要下载的编译包为python_geohash-0.8.5-cp38-cp38-win_amd64.whl。将终端定位到下载文件位置，在终端先输入pip install wheel确认wheel包已经存在，再输入pip install python_geohash‑0.8.5‑cp38‑cp38‑win_amd64.whl即可，注意文件名换为读者所使用的的whl文件名。
    • 网络上讲述的另一种方法——通过安装c++ build tool解决问题，我尝试了一半，发现需要用vs install安装几个G的东西，占内存、下载还很耗时，改用上面这种方式还是非常高效简洁

  • 报错2：与报错1相似，但是python-geohash换成mysqlclient

    • 解决方法：与报错1相似，在这个网址上下载对应版本的预编译包。这里作者使用的python是3.8，且为x64的windows系统，所以需要下载的编译包为mysqlclient‑1.4.6‑cp38‑cp38‑win_amd64.whl。与报错1一样，在终端中检查wheel是否安装pip install wheel，再定位到whl文件所在文件夹去安装，指令为pip install mysqlclient‑1.4.6‑cp38‑cp38‑win_amd64.whl

  • 报错3：与报错1相似，但是python-geohash换成sasl

    • 解决方法：与报错1相似，在这个网址上下载对应版本的预编译包。这里作者使用的python是3.8，且为x64的windows系统，所以需要下载的编译包为sasl‑0.3.1‑cp38‑cp38‑win_amd64.whl。与报错1一样，在终端中检查wheel是否安装pip install wheel，再定位到whl文件所在文件夹去安装，指令为pip install sasl‑0.3.1‑cp38‑cp38‑win_amd64.whl

  • 报错4：ERROR: pip’s dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.apache-iotdb 1.1.0 requires sqlalchemy!=1.3.21,<1.4,>=1.3.16, but you have sqlalchemy 1.4.47 which is incompatible.apache-iotdb 1.1.0 requires sqlalchemy-utils<0.38,>=0.37.8, but you have sqlalchemy-utils 0.38.3 which is incompatible.

    • 这个报错是因为作者使用的iotdb的python包对于sqlalchemy的版本限制与superset所使用的的sqlalchemy版本冲突。
    • 解决方法: 简而言之就是去除这个iotdb的python包对于sqlalchemy的版本限制。电脑上需要有python3、pip3;使用python3 -m pip install --user --upgrade setuptools wheel和python3 -m pip install --user --upgrade twine指令安装setuptools和wheel和twine，进入到iotdb源码文件夹下的client-py文件夹，打开setup.py文件，修改版本号为任意非中文符号串，如1.2.0-rc1，随后去除sglalchemy和"sglalchemy-utils的版本上限限制，随后执行python3 setup.py sdist bdist_wheel打包出一个临时的iotdb包(点击直接下载)——client_py/dist/apache iotdb-1.2.0rc1-py3-none-any.whl,随后在终端定位到这个文件的位置去安装这个whl文件，执行指令为pip3 install apache iotdb-1.2.0rc1-py3-none-any.whl

初始化superset的元数据数据库

  • 在虚拟环境当中输入superset db upgrade，这里如果没有报错，可以进入下一步。下面介绍作者遇到的几个问题

  • 报错1:Error: Could not locate a Flask application. You did not provide the “FLASK_APP” environment variable, and a “wsgi.py” or “app.py” module was not found in the current directory.

    • 需要设置flask_app这个环境变量为superset，但是作者尝试了set FLASK_APP=superset指令进行设置，但是使用echo %FLASK_APP%进行检查却发现一直没有设置成功。
    • 解决方式:使用$env:FLASK_APP = "superset"设置flask_app,可以使用echo $env:FLASK_APP检查flask_app是否设置成功
    • 需要注意，这里的解决方式中设置flask_app的方式是一种临时的设置方式，终端关掉重启就会取消，如果设备不是长期只使用superset还是不建议考虑设置成永久的，永久设置指令是用setx代替上面的set，这种设置是覆盖性质的，也就是要清除直接设置为空即可

  • (生产环境) 报错2:AttributeError: module ‘sqlparse.keywords’ has no attribute ‘FLAGS’

    • 这是superset的一个离奇bug，多次出现在issue当中，我在issue当中找到了一个可行的解决方法，这个方法的具体实现方式就是将superset_venv\lib\superset\sql_parse.py的re.compile(r"'(''|\\\\|\\|[^'])*'", sqlparse.keywords.FLAGS).match改为re.compile(r"'(''|\\\\|\\|[^'])*'", re.IGNORECASE | re.UNICODE).match

  • 报错3:一个非常规整的warning，最后是Refusing to start due to insecure SECRET_KEY

    • Superset 使用了默认的 SECRET_KEY，这可能会导致安全问题，于是拒绝执行
    • 解决方法：
      • 对于生产环境
        • 在虚拟环境的终端当中输入openssl rand -base64 42获取一个密钥,随后在文件夹superset_venv的根目录,创建superset_config.py，把这个句子SECRET_KEY = “密钥”写进superset_config.py即可
      • 对于开发环境
        • 在生产环境的基础上，在终端输入指令set SUPERSET_CONFIG_PATH path\to\your\superset_config.py或者$env:SUPERSET_CONFIG_PATH = "path\to\your\superset_config.py"
        • 这里的设置方式是一种临时的设置方式，终端关掉重启就会取消，如果设备不是长期只使用superset还是不建议考虑设置成永久的，永久设置指令是用setx代替上面的set，这种设置是覆盖性质的，也就是要清除直接设置为空即可
    • 非常重要的一点是openssl rand -base64 42所获得的的密钥还请自己妥善保管，

  • 报错4:Can’t locate revision identified by ‘7e67aecbf3f1’

    • 因为作者一开始在本地环境上切换过版本，在其他版本中执行过superset db upgrade,造成本地留存了一个superset.db文件，而这个报错就是说这个留存的superset.db和当前使用的superset的版本不同
    • 解决方法：找到superset.db，删除即可，重新运行superset db upgrade会再生成的
    • 如果不知道这个superset.db在哪里，推荐电脑下载everything工具进行搜索

  • 除此之外，在开发环境当中，这里会有多个警告，这些警告可以忽略

    • We haven't found any Content Security Policy (CSP) defined in the configurations... 这是一个关于未定义内容安全策略 (CSP) 的警告。
    • Falling back to the built-in cache...这是一个关于缓存配置的警告。
    • WARNI [alembic.env] SQLite Database support for metadata databases will be removed in a future version of Superset.这是一个关于未来 Superset 版本将不再支持 SQLite 作为元数据数据库的警告。

  • 注意上述的操作都在虚拟环境的终端当中，错误解决之后需要运行一下superset db upgrade

创建管理员用户/初始化Superset的应用程序环境

  • 在终端当中输入superset fab create-admin创建管理员用户，依次输入用户名、用户名字、用户姓氏、邮箱、密码、确认密码
  • 需要注意，用户名和密码是用于后续登录superset网站的
  • 在终端输入superset init的应用程序环境，如果前面没有创建管理员用户，且superset当中不存在用户记录，那么这句指令将会强制要求创建一个。

启动superset网站

  • 在终端输入superset run -p 8080 --with-threads --reload --debugger,这里的superset很多博客甚至官网教程都是用flask，两者效果是一样的。随后可以在终端的输出当中找到一个本地网站链接http://127.0.0.1:8080/,或者直接在浏览器当中输入这个网址启动即可
  • 到这里superset的启动也是顺利结束了

docker下的安装启动流程

用docker实现superset的安装和启动应该是最为稳定的方式，一方面是因为可以与本地环境完全隔离，不用担心本地环境对于superset安装的影响，另一方面是使用的linux的镜像，在指令使用上与官方推荐也更为贴合。不过由于作者在最后改用docker去完成安装和启动的过程中，前面虚拟环境的部分的bug得到了解决，已经可以顺利启动。这个部分的文案就暂且搁置，等之后完成这个项目之后再来补充。