feat(media): 重构媒体下载，支持 xhs/dy/ks/bili/wb 五平台

旧实现只覆盖 4 个平台，且把整个文件读进内存、无重试与完整性校验，
代码按平台复制粘贴了 4 份。本次用统一下载器替换：

- 新增 media_downloader/：流式写入、Range 续传、指数退避重试、大小校验、
  路径穿越防护；B 站 DASH 音视频分轨下载后交由 ffmpeg 无损合流
- 新增 media_platform/<平台>/media.py：从平台原始响应提取媒体地址，
  与下载器解耦；快手首次接入下载能力
- 开关：config.ENABLE_GET_MEDIA 与 --get_media，并打通 API/WebUI；
  同时修正旧配置项 ENABLE_GET_MEIDAS 的拼写
- 落盘按帖子聚合：{SAVE_DATA_PATH 或 data}/{platform}/media/{内容ID}/
- B 站装好 ffmpeg 时走 DASH 最高画质，否则降级 mp4 直链（产物 video-durl.mp4，
  避免低清文件阻塞后续的高清路径）
- 删除 4 个 *_store_media.py、AbstractStoreImage/Video 及各 client 的媒体 GET 方法

媒体下载失败只记录日志，不中断爬取主流程。

media_platform/bilibili/client.py

@@ -42,6 +42,7 @@ if TYPE_CHECKING:
 from .exception import DataFetchError
 from .field import CommentOrderType, SearchOrderType
 from .help import BilibiliSign
+from .media import DASH_FNVAL
 
 
 def _extract_pinned_comments(value: Any) -> List[Dict]:
@@ -213,11 +214,13 @@ class BilibiliClient(AbstractApiClient, ProxyRefreshMixin):
             params.update({"bvid": bvid})
         return await self.get(uri, params, enable_params_sign=False)
 
-    async def get_video_play_url(self, aid: int, cid: int) -> Dict:
+    async def get_video_play_url(self, aid: int, cid: int, fnval: int = DASH_FNVAL) -> Dict:
         """
         Bilibli web video play url api
         :param aid: Video aid
         :param cid: cid
+        :param fnval: 请求的媒体格式位掩码，默认请求 DASH（含 4K/8K/HDR/AV1）；
+                      传 1 则请求音视频合一的 mp4 直链
         :return:
         """
         if not aid or not cid or aid <= 0 or cid <= 0:
@@ -229,28 +232,12 @@ class BilibiliClient(AbstractApiClient, ProxyRefreshMixin):
             "cid": cid,
             "qn": qn_value,
             "fourk": 1,
-            "fnval": 1,
+            "fnval": fnval,
             "platform": "pc",
         }
 
         return await self.get(uri, params, enable_params_sign=True)
 
-    async def get_video_media(self, url: str) -> Union[bytes, None]:
-        # Follow CDN 302 redirects and treat any 2xx as success (some endpoints return 206)
-        async with make_async_client(proxy=self.proxy, follow_redirects=True) as client:
-            try:
-                response = await client.request("GET", url, timeout=self.timeout, headers=self.headers)
-                response.raise_for_status()
-                if 200 <= response.status_code < 300:
-                    return response.content
-                utils.logger.error(
-                    f"[BilibiliClient.get_video_media] Unexpected status {response.status_code} for {url}"
-                )
-                return None
-            except httpx.HTTPError as exc:  # some wrong when call httpx.request method, such as connection error, client error, server error or response status code is not 2xx
-                utils.logger.error(f"[BilibiliClient.get_video_media] {exc.__class__.__name__} for {exc.request.url} - {exc}")  # Keep original exception type name for developer debugging
-                return None
-
     async def get_video_comments(
         self,
         video_id: str,

media_platform/bilibili/core.py

@@ -41,12 +41,14 @@ from playwright._impl._errors import TargetClosedError
 
 import config
 from base.base_crawler import AbstractCrawler
+from media_downloader import MediaDownloader, is_ffmpeg_available
 from proxy.proxy_ip_pool import IpInfoModel, create_ip_pool
 from store import bilibili as bilibili_store
 from tools import utils
 from tools.cdp_browser import CDPBrowserManager
 from var import crawler_type_var, source_keyword_var
 
+from . import media as bili_media
 from .client import BilibiliClient
 from .exception import DataFetchError
 from .field import SearchOrderType
@@ -66,6 +68,7 @@ class BilibiliCrawler(AbstractCrawler):
         self.user_agent = utils.get_user_agent()
         self.cdp_manager = None
         self.ip_proxy_pool = None  # Proxy IP pool for automatic proxy refresh
+        self._media_downloader: Optional[MediaDownloader] = None
 
     async def start(self):
         playwright_proxy_format, httpx_proxy_format = None, None
@@ -228,7 +231,7 @@ class BilibiliCrawler(AbstractCrawler):
                         video_id_list.append(video_item.get("View").get("aid"))
                         await bilibili_store.update_bilibili_video(video_item)
                         await bilibili_store.update_up_info(video_item)
-                        await self.get_bilibili_video(video_item, semaphore)
+                        await self.download_media(video_item, semaphore)
                 page += 1
 
                 # Sleep after page navigation
@@ -308,7 +311,7 @@ class BilibiliCrawler(AbstractCrawler):
                                 video_id_list.append(video_item.get("View").get("aid"))
                                 await bilibili_store.update_bilibili_video(video_item)
                                 await bilibili_store.update_up_info(video_item)
-                                await self.get_bilibili_video(video_item, semaphore)
+                                await self.download_media(video_item, semaphore)
 
                         page += 1
 
@@ -413,7 +416,7 @@ class BilibiliCrawler(AbstractCrawler):
                     video_aids_list.append(video_aid)
                 await bilibili_store.update_bilibili_video(video_detail)
                 await bilibili_store.update_up_info(video_detail)
-                await self.get_bilibili_video(video_detail, semaphore)
+                await self.download_media(video_detail, semaphore)
         await self.batch_get_video_comments(video_aids_list)
 
     async def get_video_info_task(self, aid: int, bvid: str, semaphore: asyncio.Semaphore) -> Optional[Dict]:
@@ -440,17 +443,24 @@ class BilibiliCrawler(AbstractCrawler):
                 utils.logger.error(f"[BilibiliCrawler.get_video_info_task] have not fund note detail video_id:{bvid}, err: {ex}")
                 return None
 
-    async def get_video_play_url_task(self, aid: int, cid: int, semaphore: asyncio.Semaphore) -> Union[Dict, None]:
+    async def get_video_play_url_task(
+        self,
+        aid: int,
+        cid: int,
+        semaphore: asyncio.Semaphore,
+        fnval: int = bili_media.DASH_FNVAL,
+    ) -> Union[Dict, None]:
         """
         Get video play url
         :param aid:
         :param cid:
         :param semaphore:
+        :param fnval: 媒体格式位掩码，默认请求 DASH 分轨流
         :return:
         """
         async with semaphore:
             try:
-                result = await self.bili_client.get_video_play_url(aid=aid, cid=cid)
+                result = await self.bili_client.get_video_play_url(aid=aid, cid=cid, fnval=fnval)
                 return result
             except DataFetchError as ex:
                 utils.logger.error(f"[BilibiliCrawler.get_video_play_url_task] Get video play url error: {ex}")
@@ -570,42 +580,128 @@ class BilibiliCrawler(AbstractCrawler):
         except Exception as e:
             utils.logger.error(f"[BilibiliCrawler.close] An error occurred during close: {e}")
 
-    async def get_bilibili_video(self, video_item: Dict, semaphore: asyncio.Semaphore):
+    async def download_media(self, video_item: Dict, semaphore: asyncio.Semaphore):
+        """下载 B 站视频与封面。
+
+        优先走 DASH（音视频分轨 + ffmpeg 合流，画质最好）；本机没有 ffmpeg
+        或 DASH 流不可用时，降级为 mp4 直链（音视频合一，清晰度受接口限制）。
+
+        :param video_item: 视频详情，需包含 View 字段（含 aid/cid/pic/bvid）
+        :param semaphore: 用于限制 playurl 接口请求并发
         """
-        download bilibili video
-        :param video_item:
-        :param semaphore:
-        :return:
-        """
-        if not config.ENABLE_GET_MEIDAS:
-            utils.logger.info(f"[BilibiliCrawler.get_bilibili_video] Crawling image mode is not enabled")
+        if not config.ENABLE_GET_MEDIA:
             return
-        video_item_view: Dict = video_item.get("View")
+        try:
+            await self._download_media(video_item, semaphore)
+        except Exception as exc:
+            # 媒体下载是旁路能力：playurl 是额外的接口调用，网络抖动不能中断爬取主流程
+            utils.logger.error(f"[BilibiliCrawler.download_media] 媒体下载异常: {exc}")
+
+    async def _download_media(self, video_item: Dict, semaphore: asyncio.Semaphore) -> None:
+        video_item_view: Dict = video_item.get("View") or {}
         aid = video_item_view.get("aid")
         cid = video_item_view.get("cid")
-        result = await self.get_video_play_url_task(aid, cid, semaphore)
-        if result is None:
-            utils.logger.info("[BilibiliCrawler.get_bilibili_video] get video play url failed")
-            return
-        durl_list = result.get("durl")
-        max_size = -1
-        video_url = ""
-        for durl in durl_list:
-            size = durl.get("size")
-            if size > max_size:
-                max_size = size
-                video_url = durl.get("url")
-        if video_url == "":
-            utils.logger.info("[BilibiliCrawler.get_bilibili_video] get video url failed")
+        content_id = video_item_view.get("bvid") or (str(aid) if aid else "")
+        if not content_id:
+            utils.logger.warning("[BilibiliCrawler.download_media] 缺少 aid/bvid，跳过媒体下载")
             return
 
-        content = await self.bili_client.get_video_media(video_url)
-        await asyncio.sleep(config.CRAWLER_MAX_SLEEP_SEC)
-        utils.logger.info(f"[BilibiliCrawler.get_bilibili_video] Sleeping for {config.CRAWLER_MAX_SLEEP_SEC} seconds after fetching video {aid}")
-        if content is None:
+        downloader = self._get_media_downloader()
+
+        cover_item = bili_media.build_cover_item(video_item_view, content_id)
+        if cover_item is not None:
+            await downloader.download(cover_item)
+
+        if not aid or not cid:
+            utils.logger.warning("[BilibiliCrawler.download_media] 缺少 aid/cid，无法获取播放地址")
             return
-        extension_file_name = f"video.mp4"
-        await bilibili_store.store_video(aid, content, extension_file_name)
+
+        # ffmpeg 是否可用在请求之前就是确定的（进程内缓存），据此一次性决定 fnval：
+        # 没装 ffmpeg 却先按 DASH 请求一次，既多打一次风控最敏感的 playurl 接口，
+        # 也拿不到可用的 durl
+        dash_supported = is_ffmpeg_available()
+        play_fnval = bili_media.DASH_FNVAL if dash_supported else bili_media.MP4_FNVAL
+        play_info = await self.get_video_play_url_task(aid, cid, semaphore, fnval=play_fnval)
+        await asyncio.sleep(config.CRAWLER_MAX_SLEEP_SEC)
+        if play_info is None:
+            utils.logger.error("[BilibiliCrawler.download_media] 获取播放地址失败")
+            return
+
+        if dash_supported:
+            # 逐档降级：未登录或权限不足时 B 站会返回高清晰度 URL，但实际取流被 CDN 403，
+            # 此时退到更低的可用档位往往能成功，比直接放弃（或退回更低质的直链）更好
+            quality: Optional[int] = getattr(config, "BILI_QN", 80)
+            while quality is not None:
+                dash_item = bili_media.build_dash_item(play_info, content_id, preferred_quality=quality)
+                if dash_item is None:
+                    break
+                if await downloader.download(dash_item) is not None:
+                    return
+                lower_quality = bili_media.next_lower_quality(play_info, quality)
+                if lower_quality is None:
+                    break
+                utils.logger.warning(
+                    f"[BilibiliCrawler.download_media] 清晰度 {quality} 取流失败，降级到 {lower_quality}"
+                )
+                quality = lower_quality
+
+            utils.logger.warning("[BilibiliCrawler.download_media] DASH 路径失败，降级为 mp4 直链")
+        else:
+            utils.logger.info("[BilibiliCrawler.download_media] 未检测到 ffmpeg，使用 mp4 直链下载（低清晰度）")
+
+        durl_play_info = play_info
+        durl_item = bili_media.build_durl_item(durl_play_info, content_id)
+        if durl_item is None:
+            # DASH 请求不会返回 durl，需要再按 mp4 格式请求一次
+            durl_play_info = await self.get_video_play_url_task(
+                aid, cid, semaphore, fnval=bili_media.MP4_FNVAL
+            ) or {}
+            await asyncio.sleep(config.CRAWLER_MAX_SLEEP_SEC)
+            durl_item = bili_media.build_durl_item(durl_play_info, content_id)
+
+        if durl_item is None:
+            utils.logger.error(
+                f"[BilibiliCrawler.download_media] 未能获取到视频直链 aid={aid} cid={cid}"
+            )
+            return
+
+        segment_count = bili_media.count_durl_segments(durl_play_info)
+        if segment_count > 1:
+            utils.logger.warning(
+                f"[BilibiliCrawler.download_media] 该视频直链被切成 {segment_count} 段，"
+                f"当前仅下载体积最大的一段，文件可能不完整；"
+                f"确认本机 ffmpeg 可用后走 DASH 路径可获取完整视频"
+            )
+
+        await downloader.download(durl_item)
+
+    def _get_media_downloader(self) -> MediaDownloader:
+        """惰性创建媒体下载器，并同步最新的代理与 Cookie（两者都会就地刷新）"""
+        if self._media_downloader is None:
+            self._media_downloader = MediaDownloader(
+                platform="bili",
+                proxy=getattr(self.bili_client, "proxy", None),
+                extra_headers=self._media_headers(),
+            )
+        else:
+            self._media_downloader.update_credentials(
+                proxy=getattr(self.bili_client, "proxy", None),
+                extra_headers=self._media_headers(),
+            )
+        return self._media_downloader
+
+    def _media_headers(self) -> Dict:
+        """媒体请求头：平台 Referer（防盗链）+ UA。
+
+        B 站清晰度由 playurl 接口依据 Cookie 决定，返回的直链里已固化流版本，
+        且带 deadline/upsig 签名，下载本身不需要 Cookie（已实测无 Cookie 可直接取流），
+        因此不透传 Cookie，避免把账号凭证扩散到 CDN 域名。
+        """
+        headers = {"Referer": "https://www.bilibili.com/"}
+        client_headers = getattr(self.bili_client, "headers", {}) or {}
+        if client_headers.get("User-Agent"):
+            headers["User-Agent"] = client_headers["User-Agent"]
+        return headers
 
     async def get_all_creator_details(self, creator_url_list: List[str]):
         """

media_platform/bilibili/media.py

@@ -0,0 +1,202 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2025 relakkes@gmail.com
+#
+# This file is part of MediaCrawler project.
+# Repository: https://github.com/NanmiCoder/MediaCrawler/blob/main/media_platform/bilibili/media.py
+# GitHub: https://github.com/NanmiCoder
+# Licensed under NON-COMMERCIAL LEARNING LICENSE 1.1
+#
+
+# 声明：本代码仅供学习和研究目的使用。使用者应遵守以下原则：
+# 1. 不得用于任何商业用途。
+# 2. 使用时应遵守目标平台的使用条款和robots.txt规则。
+# 3. 不得进行大规模爬取或对平台造成运营干扰。
+# 4. 应合理控制请求频率，避免给目标平台带来不必要的负担。
+# 5. 不得用于任何非法或不当的用途。
+#
+# 详细许可条款请参阅项目根目录下的LICENSE文件。
+# 使用本代码即表示您同意遵守上述原则和LICENSE中的所有条款。
+
+"""B 站媒体地址提取与流选择。
+
+B 站的播放地址需要先调 playurl 接口获取：
+- ``fnval=DASH_FNVAL`` 返回音视频分轨的 DASH 流，画质最好，但需要 ffmpeg 合流
+- ``fnval=MP4_FNVAL`` 返回音视频合一的 mp4 直链，无需外部依赖，但清晰度受限
+
+本模块只做纯计算，接口调用与降级编排由 core 负责。
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+import config
+from media_downloader import MediaItem, MediaType
+
+# fnval 位掩码：16(DASH) | 64(HDR) | 128(4K) | 256(Dolby Audio) | 512(Dolby Vision) | 1024(8K) | 2048(AV1)
+DASH_FNVAL = 4048
+# 请求音视频合一的 mp4 直链
+MP4_FNVAL = 1
+
+# B 站 codecid：7=AVC(H.264) 12=HEVC(H.265) 13=AV1 14=AV2
+# 同一清晰度下优先 AVC：下载后的文件要进剪辑软件/播放器，H.264 的兼容性最好
+_CODEC_PRIORITY = {7: 0, 13: 1, 12: 2}
+_UNKNOWN_CODEC_PRIORITY = 3
+
+
+def _as_dict(value) -> Dict:
+    """接口响应里同名字段可能是字符串或 None，统一收敛为 dict"""
+    return value if isinstance(value, dict) else {}
+
+
+def _stream_url(stream) -> str:
+    if not isinstance(stream, dict):
+        return ""
+    return stream.get("base_url") or stream.get("baseUrl") or ""
+
+
+def _to_int(value, default: int = 0) -> int:
+    """接口偶尔把 id/bandwidth 返回成字符串，排序与比较前统一转 int"""
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _stream_sort_key(stream: Dict) -> tuple:
+    """同清晰度下把兼容性最好的编码排在后面（取 [-1] 即选中它）"""
+    codec_rank = _CODEC_PRIORITY.get(_to_int(stream.get("codecid"), -1), _UNKNOWN_CODEC_PRIORITY)
+    return (_to_int(stream.get("id")), -codec_rank, _to_int(stream.get("bandwidth")))
+
+
+def _stream_backup_urls(stream) -> tuple:
+    if not isinstance(stream, dict):
+        return ()
+    backups = stream.get("backup_url") or stream.get("backupUrl") or []
+    return tuple(url for url in backups if isinstance(url, str) and url)
+
+
+def build_cover_item(view: Dict, content_id: str) -> Optional[MediaItem]:
+    """封面地址来自稿件详情里的 pic 字段"""
+    cover_url = _as_dict(view).get("pic")
+    if not isinstance(cover_url, str) or not cover_url:
+        return None
+    return MediaItem(
+        url=cover_url,
+        media_type=MediaType.IMAGE,
+        content_id=content_id,
+        stem="cover",
+    )
+
+
+def pick_video_stream(play_info: Dict, preferred_quality: Optional[int] = None) -> Optional[Dict]:
+    """挑选视频流：优先不超过用户清晰度设置的最高档，都超出时取最低档。
+
+    同一清晰度可能同时提供 AVC/HEVC/AV1 多种编码，按 ``_CODEC_PRIORITY``
+    取兼容性最好的那一种（排序 key 让优先级高的排在末尾）。
+    """
+    if preferred_quality is None:
+        preferred_quality = getattr(config, "BILI_QN", 80)
+
+    dash = _as_dict(play_info).get("dash")
+    if not isinstance(dash, dict):
+        return None
+    streams = [stream for stream in (dash.get("video") or []) if _stream_url(stream)]
+    if not streams:
+        return None
+
+    streams.sort(key=_stream_sort_key)
+    within_quality = [stream for stream in streams if _to_int(stream.get("id")) <= preferred_quality]
+    if within_quality:
+        return within_quality[-1]
+
+    # 所有档位都超过用户设置时取最低清晰度，但编码优先级仍要生效：
+    # 排序把每个 id 档内兼容性最好的编码放在该档最后，所以要在同 id 组里取最后一个
+    lowest_id = _to_int(streams[0].get("id"))
+    same_quality = [stream for stream in streams if _to_int(stream.get("id")) == lowest_id]
+    return same_quality[-1]
+
+
+def pick_audio_stream(play_info: Dict) -> Optional[Dict]:
+    """音频流取码率最高的一档（id 越大码率越高）"""
+    dash = _as_dict(play_info).get("dash")
+    if not isinstance(dash, dict):
+        return None
+    streams = [stream for stream in (dash.get("audio") or []) if _stream_url(stream)]
+    if not streams:
+        return None
+    return max(streams, key=lambda stream: (_to_int(stream.get("id")), _to_int(stream.get("bandwidth"))))
+
+
+def build_dash_item(play_info: Dict, content_id: str, preferred_quality: Optional[int] = None) -> Optional[MediaItem]:
+    """构建 DASH 下载任务（视频轨 + 音频轨，交由下载器用 ffmpeg 合流）"""
+    video_stream = pick_video_stream(play_info, preferred_quality)
+    audio_stream = pick_audio_stream(play_info)
+    if video_stream is None or audio_stream is None:
+        return None
+
+    return MediaItem(
+        url=_stream_url(video_stream),
+        backup_urls=_stream_backup_urls(video_stream),
+        audio_url=_stream_url(audio_stream),
+        audio_backup_urls=_stream_backup_urls(audio_stream),
+        media_type=MediaType.VIDEO,
+        content_id=content_id,
+        stem="video",
+    )
+
+
+def available_qualities(play_info: Dict) -> List[int]:
+    """响应中实际可用的视频清晰度档位（从高到低）"""
+    dash = _as_dict(play_info).get("dash")
+    if not isinstance(dash, dict):
+        return []
+    qualities = {
+        _to_int(stream.get("id"))
+        for stream in (dash.get("video") or [])
+        if _stream_url(stream)
+    }
+    return sorted(qualities, reverse=True)
+
+
+def next_lower_quality(play_info: Dict, current_quality: int) -> Optional[int]:
+    """比 ``current_quality`` 更低的下一个可用档位，没有则返回 None。
+
+    用于"playurl 给了高清地址但 CDN 拒绝下载"时逐档降级
+    （未登录或权限不足时 B 站会返回高清晰度 URL，但实际取流会被 403）。
+    """
+    lower = [quality for quality in available_qualities(play_info) if quality < current_quality]
+    return lower[0] if lower else None
+
+
+def count_durl_segments(play_info: Dict) -> int:
+    """durl 的分段数量。大于 1 表示整片被切分，只下最大一段会得到不完整的文件。"""
+    return len(
+        [
+            entry
+            for entry in _as_dict(play_info).get("durl") or []
+            if isinstance(entry, dict) and entry.get("url")
+        ]
+    )
+
+
+def build_durl_item(play_info: Dict, content_id: str) -> Optional[MediaItem]:
+    """构建 mp4 直链下载任务（取体积最大的一段）。
+
+    stem 刻意与 DASH 产物（``video``）区分：直链画质受接口限制，是降级产物。
+    两者同名会让先下到的低清文件被"已存在即跳过"永久信任，
+    之后即使装好 ffmpeg 也再拿不到高清。
+    """
+    durl_list: List[Dict] = _as_dict(play_info).get("durl") or []
+    candidates = [entry for entry in durl_list if isinstance(entry, dict) and entry.get("url")]
+    if not candidates:
+        return None
+
+    best = max(candidates, key=lambda entry: _to_int(entry.get("size")))
+    return MediaItem(
+        url=best["url"],
+        backup_urls=tuple(best.get("backup_url") or ()),
+        media_type=MediaType.VIDEO,
+        content_id=content_id,
+        stem="video-durl",
+    )