@xcanwin/manyoyo 8.4.0 → 8.5.0

package/bin/manyoyo.js

@@ -9,6 +9,7 @@ const net = require('net');
 const readline = require('readline');
 const { Command, Help } = require('commander');
 const { startWebServer } = require('../lib/web/server');
+const { isSidecarName } = require('../lib/egress-sidecar');
 const { buildContainerRunArgs, buildContainerRunCommand, runWithEnvFile, hasNetworkArg } = require('../lib/container-run');
 const { getManyoyoConfigPath, readManyoyoConfig, syncGlobalImageVersion } = require('../lib/global-config');
 const { resolveUpdateImageVersion } = require('../lib/image-version-policy');
@@ -994,6 +995,7 @@ function getContList() {
                 const image = cols[4] || '';
                 // include manyoyo runtime containers (image match)
                 // and plugin containers (both legacy manyoyo-* and new my-* prefixes)
+                if (isSidecarName(name)) return false; // 域名白名单的过滤代理容器不是用户的会话容器
                 return image.includes('manyoyo') || name.startsWith('manyoyo-') || name.startsWith('my-');
             });
 

package/lib/browser-background.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const { domainAllowed } = require('./network-policy');
+
+// 容器里的 Chrome 启动后会自己连一些谷歌的后台服务（更新、账号同步、字体 / 资源）。白名单下它们必然被拦，
+// 对用户没有意义：网络分区的“最近被拦截”把它们折叠成“浏览器后台请求”，对话里也不为它们提示。
+// 数据只写在这一处。
+const BROWSER_BACKGROUND_DOMAINS = [
+    'accounts.google.com',
+    'update.googleapis.com',
+    'www.google.com',
+    'www.gstatic.com',
+    'dl.google.com',
+    'clients2.google.com',
+    'android.clients.google.com',
+    'content-autofill.googleapis.com'
+];
+
+function isBrowserBackground(host) {
+    return domainAllowed(BROWSER_BACKGROUND_DOMAINS, host);
+}
+
+module.exports = { BROWSER_BACKGROUND_DOMAINS, isBrowserBackground };

package/lib/container-env.sh

@@ -0,0 +1,34 @@
+# manyoyo 容器内的 env 加载：init.sh 启动自启动前加载，终端里的 `reload-env` 也用它。
+# 由宿主机以只读目录挂到 /run/manyoyo-sys/env.sh，容器内不可改。
+# 与宿主机侧（lib/env-text.js）同一语法：一行 KEY=VALUE，# 注释与空行忽略，可选 `export ` 前缀与 `=` 两侧空白，
+# 值两端成对的引号去掉；不展开变量、不执行命令；key 必须合法
+load_env() {
+    local file=$1 line key val
+    [ -f "$file" ] || return 0
+    while IFS= read -r line || [ -n "$line" ]; do
+        line=${line%$'\r'}
+        line="${line#"${line%%[![:space:]]*}"}"
+        line="${line%"${line##*[![:space:]]}"}"
+        case $line in ''|'#'*) continue ;; esac
+        if [[ $line =~ ^export[[:space:]]+ ]]; then line=${line#"${BASH_REMATCH[0]}"}; fi
+        [[ $line =~ ^([^=[:space:]]+)[[:space:]]*=[[:space:]]*(.*)$ ]] || continue
+        key=${BASH_REMATCH[1]}
+        val=${BASH_REMATCH[2]}
+        [[ $key =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || continue
+        if [ "${#val}" -ge 2 ]; then
+            case $val in
+                \"*\") val=${val:1:${#val}-2} ;;
+                \'*\') val=${val:1:${#val}-2} ;;
+            esac
+        fi
+        export "$key=$val"
+    done < "$file"
+}
+
+# 已打开的终端里让最新的环境变量生效（优先级与新开终端一致：managed < 环境变量文件 < 用户 env）
+reload-env() {
+    local sys=${MANYOYO_SYS_DIR:-/run/manyoyo-sys} box=${MANYOYO_BOX_DIR:-/run/manyoyo}
+    load_env "$sys/managed.env"
+    load_env "$sys/files.env"
+    load_env "$box/env"
+}

package/lib/container-id.js

@@ -0,0 +1,11 @@
+'use strict';
+
+// 容器 id：随机 16 位十六进制，状态目录、过滤代理的映射与拒绝记录都按它索引。
+// 单独成文件：过滤代理 sidecar 里只带得动这几个无依赖的小文件。
+const ID_RE = /^[0-9a-f]{16}$/;
+
+function isValidId(id) {
+    return typeof id === 'string' && ID_RE.test(id);
+}
+
+module.exports = { ID_RE, isValidId };

package/lib/container-init.sh

@@ -10,30 +10,7 @@ log() { printf '%s %s\n' "$(date '+%F %T')" "$*" >> "$LOG" 2>/dev/null; }
 
 trap 'kill -TERM -1 2>/dev/null; exit 0' TERM INT
 
-# 与宿主机侧（lib/env-text.js）同一语法：一行 KEY=VALUE，# 注释与空行忽略，可选 `export ` 前缀与 `=` 两侧空白，
-# 值两端成对的引号去掉；不展开变量、不执行命令；key 必须合法
-load_env() {
-    local file=$1 line key val
-    [ -f "$file" ] || return 0
-    while IFS= read -r line || [ -n "$line" ]; do
-        line=${line%$'\r'}
-        line="${line#"${line%%[![:space:]]*}"}"
-        line="${line%"${line##*[![:space:]]}"}"
-        case $line in ''|'#'*) continue ;; esac
-        if [[ $line =~ ^export[[:space:]]+ ]]; then line=${line#"${BASH_REMATCH[0]}"}; fi
-        [[ $line =~ ^([^=[:space:]]+)[[:space:]]*=[[:space:]]*(.*)$ ]] || continue
-        key=${BASH_REMATCH[1]}
-        val=${BASH_REMATCH[2]}
-        [[ $key =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || continue
-        if [ "${#val}" -ge 2 ]; then
-            case $val in
-                \"*\") val=${val:1:${#val}-2} ;;
-                \'*\') val=${val:1:${#val}-2} ;;
-            esac
-        fi
-        export "$key=$val"
-    done < "$file"
-}
+. "$SYS/env.sh"
 
 # 日志超过 256 KiB 时只保留尾部 128 KiB
 if [ -f "$LOG" ] && [ "$(stat -c %s "$LOG" 2>/dev/null || echo 0)" -gt 262144 ]; then
@@ -44,8 +21,12 @@ run_autostart() {
     if [ -e "$SYS/net-required" ]; then
         log "等待 manyoyo 下发网络规则"
         while [ ! -e "$GATE/ready" ]; do sleep 0.5; done
+        log "网络规则已就绪"
+    fi
+    if [ ! -s "$BOX/autostart.sh" ]; then
+        log "没有自启动命令"
+        exit 0
     fi
-    [ -s "$BOX/autostart.sh" ] || exit 0
     load_env "$SYS/managed.env"
     load_env "$SYS/files.env"
     load_env "$BOX/env"

package/lib/container-network.js

@@ -11,6 +11,7 @@ const path = require('path');
 const state = require('./container-state');
 const { buildExecArgs } = require('./container-exec');
 const policyLib = require('./network-policy');
+const { createSidecarManager } = require('./egress-sidecar');
 
 // 容器网络：把策略翻译成 nft 规则，用一次性 helper 容器（--network container:<名> + NET_ADMIN）写进
 // 目标容器自己的 netns。Agent 没有 NET_ADMIN，改不掉；规则热更新，不重启。
@@ -113,7 +114,7 @@ function createNetworkManager(options) {
     const runtimeEnv = options.env ? { ...process.env, ...options.env } : process.env;
     const getImageRef = typeof options.imageRef === 'function' ? options.imageRef : () => options.imageRef;
     const getMirrorUrls = options.getMirrorUrls || (() => []);
-    const getFilterProxy = options.getFilterProxy || (() => null);
+    const getUpstream = options.getUpstream || (() => process.env.HTTPS_PROXY || process.env.https_proxy || process.env.HTTP_PROXY || process.env.http_proxy || '');
     const warn = options.warn || (() => {});
     const locks = new Map();
 
@@ -147,6 +148,9 @@ function createNetworkManager(options) {
         });
     }
 
+    // 域名白名单的过滤代理：manyoyo 网络里的 sidecar 容器，按来源 IP 认容器（见 egress-sidecar.js）
+    const sidecar = createSidecarManager({ run, command, homeDir, imageRef: getImageRef, networkName: NETWORK_NAME, ensureNetwork: ensureBridgeNetwork, getUpstream });
+
     // buildExecArgs 只需要同步 inspect 取 id；这里 withEnv:false 不会用到
     const execCtx = { homeDir, dockerExecArgs: () => '' };
 
@@ -252,14 +256,17 @@ function createNetworkManager(options) {
         for (const target of uniqueBy(proxyTargets, t => `${t.host}:${t.port}`)) {
             for (const ip of await resolveHostToIps(target.host)) allow.push({ ip, ports: String(target.port), proto: 'tcp' });
         }
-        // 过滤代理（serve 进程内）：allowlist 容器经它出网；宿主机 IP 取容器视角的 host.containers.internal
+        // 过滤代理（sidecar 容器）：allowlist 容器经它出网，只放行到它的 IP:端口；
+        // 容器发往它的包来源必须是自己的 IP（第二道保险：识别身份靠的就是来源 IP）
         let managedEnv = [];
+        const antiSpoof = [];
         if (policy.preset === 'allowlist' && policy.egress.domains.length) {
-            const filter = await getFilterProxy(self.id);
-            if (!filter || !filter.port) throw new Error('域名白名单需要 manyoyo serve 运行（过滤代理在 serve 进程里）');
-            if (!hostIps.length) throw new Error('容器里找不到宿主机地址（host.containers.internal / 网关），无法使用域名白名单');
-            addHost(filter.port, 'tcp');
-            const url = `http://${self.id}:${state.ensureEgressToken(homeDir, self.id)}@${hostIps[0]}:${filter.port}`;
+            const selfBridge = safeBridge(self.info);
+            if (!selfBridge) throw new Error('域名白名单需要容器在 manyoyo 网络里，这个容器的网络不支持');
+            const proxy = await sidecar.ensure();
+            allow.push({ ip: proxy.ip, ports: String(proxy.port), proto: 'tcp' });
+            antiSpoof.push({ daddr: proxy.ip, saddr: selfBridge.ip });
+            const url = `http://${proxy.ip}:${proxy.port}`;
             managedEnv = ['HTTP_PROXY', 'HTTPS_PROXY', 'http_proxy', 'https_proxy'].map(key => `${key}=${url}`);
         }
         playwrightHostPorts().forEach(port => addHost(port, 'tcp'));
@@ -285,6 +292,7 @@ function createNetworkManager(options) {
         }
         return {
             managedEnv,
+            antiSpoof,
             dns: dnsServers,
             allow: uniqueBy(allow, a => `${a.ip}|${a.ports}|${a.proto}`),
             peerIn,
@@ -296,6 +304,20 @@ function createNetworkManager(options) {
         try { return bridgeOf(info); } catch (e) { return null; }
     }
 
+    // 过滤代理的「来源 IP → 容器 id + 策略」：所有运行中、属于本 HOME、策略是 allowlist 的容器
+    function syncEgressClients(all) {
+        const clients = {};
+        for (const item of all) {
+            if (!item.running || !state.stateExists(homeDir, item.id)) continue;
+            let policy;
+            try { policy = loadPolicy(item.id); } catch (e) { continue; }
+            if (policy.preset !== 'allowlist') continue;
+            const bridge = safeBridge(item.info);
+            if (bridge) clients[bridge.ip] = { id: item.id, preset: policy.preset, domains: policy.egress.domains, rules: policy.egress.rules };
+        }
+        sidecar.writeClients(clients);
+    }
+
     async function sendRuleset(name, text) {
         await run([
             'run', '--rm', '-i',
@@ -348,6 +370,7 @@ function createNetworkManager(options) {
             const endpoints = await resolveEndpoints(self, policy, all);
             state.syncFilesEnv(homeDir, self.id); // 环境变量文件的最新快照（供自启动脚本用）
             state.writeManagedEnv(homeDir, self.id, endpoints.managedEnv);
+            syncEgressClients(all); // 先让代理认得这个容器，再放行门闩
             await sendRuleset(name, policyLib.buildNftRuleset(policy, endpoints));
             await execInContainer(name, ['/bin/sh', '-c', `mkdir -p ${path.posix.dirname(GATE_READY)} && : > ${GATE_READY}`]);
             const privileged = Boolean(self.info.HostConfig && self.info.HostConfig.Privileged);
@@ -403,7 +426,18 @@ function createNetworkManager(options) {
         const startedAt = String((info.State && info.State.StartedAt) || '');
         const sameRun = status && status.startedAt === startedAt;
         if (sameRun && status.status === 'unsupported') return { status: 'unsupported' };
-        if (policy && sameRun && status.status === 'applied' && status.policyHash === policyHashOf(policy)) return { status: 'applied' };
+        if (policy && sameRun && status.status === 'applied' && status.policyHash === policyHashOf(policy)) {
+            // 规则还在，但过滤代理可能意外退了（容器出网此时是失败即关闭）：顺手拉起，失败不拦 exec
+            if (policy.preset === 'allowlist' && policy.egress.domains.length) {
+                try {
+                    if (!await sidecar.isHealthy()) {
+                        await sidecar.ensure();
+                        syncEgressClients(await listManaged());
+                    }
+                } catch (e) { warn(`域名白名单代理恢复失败: ${e.message}`); }
+            }
+            return { status: 'applied' };
+        }
         return await apply(name, { expectId: id });
     }
 
@@ -433,11 +467,49 @@ function createNetworkManager(options) {
                 warn(`容器 ${item.name} 网络规则下发失败: ${e.message}`);
             }
         }
+        // 没有容器需要重新下发规则时，过滤代理也要在（运行时重启后它同样是停着的）
+        await healSidecar().catch(e => warn(`域名白名单代理恢复失败: ${e.message}`));
     }
 
     // 订阅容器 start 事件：容器被外部重启（podman restart、machine 重启后手动 start）后 netns 重建、规则丢失，
     // 事件到来就重新下发，并重算与它有 peers 关系的容器（它的 IP 可能变了）。
-    function watchStarts() {
+    async function needsSidecar(all) {
+        return all.some(item => {
+            if (!state.stateExists(homeDir, item.id)) return false;
+            try {
+                const policy = loadPolicy(item.id);
+                return policy.preset === 'allowlist' && policy.egress.domains.length > 0;
+            } catch (e) { return false; }
+        });
+    }
+
+    // 过滤代理容器自己退出 / 被删：有 allowlist 容器就拉起来，并重写映射
+    let lastHealAt = 0;
+    let healTimer = null;
+    async function healSidecar() {
+        // 起不来时（镜像坏了、权限问题）die 事件会反复触发：至少隔 10 秒才再试一次，不能形成忙等循环；
+        // 冷却期内的请求合并成冷却结束后的一次
+        const wait = 10000 - (Date.now() - lastHealAt);
+        if (wait > 0) {
+            if (!healTimer) {
+                healTimer = setTimeout(() => {
+                    healTimer = null;
+                    healSidecar().catch(e => warn(`域名白名单代理恢复失败: ${e.message}`));
+                }, wait + 50);
+                if (healTimer.unref) healTimer.unref();
+            }
+            return;
+        }
+        lastHealAt = Date.now();
+        const all = await listManaged();
+        if (!await needsSidecar(all)) return;
+        await sidecar.ensure();
+        syncEgressClients(all);
+    }
+
+    function watchStarts(watchOptions = {}) {
+        let attempts = 0;
+        let outageWarned = false;
         let stopped = false;
         let child = null;
         let delay = 1000;
@@ -451,7 +523,12 @@ function createNetworkManager(options) {
             timers.set(key, setTimeout(async () => {
                 timers.delete(key);
                 try {
+                    if (name === sidecar.name) {
+                        await healSidecar();
+                        return;
+                    }
                     if (status === 'start') await apply(name);
+                    if (status === 'die') syncEgressClients(await listManaged()); // 回收的 IP 不能再被认成它
                     for (const related of await relatedContainers(name, { includeStopped: status === 'die' })) {
                         await apply(related).catch(e => warn(`容器 ${related} 网络规则重算失败: ${e.message}`));
                     }
@@ -467,7 +544,9 @@ function createNetworkManager(options) {
             const attrs = event.Attributes || (event.Actor && event.Actor.Attributes) || {};
             const name = event.Name || attrs.name;
             const status = event.Status || event.status || event.Action;
-            if ((status !== 'start' && status !== 'die') || !name || !state.isValidId(attrs['manyoyo.id'])) return null;
+            if ((status !== 'start' && status !== 'die') || !name) return null;
+            if (name === sidecar.name && attrs['manyoyo.role'] === 'egress') return { name, status };
+            if (!state.isValidId(attrs['manyoyo.id'])) return null;
             return { name, status };
         };
 
@@ -499,7 +578,17 @@ function createNetworkManager(options) {
             };
             child.on('error', again);
             child.on('close', again);
-            reconcileAll().catch(e => warn(`网络规则对账失败: ${e.message}`));
+            // 第二次起的连接 = 事件流断过，运行时可能重启过（machine 重启、服务重置）：除了补下发规则，
+            // 还要让调用方把该拉起的容器拉起来。运行时还没恢复时对账会失败，每次断线只警告一次
+            attempts += 1;
+            const reconnected = attempts > 1;
+            reconcileAll()
+                .then(() => (reconnected && watchOptions.onReconnect ? watchOptions.onReconnect() : null))
+                .then(() => { outageWarned = false; })
+                .catch(e => {
+                    if (!outageWarned) warn(`网络规则对账失败: ${e.message}`);
+                    outageWarned = true;
+                });
         };
         connect();
         return {
@@ -512,7 +601,7 @@ function createNetworkManager(options) {
         };
     }
 
-    return { NETWORK_NAME, run, listManaged, loadPolicy, ensureBridgeNetwork, apply, ensureReady, relatedContainers, resolveEndpoints, reconcileAll, watchStarts };
+    return { NETWORK_NAME, sidecar, run, listManaged, loadPolicy, ensureBridgeNetwork, apply, ensureReady, relatedContainers, resolveEndpoints, reconcileAll, watchStarts };
 }
 
 module.exports = {

package/lib/container-run.js

@@ -26,6 +26,9 @@ function buildContainerRunArgs(options) {
         'run', '-d',
         '--name', options.containerName,
         '--entrypoint', `${SYS_MOUNT}/init.sh`,
+        // docker 默认带 NET_RAW（podman 默认不带）：有它的容器能发原始包 / 伪造 ARP，冒充别的容器的来源 IP，
+        // 域名白名单的过滤代理就是按来源 IP 认容器的，所以统一去掉
+        '--cap-drop', 'NET_RAW',
         ...(options.contModeArgs || []),
         ...(options.containerExtraArgs || []),
         ...(options.defaultNetwork && !hasNetworkArg([...(options.contModeArgs || []), ...(options.containerExtraArgs || [])])

package/lib/container-state.js

@@ -9,17 +9,14 @@ const { parseEnvEntry } = require('./runtime-normalizers');
 
 // 每个容器一个状态目录，按随机 manyoyo.id 索引（不按容器名：删了重建同名容器不会继承旧文件）
 //   box/  读写挂到 /run/manyoyo/        env、autostart.sh、autostart.log（容器可写）
-//   sys/  只读挂到 /run/manyoyo-sys/    init.sh、managed.env、net-required
+//   sys/  只读挂到 /run/manyoyo-sys/    init.sh、env.sh、managed.env、net-required
 //   network.json / meta.json            不挂进容器
-const ID_RE = /^[0-9a-f]{16}$/;
 const { ENV_KEY_RE, parseEnvText, serializeEnvEntries, formatEnvValue } = require('./env-text');
 const MAX_ENV_BYTES = 256 * 1024;
 const MAX_AUTOSTART_BYTES = 256 * 1024;
 const INIT_TEMPLATE = path.join(__dirname, 'container-init.sh');
-
-function isValidId(id) {
-    return typeof id === 'string' && ID_RE.test(id);
-}
+const ENV_TEMPLATE = path.join(__dirname, 'container-env.sh');
+const { ID_RE, isValidId } = require('./container-id');
 
 function newId() {
     return crypto.randomBytes(8).toString('hex');
@@ -44,13 +41,13 @@ function paths(homeDir, id) {
         autostart: path.join(dir, 'box', 'autostart.sh'),
         autostartLog: path.join(dir, 'box', 'autostart.log'),
         init: path.join(dir, 'sys', 'init.sh'),
+        envLoader: path.join(dir, 'sys', 'env.sh'),
         netRequired: path.join(dir, 'sys', 'net-required'),
         managedEnv: path.join(dir, 'sys', 'managed.env'),
         filesEnv: path.join(dir, 'sys', 'files.env'),
         envFiles: path.join(dir, 'env-files.json'),
         network: path.join(dir, 'network.json'),
         netStatus: path.join(dir, 'net-status.json'),
-        egressToken: path.join(dir, 'egress-token'),
         meta: path.join(dir, 'meta.json')
     };
 }
@@ -189,6 +186,7 @@ function createState(options) {
 function refreshInit(homeDir, id) {
     const p = paths(homeDir, id);
     ensureDir(p.sys, 0o700);
+    writeFileAtomic(p.envLoader, fs.readFileSync(ENV_TEMPLATE, 'utf-8'), 0o644);
     writeFileAtomic(p.init, fs.readFileSync(INIT_TEMPLATE, 'utf-8'), 0o755);
 }
 
@@ -400,23 +398,6 @@ function writeNetStatus(homeDir, id, status) {
     writeFileAtomic(paths(homeDir, id).netStatus, `${JSON.stringify(status)}\n`);
 }
 
-// 过滤代理的容器凭据：256 bit 随机，只存宿主机侧（不挂进容器，容器从自己的 managed.env 拿到带凭据的代理地址）
-function readEgressToken(homeDir, id) {
-    try {
-        return fs.readFileSync(paths(homeDir, id).egressToken, 'utf-8').trim() || null;
-    } catch (e) {
-        return null;
-    }
-}
-
-function ensureEgressToken(homeDir, id) {
-    const existing = readEgressToken(homeDir, id);
-    if (existing) return existing;
-    const token = crypto.randomBytes(32).toString('hex');
-    writeFileAtomic(paths(homeDir, id).egressToken, `${token}\n`);
-    return token;
-}
-
 function removeState(homeDir, id) {
     if (!isValidId(id)) return false;
     fs.rmSync(stateDir(homeDir, id), { recursive: true, force: true });
@@ -480,8 +461,6 @@ module.exports = {
     writeNetworkRaw,
     readNetStatus,
     writeNetStatus,
-    readEgressToken,
-    ensureEgressToken,
     removeState,
     listStateIds,
     findOrphans

package/lib/egress-denied.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { isValidId } = require('./container-id');
+
+// 过滤代理拒绝过的访问记录：每个容器一个 <id>.jsonl，同一 host:port 合并计数。
+// sidecar 里写（目录以读写方式挂入）、宿主机读 / 清空。文件超过 256 KiB 就丢最久没出现的。
+// 只依赖 node 内置模块：sidecar 里带的就是这个文件。
+const MAX_BYTES = 256 * 1024;
+const MAX_RECORDS = 1000;
+const FLUSH_MS = 1000;
+const MAX_PENDING_PER_ID = 500; // 一次合并周期内最多攒这么多不同的 host:port，防止被刷爆内存
+const MAX_HOST_LENGTH = 255;
+
+function fileOf(dir, id) {
+    if (!isValidId(id)) throw new Error(`非法的容器 id: ${id}`);
+    return path.join(dir, `${id}.jsonl`);
+}
+
+function parse(text) {
+    const records = [];
+    String(text || '').split('\n').forEach(line => {
+        if (!line.trim()) return;
+        try {
+            const r = JSON.parse(line);
+            if (typeof r.host === 'string' && Number.isInteger(r.port) && Number.isInteger(r.count)) {
+                records.push({ host: r.host, port: r.port, reason: String(r.reason || ''), count: r.count, first: String(r.first || ''), last: String(r.last || '') });
+            }
+        } catch (e) { /* 损坏的行跳过 */ }
+    });
+    return records;
+}
+
+function readFileSafe(file) {
+    try {
+        const stat = fs.statSync(file);
+        if (!stat.isFile() || stat.size > MAX_BYTES * 2) return '';
+        return fs.readFileSync(file, 'utf-8');
+    } catch (e) {
+        return '';
+    }
+}
+
+/** 宿主机：按最近出现时间倒序返回 [{host, port, reason, count, first, last}] */
+function read(dir, id) {
+    return parse(readFileSafe(fileOf(dir, id))).sort((a, b) => (a.last < b.last ? 1 : a.last > b.last ? -1 : 0));
+}
+
+/** 宿主机：清空（删文件；目录是宿主机用户的，sidecar 以 root 写出的文件也删得掉） */
+function clear(dir, id) {
+    try { fs.unlinkSync(fileOf(dir, id)); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+}
+
+function serialize(records) {
+    const sorted = records.slice().sort((a, b) => (a.last < b.last ? 1 : a.last > b.last ? -1 : 0)).slice(0, MAX_RECORDS);
+    let text = '';
+    const kept = [];
+    for (const r of sorted) {
+        const line = `${JSON.stringify(r)}\n`;
+        if (text.length + line.length > MAX_BYTES) break;
+        text += line;
+        kept.push(r);
+    }
+    return text;
+}
+
+/**
+ * sidecar：记录拒绝。内存里只攒“还没写盘的增量”，每秒合并进文件一次（高频路径不逐条写盘）；
+ * 合并时总是以磁盘上的当前内容为底，所以宿主机清空（删文件）后会从空白重新计数。
+ */
+function createRecorder(options) {
+    const dir = options.dir;
+    const now = options.now || (() => new Date().toISOString());
+    const pending = new Map(); // id → Map(host:port → record 增量)
+    let timer = null;
+
+    function record({ id, host, port, reason }) {
+        if (!isValidId(id) || !host || host.length > MAX_HOST_LENGTH || !Number.isInteger(port)) return;
+        const byKey = pending.get(id) || new Map();
+        pending.set(id, byKey);
+        const key = `${host}:${port}`;
+        if (!byKey.has(key) && byKey.size >= MAX_PENDING_PER_ID) return;
+        const at = now();
+        const hit = byKey.get(key);
+        if (hit) {
+            hit.count += 1;
+            hit.last = at;
+            hit.reason = reason;
+        } else {
+            byKey.set(key, { host, port, reason, count: 1, first: at, last: at });
+        }
+        if (!timer) {
+            timer = setTimeout(() => { timer = null; flush(); }, FLUSH_MS);
+            if (timer.unref) timer.unref();
+        }
+    }
+
+    function flush() {
+        const batch = [...pending.entries()];
+        pending.clear();
+        for (const [id, byKey] of batch) {
+            try {
+                const file = fileOf(dir, id);
+                const merged = new Map(parse(readFileSafe(file)).map(r => [`${r.host}:${r.port}`, r]));
+                byKey.forEach((delta, key) => {
+                    const old = merged.get(key);
+                    merged.set(key, old
+                        ? { ...old, reason: delta.reason, count: old.count + delta.count, last: delta.last }
+                        : delta);
+                });
+                const tmp = `${file}.tmp`;
+                fs.writeFileSync(tmp, serialize([...merged.values()]), { mode: 0o644 });
+                fs.renameSync(tmp, file);
+            } catch (e) { /* 写不进去不影响代理本身 */ }
+        }
+    }
+
+    function stop() {
+        if (timer) clearTimeout(timer);
+        timer = null;
+        flush();
+    }
+
+    return { record, flush, stop };
+}
+
+module.exports = { MAX_BYTES, MAX_RECORDS, MAX_PENDING_PER_ID, read, clear, parse, serialize, createRecorder };