Agent Skills
返回列表
Superset 故障排查

Superset 故障排查

IT 运维与安全 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中：

请根据 https://skillhub.cn/install/skillhub.md，安装 @user_1f020d8e/supersettroubleshoot。

技能介绍

你会遇到什么问题

Apache Superset 在生产里一旦「能登录但用不了」，往往卡在元数据、加密字段或图表参数上，而不是单纯的 SQL 写错。常见报错包括：Invalid decryption key / InvalidToken（SECRET_KEY 变更后 dbs 表里加密字段无法解密）、仪表盘 TypeError: Cannot read properties of undefined (reading 'width')（position_json 缺少 ROW → COLUMN → CHART 层级）、Item with key "scatter_chart" is not registered（旧 viz_type 未注册）、饼图 reading 'label'（参数里用了 metrics 数组而非单对象 metric）、虚拟数据集 Missing columns in datasource、以及 SQL Lab 在 allow_run_async=True 却无 Celery worker 时长时间挂起。部分问题可在 REST API 层修复，但本技能侧重需要 shell 进入 Superset 宿主机或容器的处置。

技能如何组织排障

技能按错误现象拆成可执行的修复路径，而不是泛泛讲 Superset 架构：

  • 密钥与解密：在应用容器内处理密钥相关状态，并提醒清理浏览器缓存或使用无痕窗口，避免前端仍持有旧会话。
  • 仪表盘布局：说明根因是 position_json 结构损坏，并指向通过容器内脚本重建布局（正确格式可参考 superset-api 技能中的 Dashboard Layout）。
  • 图表与数据集：区分 viz_type 替换（可查 superset-api 的 Available viztype）、饼图 metric vs metrics、以及虚拟数据集列缺失时的 datasourceid 错绑 与 列缓存未同步（后者需在容器内执行同步类操作）。
  • 异步与外部连接：SQL Lab 挂起与 Celery worker 配置的关系；Databricks 场景下强调应更新 password 字段，而非误改 encrypted_extra。

文档还强调：上述 Python 脚本应在 Superset application context（容器或 virtualenv）中运行；psql 类操作需要能访问元数据库；修改配置或库表后应重启 Superset 服务。

适用边界

不涉及从零部署 Superset，也不替代官方文档里的版本升级矩阵。REST 可完成的修改（如部分 viz_type、图表参数、datasource 指向）技能会标明可交给 superset-api；你仍需自行确认环境权限、备份元库，且 deploy/.env 等含密钥的文件不要提交到 git。

使用场景

  • 生产环境更换 SECRET_KEY 后，数据源连接报 Invalid decryption key，需在 Superset 容器内处理并让用户清浏览器缓存。
  • 仪表盘迁移或升级后整板无法渲染，控制台出现 reading 'width'，需按 ROW→COLUMN→CHART 重建 position_json。
  • 历史看板仍使用 scatter_chart 等旧 viz_type，页面提示未注册，需对照映射改图表参数或通过 REST 修复。
  • 虚拟数据集 SQL 已改但图表报 Missing columns，需区分 datasource_id 错绑与列缓存未同步并在容器内同步列。

适合人员

  • 在 Kubernetes 或 VM 上维护 Superset 实例的平台工程师，值班时需要 shell 进容器处理元库加密与配置类故障。
  • 负责看板交付与升级的 BI 管理员，要在版本变更后修复布局、viz_type 与饼图 metric 参数不一致问题。
  • 对接 Databricks 等仓库的数据工程师，在 Token 轮换后需正确更新连接里的 password 字段而非误改 encrypted_extra。
  • 能访问 Superset 元数据库（psql）与应用容器的运维人员，变更后负责重启服务并遵守不把 deploy/.env 提交进版本库。