nonebot-plugin-proxy-probe 0.2.2__py3-none-any.whl

nonebot_plugin_proxy_probe/__init__.py

@@ -0,0 +1,26 @@
+"""NoneBot 代理扫描与缓存插件。"""
+
+from nonebot import require
+from nonebot.plugin import PluginMetadata
+
+require("nonebot_plugin_localstore")
+
+from .config import PluginConfig  # noqa: E402
+
+__plugin_meta__ = PluginMetadata(
+    name="代理扫描",
+    description="扫描并缓存 Clash HTTP 代理、出口 IP 与属地",
+    usage=(
+        "/proxy 显示缓存结果\n"
+        "/proxy -h 或 --help 显示帮助\n"
+        "/proxy -i <IPv4> 或 --ip <IPv4> 设置目标参考 IP\n"
+        "/proxy -p 或 --probe 重新扫描\n"
+        "/proxy -r 或 --refresh 刷新缓存\n"
+        "/proxy -s 或 --stop 停止后台任务"
+    ),
+    type="application",
+    supported_adapters={"~onebot.v11"},
+    config=PluginConfig,
+)
+
+from . import commands as commands  # noqa: E402,F401

nonebot_plugin_proxy_probe/cache.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import ipaddress
+import json
+import os
+import threading
+from pathlib import Path
+
+from nonebot import require
+
+require("nonebot_plugin_localstore")
+
+import nonebot_plugin_localstore as localstore  # noqa: E402
+
+from .models import CacheState  # noqa: E402
+
+
+DATA_DIR: Path = localstore.get_plugin_data_dir()
+CACHE_PATH = DATA_DIR / "proxy_cache.json"
+SETTINGS_PATH = DATA_DIR / "settings.json"
+_CACHE_LOCK = threading.RLock()
+
+
+def _write_json(path: Path, data: dict[str, object]) -> None:
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    payload = json.dumps(data, ensure_ascii=False, indent=2)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    temporary.write_text(payload, encoding="utf-8")
+    os.replace(temporary, path)
+
+
+def load_cache() -> CacheState:
+    with _CACHE_LOCK:
+        try:
+            raw = json.loads(CACHE_PATH.read_text(encoding="utf-8"))
+        except (FileNotFoundError, json.JSONDecodeError, OSError):
+            return CacheState()
+        if not isinstance(raw, dict):
+            return CacheState()
+        try:
+            state = CacheState.from_dict(raw)
+        except (TypeError, ValueError):
+            return CacheState()
+
+        # Bot 重启后不存在可恢复的工作线程，不能继续显示“运行中”。
+        if state.running:
+            state.running = False
+            state.task_status = "任务因 Bot 重启而中止"
+        return state
+
+
+def save_cache(state: CacheState) -> None:
+    with _CACHE_LOCK:
+        _write_json(CACHE_PATH, state.to_dict())
+
+
+def load_target_ip() -> str:
+    """读取用户通过命令持久化设置的目标参考 IPv4。"""
+    with _CACHE_LOCK:
+        try:
+            raw = json.loads(SETTINGS_PATH.read_text(encoding="utf-8"))
+        except (FileNotFoundError, json.JSONDecodeError, OSError):
+            return ""
+    if not isinstance(raw, dict):
+        return ""
+    value = str(raw.get("target_ip") or "").strip()
+    try:
+        return str(ipaddress.IPv4Address(value)) if value else ""
+    except ValueError:
+        return ""
+
+
+def save_target_ip(target_ip: str) -> None:
+    normalized = str(ipaddress.IPv4Address(target_ip))
+    with _CACHE_LOCK:
+        _write_json(
+            SETTINGS_PATH,
+            {
+                "version": 1,
+                "target_ip": normalized,
+            },
+        )

nonebot_plugin_proxy_probe/commands.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import ipaddress
+
+from nonebot import on_command
+from nonebot.adapters.onebot.v11 import (
+    Bot,
+    GroupMessageEvent,
+    Message,
+    MessageEvent,
+)
+from nonebot.log import logger
+from nonebot.params import CommandArg
+
+from .manager import manager
+
+
+USAGE = (
+    "用法：\n"
+    "/proxy 显示缓存结果\n"
+    "/proxy -h 或 --help 显示命令帮助\n"
+    "/proxy -i <IPv4> 或 --ip <IPv4> 设置目标参考 IP\n"
+    "/proxy -p 或 --probe 重新扫描\n"
+    "/proxy -r 或 --refresh 刷新缓存\n"
+    "/proxy -s 或 --stop 停止后台任务"
+)
+
+
+def parse_command(argument: str) -> tuple[str, str] | None:
+    normalized = " ".join(argument.strip().split())
+    actions = {
+        "": ("show", ""),
+        "-h": ("help", ""),
+        "--help": ("help", ""),
+        "-p": ("probe", ""),
+        "--probe": ("probe", ""),
+        "-r": ("refresh", ""),
+        "--refresh": ("refresh", ""),
+        "-s": ("stop", ""),
+        "--stop": ("stop", ""),
+    }
+    exact = actions.get(normalized)
+    if exact is not None:
+        return exact
+
+    if normalized.startswith("--ip="):
+        return "ip", normalized.partition("=")[2].strip()
+    fields = normalized.split(" ", 1)
+    if fields[0] in {"-i", "--ip"}:
+        return "ip", fields[1].strip() if len(fields) == 2 else ""
+    return None
+
+
+def parse_action(argument: str) -> str | None:
+    """保留简单动作解析接口，供旧调用方兼容。"""
+    parsed = parse_command(argument)
+    return parsed[0] if parsed is not None else None
+
+
+async def set_emoji(
+    bot: Bot,
+    event: MessageEvent,
+    emoji_id: str,
+) -> None:
+    if not isinstance(event, GroupMessageEvent):
+        return
+    try:
+        await bot.call_api(
+            "set_msg_emoji_like",
+            group_id=event.group_id,
+            message_id=event.message_id,
+            emoji_id=emoji_id,
+            set=True,
+        )
+    except Exception as exc:
+        logger.warning(f"设置消息表情失败: {exc}")
+
+
+proxy_command = on_command("proxy", priority=5, block=True)
+
+
+@proxy_command.handle()
+async def handle_proxy(
+    bot: Bot,
+    event: MessageEvent,
+    args: Message = CommandArg(),
+) -> None:
+    parsed = parse_command(args.extract_plain_text())
+    if parsed is None:
+        await proxy_command.finish(USAGE)
+    action, value = parsed
+
+    if action == "show":
+        await proxy_command.finish(manager.get_image_segment())
+
+    if action == "help":
+        await proxy_command.finish(USAGE)
+
+    if action == "ip":
+        if not value:
+            await proxy_command.finish(
+                "请提供目标参考 IPv4，例如："
+                "/proxy -i 218.194.50.3"
+            )
+        try:
+            target_ip = str(ipaddress.IPv4Address(value))
+        except ValueError:
+            await proxy_command.finish(f"不是有效的 IPv4 地址：{value}")
+        saved, message = await manager.set_target_ip(target_ip)
+        await proxy_command.finish(message)
+
+    if action == "probe":
+        await set_emoji(bot, event, "427")
+        started, message = await manager.start("probe", bot, event)
+        if not started:
+            await proxy_command.finish(message)
+        return
+
+    if action == "refresh":
+        await set_emoji(bot, event, "294")
+        started, message = await manager.start("refresh", bot, event)
+        if not started:
+            await proxy_command.finish(message)
+        return
+
+    if action == "stop":
+        stopped, message = await manager.stop(bot, event)
+        if not stopped:
+            await proxy_command.finish(message)
+        return

nonebot_plugin_proxy_probe/config.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from nonebot import get_plugin_config
+from pydantic import BaseModel, Field
+
+
+class PluginConfig(BaseModel):
+    proxy_probe_local_ip: str = ""
+    proxy_probe_target_ip: str = ""
+    proxy_probe_prefix_length: int = 20
+    proxy_probe_ports: list[int] = Field(default_factory=lambda: [7897,7890])   # default_factory 可以明确避免多个实例共享同一个可变列表。
+    proxy_probe_connect_timeout: float = 0.35
+    proxy_probe_proxy_timeout: float = 5.0
+    proxy_probe_geo_timeout: float = 5.0
+    proxy_probe_workers: int = 256
+    proxy_probe_proxy_workers: int = 256
+    proxy_probe_geo_workers: int = 256
+    proxy_probe_bind_source_ip: bool = True
+    proxy_probe_test_urls: list[str] = Field(
+        default_factory=lambda: [
+            "https://api.ip.sb/ip",
+            "https://cp.cloudflare.com/generate_204",
+            "https://www.gstatic.com/generate_204",
+        ]
+    )
+    proxy_probe_exclude_ips: list[str] = Field(default_factory=list)
+
+
+plugin_config = get_plugin_config(PluginConfig)

nonebot_plugin_proxy_probe/manager.py

@@ -0,0 +1,360 @@
+from __future__ import annotations
+
+import asyncio
+import copy
+import threading
+import time
+from datetime import datetime
+
+from nonebot.adapters.onebot.v11 import (
+    Bot,
+    GroupMessageEvent,
+    MessageEvent,
+    MessageSegment,
+)
+from nonebot.log import logger
+
+from .cache import load_cache, load_target_ip, save_cache, save_target_ip
+from .config import PluginConfig, plugin_config
+from .models import CacheState, PipelineProgress, ProxyRecord
+from .probe import (
+    ProbeConfig,
+    ProbeRunResult,
+    RefreshProgress,
+    RefreshRunResult,
+    detect_direct_public_ip,
+    detect_local_network,
+    run_probe,
+    run_refresh,
+)
+from .render import image_to_base64, render_cache_image
+
+
+def format_time() -> str:
+    return datetime.now().astimezone().strftime("%Y-%m-%d %H:%M:%S")
+
+
+def build_probe_config(
+    config: PluginConfig,
+    persisted_target_ip: str = "",
+) -> ProbeConfig:
+    network = detect_local_network(config.proxy_probe_local_ip.strip())
+    local_ip = network.local_ip
+    target_ip = (
+        persisted_target_ip.strip()
+        or config.proxy_probe_target_ip.strip()
+    )
+    if not target_ip:
+        target_ip = detect_direct_public_ip(
+            local_ip,
+            config.proxy_probe_geo_timeout,
+            config.proxy_probe_bind_source_ip,
+            network.dns_servers,
+        )
+    logger.info(
+        f"代理扫描使用网卡 {network.interface_name or '自动路由'} "
+        f"({local_ip})，目标参考 IP {target_ip}"
+    )
+    return ProbeConfig(
+        local_ip=local_ip,
+        target_ip=target_ip,
+        prefix_length=config.proxy_probe_prefix_length,
+        proxy_ports=tuple(config.proxy_probe_ports),
+        connect_timeout=config.proxy_probe_connect_timeout,
+        proxy_timeout=config.proxy_probe_proxy_timeout,
+        geo_timeout=config.proxy_probe_geo_timeout,
+        workers=config.proxy_probe_workers,
+        proxy_workers=config.proxy_probe_proxy_workers,
+        geo_workers=config.proxy_probe_geo_workers,
+        bind_source_ip=config.proxy_probe_bind_source_ip,
+        proxy_test_urls=tuple(config.proxy_probe_test_urls),
+        exclude_ips=tuple(config.proxy_probe_exclude_ips),
+    )
+
+
+class ProbeManager:
+    def __init__(self) -> None:
+        self._state_lock = threading.RLock()
+        self._state = load_cache()
+        self._persisted_target_ip = load_target_ip()
+        self._task_lock = asyncio.Lock()
+        self._task: asyncio.Task[None] | None = None
+        self._stop_event: threading.Event | None = None
+        self._recipient: tuple[Bot, MessageEvent] | None = None
+        self._last_save = 0.0
+        self._persist_lock = threading.RLock()
+        environment_target_ip = plugin_config.proxy_probe_target_ip.strip()
+        if self._persisted_target_ip and environment_target_ip:
+            logger.warning(
+                "proxy_probe_target_ip 环境变量与 LocalStore 持久化设置"
+                "同时存在，将使用 LocalStore 缓存值 "
+                f"{self._persisted_target_ip}，忽略环境变量值 "
+                f"{environment_target_ip}"
+            )
+        if self._state.running:
+            self._state.running = False
+            self._state.task_status = "任务因 Bot 重启而中止"
+            save_cache(self._state)
+
+    def get_state(self) -> CacheState:
+        with self._state_lock:
+            return copy.deepcopy(self._state)
+
+    def get_image_segment(self) -> MessageSegment:
+        image = render_cache_image(self.get_state())
+        return MessageSegment.image(image_to_base64(image))
+
+    def running_description(self) -> str:
+        state = self.get_state()
+        names = {"probe": "重新扫描", "refresh": "缓存刷新"}
+        return names.get(state.operation, "后台")
+
+    def configured_target_ip(self) -> str:
+        return (
+            self._persisted_target_ip
+            or plugin_config.proxy_probe_target_ip.strip()
+        )
+
+    async def set_target_ip(self, target_ip: str) -> tuple[bool, str]:
+        async with self._task_lock:
+            if self._task is not None and not self._task.done():
+                return (
+                    False,
+                    f"已有{self.running_description()}任务正在运行，"
+                    "请先使用 /proxy -s 停止。",
+                )
+            try:
+                await asyncio.to_thread(save_target_ip, target_ip)
+            except (OSError, ValueError) as exc:
+                return False, f"保存目标 IP 失败：{exc}"
+            self._persisted_target_ip = target_ip
+            return (
+                True,
+                f"目标参考 IP 已持久化为 {target_ip}，"
+                "后续扫描和刷新将优先使用该值。",
+            )
+
+    def _persist(self, force: bool = False) -> None:
+        with self._persist_lock:
+            now = time.monotonic()
+            if not force and now - self._last_save < 0.5:
+                return
+            with self._state_lock:
+                snapshot = copy.deepcopy(self._state)
+            try:
+                save_cache(snapshot)
+                self._last_save = now
+            except OSError as exc:
+                logger.warning(f"保存代理缓存失败: {exc}")
+
+    def _probe_callback(
+        self,
+        progress: PipelineProgress,
+        results: list[ProxyRecord],
+        current: int,
+        total: int,
+    ) -> None:
+        with self._state_lock:
+            self._state.progress = progress
+            self._state.results = list(results)
+            self._state.task_current = current
+            self._state.task_total = total
+        self._persist()
+
+    def _refresh_callback(
+        self,
+        results: list[ProxyRecord],
+        refresh: RefreshProgress,
+    ) -> None:
+        with self._state_lock:
+            self._state.results = list(results)
+            current = self._state.progress
+            self._state.progress = PipelineProgress(
+                total=current.total,
+                scan_completed=current.scan_completed,
+                open_count=current.open_count,
+                proxy_tested=refresh.proxy_tested,
+                proxy_count=refresh.proxy_count,
+                geo_tested=refresh.geo_tested,
+                geo_success=refresh.geo_success,
+            )
+            self._state.task_current = refresh.completed
+            self._state.task_total = refresh.total
+        self._persist()
+
+    async def start(
+        self,
+        operation: str,
+        bot: Bot,
+        event: MessageEvent,
+    ) -> tuple[bool, str]:
+        async with self._task_lock:
+            if self._task is not None and not self._task.done():
+                return (
+                    False,
+                    f"已有{self.running_description()}任务正在运行，"
+                    "可使用 /proxy -s 停止。",
+                )
+            if operation == "refresh" and not self.get_state().results:
+                return False, "当前没有缓存代理，请先使用 /proxy -p 扫描。"
+
+            self._stop_event = threading.Event()
+            self._recipient = (bot, event)
+            with self._state_lock:
+                self._state.running = True
+                self._state.operation = operation
+                self._state.task_status = "运行中"
+                self._state.task_current = 0
+                if operation == "probe":
+                    total = 1 << (32 - plugin_config.proxy_probe_prefix_length)
+                    self._state.task_total = total
+                    self._state.progress = PipelineProgress(total=total)
+                    self._state.results = []
+                else:
+                    self._state.task_total = len(self._state.results)
+                    current = self._state.progress
+                    self._state.progress = PipelineProgress(
+                        total=current.total,
+                        scan_completed=current.scan_completed,
+                        open_count=current.open_count,
+                    )
+            self._persist(force=True)
+            self._task = asyncio.create_task(
+                self._run(operation),
+                name=f"nonebot-proxy-{operation}",
+            )
+            return True, ""
+
+    async def stop(
+        self,
+        bot: Bot,
+        event: MessageEvent,
+    ) -> tuple[bool, str]:
+        async with self._task_lock:
+            task = self._task
+            stop_event = self._stop_event
+            if task is None or task.done() or stop_event is None:
+                return False, "当前没有正在运行的代理任务。"
+            self._recipient = (bot, event)
+            with self._state_lock:
+                self._state.task_status = "正在停止"
+            self._persist(force=True)
+            stop_event.set()
+        await asyncio.shield(task)
+        return True, ""
+
+    async def _run(self, operation: str) -> None:
+        stopped = False
+        error: Exception | None = None
+        origin_recipient = self._recipient
+        persisted_target_ip = self._persisted_target_ip
+        target_ip_auto_detected = not (
+            persisted_target_ip
+            or plugin_config.proxy_probe_target_ip.strip()
+        )
+        try:
+            config = await asyncio.to_thread(
+                build_probe_config,
+                plugin_config,
+                persisted_target_ip,
+            )
+            with self._state_lock:
+                self._state.local_ip = config.local_ip
+                self._state.target_ip = config.target_ip
+            self._persist(force=True)
+            if (
+                target_ip_auto_detected
+                and origin_recipient is not None
+            ):
+                bot, event = origin_recipient
+                if isinstance(event, GroupMessageEvent):
+                    try:
+                        await bot.call_api(
+                            "set_msg_emoji_like",
+                            group_id=event.group_id,
+                            message_id=event.message_id,
+                            emoji_id="4",
+                            set=True,
+                        )
+                    except Exception as exc:
+                        logger.warning(f"设置 IP 探测成功表情失败: {exc}")
+            stop_event = self._stop_event
+            if stop_event is None:
+                raise RuntimeError("停止事件未初始化")
+            if operation == "probe":
+                result: ProbeRunResult = await asyncio.to_thread(
+                    run_probe,
+                    config,
+                    stop_event,
+                    self._probe_callback,
+                )
+                stopped = result.interrupted
+                with self._state_lock:
+                    self._state.progress = result.progress
+                    self._state.results = result.results
+                    self._state.task_current = result.progress.scan_completed
+                    self._state.task_total = result.progress.total
+                    completed_at = format_time()
+                    self._state.scan_time = completed_at
+                    self._state.refresh_time = completed_at
+            else:
+                cached = self.get_state().results
+                refresh_result: RefreshRunResult = await asyncio.to_thread(
+                    run_refresh,
+                    config,
+                    cached,
+                    stop_event,
+                    self._refresh_callback,
+                )
+                stopped = refresh_result.interrupted
+                with self._state_lock:
+                    self._state.results = refresh_result.results
+                    refresh = refresh_result.progress
+                    current = self._state.progress
+                    self._state.progress = PipelineProgress(
+                        total=current.total,
+                        scan_completed=current.scan_completed,
+                        open_count=current.open_count,
+                        proxy_tested=refresh.proxy_tested,
+                        proxy_count=refresh.proxy_count,
+                        geo_tested=refresh.geo_tested,
+                        geo_success=refresh.geo_success,
+                    )
+                    self._state.task_current = refresh.completed
+                    self._state.task_total = refresh.total
+                    self._state.refresh_time = format_time()
+        except Exception as exc:
+            error = exc
+            logger.exception("代理探测后台任务失败")
+        finally:
+            with self._state_lock:
+                self._state.running = False
+                if error is not None:
+                    self._state.task_status = f"失败：{error}"
+                elif stopped:
+                    self._state.task_status = "已停止，显示部分结果"
+                else:
+                    self._state.task_status = "已完成"
+                snapshot = copy.deepcopy(self._state)
+            try:
+                save_cache(snapshot)
+            except OSError as exc:
+                logger.warning(f"保存代理最终缓存失败: {exc}")
+
+            recipient = self._recipient
+            if recipient is not None:
+                bot, event = recipient
+                try:
+                    if error is not None:
+                        await bot.send(event, f"代理任务失败：{error}")
+                    await bot.send(event, self.get_image_segment())
+                except Exception:
+                    logger.exception("发送代理结果图片失败")
+
+            async with self._task_lock:
+                self._task = None
+                self._stop_event = None
+                self._recipient = None
+
+
+manager = ProbeManager()