qq-bot-roost 0.8.8 → 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.8",
+  "version": "0.8.10",
   "type": "module",
   "description": "栖 Roost：零依赖的 QQ 官方机器人框架，填 AppID/AppSecret 即连，插件可写任意语言",
   "license": "SEE LICENSE IN LICENSE",
@@ -36,7 +36,10 @@
     "create": "node scripts/create-plugin.mjs",
     "test:plugin": "node scripts/test-plugin.mjs",
     "live": "node scripts/live-test.mjs",
-    "market:index": "node scripts/build-market-index.mjs"
+    "market:index": "node scripts/build-market-index.mjs",
+    "sums": "node scripts/build-sums.mjs",
+    "sums:check": "node scripts/build-sums.mjs --check",
+    "sums:verify": "node scripts/build-sums.mjs --verify"
   },
   "author": {
     "name": "倦飞之鸟"

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/fsutil.js

@@ -23,7 +23,20 @@ export async function writeJsonAtomic(file, data) {
   const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
   const text = `${JSON.stringify(data, null, 2)}\n`;
   try {
-    await fs.writeFile(tmp, text, 'utf8');
+    /**
+     * `mode: 0o600` —— 只有属主能读写。
+     *
+     * 这些 JSON 里有 `config/bot.json`、`config/bots/<id>.json`，都带明文
+     * AppSecret；还有权限表、群档案。Linux 默认 umask 022 下新建文件是 644，
+     * 同机其他用户直接 `cat` 就能拿到机器人凭证。
+     *
+     * 注意两点：
+     *   - mode 只在**创建**时生效，而这里的 tmp 每次都是新文件，所以一定吃到
+     *   - rename 会保留临时文件的权限，覆盖掉旧文件原来的 644 —— 也就是说
+     *     用户只要保存过一次配置，老文件的权限就被修正了，不需要单独做迁移
+     *   - Windows 上 mode 被忽略，不影响运行
+     */
+    await fs.writeFile(tmp, text, { encoding: 'utf8', mode: 0o600 });
     await fs.rename(tmp, file);
   } catch (e) {
     await fs.rm(tmp, { force: true }).catch(() => {});

package/src/hashdir.js

@@ -77,16 +77,24 @@ async function collect(root) {
 }
 
 /**
- * 算目录的内容指纹。
+ * 按给定的相对路径清单算指纹。
  *
- * @param {string} dir 插件目录
+ * 为什么要单独一个入口：仓库根目录里有 `data/`、`logs/`、`config/`、`plugins/`
+ * 这些**不会被 tarball 打包**的东西，直接 `hashDir(ROOT)` 会把它们算进去，
+ * 跟「解包后的 tarball」永远对不上。
+ *
+ * 所以发布流程用 `git ls-files` 拿到「真正会被打进包的文件」，再喂给这里；
+ * 更新校验则用 `hashDir(解包目录)`。两边必须用同一套拼接方式，否则校验必失败。
+ *
+ * @param {string} root 根目录
+ * @param {string[]} rels 相对路径（`/` 分隔）；内部会去重并排序，顺序无关
  * @returns {Promise<string>} 64 位十六进制
  */
-export async function hashDir(dir) {
-  const files = await collect(dir);
+export async function hashFileList(root, rels) {
+  const files = [...new Set(rels)].sort();
   const h = crypto.createHash('sha256');
   for (const rel of files) {
-    const buf = normalize(await fs.readFile(path.join(dir, rel)));
+    const buf = normalize(await fs.readFile(path.join(root, rel)));
     h.update(rel);
     h.update('\0');
     h.update(String(buf.length));
@@ -96,3 +104,38 @@ export async function hashDir(dir) {
   }
   return h.digest('hex');
 }
+
+/**
+ * 算目录的内容指纹。
+ *
+ * @param {string} dir 插件目录
+ * @param {{exclude?: string[], only?: string[]}} [opts]
+ *   - `exclude`：精确匹配要跳过的相对路径（如 `SHA256SUMS` 这种会自引用的文件）
+ *   - `only`：只算这些路径（`src` 这类目录前缀，或 `package.json` 这类文件名）。
+ *     用途：GitHub 的 tarball 是**全量**（含 .github、scripts、sdk），
+ *     而 Gitee 源只拉会被更新覆盖的那几个条目，两边目录内容天生不同。
+ *     用 `only` 把范围收窄到「真正会被替换的代码」，两边才算得出同一个值。
+ * @returns {Promise<string>} 64 位十六进制
+ */
+export async function hashDir(dir, opts = {}) {
+  /**
+   * 根目录不存在时必须报错，**不能静默返回空哈希**。
+   *
+   * `collect()` 里对每个目录都有 try/catch（遍历时子目录读不到要跳过），
+   * 但连根目录都不存在时它也会安静地返回空数组，算出来就是
+   * `e3b0c442…`（空字符串的 sha256）—— 那是一个**合法值**，会像真指纹一样
+   * 参与比对，现象是「内容全变了」而不是「路径写错了」，排查时非常误导。
+   */
+  const st = await fs.stat(dir).catch(() => null);
+  if (!st?.isDirectory()) throw new Error(`算指纹失败：目录不存在或不是目录 —— ${dir}`);
+
+  const skip = new Set(opts.exclude ?? []);
+  const only = (opts.only ?? []).map((p) => String(p));
+  let files = (await collect(dir)).filter((rel) => !skip.has(rel));
+  if (only.length) {
+    files = files.filter((rel) =>
+      only.some((p) => rel === p || rel.startsWith(p.endsWith('/') ? p : `${p}/`)),
+    );
+  }
+  return hashFileList(dir, files);
+}

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/mirror.js

@@ -86,9 +86,36 @@ const AUTO_TTL = 10 * 60_000;
 export function configureMirror(globalCfg) {
   const n = globalCfg?.network ?? {};
   const id = String(n.mirror ?? 'auto').trim() || 'auto';
+
+  /**
+   * 自定义下载前缀必须是 https。
+   *
+   * 这个值会被直接拼在 tarball 地址前面（见 applyMirror），而这个项目**更新包
+   * 没有内容校验**（updater.js 的 expectSha256 恒为 null）。也就是说：
+   * 填一个 http 地址，等于让链路上的任何人决定你下一版跑什么代码。
+   *
+   * 不合法就退回默认（不用它），而不是抛错 —— 配置文件写错了不该让整个框架起不来。
+   */
+  let custom = String(n.mirrorCustom ?? '').trim();
+  if (custom) {
+    let u = null;
+    try {
+      u = new URL(custom.includes('://') ? custom : `https://${custom}`);
+    } catch {
+      u = null;
+    }
+    if (!u || u.protocol !== 'https:') {
+      log.warn(
+        `network.mirrorCustom 必须是 https:// 开头，已忽略：${custom}\n` +
+          '  （自定义下载源会决定你下一版跑什么代码，明文 http 等于把它交给链路上的任何人）',
+      );
+      custom = '';
+    }
+  }
+
   current = {
     id: PRESETS.some((p) => p.id === id) ? id : 'auto',
-    custom: String(n.mirrorCustom ?? '').trim(),
+    custom,
     // Gitee 私人令牌：选填。公开仓库匿名也能用，填了只是把 API 配额提上去
     giteeToken: String(n.giteeToken ?? '').trim(),
   };
@@ -160,6 +187,17 @@ export function applyMirror(url, preset, custom = current.custom) {
     // 允许用户只填域名，自动补协议和结尾斜杠
     let b = base.trim();
     if (!/^https?:\/\//i.test(b)) b = `https://${b}`;
+    /**
+     * 自定义前缀必须是 https —— 这里再挡一道。
+     *
+     * configureMirror 已经校验过配置里的值，但 `probeMirrors` 的 custom 是
+     * 面板请求体直接传进来的（「测速」按钮），不经过 configureMirror。
+     * 不合法就**退回原始地址**，不要拼一个 http 前缀上去。
+     */
+    if (preset.kind === 'custom' && !/^https:\/\//i.test(b)) {
+      log.warn(`自定义下载源必须是 https，已忽略：${base}`);
+      return url;
+    }
     if (!b.endsWith('/')) b += '/';
     // 已经是这个前缀了就别套第二次
     if (url.startsWith(b)) return url;

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/update-scope.js

@@ -0,0 +1,28 @@
+/**
+ * 更新会替换的代码条目（单一来源）
+ * ================================
+ *
+ * 三处共用：
+ *   1. `updater.js` 备份与替换（rsync 式覆盖，绝不碰 config/data/logs/plugins）
+ *   2. `gitee.js` 的前缀过滤（Gitee 没有 archive 直链，只能按清单逐个拉）
+ *   3. `scripts/build-sums.mjs` 算内容指纹的范围
+ *
+ * 为什么指纹也按这个范围算：GitHub 的 tarball 是**全量**（还带 .github、
+ * scripts、sdk、types），而 Gitee 源只拉下面这几个条目。如果指纹按「包里的
+ * 全部文件」算，两条下载路径永远对不上 —— 一边写死校验失败，一边等于没校验。
+ *
+ * 改这个清单要连带重跑 `npm run sums`，否则已发布的指纹会全部失配。
+ */
+export const CODE_ENTRIES = [
+  'src',
+  'web',
+  'test',
+  'docs',
+  'package.json',
+  'README.md',
+  'LICENSE',
+  'start.bat',
+];
+
+/** 绝对不能删/覆盖的目录（双保险） */
+export const PROTECTED_ENTRIES = new Set(['config', 'data', 'logs', 'plugins', 'node_modules', '.git']);

package/src/updater.js

@@ -20,6 +20,8 @@ import { createLogger } from './logger.js';
 import { fetchAndExtract } from './tarball.js';
 import { fetchViaMirror, currentMirror } from './mirror.js';
 import { fetchGiteeTree, detectGiteeRef, giteeRawUrl } from './gitee.js';
+import { hashDir } from './hashdir.js';
+import { CODE_ENTRIES, PROTECTED_ENTRIES as PROTECTED } from './update-scope.js';
 import { ROOT } from './config.js';
 
 const log = createLogger('update');
@@ -27,11 +29,11 @@ const log = createLogger('update');
 /** 仓库信息。换成自己的 fork 就改这里 */
 const REPO = 'tdcq9594/qq-bot-roost';
 
-/** 允许被更新覆盖的顶层条目。**用户数据一个都不在里面** */
-const CODE_ENTRIES = ['src', 'web', 'test', 'docs', 'package.json', 'README.md', 'LICENSE', 'start.bat'];
-
-/** 绝对不能删的目录，双保险 */
-const PROTECTED = new Set(['config', 'data', 'logs', 'plugins', 'node_modules', '.git']);
+/**
+ * 允许被更新覆盖的顶层条目、以及绝对不能碰的目录，都在 ./update-scope.js。
+ * 内容指纹用的是**同一份清单**——GitHub tarball 是全量、Gitee 只拉这几个条目，
+ * 范围不一致的话两条下载路径算出来的指纹永远对不上。
+ */
 
 /**
  * Gitee 源下拉取的文件范围：只拉会被更新覆盖的代码条目。
@@ -100,9 +102,58 @@ async function updatedButNotRestarted() {
  * 包一层而不是往 checkUpdate 里塞：里面有好几个返回分支（Gitee /
  * 主站 302 / API 兜底 / 404 / 失败），每个都手写一遍 needsRestart 迟早漏一个。
  */
+/**
+ * 拉 SHA256SUMS，得到「版本 → 内容指纹」的映射。
+ *
+ * 两个源都试：GitHub raw（经下载源改写）和 Gitee raw。任何一边拿到都行，
+ * 因为指纹是「代码内容」的，与从哪个源下载无关。
+ *
+ * @returns {Promise<Map<string,string>>} 版本号 → 64 位十六进制
+ */
+async function fetchSumsMap() {
+  const urls = [
+    `https://raw.githubusercontent.com/${REPO}/master/SHA256SUMS`,
+    `https://gitee.com/${REPO}/raw/master/SHA256SUMS`,
+  ];
+  for (const u of urls) {
+    try {
+      const res = await fetchViaMirror(u, {
+        headers: { 'User-Agent': 'qq-bot-roost-updater' },
+        signal: AbortSignal.timeout(8000),
+      });
+      if (!res.ok) continue;
+      const text = await res.text();
+      const map = new Map();
+      for (const line of text.split(/\r?\n/)) {
+        const m = /^([a-f0-9]{64})\s+v?([0-9][\w.+-]*)$/i.exec(line.trim());
+        if (m) map.set(m[2].replace(/^v/i, ''), m[1].toLowerCase());
+      }
+      if (map.size) return map;
+    } catch {
+      // 换下一个源
+    }
+  }
+  return new Map();
+}
+
+/**
+ * 查某个版本的内容指纹。拿不到返回 null —— 真正的拒绝发生在 applyUpdate，
+ * 因为「只检查不安装」时面板仍应正常显示有新版本，只是点更新会失败。
+ */
+async function fetchTreeSha256(version) {
+  try {
+    const map = await fetchSumsMap();
+    return map.get(String(version).replace(/^v/, '')) ?? null;
+  } catch {
+    return null;
+  }
+}
+
 export async function checkUpdate() {
   const needsRestart = await updatedButNotRestarted();
   const r = await checkUpdateCore();
+  // 有新版本才值得多跑一次网络请求
+  if (r?.ok && r.hasUpdate) r.treeSha256 = await fetchTreeSha256(r.latest);
   return { ...r, needsRestart };
 }
 
@@ -442,6 +493,37 @@ async function applyUpdateOnce(info) {
       throw new Error('下载的包里没有 src/main.js，不是合法的框架包，已中止');
     });
 
+    /**
+     * 内容指纹校验 —— **必须放在备份和替换之前**。
+     *
+     * 这一步失败就等于什么都没发生过：文件没动、备份也没建。
+     *
+     * 为什么必须严格：更新会直接覆盖 `src/`、`web/` 这些要执行的代码。
+     * 只要能改掉下载地址（自定义镜像、上游仓库被入侵、链路劫持），
+     * 就能决定用户下一版跑什么。指纹对不上就说明「下载到的东西不是作者发的」。
+     *
+     * 为什么没有指纹也要拒绝：留一个「没指纹就放行」的口子，攻击者只要把
+     * SHA256SUMS 里那条删掉或让仓库回到没有该文件的形态就能绕过。
+     * 代价是发布流程必须每版都带指纹 —— 这由 CI 的 `npm run sums:check` 守着。
+     */
+    if (!rel.treeSha256) {
+      throw new Error(
+        `v${rel.latest} 没有发布内容指纹（SHA256SUMS 里查不到），已拒绝自动更新。\n` +
+          '这不是你的网络问题：作者这一版可能漏了生成指纹。\n' +
+          '可以手动到 GitHub Releases 下载安装，或等下一版。你的代码没有任何改动。',
+      );
+    }
+    const gotHash = await hashDir(workDir, { only: CODE_ENTRIES });
+    if (gotHash !== rel.treeSha256) {
+      throw new Error(
+        `更新内容校验失败，已中止（你的代码没有任何改动）。\n` +
+          `  期望 ${rel.treeSha256}\n` +
+          `  实际 ${gotHash}\n` +
+          '可能是下载源被篡改，或者发布时改了代码却忘了重跑 npm run sums。',
+      );
+    }
+    log.info(`内容指纹校验通过（${gotHash.slice(0, 12)}…）`);
+
     // 备份现有代码
     await fs.mkdir(backupDir, { recursive: true });
     for (const name of CODE_ENTRIES) {

package/src/web/server.js

@@ -43,6 +43,19 @@ import {
 const log = createLogger('webui');
 const WEB_ROOT = path.join(ROOT, 'web');
 
+/**
+ * 进程实例标识。
+ *
+ * 面板用它判断「服务是不是重启过」。重启意味着两件事同时发生：
+ *   - 页面令牌全部重新生成 → 已打开的插件页 iframe 手里拿的全是废牌，
+ *     之后每个请求都会被判成跨站（403）
+ *   - 会话 Cookie 全部失效
+ *
+ * 前端拿到这个值一变化，就可以立刻重载 iframe，而不是干等兜底轮询
+ * （用户会看到一条红色报错闪过，体验很差）。
+ */
+const PROCESS_STARTED_AT = Date.now();
+
 /**
  * 主面板的 CSP。
  *
@@ -321,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 连接（一个页面一个） */
@@ -433,6 +505,11 @@ export async function startWebServer({
             : people.find((p) => p.openid === c.id)?.name ?? '',
       }));
     }
+    /**
+     * 进程实例标识：前端一看到它变了就知道服务重启过，
+     * 页面令牌和会话都已作废，需要立刻重载插件页而不是等下轮轮询。
+     */
+    snap.instanceId = `${process.pid}-${PROCESS_STARTED_AT}`;
     return snap;
   };
 
@@ -585,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) {
@@ -645,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;
@@ -853,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);
@@ -884,11 +997,25 @@ export async function startWebServer({
          */
         if (req.method === 'OPTIONS') {
           const origin = String(req.headers.origin || '');
+          /**
+           * 允许的头**回显浏览器要的那个**，不写死。
+           *
+           * 踩过的坑：原来写死 `Content-Type`，看着没错，但浏览器报的是
+           * 「Request header field content-type is not allowed by
+           * Access-Control-Allow-Headers in preflight response」。
+           * 回显 `Access-Control-Request-Headers` 就永远不会对不上 ——
+           * 它问什么我给什么，反正是插件页自己的只读请求。
+           *
+           * **不要加 `Access-Control-Max-Age`**：加了浏览器会把这次预检结果
+           * 缓存好几分钟，一旦某次响应是错的（或者服务端刚改过逻辑），
+           * 后面再改代码都没用 —— 浏览器压根不会重新来问，只会一直报同一个错，
+           * 排查时会以为是代码没生效。本地面板的预检几乎没有开销，不值得缓存。
+           */
+          const wantHeaders = String(req.headers['access-control-request-headers'] || '');
           res.writeHead(204, {
             ...(origin === 'null' ? { 'Access-Control-Allow-Origin': 'null', Vary: 'Origin' } : {}),
             'Access-Control-Allow-Methods': 'GET, POST, PATCH, PUT, DELETE, OPTIONS',
-            'Access-Control-Allow-Headers': 'Content-Type, X-Access-Key, X-Token',
-            'Access-Control-Max-Age': '600',
+            'Access-Control-Allow-Headers': wantHeaders || 'Content-Type, X-Access-Key, X-Token',
           });
           return res.end();
         }
@@ -910,9 +1037,41 @@ export async function startWebServer({
          * 完全不受保护——跨站页面一个 text/plain 表单就能把它们打出去。
          */
         if (req.method !== 'GET' && req.method !== 'HEAD' && !isJsonRequest(req)) {
+          /**
+           * 这里以前完全静默 —— 而它恰恰是「插件页一片空白」最可能的入口：
+           * CORS 预检（OPTIONS）没有 body，如果哪天 OPTIONS 分支漏了或顺序错了，
+           * 预检就会掉进这里拿 415，浏览器判定预检失败，页面只看到
+           * `TypeError: Failed to fetch`，服务端一条日志都没有，排查全靠猜。
+           */
+          log.warn(
+            `拒绝写操作：${req.method} ${pathname}` +
+              `（Content-Type: ${req.headers['content-type'] || '无'}，需要 application/json）`,
+          );
           return json(res, 415, { error: '写操作需要 Content-Type: application/json' });
         }
         if (!isSameOrigin(req, ptPage)) {
+          /**
+           * 这里踩过一个很隐蔽的坑：插件页是 opaque origin，请求 `Origin` 恒为
+           * 字符串 `null`。它发的请求如果没带有效 `pt`（比如面板重启后 iframe
+           * 还拿着旧令牌），就会落到这个分支。
+           *
+           * 两个后果叠加，导致排查极其困难：
+           *   1. 403 响应没带 CORS 头 → 浏览器不给页面读状态码，页面只看到
+           *      `TypeError: Failed to fetch`，看起来像网络断了或服务没起
+           *   2. 这里不写日志 → 服务端一条记录都没有，像是请求根本没到
+           *
+           * 所以：给 opaque origin 补上 CORS 头（让它能读到 403 和错误文案），
+           * 并且**一定要留一条 warn**。没带令牌的情况单独说清楚，否则下次
+           * 还是得靠猜。
+           */
+          if (String(req.headers.origin || '') === 'null') {
+            res.setHeader('Access-Control-Allow-Origin', 'null');
+            res.setHeader('Vary', 'Origin');
+          }
+          log.warn(
+            `拒绝跨站请求：${req.method} ${pathname}` +
+              `（Origin: ${req.headers.origin || '无'}${ptPage ? '，页面令牌有效' : '，无有效页面令牌'}）`,
+          );
           return json(res, 403, { error: '跨站请求被拒绝' });
         }
 
@@ -1146,7 +1305,36 @@ export async function startWebServer({
           if (typeof body.appSecret === 'string' && body.appSecret && body.appSecret !== '********') {
             cfg.appSecret = body.appSecret.trim();
           }
-          if (body.baseUrl) cfg.baseUrl = body.baseUrl.trim();
+          /**
+           * baseUrl 必须校验，否则这里等于「把 access_token 送人」的开关。
+           *
+           * `api.js` 用这个 baseUrl 拼请求，并带上 `Authorization: QQBot <token>`。
+           * 面板一旦被改成第三方地址，下一次 API 调用就把机器人令牌发到那台机器，
+           * 拿到令牌就能冒充机器人在它所在的任何群里发消息 —— 面板弱口令会因此
+           * 直接升级成「机器人身份被完全接管」。
+           *
+           * 用 `*.qq.com` 而不是写死 `api.sgroup.qq.com`：官方历史上用过
+           * `api.bot.qq.com` 这类别名（现有配置里就有），写死会把用户自己的
+           * 合法配置挡回去。qq.com 是腾讯的域，第三方拿不到子域。
+           */
+          if (body.baseUrl !== undefined && body.baseUrl !== '') {
+            let u = null;
+            try {
+              u = new URL(String(body.baseUrl).trim());
+            } catch {
+              return json(res, 400, { error: 'baseUrl 不是合法 URL' });
+            }
+            const host = u.hostname.toLowerCase();
+            const official = host === 'qq.com' || host.endsWith('.qq.com');
+            if (u.protocol !== 'https:' || !official) {
+              return json(res, 400, {
+                error:
+                  'baseUrl 只允许 https 的腾讯官方域名（如 https://api.sgroup.qq.com）。\n' +
+                  '改成第三方地址会把 access_token 发过去，等于交出机器人身份。',
+              });
+            }
+            cfg.baseUrl = u.origin;
+          }
           if (body.intents !== undefined) {
             const n = Number(body.intents);
             if (!Number.isInteger(n) || n < 0 || n > 0x7fffffff) {
@@ -1269,7 +1457,12 @@ export async function startWebServer({
          * 面板据此显示「统计不可用」而不是画一堆 0。
          */
         if (pathname === '/api/stats' && req.method === 'GET') {
-          const days = Number(url.searchParams.get('days')) || 7;
+          /**
+           * `days` 必须夹紧。同文件下面的 `/api/stats/export` 早就 clamp 到
+           * 1~365 了，这里漏了 —— 传个极大值就能让 SQLite 扫全表，
+           * 面板上一次点击就变成一次自伤式 DoS。
+           */
+          const days = Math.max(1, Math.min(365, Number(url.searchParams.get('days')) || 7));
           try {
             return json(res, 200, rt.stats?.overview(days) ?? { available: false });
           } catch (e) {
@@ -1985,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);
@@ -2223,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

@@ -14,7 +14,16 @@
  * 这点和官方示例一致——一个回调地址服务多个机器人，省得每个机器人开一个端口。
  */
 import http from 'node:http';
+import fs from 'node:fs';
+/**
+ * 这里**必须具名导入** `join` / `dirname`，不能 `import path from 'node:path'`。
+ * constructor 有个参数就叫 `path`（回调路径），会把模块级的 `path` 遮蔽掉，
+ * 于是 `path.join(...)` 变成「字符串.join」→ `TypeError: path.join is not a function`，
+ * 整个 Webhook 服务直接起不来。这个坑是靠实测抓到的，不是看代码能看出来的。
+ */
+import { join, dirname } from 'node:path';
 import { createLogger } from './logger.js';
+import { DIRS } from './paths.js';
 import { verifyRequest, verifyEventSignature } from './sign.js';
 
 const log = createLogger('webhook');
@@ -24,25 +33,119 @@ 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 && 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.verifySignature = verifySignature !== false;
+    this.seenEvents = new Map();
     /** @type {Map<string, {secret:string, onEvent:Function, onError?:Function}>} */
     this.bots = new Map();
     this.server = null;
     this.running = false;
     /** 收到过多少事件，面板显示用 */
     this.counters = { received: 0, rejected: 0, verify: 0 };
+    /**
+     * 回调验证（op=13）的状态，按 appId 记：`{ okAt: 时间戳, hits: [最近一分钟的尝试] }`。
+     *
+     * 为什么需要它，见 #handle 里 op=13 那段长注释。简单说：这个接口会用
+     * AppSecret 给「任意提交内容」签名，而事件验签用的是同一把密钥、同一种
+     * 拼接方式 —— 放开了就等于对外提供签名服务。
+     */
+    this.verifyState = new Map();
+    this.verifyFile = join(DIRS.data, 'webhook-verified.json');
+    this.#loadVerifyState();
+  }
+
+  /** 读回落盘的回调验证记录：重启不该让平台被迫重新验证一次 */
+  #loadVerifyState() {
+    try {
+      const obj = JSON.parse(fs.readFileSync(this.verifyFile, 'utf8'));
+      for (const [id, at] of Object.entries(obj)) {
+        const t = Number(at);
+        if (Number.isFinite(t) && t > 0) this.verifyState.set(id, { okAt: t, hits: [] });
+      }
+    } catch (e) {
+      // 文件不存在是正常的（第一次跑），其它错误才值得说一句
+      if (e.code !== 'ENOENT') log.warn(`回调验证记录读不出来（忽略）：${e.message}`);
+    }
+  }
+
+  #saveVerifyState() {
+    try {
+      fs.mkdirSync(dirname(this.verifyFile), { recursive: true });
+      const obj = {};
+      for (const [id, s] of this.verifyState) if (s.okAt) obj[id] = s.okAt;
+      const tmp = `${this.verifyFile}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(obj, null, 2));
+      fs.renameSync(tmp, this.verifyFile); // 原子替换，避免写一半断电
+    } catch (e) {
+      log.warn(`回调验证记录写不进去（不影响运行）：${e.message}`);
+    }
+  }
+
+  /**
+   * 重置某个机器人的回调验证状态。
+   *
+   * 用途：平台那边改了回调地址 / 换了域名，需要重新走一次 op=13 验证。
+   * 面板可以挂一个「重新验证回调」按钮调它，也可以直接删
+   * `data/webhook-verified.json` 里对应的那条。
+   *
+   * @returns {boolean} 是否真的重置了（原来有记录才返回 true）
+   */
+  resetVerify(appId) {
+    const id = String(appId ?? '').trim();
+    if (!id) return false;
+    const s = this.verifyState.get(id);
+    if (!s) return false;
+    this.verifyState.set(id, { okAt: 0, hits: [] });
+    this.#saveVerifyState();
+    log.info(`[${id}] 已重置回调验证状态，等待平台重新验证`);
+    return true;
   }
 
   /**
@@ -131,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' });
@@ -143,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();
@@ -173,14 +307,68 @@ export class WebhookServer {
 
     // op=13：平台验证回调地址，用 AppSecret 签名后原样返回
     if (payload?.op === 13) {
+      /**
+       * ⚠️ 整段 Webhook 里最危险的就是这里，改之前把这段读完。
+       *
+       * op=13 的签名内容是 `${event_ts}${plain_token}`，事件验签是
+       * `${timestamp}${rawBody}` —— **同一把密钥、同一种拼接、没有域分离**。
+       * 而 op=13 在验签之前、也不需要任何认证，只要 appId 在册就回签。
+       *
+       * 于是它可以被当成「任意内容签名服务」：把要伪造的事件体当 plain_token
+       * 提交，拿回来的签名直接能过事件验签 —— 冒充任意 openid 触发管理命令。
+       * 也就是说 `verifySignature: true` 在攻击者面前是形同虚设的。
+       *
+       * 签名内容由官方协议规定，应用层改不了（改了平台就不认）。所以只能
+       * 收紧「谁能调、能调几次」：
+       *
+       *   1. **plain_token 形态校验**：事件体必然是 JSON，一定含 { } " \ 或空白；
+       *      合法 token 是平台生成的随机串。这条零成本、不影响正常流程，是主防线。
+       *   2. **24 小时内只回签一次**：平台只在配置回调地址时验证。
+       *      不做成「永久一次」是因为换域名/端口要重新验证，永久锁死会让用户
+       *      卡在「回调地址验证失败」上，反而制造新的排查成本。
+       *   3. **每分钟最多 3 次尝试**，把爆破与滥用压到没有价值。
+       */
+      const st = this.verifyState.get(appId) ?? { okAt: 0, hits: [] };
+      const now = Date.now();
+      st.hits = st.hits.filter((t) => now - t < 60_000);
+
+      if (st.okAt && now - st.okAt < 24 * 3600_000) {
+        this.counters.rejected += 1;
+        log.warn(
+          `[${appId}] 拒绝重复的 op=13：该 appId 24 小时内已通过验证。` +
+            `如果确实要重新验证（换回调地址等），调 resetVerify() 或删掉 ` +
+            `data/webhook-verified.json 里这一条`,
+        );
+        return this.#json(res, 403, { error: 'already verified' });
+      }
+      if (st.hits.length >= 3) {
+        this.counters.rejected += 1;
+        log.warn(`[${appId}] op=13 尝试过频（每分钟上限 3 次），已限速`);
+        return this.#json(res, 429, { error: 'too many validation attempts' });
+      }
+      st.hits.push(now);
+      this.verifyState.set(appId, st);
+
+      const tok = String(payload?.d?.plain_token ?? '');
+      if (!tok || tok.length > 128 || /[\s{}"\\]/.test(tok)) {
+        this.counters.rejected += 1;
+        log.warn(
+          `[${appId}] op=13 的 plain_token 形态异常，已拒绝（疑似把事件体当 token 提交）`,
+        );
+        return this.#json(res, 400, { error: 'invalid validation' });
+      }
+
       const signed = verifyRequest(bot.secret, payload);
       if (!signed) {
         this.counters.rejected += 1;
         log.warn(`[${appId}] 回调验证缺少 plain_token / event_ts`);
         return this.#json(res, 400, { error: 'invalid validation' });
       }
+      st.okAt = now;
+      this.verifyState.set(appId, st);
+      this.#saveVerifyState();
       this.counters.verify += 1;
-      log.info(`[${appId}] Webhook 回调验证通过`);
+      log.info(`[${appId}] Webhook 回调验证通过（24 小时内不再重复回签）`);
       return this.#json(res, 200, signed);
     }
 
@@ -205,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 ?? {};

package/web/app.js

@@ -725,9 +725,25 @@ function renderStatus(s) {
   }
 }
 
+/** 上一次看到的进程实例标识，用来判断服务是不是重启过 */
+let lastInstanceId = '';
+
 async function pollStatus() {
   try {
-    renderStatus(await api('/api/status'));
+    const d = await api('/api/status');
+    /**
+     * 进程重启 ⇒ 页面令牌全部重新生成、会话也全失效。
+     * 已打开的插件页 iframe 手里还是旧令牌，接下来每个请求都会被判成跨站（403），
+     * 用户看到的就是「切过去先红一下，等一会儿才好」。
+     *
+     * 这里一发现实例换了就立刻刷新令牌并重载 iframe，不必等兜底轮询。
+     */
+    const iid = String(d?.instanceId || '');
+    if (lastInstanceId && iid && iid !== lastInstanceId) {
+      refreshPageTokens();
+    }
+    lastInstanceId = iid;
+    renderStatus(d);
   } catch (e) {
     $('#connText').textContent = '面板断开';
     $('#connPill').className = 'status-pill offline';
@@ -1351,6 +1367,17 @@ async function loadPluginPages() {
     frame.dataset.key = p.key;
     // 页面令牌：不是面板密钥，只对这一个插件自己的接口有效
     frame.dataset.token = p.token || '';
+    /**
+     * **直接设上地址（预加载），不再等用户点开。**
+     *
+     * 以前这里是懒加载：注释写「地址在点开的时候才算」，好处是不点就不请求。
+     * 但代价是第一次点插件标签要走完「下载 35KB HTML → 解析几百行内联脚本 →
+     * 拉数据 → 渲染」，主观上就是卡一下，用户容易以为坏了。
+     *
+     * 现在建标签时就开始加载，点过去就是现成的。切换机器人时这个函数会重跑，
+     * 地址里带上了新的 bot 参数，所以也不会串台。
+     */
+    frame.src = pluginPageUrl(p.key, p.token || '');
     sec.appendChild(frame);
     main.appendChild(sec);
   }
@@ -1385,6 +1412,64 @@ function pluginPageUrl(key, token) {
   return `/api/pages/${encodeURIComponent(key)}/html${s ? `?${s}` : ''}`;
 }
 
+/**
+ * 跟着进程重启自动换令牌。
+ *
+ * 页面令牌只存在服务端内存里，进程重启就全部重新生成。而面板页如果是在重启
+ * **之前**打开的，iframe 里还挂着旧令牌，插件页的所有请求都会被判成跨站
+ * （403），表现为「数据空白」或者直接 `Failed to fetch` —— 用户完全看不出
+ * 是重启导致的，只会觉得面板坏了。
+ *
+ * 这里定期问一次页面列表：令牌变了就更新 iframe 的地址并重载它。
+ * 只在令牌真的变化时才重载（也就是重启过），平时不会打断用户操作。
+ */
+async function refreshPageTokens() {
+  let list = null;
+  try {
+    list = await api('/api/pages');
+  } catch {
+    return 0;
+  }
+  if (!Array.isArray(list)) return 0;
+
+  let reloaded = 0;
+  for (const p of list) {
+    for (const f of $$('.plugin-page')) {
+      if (f.dataset.key !== p.key) continue;
+      if (f.dataset.token === (p.token || '')) continue;
+      f.dataset.token = p.token || '';
+      // 只重载已经打开过的（没加载过的不去碰，免得白跑一次请求）
+      if (f.getAttribute('src')) {
+        f.src = pluginPageUrl(f.dataset.key, f.dataset.token);
+        reloaded += 1;
+      }
+    }
+  }
+  return reloaded;
+}
+
+// 15 秒足够快，又不会给面板添负担；令牌不变时这里什么都不做
+setInterval(() => {
+  refreshPageTokens();
+}, 15000);
+
+/**
+ * 切回面板时立刻补一次。
+ *
+ * 两个真实场景：
+ *   1. 浏览器会把后台标签页的定时器降频（Chrome 最长到 1 分钟一次），
+ *      所以「去改个配置再切回来」最容易撞上旧令牌
+ *   2. 保存配置会触发 config-watch 热加载，插件被卸载重载 → 页面令牌
+ *      跟着重新生成 → 已打开的 iframe 立刻变无效
+ * 回来这一下立刻修，比等定时器体感好得多。
+ */
+window.addEventListener('focus', () => {
+  refreshPageTokens();
+});
+document.addEventListener('visibilitychange', () => {
+  if (!document.hidden) refreshPageTokens();
+});
+
 /* ---------------- 统计 ---------------- */
 
 /** 每天一根柱子，纯 CSS 不用图表库——多引一个库就破了零依赖 */