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/xhs/client.py

@@ -246,29 +246,6 @@ class XiaoHongShuClient(AbstractApiClient, ProxyRefreshMixin):
             **kwargs,
         )
 
-    async def get_note_media(self, url: str) -> Union[bytes, None]:
-        # Check if proxy is expired before request
-        await self._refresh_proxy_if_expired()
-
-        async with make_async_client(proxy=self.proxy) as client:
-            try:
-                response = await client.request("GET", url, timeout=self.timeout)
-                response.raise_for_status()
-                if not response.reason_phrase == "OK":
-                    utils.logger.error(
-                        f"[XiaoHongShuClient.get_note_media] request {url} err, res:{response.text}"
-                    )
-                    return None
-                else:
-                    return response.content
-            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"[XiaoHongShuClient.get_aweme_media] {exc.__class__.__name__} for {exc.request.url} - {exc}"
-                )  # Keep original exception type name for developer debugging
-                return None
-
     async def query_self(self) -> Optional[Dict]:
         """
         Query self user info to check login state

media_platform/xhs/core.py

@@ -34,6 +34,7 @@ from tenacity import RetryError
 
 import config
 from base.base_crawler import AbstractCrawler
+from media_downloader import MediaDownloader
 from model.m_xiaohongshu import NoteUrlInfo, CreatorUrlInfo
 from proxy.proxy_ip_pool import IpInfoModel, create_ip_pool
 from store import xhs as xhs_store
@@ -41,6 +42,7 @@ from tools import utils
 from tools.cdp_browser import CDPBrowserManager
 from var import crawler_type_var, source_keyword_var
 
+from . import media as xhs_media
 from .client import XiaoHongShuClient
 from .exception import (
     DataFetchError,
@@ -66,6 +68,7 @@ class XiaoHongShuCrawler(AbstractCrawler):
         self.user_agent = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36"
         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) -> None:
         playwright_proxy_format, httpx_proxy_format = None, None
@@ -176,7 +179,7 @@ class XiaoHongShuCrawler(AbstractCrawler):
                     for note_detail in note_details:
                         if note_detail:
                             await xhs_store.update_xhs_note(note_detail)
-                            await self.get_notice_media(note_detail)
+                            await self.download_media(note_detail)
                             note_ids.append(note_detail.get("note_id"))
                             xsec_tokens.append(note_detail.get("xsec_token"))
                     page += 1
@@ -253,7 +256,7 @@ class XiaoHongShuCrawler(AbstractCrawler):
         for note_detail in note_details:
             if note_detail:
                 await xhs_store.update_xhs_note(note_detail)
-                await self.get_notice_media(note_detail)
+                await self.download_media(note_detail)
 
     async def get_specified_notes(self):
         """Get the information and comments of the specified post
@@ -280,7 +283,7 @@ class XiaoHongShuCrawler(AbstractCrawler):
                 need_get_comment_note_ids.append(note_detail.get("note_id", ""))
                 xsec_tokens.append(note_detail.get("xsec_token", ""))
                 await xhs_store.update_xhs_note(note_detail)
-                await self.get_notice_media(note_detail)
+                await self.download_media(note_detail)
         await self.batch_get_note_comments(need_get_comment_note_ids, xsec_tokens)
 
     async def get_note_detail_async_task(
@@ -480,63 +483,40 @@ class XiaoHongShuCrawler(AbstractCrawler):
             await self.browser_context.close()
         utils.logger.info("[XiaoHongShuCrawler.close] Browser context closed ...")
 
-    async def get_notice_media(self, note_detail: Dict):
-        if not config.ENABLE_GET_MEIDAS:
-            utils.logger.info(f"[XiaoHongShuCrawler.get_notice_media] Crawling image mode is not enabled")
-            return
-        await self.get_note_images(note_detail)
-        await self.get_notice_video(note_detail)
-
-    async def get_note_images(self, note_item: Dict):
-        """Get note images. Please use get_notice_media
+    async def download_media(self, note_detail: Dict) -> None:
+        """下载笔记的媒体资源（封面、视频或图文图片）
 
         Args:
-            note_item: Note item dictionary
+            note_detail: 笔记详情（原始 note_card 结构）
         """
-        if not config.ENABLE_GET_MEIDAS:
+        if not config.ENABLE_GET_MEDIA:
             return
-        note_id = note_item.get("note_id")
-        image_list: List[Dict] = note_item.get("image_list", [])
+        try:
+            items = xhs_media.build_media_items(note_detail)
+            if items:
+                await self._get_media_downloader().download_all(items)
+        except Exception as exc:
+            # 媒体下载是旁路能力，解析异常/网络异常都不能中断爬取主流程
+            utils.logger.error(f"[XiaoHongShuCrawler.download_media] 媒体下载异常: {exc}")
 
-        for img in image_list:
-            if img.get("url_default") != "":
-                img.update({"url": img.get("url_default")})
+    def _get_media_downloader(self) -> MediaDownloader:
+        """惰性创建媒体下载器，并同步最新的代理设置（代理池是就地刷新的）"""
+        if self._media_downloader is None:
+            self._media_downloader = MediaDownloader(
+                platform="xhs",
+                proxy=getattr(self.xhs_client, "proxy", None),
+                extra_headers=self._media_headers(),
+            )
+        else:
+            self._media_downloader.update_credentials(
+                proxy=getattr(self.xhs_client, "proxy", None),
+                extra_headers=self._media_headers(),
+            )
+        return self._media_downloader
 
-        if not image_list:
-            return
-        picNum = 0
-        for pic in image_list:
-            url = pic.get("url")
-            if not url:
-                continue
-            content = await self.xhs_client.get_note_media(url)
-            await asyncio.sleep(random.random())
-            if content is None:
-                continue
-            extension_file_name = f"{picNum}.jpg"
-            picNum += 1
-            await xhs_store.update_xhs_note_image(note_id, content, extension_file_name)
-
-    async def get_notice_video(self, note_item: Dict):
-        """Get note videos. Please use get_notice_media
-
-        Args:
-            note_item: Note item dictionary
-        """
-        if not config.ENABLE_GET_MEIDAS:
-            return
-        note_id = note_item.get("note_id")
-
-        videos = xhs_store.get_video_url_arr(note_item)
-
-        if not videos:
-            return
-        videoNum = 0
-        for url in videos:
-            content = await self.xhs_client.get_note_media(url)
-            await asyncio.sleep(random.random())
-            if content is None:
-                continue
-            extension_file_name = f"{videoNum}.mp4"
-            videoNum += 1
-            await xhs_store.update_xhs_note_video(note_id, content, extension_file_name)
+    def _media_headers(self) -> Dict:
+        """媒体请求头：平台 Referer（防盗链）+ UA"""
+        return {
+            "Referer": "https://www.xiaohongshu.com/",
+            "User-Agent": self.user_agent,
+        }

media_platform/xhs/media.py

@@ -0,0 +1,160 @@
+# -*- 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/xhs/media.py
+# GitHub: https://github.com/NanmiCoder
+# Licensed under NON-COMMERCIAL LEARNING LICENSE 1.1
+#
+
+# 声明：本代码仅供学习和研究目的使用。使用者应遵守以下原则：
+# 1. 不得用于任何商业用途。
+# 2. 使用时应遵守目标平台的使用条款和robots.txt规则。
+# 3. 不得进行大规模爬取或对平台造成运营干扰。
+# 4. 应合理控制请求频率，避免给目标平台带来不必要的负担。
+# 5. 不得用于任何非法或不当的用途。
+#
+# 详细许可条款请参阅项目根目录下的LICENSE文件。
+# 使用本代码即表示您同意遵守上述原则和LICENSE中的所有条款。
+
+"""小红书媒体地址提取。
+
+输入是 ``/api/sns/web/v1/feed`` 返回的原始 ``note_card``（snake_case 字段），
+输出是下载器可直接消费的 ``MediaItem`` 列表。无 IO（会读取 config 决定国际版策略）。
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+import config
+from media_downloader import MediaItem, MediaType
+
+# 小红书视频 CDN：origin_video_key 拼在此域名后可拿到无水印源片
+XHS_VIDEO_CDN_HOST = "https://sns-video-bd.xhscdn.com"
+
+
+def _as_dict(value) -> Dict:
+    """接口响应里同名字段可能是字符串或 None，统一收敛为 dict"""
+    return value if isinstance(value, dict) else {}
+
+
+def _extract_origin_video_key(video_dict: Dict) -> str:
+    """从 video.consumer 中取无水印源片 key（兼容 snake_case 与 camelCase）"""
+    consumer = _as_dict(video_dict.get("consumer"))
+    return consumer.get("origin_video_key") or consumer.get("originVideoKey") or ""
+
+
+def extract_video_urls(note_item: Dict) -> List[str]:
+    """提取视频地址候选列表，按可用性排序。
+
+    优先无水印源片（origin_video_key），其余为带水印的 h264 master_url 备用。
+    国际版（rednote）的 CDN 域名与国内不同，不能拼接 xhscdn 域名。
+    """
+    if note_item.get("type") != "video":
+        return []
+
+    video_dict = _as_dict(note_item.get("video"))
+    if not video_dict:
+        return []
+
+    urls: List[str] = []
+    origin_video_key = _extract_origin_video_key(video_dict)
+    if origin_video_key and not getattr(config, "XHS_INTERNATIONAL", False):
+        urls.append(f"{XHS_VIDEO_CDN_HOST}/{origin_video_key}")
+
+    stream = _as_dict(_as_dict(video_dict.get("media")).get("stream"))
+    for item in stream.get("h264") or []:
+        master_url = item.get("master_url") if isinstance(item, dict) else None
+        if master_url and master_url not in urls:
+            urls.append(master_url)
+
+    return urls
+
+
+def extract_image_urls(note_item: Dict) -> List[str]:
+    """提取图文笔记的图片地址（按原始顺序）"""
+    urls: List[str] = []
+    for image_item in note_item.get("image_list") or []:
+        if not isinstance(image_item, dict):
+            continue
+        url = image_item.get("url_default") or image_item.get("url") or ""
+        if isinstance(url, str) and url:
+            urls.append(url)
+    return urls
+
+
+def extract_cover_url(note_item: Dict) -> str:
+    """提取封面地址。
+
+    小红书不同接口返回的封面字段位置不一致，这里按可靠性依次兜底；
+    视频笔记的 image_list 通常就是封面图，作为最后兜底。
+    """
+    video_dict = _as_dict(note_item.get("video"))
+    cover_dict = _as_dict(note_item.get("cover"))
+    video_cover = _as_dict(video_dict.get("cover"))
+
+    candidates = [
+        video_cover.get("url_default"),
+        video_cover.get("url"),
+        cover_dict.get("url_default"),
+        cover_dict.get("url"),
+    ]
+    for candidate in candidates:
+        if candidate:
+            return candidate
+
+    images = extract_image_urls(note_item)
+    return images[0] if images else ""
+
+
+def build_media_items(note_item: Dict) -> List[MediaItem]:
+    """把一个笔记转换成待下载的媒体任务列表。
+
+    - 视频笔记：封面 + 视频。其 image_list 通常只有封面一张，不再按图集重复下载
+    - 图文笔记：各张图片（第一张即封面，因此不再单独下载一份 cover）
+    """
+    if not isinstance(note_item, dict):
+        return []
+
+    content_id = note_item.get("note_id") or note_item.get("id") or ""
+    if not content_id:
+        return []
+
+    items: List[MediaItem] = []
+
+    if note_item.get("type") == "video":
+        cover_url = extract_cover_url(note_item)
+        if cover_url:
+            items.append(
+                MediaItem(
+                    url=cover_url,
+                    media_type=MediaType.IMAGE,
+                    content_id=content_id,
+                    stem="cover",
+                )
+            )
+
+        video_urls = extract_video_urls(note_item)
+        if video_urls:
+            items.append(
+                MediaItem(
+                    url=video_urls[0],
+                    backup_urls=tuple(video_urls[1:]),
+                    media_type=MediaType.VIDEO,
+                    content_id=content_id,
+                    stem="video",
+                )
+            )
+    else:
+        for index, image_url in enumerate(extract_image_urls(note_item), start=1):
+            items.append(
+                MediaItem(
+                    url=image_url,
+                    media_type=MediaType.IMAGE,
+                    content_id=content_id,
+                    stem=f"{index:03d}",
+                )
+            )
+
+    return items