fix(db,downloader): fix server error on upgrade from 3.1.x to 3.2.x (#956)

- Fix 'dict' object has no attribute 'files' in renamer by using dict
  access for qBittorrent API responses and fetching file lists via
  separate torrents/files endpoint
- Replace version-file-based migration with schema_version table to
  reliably track and apply database migrations on every startup
- Add air_weekday column migration as versioned migration entry
- Add torrents_files method to QbDownloader and Aria2Downloader

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

Author: 3 people

CHANGELOG.md

@@ -1,3 +1,21 @@
+# [3.2.0-beta.2] - 2026-01-24
+
+## Backend
+
+### Bugfixes
+
+- 修复从 3.1.x 升级后数据库缺少 `air_weekday` 列导致服务器错误的问题 (#956)
+- 修复重命名模块中 `'dict' object has no attribute 'files'` 的错误
+- 新增 `schema_version` 表追踪数据库版本，确保迁移可靠执行
+- 修复 qBittorrent 下载器中缺少 `torrents_files` API 调用的问题
+
+### Changes
+
+- 数据库迁移机制重构：使用 `schema_version` 表替代仅依赖应用版本号的迁移策略
+- 启动时始终检查并执行未完成的迁移，防止迁移中断后无法恢复
+
+---
+
 # [3.1] - 2023-08
 
 - 合并了后端和前端仓库，优化了项目目录

backend/src/module/core/program.py

@@ -9,6 +9,7 @@
     first_run,
     from_30_to_31,
     from_31_to_32,
+    run_migrations,
     start_up,
 )
 
@@ -58,6 +59,10 @@ async def startup(self):
                     logger.info("[Core] Database migrated from 3.0 to 3.1.")
                 await from_31_to_32()
                 logger.info("[Core] Database updated.")
+            else:
+                # Always check schema version and run pending migrations,
+                # in case a previous migration was interrupted or failed.
+                run_migrations()
         if not self.img_cache:
             logger.info("[Core] No image cache exists, create image cache.")
             await cache_image()

backend/src/module/database/combine.py

@@ -14,6 +14,20 @@
 
 logger = logging.getLogger(__name__)
 
+# Increment this when adding new migrations to MIGRATIONS list.
+CURRENT_SCHEMA_VERSION = 1
+
+# Each migration is a tuple of (version, description, list of SQL statements).
+# Migrations are applied in order. A migration at index i brings the schema
+# from version i to version i+1.
+MIGRATIONS = [
+    (
+        1,
+        "add air_weekday column to bangumi",
+        ["ALTER TABLE bangumi ADD COLUMN air_weekday INTEGER"],
+    ),
+]
+
 
 class Database(Session):
     def __init__(self, engine=e):
@@ -26,20 +40,64 @@ def __init__(self, engine=e):
 
     def create_table(self):
         SQLModel.metadata.create_all(self.engine)
-        self._migrate_columns()
+        self._ensure_schema_version_table()
+
+    def _ensure_schema_version_table(self):
+        """Create the schema_version table if it doesn't exist."""
+        with self.engine.connect() as conn:
+            conn.execute(text(
+                "CREATE TABLE IF NOT EXISTS schema_version ("
+                "  id INTEGER PRIMARY KEY,"
+                "  version INTEGER NOT NULL"
+                ")"
+            ))
+            conn.commit()
+
+    def _get_schema_version(self) -> int:
+        """Get the current schema version from the database."""
+        inspector = inspect(self.engine)
+        if "schema_version" not in inspector.get_table_names():
+            return 0
+        with self.engine.connect() as conn:
+            result = conn.execute(text("SELECT version FROM schema_version WHERE id = 1"))
+            row = result.fetchone()
+            return row[0] if row else 0
+
+    def _set_schema_version(self, version: int):
+        """Update the schema version in the database."""
+        with self.engine.connect() as conn:
+            conn.execute(text(
+                "INSERT OR REPLACE INTO schema_version (id, version) VALUES (1, :version)"
+            ), {"version": version})
+            conn.commit()
 
-    def _migrate_columns(self):
-        """Add new columns to existing tables if they don't exist."""
+    def run_migrations(self):
+        """Run pending schema migrations based on the stored schema version."""
+        self._ensure_schema_version_table()
+        current = self._get_schema_version()
+        if current >= CURRENT_SCHEMA_VERSION:
+            return
         inspector = inspect(self.engine)
-        if "bangumi" in inspector.get_table_names():
-            columns = [col["name"] for col in inspector.get_columns("bangumi")]
-            if "air_weekday" not in columns:
+        tables = inspector.get_table_names()
+        for version, description, statements in MIGRATIONS:
+            if version <= current:
+                continue
+            # Check if migration is actually needed (column may already exist)
+            needs_run = True
+            if "bangumi" in tables and version == 1:
+                columns = [col["name"] for col in inspector.get_columns("bangumi")]
+                if "air_weekday" in columns:
+                    needs_run = False
+            if needs_run:
                 with self.engine.connect() as conn:
-                    conn.execute(
-                        text("ALTER TABLE bangumi ADD COLUMN air_weekday INTEGER")
-                    )
+                    for stmt in statements:
+                        conn.execute(text(stmt))
                     conn.commit()
-                logger.info("[Database] Migrated: added air_weekday column to bangumi table.")
+                logger.info(f"[Database] Migration v{version}: {description}")
+            else:
+                logger.debug(f"[Database] Migration v{version} skipped (already applied): {description}")
+        self._set_schema_version(CURRENT_SCHEMA_VERSION)
+        logger.info(f"[Database] Schema version is now {CURRENT_SCHEMA_VERSION}.")
 
     def drop_table(self):
         SQLModel.metadata.drop_all(self.engine)

backend/src/module/downloader/client/aria2_downloader.py

@@ -54,6 +54,9 @@ async def logout(self):
             await self._client.aclose()
             self._client = None
 
+    async def torrents_files(self, torrent_hash: str):
+        return []
+
     async def add_torrents(self, torrent_urls, torrent_files, save_path, category):
         import base64
         options = {"dir": save_path}

backend/src/module/downloader/client/qb_downloader.py

@@ -107,6 +107,13 @@ async def torrents_info(self, status_filter, category, tag=None):
         resp = await self._client.get(self._url("torrents/info"), params=params)
         return resp.json()
 
+    @qb_connect_failed_wait
+    async def torrents_files(self, torrent_hash: str):
+        resp = await self._client.get(
+            self._url("torrents/files"), params={"hash": torrent_hash}
+        )
+        return resp.json()
+
     async def add_torrents(self, torrent_urls, torrent_files, save_path, category):
         data = {
             "savepath": save_path,

backend/src/module/downloader/download_client.py

@@ -107,6 +107,9 @@ async def get_torrent_info(self, category="Bangumi", status_filter="completed",
             status_filter=status_filter, category=category, tag=tag
         )
 
+    async def get_torrent_files(self, torrent_hash: str):
+        return await self.client.torrents_files(torrent_hash=torrent_hash)
+
     async def rename_torrent_file(self, _hash, old_path, new_path) -> bool:
         logger.info(f"{old_path} >> {new_path}")
         return await self.client.torrents_rename_file(

backend/src/module/downloader/path.py

@@ -18,11 +18,11 @@ def __init__(self):
         pass
 
     @staticmethod
-    def check_files(info):
+    def check_files(files: list[dict]):
         media_list = []
         subtitle_list = []
-        for f in info.files:
-            file_name = f.name
+        for f in files:
+            file_name = f["name"]
             suffix = Path(file_name).suffix
             if suffix.lower() in [".mp4", ".mkv"]:
                 media_list.append(file_name)

backend/src/module/manager/renamer.py

@@ -143,14 +143,18 @@ async def rename(self) -> list[Notification]:
         torrents_info = await self.get_torrent_info()
         renamed_info: list[Notification] = []
         for info in torrents_info:
-            media_list, subtitle_list = self.check_files(info)
-            bangumi_name, season = self._path_to_bangumi(info.save_path)
+            torrent_hash = info["hash"]
+            torrent_name = info["name"]
+            save_path = info["save_path"]
+            files = await self.get_torrent_files(torrent_hash)
+            media_list, subtitle_list = self.check_files(files)
+            bangumi_name, season = self._path_to_bangumi(save_path)
             kwargs = {
-                "torrent_name": info.name,
+                "torrent_name": torrent_name,
                 "bangumi_name": bangumi_name,
                 "method": rename_method,
                 "season": season,
-                "_hash": info.hash,
+                "_hash": torrent_hash,
             }
             # Rename single media file
             if len(media_list) == 1:
@@ -166,9 +170,9 @@ async def rename(self) -> list[Notification]:
                 await self.rename_collection(media_list=media_list, **kwargs)
                 if len(subtitle_list) > 0:
                     await self.rename_subtitles(subtitle_list=subtitle_list, **kwargs)
-                await self.set_category(info.hash, "BangumiCollection")
+                await self.set_category(torrent_hash, "BangumiCollection")
             else:
-                logger.warning(f"[Renamer] {info.name} has no media file")
+                logger.warning(f"[Renamer] {torrent_name} has no media file")
         logger.debug("[Renamer] Rename process finished.")
         return renamed_info
 

backend/src/module/update/__init__.py

@@ -1,4 +1,4 @@
-from .cross_version import cache_image, from_30_to_31, from_31_to_32
+from .cross_version import cache_image, from_30_to_31, from_31_to_32, run_migrations
 from .data_migration import data_migration
 from .startup import first_run, start_up
 from .version_check import version_check

backend/src/module/update/cross_version.py

@@ -38,10 +38,17 @@ async def from_30_to_31():
 async def from_31_to_32():
     """Migrate database schema from 3.1.x to 3.2.x."""
     with RSSEngine() as db:
-        db.create_table()  # Handles adding new columns (e.g., air_weekday)
+        db.create_table()
+        db.run_migrations()
     logger.info("[Migration] 3.1 -> 3.2 migration completed.")
 
 
+def run_migrations():
+    """Check schema version and run any pending migrations."""
+    with RSSEngine() as db:
+        db.run_migrations()
+
+
 async def cache_image():
     with RSSEngine() as db:
         bangumis = db.bangumi.search_all()