nonebot-plugin-botui 0.1.0__py3-none-any.whl

nonebot_plugin_botui/config.py

@@ -0,0 +1,170 @@
+"""nonebot-plugin-botui 的配置与全局常量。"""
+
+from __future__ import annotations
+
+from nonebot import get_driver, get_plugin_config
+from pydantic import BaseModel, field_validator
+
+# 机器人发送消息时可能调用的 API 名称（用于区分“发出”的消息）
+SEND_APIS: frozenset[str] = frozenset(
+    {
+        # OneBot V11 / V12
+        'send_msg',
+        'send_private_msg',
+        'send_group_msg',
+        'send_group_forward_msg',
+        'send_private_forward_msg',
+        # 通用 / 其他适配器
+        'send_message',
+        'send_group_message',
+        'send_private_message',
+        'send_channel_message',
+        'post_message',
+        'create_message',
+        'send',
+        'send_group_file',
+        'upload_group_file',
+        'upload_private_file',
+        'send_group_notice',
+    }
+)
+
+
+class Config(BaseModel):
+    """插件配置项（环境变量前缀：BOTUI_）"""
+
+    model_config = {'extra': 'ignore'}
+
+    # ── 基础开关 ────────────────────────────────────────────────────────
+    botui_enabled: bool = True
+    """是否启用 WebUI"""
+    botui_route: str = '/botui'
+    """WebUI 挂载路径（需以 / 开头）"""
+    botui_host: str = '127.0.0.1'
+    """提示链接里使用的主机名（只影响链接显示，不影响服务实际监听地址）"""
+    botui_allow_remote: bool = False
+    """是否允许非本机来源访问。开启前请确保已启用令牌鉴权或放在反向代理之后"""
+    botui_allowed_hosts: tuple[str, ...] = ()
+    """允许的 ``Host`` 头（走反向代理用域名访问时填写）。
+
+    用来挡 DNS rebinding：浏览器访问 ``http://attacker.example`` 时，该域名可以
+    先解析到攻击者服务器、再重新解析到 ``127.0.0.1``，此时来源就成了环回，只
+    看来源会被放行。因此这里再校验 ``Host`` —— 本机主机名（``localhost`` /
+    环回 IP）始终允许，用域名访问就把域名写进来。``BOTUI_ALLOW_REMOTE=true``
+    时不再限制。"""
+
+    # ── 鉴权 ────────────────────────────────────────────────────────────
+    botui_auth: bool = True
+    """是否启用 Token 鉴权（强烈建议保持开启）"""
+    botui_token: str = ''
+    """访问令牌；留空则自动生成并保存到数据目录的 token.txt"""
+
+    # ── 记录 ────────────────────────────────────────────────────────────
+    botui_capture_received: bool = True
+    """是否记录机器人收到的消息"""
+    botui_capture_sent: bool = True
+    """是否记录机器人发出的消息"""
+    botui_capture_self: bool = False
+    """是否记录「自己发出的消息被适配器回传成事件」；关闭可避免同一条消息记两次"""
+    botui_exclude_adapters: tuple[str, ...] = ()
+    """不记录这些适配器的消息，例如 ('OneBot V12',)"""
+    botui_max_records: int = 200_000
+    """消息记录上限，超出后自动删除最旧的记录；0 表示不限制"""
+    botui_retention_days: int = 0
+    """消息保留天数，超期自动清理；0 表示不限制"""
+    botui_resolve_at_name: bool = True
+    """是否尝试把 @某人 解析成群名片（会调用适配器接口并缓存）"""
+    botui_api_timeout: float = 10.0
+    """插件内部调用适配器接口的超时时间（秒）"""
+
+    # ── WebUI 行为 ──────────────────────────────────────────────────────
+    botui_page_size: int = 50
+    """聊天记录每页条数"""
+    botui_write_enabled: bool = True
+    """是否允许在 WebUI 中代替机器人发送消息"""
+    botui_allow_recall: bool = True
+    """是否允许在 WebUI 中撤回消息"""
+    botui_send_interval: float = 1.0
+    """同一会话两次发送之间的最小间隔（秒），用于限流"""
+    botui_media_allow_private: bool = False
+    """是否允许 /media 代理内网/环回地址。
+
+    默认 false，只允许公网图片链接——否则 /media 会变成 SSRF 跳板，能被用来
+    探测内网服务或读取云元数据接口（169.254.169.254）。仅当你确实要显示来自
+    内网的图片时才打开。"""
+    botui_file_preview: bool = True
+    """是否允许在网页上在线预览收到的文件（文本 / 图片 / PDF / 音视频）。"""
+    botui_file_max_bytes: int = 100 * 1024 * 1024
+    """文件下载代理允许的最大体积（字节），101 MB。
+
+    ``0`` 表示不限制。文本在线预览另有 512 KB 的读取上限，不受这里影响。"""
+
+    # ── 媒体库（图片 / 语音 / 文件）──────────────────────────────────────
+    # 机器人收到的媒体直链大多带防盗链、而且**会过期**：过一阵子再点开聊天
+    # 记录，链接就已经打不开了。WebUI 上传的附件也有同样的问题。所以统一把
+    # 它们存进一个本地媒体库（见 mediastore.py），之后一律读本地副本。
+    # 资源按**内容 md5** 命名，内容相同天然只有一份。
+    botui_media_enabled: bool = True
+    """是否把机器人收发的媒体 / 文件保存到本地媒体库。
+
+    数据放在 localstore 插件数据目录下的 ``blobs/``（与数据库同一个目录），
+    元数据写在 SQLite 的 ``blobs`` 表里。"""
+    botui_media_max_bytes: int = 512 * 1024 * 1024
+    """媒体库总体积上限（字节），默认 512 MB。
+
+    超出后先淘汰**没有被任何聊天记录引用**的资源（按最久未访问），仍超才动
+    被引用的那批。``0`` 表示不限制 —— 与 ``BOTUI_MEDIA_MAX_FILES`` 同时为
+    ``0`` 时等于关闭媒体库。"""
+    botui_media_max_files: int = 20000
+    """媒体库的资源条数上限，默认 2 万条；``0`` 表示不限制。
+
+    资源按内容去重，条数通常远小于消息数。"""
+    botui_media_file_max_bytes: int = 20 * 1024 * 1024
+    """单个资源超过这个体积就不入库（字节），默认 20 MB；``0`` 表示只受总量限制。
+
+    大视频这类动辄几百 MB 的文件没必要为了「防链接失效」占满磁盘。"""
+    botui_media_ttl: float = 3 * 24 * 3600.0
+    """**没有被聊天记录引用**的资源保留多久（秒），默认 3 天；``0`` 表示不回收。
+
+    覆盖「选了附件没发出去」「抓回来但消息很快被删了」这类情况。"""
+    botui_media_retention: float = 7 * 24 * 3600.0
+    """**被聊天记录引用**的资源最多保留多久（秒），默认 7 天。
+
+    ``0`` 表示永不按时间回收（只受体积 / 条数上限约束）—— 想「一直留着」就
+    设成 0，同时把两个上限调大。"""
+    botui_media_fetch_timeout: float = 20.0
+    """下载单个媒体 / 文件到媒体库时的超时时间（秒）。"""
+    botui_media_max_bytes_per_message: int = 5 * 1024 * 1024 * 4
+    """单条消息里所有待入库内容加起来的上限（字节），默认 20 MB。
+
+    防止「一条消息里塞几十个文件」把一次采集拖成几十秒。"""
+    botui_media_cleanup_interval: int = 10
+    """媒体库与过期数据自动回收的间隔（分钟），默认 10 分钟；``0`` 表示不周期回收。
+
+    启动时会先回收一次，之后按这个间隔轮询 —— 上传后不发送的附件因此最多
+    留一个周期就被清掉，不会一直占着磁盘。"""
+
+    # ── 其他 ────────────────────────────────────────────────────────────
+    botui_debug: bool = False
+    """打印更详细的调试日志"""
+
+    @field_validator('botui_route')
+    @classmethod
+    def _check_route(cls, v: str) -> str:
+        route = (v or '').strip()
+        if not route.startswith('/'):
+            route = '/' + route
+        return '/' if route == '/' else route.rstrip('/')
+
+    @field_validator('botui_page_size')
+    @classmethod
+    def _check_page_size(cls, v: int) -> int:
+        return min(200, max(10, int(v)))
+
+
+# 配置加载
+plugin_config: Config = get_plugin_config(Config)
+global_config = get_driver().config
+
+# 机器人昵称（用于给自己发出的消息署名）
+NICKNAME: str = next(iter(global_config.nickname), '') if global_config.nickname else ''

nonebot_plugin_botui/ingest.py

@@ -0,0 +1,216 @@
+"""把消息里可抓的媒体 / 文件收进媒体库（见 ``mediastore.py``）。
+
+为什么要单独一个模块、而不是直接写在 ``capture.py`` 里：下载是**纯 IO**，
+既要能被「收到消息」的钩子调用，也必须能被定时任务、测试单独驱动；把「从
+消息段里挑出可入库的项 → 下载 → 落盘 → 回填地址」这套流程收在一处，采集侧
+只需调一个 :func:`ingest_message`。
+
+回填（把段里的 ``url`` 换成 ``/api/media/<id>``）是这里的关键副作用：一旦换成
+媒体库地址，WebUI 就再也不会去碰那个随时会失效的原始链接 —— 这也正是「避免
+url 失效以后打不开」的落点。
+"""
+
+from __future__ import annotations
+
+import time
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from nonebot import logger
+
+from .media import Blocked, TooLarge, download
+from .models import DIR_OUT, MessageRecord
+from .segments import cacheable_segments
+from .mediastore import (
+    url_of,
+    kind_of,
+    ref_for,
+    id_from_url,
+    ref_of_message_id,
+)
+
+if TYPE_CHECKING:
+    from .config import Config
+    from .mediastore import MediaStore
+
+#: 媒体直链普遍几分钟就失效，收到消息后多久之内要开始抓（秒）
+FETCH_DELAY = 0.5
+#: 一次并发下载几个（够快，又不至于同时朝上游开几十条连接）
+MAX_CONCURRENCY = 4
+
+
+async def ingest_segment(
+    media: 'MediaStore',
+    seg: dict[str, Any],
+    *,
+    cfg: 'Config',
+    ref: str = '',
+) -> bool:
+    """下载并保存单个段，成功时把段里的 ``url`` 换成媒体库地址。
+
+    返回是否「已经就位」；失败一律静默（媒体库只是「锦上添花」，绝不能影响
+    消息记录本身），但会把原因记进 debug 日志。
+
+    先查库再决定要不要下载 —— 一次查询就同时覆盖了三种情况：原链接已有本地
+    副本（命中）、段里本来就是媒体库地址（重复处理）、以及自己发出的附件
+    （发送时已入库）。命中时把 ``url`` 统一换成媒体库地址：它是这套东西里最稳
+    的门牌，图片、文件、音视频都由同一个接口带着 Range 支持供出。
+
+    注意回填的是**内存里的段**（返回给前端 / WebSocket 推送的那份，也因此第一
+    时间就是稳定地址）。数据库里存的仍是原始地址：万一媒体库被清空，库里如果
+    只剩媒体库地址就再也取不回来了，而存原始地址还能回源重下。
+    """
+    source = str(seg.get('url') or '').strip()
+    if not source:
+        return False
+
+    hit = await media.lookup(source)
+    if hit is not None:
+        seg['url'] = url_of(hit.id)
+        if not seg.get('size'):
+            seg['size'] = hit.size
+        if not seg.get('mime'):
+            seg['mime'] = hit.mime or None
+        if ref:
+            await media.add_ref(source, ref)
+        return True
+
+    # 媒体库地址但取不到条目（被清理了）：没有可抓的原始链接，放弃
+    if id_from_url(source) or not source.startswith(('http://', 'https://')):
+        return False
+
+    limit = int(cfg.botui_media_file_max_bytes)
+    name = _name_of(seg)
+    kind = kind_of(name, str(seg.get('mime') or ''))
+    tmp = await asyncio.to_thread(media.tmp_dir)
+    target = tmp / f'{int(time.time() * 1000)}-{abs(hash(source)) % 10**8}.part'
+    try:
+        size, mime = await download(
+            source,
+            target,
+            max_bytes=limit,
+            timeout=float(cfg.botui_media_fetch_timeout),
+        )
+    except TooLarge:
+        logger.debug(f'BotUI 跳过媒体：资源超过上限 {source[:64]}')
+        return False
+    except Blocked as e:
+        logger.debug(f'BotUI 跳过媒体：{e}')
+        return False
+    except Exception as e:
+        logger.debug(f'BotUI 下载媒体失败 {source[:64]}：{e}')
+        return False
+
+    record = await media.put(
+        target,
+        name=name,
+        mime=str(seg.get('mime') or mime or ''),
+        kind=kind,
+        source=source,
+        ref=ref,
+    )
+    if record is None:
+        return False
+    seg['url'] = url_of(record.id)
+    seg['name'] = name
+    if not seg.get('mime'):
+        seg['mime'] = record.mime or None
+    if not seg.get('size'):
+        seg['size'] = size
+    return True
+
+
+def _name_of(seg: dict[str, Any], fallback: str = 'file') -> str:
+    from .segments import resolve_file_name
+
+    return resolve_file_name(
+        seg.get('name'), str(seg.get('url') or ''), fallback=fallback
+    )
+
+
+async def ingest_segments(
+    media: 'MediaStore | None',
+    segments: list[dict[str, Any]],
+    *,
+    cfg: 'Config',
+    ref: str = '',
+    budget: int = 0,
+) -> int:
+    """批量入库（受并发与总预算限制），返回成功条数。
+
+    传了 ``budget`` 时改成**逐个**下载：下载前不可能知道真实大小，只有串行才能
+    保证「这一条消息总共抓的字节数」不越过上限 —— 并发会让几个资源一起冲进
+    闸门，把上限顶穿。预算是给「一条消息塞几十张图」兜底的，串行一点换取硬
+    上限是划算的；不同消息之间仍是并发（各自一个后台任务）。
+    """
+    if media is None or not media.enabled or not segments:
+        return 0
+    picked = cacheable_segments(segments)
+    if not picked:
+        return 0
+
+    max_workers = 1 if budget > 0 else MAX_CONCURRENCY
+    semaphore = asyncio.Semaphore(max_workers)
+    spent = 0
+    done = 0
+    lock = asyncio.Lock()
+
+    async def _one(seg: dict[str, Any]) -> None:
+        nonlocal spent, done
+        async with semaphore:
+            async with lock:
+                if budget > 0 and spent >= budget:
+                    return
+            ok = await ingest_segment(media, seg, cfg=cfg, ref=ref)
+        if ok:
+            async with lock:
+                done += 1
+                spent += int(seg.get('size') or 0)
+
+    await asyncio.gather(*(_one(seg) for seg in picked), return_exceptions=True)
+    return done
+
+
+async def ingest_message(
+    media: 'MediaStore | None',
+    record: MessageRecord,
+    *,
+    cfg: 'Config',
+) -> int:
+    """把一条记录里可入库的段收进媒体库，并回填段里的链接。
+
+    - 收到的消息：先落库拿到行号，再抓媒体 —— 抓完用 ``msg:<会话>:<行号>``
+      建立引用，回收时就知道这条资源还被聊天记录用着；
+    - 自己发出的消息：段里本来就是媒体库地址或本地附件（**不需要也不想**重新
+      下载），带 ``msgid:<消息 ID>`` 建立引用即可。
+
+    两条路径共用 :func:`ingest_segments`：:func:`ingest_segment` 自己会跳过
+    已经指向媒体库的段、命中已有副本时复用本地文件，所以这里不必分叉。
+    """
+    if media is None or not media.enabled or not record.segments:
+        return 0
+    if record.direction == DIR_OUT:
+        ref = ref_of_message_id(record.message_id) or ref_for(
+            record.chat_key, record.row_id
+        )
+    else:
+        ref = ref_for(record.chat_key, record.row_id)
+    try:
+        return await ingest_segments(
+            media,
+            record.segments,
+            cfg=cfg,
+            ref=ref,
+            budget=int(cfg.botui_media_max_bytes_per_message),
+        )
+    except Exception as e:  # pragma: no cover - 入库失败不影响记录
+        logger.debug(f'BotUI 保存消息媒体失败：{e}')
+        return 0
+
+
+__all__ = [
+    'FETCH_DELAY',
+    'ingest_message',
+    'ingest_segment',
+    'ingest_segments',
+]