qq-bot-roost 0.8.9 → 0.8.10

package/README.md

@@ -10,8 +10,9 @@
 <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="零依赖">
 <img src="https://img.shields.io/badge/tests-600%2B%20passed-brightgreen" alt="测试 600+ 项">
 <img src="https://img.shields.io/badge/plugins-JS%20%7C%20Python%20%7C%20Go%20%7C%20any-blue" alt="多语言插件">
-<img src="https://img.shields.io/badge/version-0.8.8-blueviolet" alt="版本 0.8.8">
+<img src="https://img.shields.io/badge/version-0.8.9-blueviolet" alt="版本 0.8.9">
 <img src="https://img.shields.io/badge/license-Non--Commercial-red" alt="禁止商用">
+<a href="https://github.com/tdcq9594/qq-bot-roost/actions"><img src="https://img.shields.io/github/actions/workflow/status/tdcq9594/qq-bot-roost/ci.yml?branch=master" alt="CI"></a>
 
 [快速开始](#3-分钟跑起来) ｜ [写插件](docs/插件开发规范.md) ｜ [外部插件协议](docs/插件协议.md) ｜ [配置参考](docs/配置参考.md) ｜ [常见问题](docs/常见问题.md) ｜ [贡献](CONTRIBUTING.md)
 
@@ -423,9 +424,10 @@ bot/
 │   ├── web/server.js           面板服务端（REST + SSE）
 │   └── plugin/                 插件加载、配置、依赖、子进程宿主、面板页面注册
 ├── test/
-│   ├── selftest.mjs            框架自检（474 项）
-│   ├── e2e.mjs                 端到端测试（147 项，起真实服务打接口）
-│   └── qrlogin.mjs             扫码建机器人（10 项）
+│   ├── selftest.mjs            框架自检（431 项）
+│   ├── e2e.mjs                 端到端测试（168 项，起真实服务打接口）
+│   ├── qrlogin.mjs             扫码建机器人（8 项）
+│   └── deps.mjs                插件依赖安装（11 项）
 ├── web/                        面板前端（原生 JS/CSS，无构建）
 └── docs/
 ```
@@ -470,9 +472,9 @@ openid 完全不同。共享 `roles.json` 等于所有权限记录全部对不
 ## 开发
 
 ```bash
-npm test              # 自检 484 项（selftest 474 + qrlogin 10）
-npm run test:e2e      # 端到端 147 项（起 mock 服务打全部接口，跑在临时目录）
-npm run test:all      # 全量约 631 项：自检 + 扫码 + e2e（真机驱动要真机，没配就跳过）
+npm test              # 450 项（selftest 431 + qrlogin 8 + deps 11）
+npm run test:e2e      # 端到端 168 项（起 mock 服务打全部接口，跑在临时目录）
+npm run test:all      # 全量约 618 项：自检 + 扫码 + 依赖 + e2e（真机驱动要真机，没配就跳过）
 npm run check:secrets # 扫硬编码凭据（CI 也跑这个，提交前建议过一遍）
 node src/main.js --mock          # 不连 QQ，命令行发假消息调插件
 node src/main.js --mock --serve  # 只开面板，调界面

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qq-bot-roost",
-  "version": "0.8.9",
+  "version": "0.8.10",
   "type": "module",
   "description": "栖 Roost：零依赖的 QQ 官方机器人框架，填 AppID/AppSecret 即连，插件可写任意语言",
   "license": "SEE LICENSE IN LICENSE",

package/src/config.js

@@ -27,6 +27,25 @@ const GLOBAL_DEFAULTS = {
     accessKey: '',
     portTries: 20,
     openBrowser: true,
+    /**
+     * 面板在 Nginx / Caddy 这类反向代理后面时设为 true。
+     *
+     * 开了之后：
+     *   - 客户端 IP 从 `X-Forwarded-For` 取（用于认证失败限速）
+     *   - 真实 Host 从 `X-Forwarded-Host` 取（用于同源校验）
+     *
+     * **默认关，而且关着的时候伪造这两个头毫无作用**——
+     * 不开就是不信任任何转发头，攻击者自己塞的值会被忽略。
+     */
+    trustProxy: false,
+    /**
+     * 反向代理层数。只有一层 Nginx = 1；CDN（Cloudflare 等）+ Nginx = 2。
+     *
+     * 取 `X-Forwarded-For` 时从**右往左**数第 hops 个：右边那些是代理自己加的，
+     * 左边的是客户端可以随便伪造的。取错了要么拿到假 IP（等于没限速），
+     * 要么把所有人当成同一个 IP（攻击者一个人就能把面板锁死）。
+     */
+    trustProxyHops: 1,
   },
 
   logs: {
@@ -41,11 +60,33 @@ const GLOBAL_DEFAULTS = {
    */
   webhook: {
     enabled: false,
-    host: '0.0.0.0',
+    /**
+     * 默认只听本机：对外回调应该由 Nginx/Caddy 反代进来并终结 TLS。
+     *
+     * 以前默认 0.0.0.0，一旦开启就对着整个网络——而 Webhook 收的是群消息与
+     * openid，明文过网、也没有速率限制。放在反代后面还有个好处：反代能直接
+     * 按平台出口 IP 做白名单，比在应用里做更可靠。
+     */
+    host: '127.0.0.1',
     port: 15208,
     path: '/webhook',
     /** 对外可访问的完整地址，只用于面板显示和提示，不参与逻辑 */
     publicUrl: '',
+    /**
+     * 只接受这些来源 IP（空数组 = 不限）。
+     * 公网部署时填平台出口 IP 最稳；也可以交给反代做。
+     */
+    allowedIps: [],
+    /** 每个 IP 每分钟最多多少个请求，防日志洪泛和刷接口 */
+    perIpPerMin: 120,
+    /**
+     * 允许「关掉验签」的第二把钥匙。
+     *
+     * 只写 `verifySignature: false` **不会**生效——必须同时把这里设为 true。
+     * 目的是防手滑：关掉验签之后，任何知道地址和 appId 的人都能伪造事件
+     * （包括冒充群主触发管理命令），这个代价不该由一个配置项决定。
+     */
+    allowUnsigned: false,
   },
 
   /**
@@ -322,6 +363,14 @@ export async function loadGlobalConfig() {
     if (Number.isInteger(p) && p > 0 && p < 65536) cfg.webui.port = p;
   }
   if (env.ROOST_WEBUI_KEY) cfg.webui.accessKey = env.ROOST_WEBUI_KEY;
+  // 反代场景常靠环境变量开，省得进容器改配置文件
+  if (env.ROOST_WEBUI_TRUST_PROXY) {
+    cfg.webui.trustProxy = /^(1|true|yes|on)$/i.test(String(env.ROOST_WEBUI_TRUST_PROXY).trim());
+  }
+  if (env.ROOST_WEBUI_TRUST_PROXY_HOPS) {
+    const h = Number(env.ROOST_WEBUI_TRUST_PROXY_HOPS);
+    if (Number.isInteger(h) && h >= 1 && h <= 10) cfg.webui.trustProxyHops = h;
+  }
   if (env.ROOST_LOG_LEVEL) cfg.logLevel = env.ROOST_LOG_LEVEL;
 
   // Webhook：容器里想开回调，两个变量就够

package/src/main.js

@@ -1044,8 +1044,12 @@ async function main() {
       host: globalCfg.webhook.host,
       port: globalCfg.webhook.port,
       path: globalCfg.webhook.path,
-      // 默认验签；只在排查「验签总是失败」时可以显式关掉
+      // 默认验签。配里写 verifySignature=false 还不够，必须同时开 allowUnsigned
+      // ——关掉之后任何知道地址和 appId 的人都能伪造事件，见 webhook.js 的注释
       verifySignature: globalCfg.webhook.verifySignature !== false,
+      allowUnsigned: globalCfg.webhook.allowUnsigned === true,
+      allowedIps: globalCfg.webhook.allowedIps,
+      perIpPerMin: globalCfg.webhook.perIpPerMin,
     });
     try {
       const port = await webhookServer.start();

package/src/plugin/deps.js

@@ -310,16 +310,28 @@ export async function ensurePluginDeps({ dir, manifest = {}, log = null, enabled
 
       /**
        * requirements.txt 里能写 `--index-url`、`-e git+...`、直接写 URL——
-       * 等于让插件作者把 pip 指到任意源、拉任意代码。这里只接受「包名 + 版本约束」。
+       * 等于让插件作者把 pip 指到任意源、拉任意代码。
+       *
+       * 这里用**白名单**（fail-closed）：只接受「包名 + 版本约束」这一种形态，
+       * 其它一律拒。不能用黑名单——pip 的选项缩写太多（`-i` = `--index-url`、
+       * `-c` = 约束文件、`-r` = 嵌套 requirement、`--no-index`、`--pre`…），
+       * 黑名单列不完，漏一个就是一条供应链后门。
+       *
+       * 合法行只匹配：包名（字母数字 + `-_.`）后面可选地跟版本约束
+       * （`==` / `>=` / `~=` / `<=` / `!=` / `>` / `<` 等，或逗号分隔的多个）。
+       * 环境标记（`; python_version < "3.8"`）一并放行，它不含网络指令。
        */
       const badLine = requirements
         .split(/\r?\n/)
         .map((l) => l.trim())
-        .find((l) => l && !l.startsWith('#') && /^(-e|--index-url|--extra-index-url|--find-links|--trusted-host|[a-z]+:\/\/|git\+)/i.test(l));
+        .find((l) => {
+          if (!l || l.startsWith('#')) return false; // 空行 / 注释放行
+          return !/^[A-Za-z0-9][A-Za-z0-9._-]*(?:\[[A-Za-z0-9._,-]+\])?(?:\s*(?:==|>=|<=|~=|!=|===|>|<)\s*[^\s,]+(?:\s*,\s*[^\s,]+)*)?(?:\s*;\s*[^\n]+)?$/.test(l);
+        });
       if (badLine) {
         throw new Error(
           `requirements.txt 里有不安全的行，已拒绝安装：${badLine}\n` +
-            '只允许「包名 + 版本约束」（如 requests>=2.31），不接受 -e / --index-url / 直接 URL。',
+            '只允许「包名 + 版本约束」（如 requests>=2.31），不接受 -e / --index-url / 直接 URL / pip 选项。',
         );
       }
 

package/src/web/server.js

@@ -334,6 +334,65 @@ export async function startWebServer({
     );
   }
 
+  /**
+   * 反向代理设置。
+   *
+   * `trustProxy` 默认关：不开就是不信任任何转发头，客户端自己塞的
+   * `X-Forwarded-For` / `X-Forwarded-Host` 一律当不存在（防伪造）。
+   * 只有用户明确知道自己在反代后面时才打开。
+   */
+  const TRUST_PROXY = wc.trustProxy === true;
+  const PROXY_HOPS = Math.min(Math.max(Number(wc.trustProxyHops) || 1, 1), 10);
+
+  /**
+   * 监听在非 loopback 却没开 trustProxy —— 十有八九是放在 Nginx 后面。
+   * 这种情况下所有请求的来源地址都是代理自己，认证失败限速会退化成
+   * 「全局一个桶」：别人打 20 次错密钥，你自己也进不来，而且日志里全是代理 IP。
+   */
+  if (!LOOPBACK_HOSTS.has(String(host)) && !TRUST_PROXY) {
+    log.warn(
+      `面板监听 ${host} 但未开启 webui.trustProxy。\n` +
+        '  如果前面有 Nginx / Caddy / CDN，请设 webui.trustProxy=true（多层再加 trustProxyHops），\n' +
+        '  否则限速会按代理地址统计：攻击者发 20 次错误密钥就能让所有人 60 秒进不来。',
+    );
+  }
+
+  /**
+   * 取客户端 IP，用于认证失败限速。
+   *
+   * 开了 trustProxy 才看 `X-Forwarded-For`，并且**从右往左**数第 `hops` 个：
+   * 右边是各级代理自己追加的（可信），左边是客户端可以随便伪造的。
+   * 单层反代取最后一个；CDN + Nginx 取倒数第二个，否则拿到的是 CDN 的地址，
+   * 所有人又挤回一个桶里，等于白配。
+   */
+  const clientIp = (req) => {
+    if (TRUST_PROXY) {
+      const xff = String(req.headers['x-forwarded-for'] || '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+      if (xff.length) {
+        return xff[Math.max(0, xff.length - PROXY_HOPS)] || xff[xff.length - 1];
+      }
+    }
+    return req.socket?.remoteAddress || 'unknown';
+  };
+
+  /**
+   * 取「浏览器实际访问的 Host」，用于同源校验。
+   *
+   * 不处理这个的话：Nginx 默认 `proxy_set_header Host $proxy_host`，转发给面板的
+   * Host 是 `127.0.0.1:15207`，而浏览器发来的 Origin 是自己的域名 —— 两者永远不等，
+   * 结果面板**所有写操作都 403**（读能用、保存全失败），现象很像权限问题。
+   */
+  const clientHost = (req) => {
+    if (TRUST_PROXY) {
+      const xfh = String(req.headers['x-forwarded-host'] || '').split(',')[0].trim();
+      if (xfh) return xfh;
+    }
+    return String(req.headers['host'] || '');
+  };
+
   // res -> 这个连接正在看哪个机器人，状态推送时按各自的目标过滤
   const sseClients = new Map();
   /** 同时最多多少个 SSE 连接（一个页面一个） */
@@ -603,7 +662,7 @@ export async function startWebServer({
       sessions.delete(sid);
     }
 
-    const ip = req.socket?.remoteAddress || 'unknown';
+    const ip = clientIp(req);
     const now = Date.now();
     const rec = authFails.get(ip);
     if (rec && now - rec.start < AUTH_WINDOW && rec.count >= AUTH_MAX_FAILS) {
@@ -663,7 +722,9 @@ export async function startWebServer({
      */
     if (ptPage && String(req.headers.origin || '') === 'null') return true;
 
-    const host = String(req.headers['host'] || '');
+    // 反代场景下要用 X-Forwarded-Host，不能直接看 req.headers.host：
+    // Nginx 默认把 Host 改写成 $proxy_host，与浏览器的 Origin 永远不等。
+    const host = clientHost(req);
     for (const h of ['origin', 'referer']) {
       const v = req.headers[h];
       if (!v) continue;
@@ -871,6 +932,40 @@ export async function startWebServer({
     }
 
     try {
+      /**
+       * 健康检查端点（**不鉴权**）。
+       *
+       * 为什么必须免鉴权：Docker 的 healthcheck 以前探 `/api/status`，而配了
+       * `accessKey` 之后那个接口恒返 401 —— 容器永久 unhealthy。反过来不配 key
+       * 时，机器人明明掉线了它照样报健康。两个方向都是错的。
+       *
+       * 返回什么：进程活着、且至少有一个机器人是 online 才算 200。
+       * 全掉线就 503，让监控一眼看出「面板在、但机器人没连上」。
+       *
+       * 只给 id / state / 计数，不给 botName（可能是群里的昵称，不该对匿名请求暴露）。
+       *
+       * 注意：Docker 的 healthcheck 只是打标记，**不会**因此重启容器
+       * （重启只由 restart 策略在进程退出时触发），所以不会变成重启循环。
+       */
+      if (pathname === '/healthz') {
+        const bots = runtimes.map((r) => ({ id: r?.id ?? '', state: r?.state ?? 'offline' }));
+        const online = bots.filter((b) => b.state === 'online').length;
+        const ok = bots.length === 0 ? true : online > 0;
+        res.writeHead(ok ? 200 : 503, {
+          'Content-Type': 'application/json; charset=utf-8',
+          'Cache-Control': 'no-store',
+        });
+        return res.end(
+          JSON.stringify({
+            ok,
+            bots,
+            online,
+            total: bots.length,
+            uptime: Math.round(process.uptime()),
+          }),
+        );
+      }
+
       // ---------------- API ----------------
       if (pathname.startsWith('/api/')) {
         const ptPage = pickPageToken(url);
@@ -2083,25 +2178,41 @@ export async function startWebServer({
 
         // SSE
         if (pathname === '/api/stream' && req.method === 'GET') {
-          res.writeHead(200, {
-            'Content-Type': 'text/event-stream; charset=utf-8',
-            'Cache-Control': 'no-cache',
-            Connection: 'keep-alive',
-          });
           /**
-           * 连接数上限。SSE 是长连接，每个连接占一个 fd + 一份缓冲；
+           * 连接数上限必须**先检查再写头**。
+           *
+           * 之前是「先 writeHead(200, SSE 头) 再判满、判满再 writeHead(503)」，
+           * 满载时对同一个 res 写两次头，Node 直接抛 `ERR_HTTP_HEADERS_SENT`，
+           * 请求崩掉、连接也不释放。SSE 是长连接，每个连接占一个 fd + 一份缓冲；
            * 面板被脚本反复刷新时不设限就是稳定泄漏。
            */
           if (sseClients.size >= MAX_SSE) {
             res.writeHead(503, { 'Content-Type': 'text/plain; charset=utf-8' });
             return res.end('SSE 连接数已满，请关闭多余的页面后重试');
           }
+          res.writeHead(200, {
+            'Content-Type': 'text/event-stream; charset=utf-8',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+          });
           res.write(`event: status\ndata: ${JSON.stringify(statusPayload(rt))}\n\n`);
           sseClients.set(res, rt.id);
           const ping = setInterval(() => {
             try {
               res.write(': ping\n\n');
-            } catch {}
+            } catch {
+              /**
+               * 写失败 = 连接其实已经断了，但 `close` 事件可能没触发
+               * （客户端异常断开、半开连接、keep-alive 下不发 FIN）。
+               * 不在这里清的话，这个僵尸连接会一直占着 MAX_SSE 的配额，
+               * 直到真 close 才释放。所以失败即主动清理。
+               */
+              clearInterval(ping);
+              sseClients.delete(res);
+              try {
+                res.end();
+              } catch {}
+            }
           }, 15000);
           req.on('close', () => {
             clearInterval(ping);
@@ -2321,7 +2432,27 @@ export async function startWebServer({
 
   /* ---------------- 监听（端口被占用自动顺延） ---------------- */
 
-  const tries = Math.max(1, Number(wc.portTries) || 20);
+  /**
+   * 容器里**禁用端口顺延**。
+   *
+   * docker-compose 把宿主机的 15207 固定映射到容器的 15207。容器内一旦因为
+   * 端口被占而顺延到 15208，宿主那边映射就悬空了 —— 面板不是报错，而是
+   * 静默地访问不到，日志里只有一行「换 15208 试试」，极难对上号。
+   *
+   * 桌面环境顺延是好事（用户不想为端口冲突折腾），容器里则应该**直接失败**，
+   * 让 restart 策略或者人看到明确的错误。
+   */
+  const IN_CONTAINER = process.env.ROOST_STRICT_PORT === '1' || (() => {
+    try {
+      return fsSync.existsSync('/.dockerenv');
+    } catch {
+      return false;
+    }
+  })();
+  const tries = IN_CONTAINER ? 1 : Math.max(1, Number(wc.portTries) || 20);
+  if (IN_CONTAINER && Number(wc.portTries) > 1) {
+    log.info(`容器环境：已禁用端口顺延（固定映射只能对上 ${port}）`);
+  }
   let actualPort;
   try {
     actualPort = await listenWithFallback(server, host, port, {

package/src/webhook.js

@@ -33,19 +33,56 @@ const MAX_BODY = 1024 * 1024;
 
 export class WebhookServer {
   /**
-   * @param {{host?:string, port?:number, path?:string}} opts
+   * @param {{
+   *   host?:string, port?:number, path?:string,
+   *   verifySignature?:boolean, allowUnsigned?:boolean,
+   *   allowedIps?:string[], perIpPerMin?:number
+   * }} opts
    */
-  constructor({ host = '0.0.0.0', port = 15208, path = '/webhook', verifySignature = true } = {}) {
+  constructor({
+    host = '127.0.0.1',
+    port = 15208,
+    path = '/webhook',
+    verifySignature = true,
+    allowUnsigned = false,
+    allowedIps = [],
+    perIpPerMin = 120,
+  } = {}) {
     this.host = host;
     this.port = port;
     this.path = path.startsWith('/') ? path : `/${path}`;
     /**
      * 是否校验事件的 Ed25519 签名。
      *
-     * 默认开。关掉只应出现在「验签总是失败、但又急着收消息」的排查场景，
-     * 关掉之后任何知道回调地址 + appId 的人都能伪造事件。
+     * **双开关**：只写 `verifySignature: false` 不生效，必须同时给
+     * `allowUnsigned: true`。关掉之后，任何知道回调地址 + appId 的人都能伪造
+     * 事件（含冒充群主触发管理命令），这个代价不该由一个配置项决定。
      */
-    this.verifySignature = verifySignature !== false;
+    this.verifySignature = !(verifySignature === false && allowUnsigned === true);
+    if (verifySignature === false && allowUnsigned !== true) {
+      log.warn(
+        'webhook.verifySignature=false 已忽略：要真的关掉验签，必须同时设置 ' +
+          'webhook.allowUnsigned=true。' +
+          '（关掉之后任何知道地址和 appId 的人都能伪造事件，包括冒充群主。默认不给这个口子。）',
+      );
+    }
+    /** 允许的来源 IP（空 = 不限）。公网部署建议填平台出口 IP，或交给反代做 */
+    this.allowedIps = new Set(
+      (Array.isArray(allowedIps) ? allowedIps : []).map((s) => String(s).trim()).filter(Boolean),
+    );
+    /** 每个 IP 每分钟上限，防日志洪泛 */
+    this.perIpPerMin = Math.max(1, Number(perIpPerMin) || 120);
+    /** ip -> { start, count } */
+    this.ipHits = new Map();
+    /**
+     * 事件去重：eventId -> 过期时间戳。
+     *
+     * 平台超时会**重推同一条事件**（报文完全一样），所以不能按签名去重
+     * （那会把重推当攻击拒掉，直接丢消息）。按事件 id 去重才对：第一次正常
+     * 处理，之后的重推一律回 200 但不再分发。顺带也挡住了「抓到一条合法请求
+     * 在时间窗内重放」。
+     */
+    this.seenEvents = new Map();
     /** @type {Map<string, {secret:string, onEvent:Function, onError?:Function}>} */
     this.bots = new Map();
     this.server = null;
@@ -197,7 +234,8 @@ export class WebhookServer {
   async #handle(req, res) {
     // 只接受 POST；健康检查给 GET
     if (req.method === 'GET') {
-      return this.#json(res, 200, { ok: true, service: 'roost-webhook', bots: this.bots.size });
+      // 不返回机器人数量：那是内部信息，不该对匿名探测暴露
+      return this.#json(res, 200, { ok: true, service: 'roost-webhook' });
     }
     if (req.method !== 'POST') {
       return this.#json(res, 405, { error: 'method not allowed' });
@@ -209,6 +247,36 @@ export class WebhookServer {
       return this.#json(res, 404, { error: 'not found' });
     }
 
+    /**
+     * 来源白名单 + 每 IP 限速。
+     *
+     * 放在路径校验之后、解析 body 之前：非法路径不该占用配额，也不该被读 body。
+     * 顺序也有讲究——先在网络层挡掉，比在业务逻辑里挡省事得多。
+     */
+    const ip = req.socket?.remoteAddress || 'unknown';
+    if (this.allowedIps.size && !this.allowedIps.has(ip)) {
+      this.counters.rejected += 1;
+      log.warn(`Webhook 拒绝非白名单来源：${ip}`);
+      return this.#json(res, 403, { error: 'forbidden' });
+    }
+    {
+      const now = Date.now();
+      const rec = this.ipHits.get(ip) ?? { start: now, count: 0 };
+      if (now - rec.start >= 60_000) {
+        rec.start = now;
+        rec.count = 0;
+      }
+      if (rec.count >= this.perIpPerMin) {
+        this.counters.rejected += 1;
+        log.warn(`Webhook 请求过频，已限速：${ip}（每分钟上限 ${this.perIpPerMin}）`);
+        return this.#json(res, 429, { error: 'too many requests' });
+      }
+      rec.count += 1;
+      this.ipHits.set(ip, rec);
+      // 防止被大量来源地址把表撑爆
+      if (this.ipHits.size > 5000) this.ipHits.clear();
+    }
+
     const url = new URL(req.url || '/', 'http://localhost');
     const appId =
       String(req.headers['x-bot-appid'] ?? '').trim() || String(url.searchParams.get('appid') ?? '').trim();
@@ -325,6 +393,36 @@ export class WebhookServer {
       }
     }
 
+    /**
+     * 事件级去重。
+     *
+     * 平台超时会**重推同一条事件**（报文完全一样）。所以不能按签名去重——
+     * 那会把重推当攻击拒掉，等于直接丢消息。按事件 id 去重才对：第一次正常
+     * 处理，之后的重推一律 200 但不再分发。顺带也挡住「抓到一条合法请求
+     * 在时间窗内重放」。
+     *
+     * 只用 `payload.id`，不猜别的字段名：猜错会把两个不同事件判成同一个，
+     * 那是真的丢消息。真没有 id 就退回只靠时间戳窗口（sign.js 里的 300 秒），
+     * 并且提醒一次。
+     */
+    const evId = String(payload?.id ?? '');
+    if (evId) {
+      const exp = this.seenEvents.get(evId);
+      if (exp && exp > Date.now()) {
+        return this.#json(res, 200, {}); // 重复：静默接受，不重复处理
+      }
+      this.seenEvents.set(evId, Date.now() + 300_000);
+      if (this.seenEvents.size > 10_000) {
+        this.seenEvents.delete(this.seenEvents.keys().next().value);
+      }
+    } else if (!this.noIdWarned) {
+      this.noIdWarned = true;
+      log.warn(
+        '收到的 Webhook 事件没有 id 字段，无法做重放去重，只能依赖 300 秒时间戳窗口。' +
+          '如果官方后续给事件加了 id，这里会自动生效。',
+      );
+    }
+
     this.counters.received += 1;
     const eventName = String(payload?.t ?? '');
     const d = payload?.d ?? {};