fix: 强制刷新插件市场绕过远端缓存

app/helper/plugin.py

@@ -8,6 +8,7 @@ import site
 import sys
 import tempfile
 import threading
+import time
 import traceback
 import zipfile
 from pathlib import Path
@@ -25,7 +26,7 @@ from packaging.version import Version, InvalidVersion
 from importlib.metadata import distributions
 from requests import Response
 
-from app.core.cache import cached
+from app.core.cache import cached, is_fresh
 from app.core.config import settings
 from app.db.systemconfig_oper import SystemConfigOper
 from app.log import logger
@@ -397,6 +398,19 @@ class PluginHelper(metaclass=WeakSingleton):
                 return candidate
         return None
 
+    @staticmethod
+    def __append_cache_buster(url: str) -> str:
+        """
+        强制刷新插件库索引时追加时间戳，绕过 GitHub 镜像或中间代理的缓存。
+        """
+        if not is_fresh():
+            return url
+
+        parts = urlsplit(url)
+        refresh_param = f"_refresh={time.time_ns()}"
+        query = f"{parts.query}&{refresh_param}" if parts.query else refresh_param
+        return parts._replace(query=query).geturl()
+
     @staticmethod
     def __parse_plugin_index_response(content: str) -> Optional[Dict[str, dict]]:
         """
@@ -432,6 +446,7 @@ class PluginHelper(metaclass=WeakSingleton):
 
         raw_url = self._base_url.format(user=user, repo=repo)
         package_url = f"{raw_url}package.{package_version}.json" if package_version else f"{raw_url}package.json"
+        package_url = self.__append_cache_buster(package_url)
 
         res = self.__request_with_fallback(package_url, headers=settings.REPO_GITHUB_HEADERS(repo=f"{user}/{repo}"))
         if res is None:
@@ -1934,6 +1949,7 @@ class PluginHelper(metaclass=WeakSingleton):
 
         raw_url = self._base_url.format(user=user, repo=repo)
         package_url = f"{raw_url}package.{package_version}.json" if package_version else f"{raw_url}package.json"
+        package_url = self.__append_cache_buster(package_url)
 
         res = await self.__async_request_with_fallback(package_url,
                                                        headers=settings.REPO_GITHUB_HEADERS(repo=f"{user}/{repo}"))

tests/test_plugin_helper.py

@@ -33,6 +33,28 @@ class PluginHelperTest(TestCase):
             PluginHelper.sanitize_repo_url_for_statistic(repo_url)
         )
 
+    def test_append_cache_buster_only_during_fresh_context(self):
+        """
+        插件库强制刷新时远端索引 URL 也要变化，避免命中镜像或代理缓存。
+        """
+        try:
+            from app.core.cache import fresh
+            from app.helper.plugin import PluginHelper
+        except ModuleNotFoundError as exc:
+            self.skipTest(f"missing dependency: {exc}")
+
+        url = "https://raw.githubusercontent.com/user/repo/main/package.json"
+
+        self.assertEqual(url, PluginHelper._PluginHelper__append_cache_buster(url))
+        with patch("app.helper.plugin.time.time_ns", return_value=1234567890):
+            with fresh(True):
+                refreshed_url = PluginHelper._PluginHelper__append_cache_buster(url)
+
+        self.assertEqual(
+            "https://raw.githubusercontent.com/user/repo/main/package.json?_refresh=1234567890",
+            refreshed_url,
+        )
+
     def test_check_plugin_system_version_allows_missing_field(self):
         """
         未声明主系统版本范围时保持旧插件兼容，不做额外限制。