一、问题背景：异步查询到底是什么

很多用 Superset 做数据看板的朋友，应该都碰到过这样一种情况：图表数据量一变大，点击“刷新”或者“运行查询”后，页面就一直转圈，等得人心焦。为了不让查询把整个服务拖垮，Superset 引入了异步查询机制。说白了，就是把一个查询任务扔到后台去跑，前端页面先返回一个“正在查询”的状态，等后台跑完了再把结果取回来。这样页面不会卡死，体验要好很多。

但是，这个异步查询机制并不是开箱即用的。它需要依赖额外的中间件和任务队列。如果配置不对，查询任务根本不会被执行，或者执行到一半就失败。而且这类错误往往不会直接显示在页面上，只会看到转圈或者“任务失败”的提示。小白用户一头雾水，老手也得翻半天日志才能定位到问题。

这篇文章就用尽量直白的话，把异步查询配置错误导致任务失败的常见原因、排查方法和解决办法讲清楚，顺便给出可以照着用的完整示例。

二、异步查询涉及的核心部件

2.1 三个关键角色

异步查询要跑起来，至少需要三个角色一起配合：

  • Superset 本体：负责接收查询请求，并把它封装成一个后台任务。
  • Celery Worker：真正干活的工人，它负责执行后台任务，去数据库里跑 SQL，把结果存起来。
  • 消息队列（比如 Redis）：相当于一个“任务传送带”，Superset 把任务放到传送带上，Celery Worker 从传送带上取任务。

这三个角色缺一不可。如果其中一个没配置好，任务就会像在传送带上卡住一样，永远到不了工人手里，或者工人拿到了任务却不知道怎么干。

2.2 配置错误为什么这么隐蔽

因为 Superset 的默认配置里，异步查询功能并不是默认开启的。哪怕你手动开启了，配置项之间也要互相匹配。比如，你告诉 Superset“用 Redis 当消息队列”，但是 Redis 的地址写错了，或者密码不对，Superset 本身还是能正常启动的，它不会在启动时报错。只有当你真正发起一个异步查询时，它才会尝试连接 Redis，这个时候才失败。所以很多人都觉得“配置没问题，为什么任务跑不起来”，其实问题就藏在这些细节里。

三、常见的配置错误案例

3.1 没开启异步查询开关

大多数情况下失败并不是因为配置值写错，而是压根没把开关打开。Superset 里控制异步查询的总开关是通过 FEATURE_FLAGS 里的 ASYNC_QUERIES 字段控制的。如果这个字段是 False 或者缺失，那么即使你配置了 Celery 和 Redis，查询也只会同步执行，或者直接走旧的逻辑，不会进入后台任务队列。

3.2 消息队列地址不一致

假设你的 Redis 装在同一台机器上，端口是 6379，但是配置里写成了 6380。或者密码写错了，Superset 连接不上 Redis，Celery Worker 也连不上同一个 Redis，两边根本不在一个“频道”上。任务放到队列里，可 Worker 根本听不到，自然就不会去执行。

3.3 Celery Worker 没启动

这不是配置值的问题，而是运行环境的问题。很多人配置好了所有东西，却忘了启动 Celery Worker，或者 Worker 启动后因为代码路径不对，没能加载到 Superset 的项目配置，导致 Worker 空转。

3.4 结果后端配置错误

异步查询跑完之后，结果需要存到某个地方，我们称之为“结果后端”。如果结果后端没配好，任务其实执行成功了，但是结果不知道存到哪里去，前端还是拿不到数据，最终也会表现为任务失败。

四、排查思路与解决办法

4.1 先从日志入手

遇到任务失败，最忌讳的就是瞎猜。第一件事应该去看日志。Superset 的日志通常会记录下任务失败的具体异常。我们可以用下面的方式启动一个临时的测试，让日志输出到控制台，方便观察。先看看用 Python 写一个简单的日志输出示例，明确本示例基于 Python 3.8+ 和 Superset 2.x 环境。

# 日志观察小脚本，用来帮助定位异步查询失败原因
import logging

# 设置日志级别，把 INFO 和 ERROR 都打出来
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# 创建 logger，名字跟 Superset 的异步任务模块保持一致
logger = logging.getLogger('superset.tasks.async_queries')

# 模拟一条错误日志，看看输出效果
logger.info("开始模拟异步任务检查")
logger.error("模拟错误：Redis 连接超时，请检查 Redis 地址和端口")

看到类似 Redis connection timed out 的日志，就可以确认是 Redis 地址或端口配置问题。如果看到 Task got unknown error，可能需要检查结果后端。

4.2 检查配置文件

Superset 的配置文件一般是 superset_config.py，我们需要在 Python 代码里定义各个配置项。这里以 Python 代码片段 的形式展示正确配置和错误配置的对比。

错误配置示例：

# 这段配置里，有几个隐藏的坑，我们一一指出

FEATURE_FLAGS = {
    # 忘了开启异步查询开关，这是最致命的
    # "ASYNC_QUERIES": True,    # 被注释掉了，等于没开
}

# 消息队列配置，端口写错成 6380，实际 Redis 跑在 6379
CELERY_BROKER_URL = "redis://localhost:6380/0"

# 结果后端，用了内存型存储，而且没写对库编号
CELERY_RESULT_BACKEND = "redis://localhost:6380/1"

上面的配置至少有三个问题。第一，总开关没打开。第二，Redis 端口错误。第三，结果后端跟消息队列用的同一个 Redis 实例，但库编号混用，容易造成数据冲突。

正确配置示例：

# 正确配置写法，同样基于 Python 代码

# 开启异步查询总开关，必须为 True
FEATURE_FLAGS = {
    "ASYNC_QUERIES": True,
}

# 消息队列地址，确保地址和端口正确
# 假定 Redis 跑在本机，端口是 6379，密码为空
CELERY_BROKER_URL = "redis://localhost:6379/0"

# 结果后端，建议和消息队列使用不同的数据库编号
# 这里用 /1，避免和 /0 的队列数据混在一起
CELERY_RESULT_BACKEND = "redis://localhost:6379/1"

# 异步查询的超时时间，单位秒
# 设置为 3600 表示一小时还没跑完就超时
ASYNC_QUERY_TIMEOUT = 3600

4.3 确保 Celery Worker 正常启动

配置文件没问题之后，还要确保 Celery Worker 真的跑起来了。启动命令需要放在一个能加载到 Superset 配置的环境里。下面给出一个通过 Python 调用来启动 Worker 的思路，但实际使用中一般在命令行直接执行。

如果你用的是 Bash 环境，可以这样启动 Worker，这里使用 Bash 命令 展示：

# 启动 Superset 的 Celery Worker
# -A 指定 worker 应用所在的位置，这里是 Superset 默认的入口
# --pool=prefork 表示使用多进程模式，适合执行数据库查询
# --loglevel=info 表示打印 INFO 级别的日志，方便观察任务执行情况
celery --app=superset.tasks.celery_app:app worker --pool=prefork --loglevel=info

启动后，你会看到日志中出现 ready 字样，说明 Worker 已经就绪。如果出现 connection refused，那就是 Redis 地址或者权限的问题。

4.4 用一个小实验验证整个链路

配置改完之后，不要急着去页面上点图表，我们可以先用一段 Python 测试脚本，直接向 Redis 队列里推送一条测试任务，看 Worker 能不能消费掉。这样可以快速验证链路是否打通。

# 用 Python 测试任务队列是否通畅
# 先导入 Celery 的发送任务方法
from superset.tasks.celery_app import app as celery_app
from celery.result import AsyncResult

# 先随便发送一个测试任务，这个任务只是打印一行字
r = celery_app.send_task(
    "superset.tasks.schedules.test_task",
    args=("hello async",),
)

# 打印任务 ID
print(f"任务已发送，ID: {r.id}")

# 等待 5 秒后，去获取任务状态
import time
time.sleep(5)

# 获取任务结果对象
result = AsyncResult(r.id, app=celery_app)

# 判断任务是否执行成功
if result.successful():
    print("任务执行成功，异步链路正常！")
else:
    print(f"任务状态：{result.state}，请检查 Worker 日志")

这段脚本的好处是，如果任务状态一直是 PENDING，说明 Worker 没启动；如果是 FAILURE，则说明配置还有问题，具体原因看 Worker 的日志。

五、应用场景与技术优缺点

5.1 适合在哪些场景使用

异步查询最适合那些查询时间比较长的场景。比如，一张表有上亿条数据，每次聚合统计要跑 20 秒以上。如果再加上多个用户同时点击，数据库压力会很大。用异步查询后，用户不需要一直等着页面响应，可以先去做别的事情，等结果出来了再通知他。另外，定时报表、预警任务这类需要后台周期性执行的查询，也依赖异步机制。

5.2 异步查询的优点

  • 响应快：前端不需要长时间挂起，网页不会一直转圈。
  • 资源复用：Celery Worker 可以控制并发数量，防止太多查询同时打爆数据库。
  • 任务可靠：配合 Redis 的持久化，任务在 Worker 崩溃后还能重新执行。
  • 方便扩展：如果任务量大了，可以多开几个 Worker 实例，横向扩展非常方便。

5.3 异步查询的缺点

  • 架构变复杂：原来只是一个 Flask 应用，现在要额外维护 Redis 和 Celery，部署成本高了不少。
  • 问题排查难度大：任务可能卡在队列里，也可能执行失败，状态需要额外查询。
  • 一致性难保证：如果 Redis 重启丢数据，正在排队的任务可能直接消失。
  • 调试不方便：本地开发时，异步查询的错误日志不像同步模式那样直接显示在网页上。

六、注意事项

配置异步查询时，有几个特别容易踩的坑，这里单独拿出来提醒。

第一，配置文件名要正确。 Superset 默认会读取当前工作目录下的 superset_config.py，或者通过环境变量 SUPERSET_CONFIG_PATH 指定。如果你改了文件名，Superset 根本不会加载你的配置。

第二，重启要彻底。 改了配置后，不光要重启 Superset 服务，还要重启 Celery Worker，否则 Worker 可能还留着旧的配置。

第三，内存要充足。 异步查询结果会暂时存在 Redis 里，如果结果集很大，Redis 内存会飙升。建议给 Redis 设置合理的内存上限和淘汰策略。

第四，注意数据库连接数。 Worker 并发数量如果设置太大，数据库连接数会被占满，反而导致查询更慢。建议根据数据库的实际能力调整 --concurrency 参数。

第五，测试时别忘清空旧任务。 如果你之前配置错误导致很多任务堆积在 Redis 里，修复后这些旧任务可能会被 Worker 捡起来继续执行。如果这些任务是没有意义的，最好先把队列清空。

# 清空 Redis 里所有异步任务队列的命令
# 注意：这个命令会删除当前 Redis 库里的所有键，小心使用
# 推荐只在测试环境这么干
redis-cli -n 0 FLUSHDB

七、总结

Superset 的异步查询功能，本质上是把“查询请求”和“查询执行”拆开，中间通过 Redis 和 Celery 来协调。配置错误的根源，往往不是某一个单项写错，而是整体链路没打通。排查的时候，按照“开关有没有开 -> 消息队列通不通 -> Worker 在不在 -> 结果能不能存”的顺序来，问题很快就会暴露出来。

最让人头疼的其实是那些“看起来成功但任务还是失败”的情况。这时候不要慌，先看日志，再检查配置。用本文里的 Python 测试脚本，可以快速验证任务队列通了没有，省去很多猜疑的时间。希望这篇文章能让你少走一些弯路，下次再遇到类似问题，心里有底，手上有招。