基于Python Tornado的MapBox GL JS自定义瓦片源加载异常排查

一、修复瓦片生成代码的明显错误 #

你提供的Python瓦片生成代码存在逻辑错误，会直接导致部分请求失败：

TILE_SIZE = 512
img = Image.new('RGBA', size=(TILE_SIZE, TILE_SIZE), color=(0, 0, 0, 0))
img_b = io.BytesIO()
img.save(img_b, "PNG")
# 错误：seek(0)返回None，无法迭代
# tile = img_b.seek(0)
# 正确写法：移动指针后直接读取BytesIO对象
img_b.seek(0)
for line in img_b:
    self.write(line)
self.set_header("Content-type", "image/png")

这段错误代码会触发TypeError: 'NoneType' object is not iterable，是部分瓦片加载失败的直接原因之一。

二、解决Tornado异步任务Pending问题 #

“Task was destroyed but it is pending!”错误本质是客户端提前取消请求后，后端异步任务（比如你的异步MySQL查询）仍在执行，Tornado销毁未完成任务时抛出警告。解决方式：

• 检查请求连接状态：在异步任务执行前后，通过self.request.connection.stream.closed()判断客户端是否已断开，若断开则终止任务。
• 绑定任务到请求生命周期：用self.add_future()管理异步任务，请求结束时自动取消未完成的future：

  async def get(self, x, y, z):
      query_future = self.db.query(...)
      self.add_future(query_future, callback=self.handle_query_result)
  def handle_query_result(self, future):
      if self.request.connection.stream.closed():
          return  # 客户端已断开，直接终止
      # 后续瓦片生成逻辑
  

• 捕获取消异常：在异步函数中捕获asyncio.CancelledError，避免冗余的错误堆栈输出。

三、优化MapBox JS瓦片请求配置 #

MapBox在视图快速变化（缩放、平移）时会自动取消无用瓦片请求，这是触发后端任务Pending的主要场景。调整source配置减少无效请求：

mapbox_obj.on('load', function(){
    mapbox_obj.addSource('rad-data', {
        "type": "raster",
        "tiles": ["/tile/{x}/{y}/{z}.png"],
        "tileSize": 512,
        // 延长请求超时，避免因瓦片生成慢被提前取消
        "tileTimeout": 15000,
        // 增大缓存，减少重复请求
        "maxTileCacheSize": 500,
        // 开启重试机制，应对偶发失败
        "retryDelay": 500,
        "maxRetryDelay": 2000
    });
    mapbox_obj.addLayer({
        "id": "rad-data-layer",
        "type": "raster",
        "source": "rad-data",
        "minzoom": 0,
        "maxzoom": 20,
        'layout': {
          'visibility': 'visible'
        }
      });
});

另外，设置和服务实际支持范围匹配的minzoom/maxzoom，避免发起超出处理能力的瓦片请求。

四、并发请求的异步处理优化 #

如果异步MySQL查询或瓦片生成是性能瓶颈，可通过以下方式优化：

• 使用数据库连接池：确保MySQL客户端使用连接池，避免并发请求时创建过多连接导致阻塞。
• 瓦片生成异步化：若PIL处理是CPU密集型操作，将其放到线程池执行，避免阻塞Tornado的IO循环：

  from concurrent.futures import ThreadPoolExecutor
  executor = ThreadPoolExecutor(max_workers=4)
  
  async def get(self, x, y, z):
      data = await self.db.query(...)
      # 在线程池生成瓦片
      img_b = await self.io_loop.run_in_executor(executor, self.generate_tile, data)
      img_b.seek(0)
      self.set_header("Content-type", "image/png")
      self.write(img_b.read())
  
  def generate_tile(self, data):
      TILE_SIZE = 512
      img = Image.new('RGBA', size=(TILE_SIZE, TILE_SIZE), color=(0, 0, 0, 0))
      # 这里添加基于data生成瓦片的业务逻辑
      img_b = io.BytesIO()
      img.save(img_b, "PNG")
      return img_b
  

内容的提问来源于stack exchange，提问作者toni