必须用虚拟环境，因为superset依赖链深、版本敏感（如markupsafe==2.0.1才兼容flask 2.x），系统python易被其他项目污染，80%的importerror或attributeerror源于环境混用。
用 Miniconda 创建独立 Python 环境再装 Superset，是最稳的路径；直接 pip install apache-superset 在系统 Python 下容易因依赖冲突失败。
为什么必须用虚拟环境？
Superset 依赖链深、版本敏感（比如 markupsafe==2.0.1 才兼容 Flask 2.x），系统 Python 或全局 pip 容易被其他项目污染。实测中，80% 的 ImportError 或 AttributeError 都源于环境混用。
- 别用系统自带的 python3 —— Ubuntu/Debian 的 python3 指向可能不一致，CentOS 的 python3-devel 包名也不同
- Miniconda 比 full Anaconda 轻量，
conda create -n superset python=3.9是当前最兼容的组合（3.10+ 有少数插件未完全适配） - 激活后执行
which python必须指向~/miniconda3/envs/superset/bin/python这类路径，否则后续所有命令都无效
安装前必须装的系统级依赖
缺这些会导致编译失败或驱动加载异常，尤其连接 MySQL/Hive 时会卡在 ImportError: libmysqlclient.so.21: cannot open shared object file 这类错误。
- Ubuntu/Debian：
sudo apt-get install build-essential libssl-dev libffi-dev python3-dev libsasl2-dev libldap2-dev - CentOS/RHEL：
sudo yum install -y gcc gcc-c++ libffi-devel python3-devel openssl-devel cyrus-sasl-devel openldap-devel mysql-devel - 注意：
mysql-devel不是可选——哪怕你只连 Hive，Superset 元数据库默认 SQLite，但初始化时仍会尝试 import pymysql，缺头文件就报错
连接 MySQL 或 Hive 时最容易漏的配置项
Web 界面只显示 “Connection failed”，真正原因藏在终端日志里。启动时加 --debug 参数（superset runserver --debug -p 8088）才能看到真实报错。
- MySQL URL 必须带
?charset=utf8mb4&connect_timeout=30，漏掉utf8mb4会导致中文字段乱码或 emoji 写入失败 - Hive URL 必须确认三件事：PyHive 已装（
pip install PyHive>=0.7.0）、telnet hive-host 10000能通、Kerberos ticket 有效（klist有输出） - Hive Kerberos 场景下，URL 中的
kerberos_service_name=hive必须和/etc/krb5.conf里[realms]下定义的服务名一致，不是主机名
启动失败先查这三处日志
Superset 不会把关键错误堆栈打到 Web 页面，全靠服务端输出定位问题。
- 终端运行
superset runserver --debug -p 8088时的实时输出 —— 最直接，比如看到ModuleNotFoundError: No module named 'pyhive'就立刻补装 -
superset db upgrade是否成功 —— 若报ImportError: cannot import name 'soft_unicode' from 'markupsafe'，降级：pip install markupsafe==2.0.1 - Hive 连接失败若含
SASL(-1): generic failure，90% 是kinit过期，或sasl_client.setAttr('host', ...)传了错误 host（某些集群强制填HADOOP而非实际 hostname）
Superset 启动本身不难，难的是环境干净、驱动对路、字符集和认证参数一个不落——这些细节没调好，界面只会安静地显示“Connection failed”，而错误其实早就在终端里滚动过去了。
