Music Tag Web 导入卡住，最后发现是 Celery 时区的问题

从树莓派迁移到飞牛OS之后，导入音乐一直卡着不动，日志里报无权限。重新部署了三四次，SQLite 和 MySQL 都试过，结果一模一样。当时还以为是激活次数到了，折腾了半天。

排查过程

树莓派上一直跑的是 V2.6，没出过问题。换到飞牛OS（x86 N200）之后就成这样了。其他功能还没测，光导入这一步就过不去。

后来在社区里看到有人遇到同样的情况，对方提到设置正确的时区后 Celery 就正常了。这才把方向转到时区上。

为什么时区会影响导入

Music Tag Web 的导入、刮削这些耗时操作，背后靠 Celery 跑异步任务。Celery 需要准确的时间来判断任务什么时候执行、有没有过期。

Docker 容器默认用的是 UTC 时间，飞牛OS 宿主机是北京时间，两者差 8 小时。容器里的时间比实际慢 8 小时，Celery 调度器看到的时间戳对不上，任务就可能被判定成过期，或者卡在队列里不执行。表现出来就是页面上点了导入，后台压根没跑起来。

Celery 官方文档里也写了，周期性任务调度默认走 UTC，时区配错的话任务触发时间会错乱。有开发者在 GitHub 上反馈过，配了 PST 时区之后任务被调度到了 16 小时以后。

解决办法

在 docker-compose.yml 里加上时区配置：

yaml 复制代码

services:
  music-tag:
    image: xhongc/music_tag_web:latest
    container_name: music-tag-web
    ports:
      - "8001:8001"
      - "8002:8002"
    volumes:
      - /vol2/1000/AudioRepo2/music:/app/media/music2
      - ./data:/app/data
      - ./download:/app/download
      - /etc/localtime:/etc/localtime:ro
    environment:
      - TZ=Asia/Shanghai
    restart: always

挂载 /etc/localtime 和设置 TZ 环境变量，选一个就行，两个都加也没问题。改完 docker compose down 再 up -d，Celery 的时间就和本地同步了，导入功能恢复正常。

社区里的其他情况

有人是直接去数据库里改调度任务的时间，这个方法能用，但对普通用户来说太麻烦了，而且容器一重建问题还会回来。

Music Tag Web 的官方 FAQ 里提到过"容器内的时间校正为北京时间，不要相差超过一分钟"，但没给出具体怎么配。如果部署文档的示例 compose 里直接加上 TZ 或者挂载 /etc/localtime，能省掉不少麻烦。

小结

NAS 上跑 Docker 应用，时区不对的话异步任务容易出问题。加一行 TZ 配置就能解决的事，愣是让我重装了三四次。