BI 2022-10-04

superset 安装

1. 安装环境要求

1.1 操作系统支持

  • Linux: Ubuntu 20.04+/CentOS 7+/Debian 10+ (推荐)
  • macOS: macOS 12+ (Monterey) 或更高版本
  • Windows: Windows 10/11 (推荐使用 WSL2)
  • 云平台: AWS EC2, Google Cloud, Azure VM

1.2 硬件要求

组件 最低配置 推荐配置
CPU 2 核 4-8 核
内存 4GB 8-16GB
磁盘 10GB 50GB+
网络 100Mbps 1Gbps

1.3 软件环境

软件 版本要求 说明
Python 3.8-3.12 Superset 3.x 支持 Python 3.8-3.12
Node.js 16.14.0+ 前端构建必需
npm 8.0.0+ 前端构建必需
Database PostgreSQL/MySQL/SQLite 元数据存储
Redis 6.0+ 缓存和异步任务队列

注意: Superset 4.0+ 已停止支持 Python 3.7 及以下版本

2. 基础配置

2.1 创建独立虚拟环境（强烈推荐）

# 使用 venv 创建虚拟环境
python3 -m venv superset_env
source superset_env/bin/activate

# 或者使用 pyenv（如果已安装）
pyenv install 3.11.9
pyenv virtualenv 3.11.9 superset-3.11
pyenv activate superset-3.11

2.2 系统依赖安装

# Ubuntu/Debian
sudo apt update
sudo apt install -y build-essential python3-dev libffi-dev libpq-dev libsasl2-dev

# CentOS/RHEL
sudo yum groupinstall -y "Development Tools"
sudo yum install -y python3-devel openssl-devel libffi-devel postgresql-devel

# macOS
brew install openssl pkg-config libffi postgresql

2.3 数据库准备

SQLite（开发环境）

  • 默认使用，无需额外配置

PostgreSQL（生产环境推荐）

-- 创建数据库和用户
CREATE DATABASE superset;
CREATE USER superset WITH PASSWORD 'superset';
GRANT ALL PRIVILEGES ON DATABASE superset TO superset;

MySQL

CREATE DATABASE superset CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'superset'@'localhost' IDENTIFIED BY 'superset';
GRANT ALL PRIVILEGES ON superset.* TO 'superset'@'localhost';
FLUSH PRIVILEGES;

3. 安装依赖

3.1 安装 Python 包管理工具

# 如果 pip 未安装
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python3 get-pip.py

# 升级 pip
pip install --upgrade pip

3.2 安装 Node.js 和 npm

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# macOS
brew install node

# 验证安装
node --version
npm --version

3.3 安装 Redis（可选但推荐）

# Ubuntu/Debian
sudo apt install redis-server
sudo systemctl enable redis-server
sudo systemctl start redis-server

# macOS
brew install redis
brew services start redis

4. 安装配置

4.1 配置文件准备

创建 superset_config.py 配置文件：

# superset_config.py
import os
from datetime import timedelta

# Basic configuration
SECRET_KEY = os.environ.get('SECRET_KEY', 'your-secret-key-here')

# Database configuration
SQLALCHEMY_DATABASE_URI = 'sqlite:////path/to/superset.db'
# 或 PostgreSQL: 'postgresql://superset:superset@localhost:5432/superset'
# 或 MySQL: 'mysql://superset:superset@localhost:3306/superset'

# Cache configuration
CACHE_CONFIG = {
    'CACHE_TYPE': 'redis',
    'CACHE_DEFAULT_TIMEOUT': 300,
    'CACHE_KEY_PREFIX': 'superset_',
    'CACHE_REDIS_URL': 'redis://localhost:6379/1'
}

# Celery configuration (for async tasks)
CELERY_CONFIG = {
    'BROKER_URL': 'redis://localhost:6379/2',
    'CELERY_IMPORTS': (
        'superset.sql_lab',
        'superset.tasks.thumbnails',
    ),
    'CELERY_RESULT_BACKEND': 'redis://localhost:6379/3',
    'CELERY_ANNOTATIONS': {
        'sql_lab.run_sync': {'rate_limit': '10000/s'},
        'sql_lab.run_async': {'rate_limit': '1000/s'},
    },
    'CELERY_TASK_PROTOCOL': 1
}

# Feature flags
FEATURE_FLAGS = {
    'ENABLE_TEMPLATE_PROCESSING': True,
    'ENABLE_ASYNC_CELERY': True,
    'ENABLE_ASYNC_FETCHING': True,
}

# Security settings
AUTH_ROLE_ADMIN = 'Admin'
AUTH_ROLE_PUBLIC = 'Public'

# Email configuration (optional)
EMAIL_NOTIFICATIONS = False

4.2 环境变量配置

# 创建 .env 文件
echo "SUPERSET_HOME=/opt/superset" > .env
echo "PYTHONPATH=/opt/superset" >> .env
echo "SUPERSET_CONFIG_PATH=/opt/superset/superset_config.py" >> .env

# 加载环境变量
source .env

5. 安装过程

5.1 方式一：使用 pip 安装（推荐）

# 激活虚拟环境
source superset_env/bin/activate

# 安装 Superset
pip install apache-superset

# 初始化数据库
superset db upgrade

# 创建管理员用户
export FLASK_APP=superset
flask fab create-admin \
    --username admin \
    --firstname Admin \
    --lastname User \
    --email admin@superset.com \
    --password admin

# 加载示例数据（可选）
superset load_examples

# 初始化角色和权限
superset init

5.2 方式二：使用 conda 安装

# 创建 conda 环境
conda create -n superset python=3.11
conda activate superset

# 安装 Superset
conda install -c conda-forge superset

# 初始化
superset db upgrade
superset fab create-admin
superset init

5.3 方式三：使用 Docker 安装（生产推荐）

# 创建 docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3.8'
services:
  superset:
    image: apache/superset:3.1.0
    container_name: superset
    ports:
      - "8088:8088"
    environment:
      - SUPERSET_SECRET_KEY=your-secret-key
      - SUPERSET_LOAD_EXAMPLES=false
      - SUPERSET_DATABASE_URI=postgresql+psycopg2://superset:superset@postgres:5432/superset
      - SUPERSET_CACHE_REDIS_URL=redis://redis:6379/1
    depends_on:
      - postgres
      - redis
    restart: unless-stopped

  postgres:
    image: postgres:13
    container_name: postgres
    environment:
      - POSTGRES_DB=superset
      - POSTGRES_USER=superset
      - POSTGRES_PASSWORD=superset
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: redis
    command: redis-server --save 60 1 --loglevel warning
    volumes:
      - redis_data:/data
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:
EOF

# 启动服务
docker-compose up -d

5.4 启动 Superset

# 开发模式启动
superset run -h 0.0.0.0 -p 8088 --with-threads --reload --debugger

# 生产模式启动（使用 gunicorn）
superset run -h 0.0.0.0 -p 8088 --with-threads --daemon --pid /tmp/superset.pid

# 使用 gunicorn（推荐生产环境）
gunicorn --bind 0.0.0.0:8088 --workers 4 --timeout 120 --max-requests 1000 --preload "superset:app" --access-logfile - --error-logfile -

6. 常见问题及解决方案

6.1 Python 包编译错误

问题现象: 

Failed building wheel for cryptography
Command "python setup.py egg_info" failed

解决方案: 

# Ubuntu/Debian
sudo apt install build-essential libssl-dev libffi-dev python3-dev

# macOS
brew install openssl libffi pkg-config
export LDFLAGS="-L$(brew --prefix openssl)/lib"
export CPPFLAGS="-I$(brew --prefix openssl)/include"

# 升级 pip 和 setuptools
pip install --upgrade pip setuptools wheel

6.2 Node.js 构建失败

问题现象: 

Error: Cannot find module 'webpack'

解决方案: 

# 清理 node_modules
rm -rf node_modules package-lock.json

# 使用国内镜像源
npm config set registry https://registry.npmmirror.com
npm install -g cnpm --registry=https://registry.npmmirror.com

# 重新安装依赖
npm install

6.3 数据库连接错误

问题现象: 

sqlalchemy.exc.OperationalError: (psycopg2.OperationalError) FATAL: database "superset" does not exist

解决方案: 

# 创建数据库
createdb superset

# 或者在 PostgreSQL 中执行
psql -U postgres -c "CREATE DATABASE superset;"

# 验证连接
psql -U superset -d superset -h localhost -p 5432

6.4 内存不足错误

问题现象: 

Killed: 9

解决方案: 

# 增加交换空间（临时）
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 或者限制内存使用
superset run --memory-limit 2g

6.5 权限问题

问题现象: 

PermissionError: [Errno 13] Permission denied

解决方案: 

# 使用正确的用户权限
sudo chown -R $USER:$USER /path/to/superset

# 或者使用用户目录
mkdir -p ~/superset
cd ~/superset

# 避免使用 sudo 安装 pip 包
pip install --user apache-superset

6.6 Webpack 编译超时

问题现象: 

Webpack compilation timed out

解决方案: 

# 增加 webpack 超时时间
export WEBPACK_TIMEOUT=300

# 或者使用预编译版本
pip install apache-superset[precompiled]

# 或者跳过前端构建
pip install apache-superset --no-deps

7. 验证安装

7.1 检查服务状态

# 检查进程
ps aux | grep superset

# 检查端口
netstat -tuln | grep 8088

# 检查日志
tail -f /var/log/superset/superset.log

7.2 访问 Web UI

  • 打开浏览器访问：http://localhost:8088
  • 默认登录：用户名 admin，密码 admin

7.3 API 测试

# 测试健康检查
curl -X GET http://localhost:8088/api/v1/_health

# 获取版本信息
curl -X GET http://localhost:8088/api/v1/version
--- 本文结束 The End ---