ghprobe 0.0.0-stage → 0.1.0

package/src/net.js

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 zmw
+// 本地网络可用性检查：本机断网时直接跳过本轮 —— 不探测、不更新池、不写 hosts。
+// 为什么需要：断网时所有候选必然全灭，跑一轮纯属浪费，而且日志会被「stuck / 全灭」刷屏，
+// 掩盖真正的故障；更糟的是会让「网络故障」和「GitHub 被墙」两种情况混在一起无法区分。
+import os from "node:os";
+import net from "node:net";
+
+// 第一步（零成本）：有没有「已启用且带非回环 IPv4」的网卡。
+// 只能排除「网卡全禁用 / 只连了回环」这种最明显的情况，不能证明真能出去。
+export function hasInterface() {
+  const ifs = os.networkInterfaces();
+  for (const list of Object.values(ifs)) {
+    for (const a of list || []) {
+      if (!a.internal && (a.family === "IPv4" || a.family === 4)) { return true; }
+    }
+  }
+  return false;
+}
+
+// 第二步：TCP 连一下基准目标。只判断「本机能不能出去」，与 GitHub 是否可达无关 ——
+// 后者交给正常探测（换 IP 能救的属于 GitHub 侧，不在这里判）。
+export function canReach(host, port, timeoutMs) {
+  return new Promise((resolve) => {
+    const sock = net.connect({ host, port });
+    let done = false;
+    const fin = (ok) => {
+      if (done) { return; }
+      done = true;
+      try { sock.destroy(); } catch { /* 忽略 */ }
+      resolve(ok);
+    };
+    sock.setTimeout(timeoutMs, () => fin(false));
+    sock.on("connect", () => fin(true));
+    sock.on("error", () => fin(false));
+  });
+}
+
+// 基准目标默认用阿里公共 DNS 的 DoH 端点（223.5.5.5:443）：
+// 国内任何正常网络都该能连上，且它不是 GitHub —— 不会被 SNI 封锁影响判断。
+export async function hasLocalNetwork(cfg) {
+  const c = cfg.networkCheck || {};
+  if (c.enabled === false) { return true; }
+  if (!hasInterface()) { return false; }
+  const p = c.probe || {};
+  return canReach(p.host || "223.5.5.5", p.port ?? 443, p.timeoutMs ?? 2000);
+}

package/src/pool.js

@@ -0,0 +1,174 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 zmw
+// 候选池自动更新：从 GitHub 官方 api.github.com/meta 拉最新网段 → 展开成候选 IP → 缓存到用户目录。
+// 为什么需要它：GitHub 的 Azure 段（20.x / 4.x）在变，内置静态池会过期
+// （2026-10-11 实测：内置 24 个里有 4 个已不在官方 web 段）。
+// 🔴 api.github.com/meta 未认证限 60 次/小时 —— 所以只能低频（默认每天 1 次），绝不能轮询。
+import fs from "node:fs";
+import path from "node:path";
+import https from "node:https";
+import { userDataDir } from "./hosts.js";
+
+export function poolCachePath() {
+  return path.join(userDataDir(), "pool.cache.json");
+}
+
+export function readPoolCache() {
+  try {
+    const o = JSON.parse(fs.readFileSync(poolCachePath(), "utf8"));
+    return o && typeof o === "object" ? o : null;
+  } catch { return null; }
+}
+
+function writePoolCache(obj) {
+  const p = poolCachePath();
+  try {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(obj, null, 2), "utf8");
+  } catch { /* 写不了就算了，探测侧对缺缓存是宽容的 */ }
+}
+
+const toInt = (s) => s.split(".").reduce((a, o) => a * 256 + Number(o), 0) >>> 0;
+const toIp = (v) => [(v >>> 24) & 255, (v >>> 16) & 255, (v >>> 8) & 255, v & 255].join(".");
+
+// CIDR -> 候选 IP。
+// 🔴 不能全展开：meta 的 web 段里有 /20、/22，一个 /20 就是 4096 个地址，全展开会让探测成本爆炸。
+//    实际在用的是 /32 单播（GitHub 把它们逐个列出来就是给你白名单用的）与大段里的固定偏移
+//    （GitHub 习惯用段内 .3 / .4 做 web/api），所以大段只采样 perBigNet 个。
+export function expandCidr(cidr, perBigNet = 4) {
+  const raw = String(cidr || "").trim();
+  if (!raw || raw.includes(":")) { return []; } // 跳过 IPv6（本项目只探 v4）
+  const slash = raw.indexOf("/");
+  const net = slash === -1 ? raw : raw.slice(0, slash);
+  const bits = slash === -1 ? 32 : Number(raw.slice(slash + 1));
+  if (!Number.isFinite(bits) || bits < 0 || bits > 32) { return []; }
+  const parts = net.split(".");
+  if (parts.length !== 4 || parts.some((x) => !/^\d{1,3}$/.test(x) || Number(x) > 255)) { return []; }
+  if (bits === 32) { return [net]; }
+  const base = toInt(net);
+  const size = 2 ** (32 - bits);
+  const out = [];
+  for (let i = 0; i < perBigNet; i++) {
+    const v = (base + 3 + i) >>> 0;            // 从段内 .3 起
+    if (v >= base + size) { break; }
+    out.push(toIp(v));
+  }
+  return out;
+}
+
+// 用指定 IP + SNI 直连拉 meta。
+// 🔴 必须用 IP 直连：api.github.com 的 DNS 在国内被污染（实测直连拿不到响应），
+//    而这里恰恰是「还没有可用 IP 时」才需要它 —— 所以只能用配置里的种子池。
+// onReq：把底层 request 暴露给调用方，便于「某个种子先成功」时掐掉其余在飞的请求。
+function fetchMeta(ip, host, pathName, timeoutMs, onReq) {
+  return new Promise((resolve, reject) => {
+    const req = https.get({
+      host: ip,
+      port: 443,
+      servername: host,
+      path: pathName,
+      headers: { Host: host, "User-Agent": "ghprobe", Accept: "application/json" },
+      rejectUnauthorized: true,
+      timeout: timeoutMs,
+    }, (res) => {
+      if (res.statusCode !== 200) {
+        res.resume();
+        reject(new Error(`HTTP ${res.statusCode}`));
+        return;
+      }
+      let b = "";
+      res.setEncoding("utf8");
+      res.on("data", (d) => { b += d; });
+      res.on("end", () => { try { resolve(JSON.parse(b)); } catch (e) { reject(new Error("meta 不是合法 JSON")); } });
+    });
+    if (onReq) { onReq(req); }
+    req.on("timeout", () => req.destroy(new Error("timeout")));
+    req.on("error", reject);
+  });
+}
+
+// 并行试所有种子，**第一个成功的立刻返回**并掐掉其余在飞请求。
+// 为什么不用 Promise.allSettled：它要等**最慢**那个（黑洞种子会一直挂到 timeoutMs），
+// 实测总耗时 = 8s（正好一个 timeout），等于没并行。
+// 为什么不用 Promise.any：它只给第一个成功的值，拿不到「是哪个 IP 拉到的」，日志里就没法记 via。
+export function fetchFirstMeta(seeds, host, pathName, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    if (!seeds.length) { reject(new Error("没有可用种子 IP")); return; }
+    const reqs = [];
+    const errs = [];
+    let left = seeds.length;
+    let done = false;
+    const finish = (fn, arg) => {
+      if (done) { return; }
+      done = true;
+      for (const r of reqs) { try { r.destroy(); } catch { /* 忽略 */ } }
+      fn(arg);
+    };
+    for (const ip of seeds) {
+      fetchMeta(ip, host, pathName, timeoutMs, (r) => reqs.push(r)).then(
+        (json) => finish(resolve, { json, via: ip }),
+        (e) => {
+          errs.push(`${ip}:${e?.message || e}`);
+          left -= 1;
+          if (left === 0) { finish(reject, new Error(`所有种子 IP 都拉不到 ${host}（${errs.slice(0, 3).join(", ")}）`)); }
+        },
+      );
+    }
+  });
+}
+
+// 种子 IP：拉 meta 用的直连入口。优先用配置里的 seed 池，再退回 azure / fastly。
+export function seedIps(cfg) {
+  const p = cfg.ipPools || {};
+  return [...new Set([...(p.seed || []), ...(p.azure || []), ...(p.fastly || [])])];
+}
+
+// 一轮更新：拉 meta -> 展开 -> 写缓存。失败也会写 lastAttempt（冷却），避免每分钟重试撞 60 次/小时限制。
+export async function updatePool(cfg, log = () => {}) {
+  const u = cfg.poolUpdate || {};
+  const url = new URL(u.source || "https://api.github.com/meta");
+  const host = u.host || url.hostname;
+  const pathName = url.pathname || "/meta";
+  const timeoutMs = u.timeoutMs ?? 8000;
+  const attemptedAt = new Date().toISOString();
+  const prev = readPoolCache();
+  try {
+    const seeds = seedIps(cfg);
+    if (!seeds.length) { throw new Error("配置里没有种子 IP（ipPools.seed / azure / fastly 全为空）"); }
+    // 并行试所有种子，第一个成功的立刻返回（实测 8.2s -> 亚秒级；串行时是 2m13s）。
+    const { json, via } = await fetchFirstMeta(seeds, host, pathName, timeoutMs);
+
+    const sections = u.sections || ["web", "api"];
+    const maxIps = u.maxIps ?? 48;
+    const perBigNet = u.perBigNet ?? 4;
+    const cidrs = [];
+    for (const s of sections) { if (Array.isArray(json[s])) { cidrs.push(...json[s]); } }
+    // /32 优先：那些才是 GitHub 实际在用的入口；大段采样只是补充
+    const singles = cidrs.filter((c) => String(c).endsWith("/32")).flatMap((c) => expandCidr(c));
+    const bigs = cidrs.filter((c) => !String(c).endsWith("/32")).flatMap((c) => expandCidr(c, perBigNet));
+    const ips = [...new Set([...singles, ...bigs])].slice(0, maxIps);
+
+    const cache = { at: new Date().toISOString(), lastAttempt: attemptedAt, via, sections, count: ips.length, ips };
+    writePoolCache(cache);
+    log(`池已更新：${ips.length} 个 IP（via ${via}，段 ${sections.join("+")}）`);
+    return { ok: true, count: ips.length, via, path: poolCachePath() };
+  } catch (e) {
+    writePoolCache({ ...(prev || {}), lastAttempt: attemptedAt, lastError: String(e.message || e) });
+    throw e;
+  }
+}
+
+// 是否该更新。🔴 **成功与失败用同一档冷却**（intervalHours，默认 24h）：
+// 拉 meta 走的是 api.github.com —— 如果它被 SNI 层封锁，换任何 IP 都救不回，
+// 那种情况下反复重试毫无意义（还白撞 60 次/小时的 API 限制），所以失败后也等满一个周期再说。
+// 手动更新不受此限制：`ghprobe update-pool` 永远立即执行。
+export function poolNeedsUpdate(cfg) {
+  if (cfg.poolUpdate?.enabled === false) { return false; }
+  const intervalH = cfg.poolUpdate?.intervalHours ?? 24;
+  const c = readPoolCache();
+  const now = Date.now();
+  const fresh = (ts) => ts && now - new Date(ts).getTime() < intervalH * 3600_000;
+  if (fresh(c?.at)) { return false; }           // 成功过，没到点
+  if (fresh(c?.lastAttempt)) { return false; }  // 尝试过（成功或失败），没到点
+  return true;
+}

package/src/probe.js

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 zmw
+// 一轮完整探测：DoH 候选 + 内置池 -> 三关并发探测 -> 排名 -> 兜底轮
+import { resolveAll } from "./doh.js";
+import { probeIp, pool } from "./prober.js";
+import { rank, neededFallbacks } from "./ranker.js";
+
+// 该域名该用哪些内置池。
+// 默认（未配 domainPools 或配了不存在的池名）用全部池 —— 保持「与域名无关地全量进候选」
+// 的老行为，由 TLS 证书终审 + 应用层终审判归属。
+// 配了 domainPools 就只取指定的池：185.199.x.x（Fastly）永远不给 github.com 服务，
+// 20.x 也不给 raw.githubusercontent.com 服务，互探纯属浪费——冷启动能省掉近一半候选。
+export function poolsForDomain(cfg, domain) {
+  const pools = cfg.ipPools || {};
+  const names = cfg.domainPools?.[domain];
+  if (!Array.isArray(names) || names.length === 0) { return Object.values(pools).flat(); }
+  const picked = names.flatMap((n) => pools[n] || []);
+  return picked.length ? picked : Object.values(pools).flat();
+}
+
+// 解析一批域名的候选 IP。域名之间并行 —— DoH 是纯网络等待，串行会把最坏耗时
+// 乘上域名数（6 个域名 × dohMs 5s = 30s），并行后压回一个 dohMs。
+async function resolveCandidates(cfg, domains, say, { usePool = true, prefix = "" } = {}) {
+  return Promise.all(domains.map(async (domain) => {
+    say(prefix ? `${prefix}探测 ${domain}` : `解析 ${domain}`);
+    const { ips } = await resolveAll(cfg.doh, domain, cfg.timeouts.dohMs);
+    // 🔴 两个来源**各自限额后再合并**，绝不能对合并结果做总限额。
+    // 实测（2026-10）：DoH 对 github.com 返回的 8 条里有一半是 Fastly 的 185.199.x.x
+    // ——那是 githubusercontent 的节点，根本不给 github.com 服务。按总限额截断时，
+    // 内置池会被这堆垃圾整个挤掉，于是出现「20.29.134.23 明明是活的，工具却报
+    // stuck=github.com」。分开限额后内置池一定拿得到名额。
+    const fromDoh = (ips || []).slice(0, cfg.probe.maxCandidates);
+    const fromPool = usePool ? poolsForDomain(cfg, domain).slice(0, cfg.probe.maxPoolIps ?? 12) : [];
+    const candidates = [...new Set([...fromDoh, ...fromPool])];
+    say(`  候选 ${candidates.length} 个: ${candidates.join(", ")}`);
+    return { domain, candidates };
+  }));
+}
+
+// 把所有 (域名, IP) 拍平成任务队列，交给一个**全局**并发池跑。
+// 每个域名各自开一个池的话，实际并发 = 域名数 × concurrency（6×6=36 条 socket），
+// 会把最坏耗时和瞬时连接数同时放大；全局单池才是真正的「同时最多 N 条」。
+function jobsOf(cfg, resolved) {
+  const jobs = [];
+  for (const { domain, candidates } of resolved) {
+    for (const ip of candidates) { jobs.push(() => probeIp(domain, ip, cfg)); }
+  }
+  return jobs;
+}
+
+// onlyDomains：只探这些域名。部分更新（health 只发现某 1 个域名坏了）时用它，
+// 避免「1 个域名失效却把 6 个域名、近 50 个候选全探一遍」——那是几十秒的纯浪费。
+// 传 null / 空数组 = 全量。注意兜底域名不在 cfg.domains 里，若被点名必须单独直探。
+export async function runProbe(cfg, log, onlyDomains = null) {
+  const say = log || (() => {});
+  const fbDomains = Object.values(cfg.fallbacks || {}).flat();
+  const want = onlyDomains && onlyDomains.length ? new Set(onlyDomains) : null;
+  const mainDomains = cfg.domains.filter((d) => !want || want.has(d));
+  const directFb = want ? [...want].filter((d) => fbDomains.includes(d) && !cfg.domains.includes(d)) : [];
+
+  const resolved = await resolveCandidates(cfg, mainDomains, say);
+  const all = await pool(jobsOf(cfg, resolved), cfg.probe.concurrency);
+  const ranked = rank(all, cfg);
+
+  // 兜底轮：主域名全灭且配了替身 -> 探测替身域名
+  const extra = new Map();
+  const alts = [...new Set([...neededFallbacks(ranked, cfg), ...directFb])];
+  if (alts.length) {
+    const altResolved = await resolveCandidates(cfg, alts, say, { usePool: false, prefix: "兜底" });
+    const rs = await pool(jobsOf(cfg, altResolved), cfg.probe.concurrency);
+    for (const [d, list] of rank(rs, cfg)) {
+      if (list.length) { extra.set(d, list); }
+    }
+  }
+  return { ranked, extra, raw: all, at: new Date().toISOString() };
+}

package/src/prober.js

@@ -0,0 +1,178 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 zmw
+// 三关探测：TCP RTT -> TLS 握手 + 证书域名校验 -> HTTP 应用层终审
+// 证书校验拦的是 DNS 污染，应用层终审拦的是共享 CDN 上未部署该域名的"假活"IP
+import tls from "node:tls";
+import https from "node:https";
+
+// 目标域名的应用层指纹：真实业务路径、必须包含的响应特征、允许状态码、拒绝特征、允许跳转的 host
+// 路径必须能代表真实业务；codeload 用归档下载路径，避免根路径 301 到 github.com 主站骗过校验
+export const DOMAIN_SIG = {
+  "github.com": {
+    path: "/",
+    mustContain: ["github"],
+    allow: [200, 204, 301, 302, 303, 304, 307, 308, 400, 401, 403, 404],
+    reject: ["unknown domain", "Fastly error"],
+    redirectHosts: ["github.com"],
+  },
+  "codeload.github.com": {
+    path: "/torvalds/linux/tar.gz/refs/heads/master",
+    mustContain: [],
+    allow: [200, 204, 302, 303, 304, 307, 308],
+    reject: ["unknown domain", "Fastly error"],
+    redirectHosts: ["codeload.github.com", "objects.githubusercontent.com"],
+  },
+  "objects.githubusercontent.com": {
+    path: "/",
+    mustContain: [],
+    allow: [200, 204, 302, 303, 304, 307, 308, 400, 401, 403, 404],
+    reject: ["unknown domain", "Fastly error"],
+    redirectHosts: ["objects.githubusercontent.com"],
+  },
+  "raw.githubusercontent.com": {
+    path: "/torvalds/linux/README.md",
+    mustContain: ["Linux kernel"],
+    allow: [200, 204, 302, 303, 304, 307, 308],
+    reject: ["unknown domain", "Fastly error"],
+    redirectHosts: ["raw.githubusercontent.com", "objects.githubusercontent.com"],
+  },
+  "gist.githubusercontent.com": {
+    path: "/",
+    mustContain: [],
+    allow: [200, 204, 301, 302, 303, 304, 307, 308, 400, 401, 403, 404],
+    reject: ["unknown domain", "Fastly error"],
+    redirectHosts: ["gist.githubusercontent.com", "gist.github.com"],
+  },
+  "avatars.githubusercontent.com": {
+    path: "/u/1?v=4",
+    mustContain: [],
+    allow: [200, 204, 302, 303, 304, 307, 308],
+    reject: ["unknown domain", "Fastly error"],
+    redirectHosts: ["avatars.githubusercontent.com"],
+  },
+  "cdn.jsdelivr.net": {
+    path: "/gh/torvalds/linux@master/README",
+    mustContain: ["Linux kernel"],
+    allow: [200, 204, 301, 302, 303, 304, 307, 308],
+    reject: ["unknown domain", "Fastly error"],
+    redirectHosts: ["cdn.jsdelivr.net", "www.jsdelivr.com", "jsdelivr.net"],
+  },
+};
+
+// 3xx Location 跳到该域名不允许的 host（如 codeload 坏节点跳回 github.com 主站）则判死
+// redirectHosts 未配置或为空数组时表示"不检查跳转"，避免兜底域名被误杀
+function badRedirect(statusCode, location, sig) {
+  if (!location || statusCode < 300 || statusCode >= 400) { return false; }
+  const hosts = sig.redirectHosts;
+  if (!hosts || hosts.length === 0) { return false; }
+  let h;
+  try { h = new URL(location).host; } catch { return false; }
+  return !new Set(hosts).has(h);
+}
+
+// 一条 TLS 连接同时量出 TCP 与 TLS 两段耗时。
+// 🔴 两段必须用**各自的超时**：黑洞 IP 的 TCP 握手会一直挂到超时，若统一用 tlsMs(6s)，
+//    十几条死候选就是几十秒 —— 池子因此不敢放宽，进而出现「明明有活 IP 却报 stuck」。
+//    这里先按 tcpMs 计，握手成功（connect 事件）后再把超时切到 tlsMs：
+//    快速淘汰死 IP，同时不误杀「连得上但 TLS 慢」的活 IP。
+function tcpTlsProbe(ip, domain, tcpMs, tlsMs) {
+  return new Promise((resolve) => {
+    const t0 = Date.now();
+    let tcpCost = -1;
+    let stage = "tcp";
+    const sock = tls.connect({ host: ip, port: 443, servername: domain, rejectUnauthorized: true });
+    const done = (r) => { try { sock.destroy(); } catch { /* 已销毁 */ } resolve(r); };
+    sock.setTimeout(tcpMs, () => done({ ok: false, stage, err: "timeout" }));
+    sock.on("connect", () => { tcpCost = Date.now() - t0; stage = "tls"; sock.setTimeout(tlsMs); });
+    sock.on("secureConnect", () => done({ ok: true, tcpMs: tcpCost, tlsMs: Date.now() - t0 }));
+    sock.on("error", (e) => done({ ok: false, stage, err: String(e.code || e.message).slice(0, 60) }));
+  });
+}
+
+// 读取响应体前 n 字节，用于特征校验；读够后立即断开，不下载完整大页面
+function readPrefix(res, maxBytes) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let got = 0;
+    let settled = false;
+    const finish = () => {
+      if (settled) { return; }
+      settled = true;
+      resolve(Buffer.concat(chunks).toString("utf8", 0, maxBytes));
+    };
+    res.on("data", (c) => {
+      if (got < maxBytes) { chunks.push(c); }
+      got += c.length;
+      if (got >= maxBytes) { res.destroy(); finish(); }
+    });
+    res.on("end", finish);
+    res.on("close", finish);
+    res.on("error", finish);
+  });
+}
+
+// 纯函数：给定状态码、响应体、Location，按域名指纹判定是否"真活"
+export function checkHttpResponse(statusCode, body, location, sig) {
+  const lower = String(body).toLowerCase();
+  for (const bad of sig.reject) {
+    if (lower.includes(bad.toLowerCase())) { return { ok: false, err: `reject:${bad}` }; }
+  }
+  if (badRedirect(statusCode, location, sig)) { return { ok: false, err: `redirect:${location}` }; }
+  if (statusCode >= 500) { return { ok: false, err: `status:${statusCode}` }; }
+  for (const need of sig.mustContain || []) {
+    if (!lower.includes(need.toLowerCase())) { return { ok: false, err: `missing:${need}` }; }
+  }
+  if (sig.allow.includes(statusCode)) { return { ok: true, err: "" }; }
+  return { ok: false, err: `status:${statusCode}` };
+}
+
+// 第三关：HTTP GET（host=IP、SNI=域名、Host头=域名），读少量响应体做终审
+function httpProbe(ip, domain, httpMs) {
+  return new Promise((resolve) => {
+    const sig = DOMAIN_SIG[domain] || { path: "/", mustContain: [], allow: [200, 204, 301, 302, 303, 304, 307, 308, 400, 401, 403, 404], reject: ["unknown domain", "Fastly error"], redirectHosts: [] };
+    const t0 = Date.now();
+    const req = https.request({
+      host: ip, servername: domain, method: "GET", path: sig.path, timeout: httpMs,
+      headers: { Host: domain, "user-agent": "ghprobe/0.1.0", accept: "*/*" },
+    }, async (res) => {
+      const ttfb = Date.now() - t0;
+      const body = await readPrefix(res, 4096);
+      const checked = checkHttpResponse(res.statusCode, body, res.headers.location, sig);
+      resolve({ ok: checked.ok, ttfb, status: res.statusCode, err: checked.err });
+    });
+    req.on("timeout", () => { req.destroy(); resolve({ ok: false, err: "timeout" }); });
+    req.on("error", (e) => resolve({ ok: false, err: String(e.code || e.message).slice(0, 60) }));
+    req.end();
+  });
+}
+
+// 探测单个 (域名, IP)：三关全过才算活；分数越小越优
+export async function probeIp(domain, ip, cfg) {
+  const { tlsMs, httpMs } = cfg.timeouts;
+  const tcpMs = cfg.timeouts.tcpMs ?? tlsMs; // 老配置没这一项时退回 tlsMs，行为不变
+  const g = await tcpTlsProbe(ip, domain, tcpMs, tlsMs);
+  if (!g.ok) { return { domain, ip, ok: false, stage: g.stage, err: g.err }; }
+  const h = await httpProbe(ip, domain, httpMs);
+  const tlsCost = g.tlsMs - g.tcpMs;
+  const score = Math.round(g.tcpMs * 0.4 + tlsCost * 0.4 + (h.ok ? h.ttfb : httpMs) * 0.2);
+  return {
+    domain, ip, ok: h.ok,
+    tcpMs: g.tcpMs, tlsMs: g.tlsMs, ttfb: h.ok ? h.ttfb : -1, status: h.ok ? h.status : -1,
+    score, err: h.ok ? "" : `http:${h.err}`,
+  };
+}
+
+// 简单并发池：限制同时握手的 socket 数量
+export async function pool(jobs, concurrency) {
+  const out = new Array(jobs.length);
+  let next = 0;
+  const worker = async () => {
+    for (;;) {
+      const i = next++;
+      if (i >= jobs.length) { return; }
+      out[i] = await jobs[i]();
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, concurrency) }, worker));
+  return out;
+}

package/src/ranker.js

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 zmw
+// 排名选优：按域名分组，只留三关全过的，score 升序，每域名限量
+export function rank(results, cfg) {
+  const byDomain = new Map();
+  for (const r of results) {
+    if (!byDomain.has(r.domain)) { byDomain.set(r.domain, []); }
+    byDomain.get(r.domain).push(r);
+  }
+  const out = new Map();
+  for (const [domain, rs] of byDomain) {
+    const alive = rs.filter((r) => r.ok).sort((a, b) => a.score - b.score);
+    out.set(domain, alive.slice(0, cfg.probe.maxPerDomain));
+  }
+  return out;
+}
+
+// 兜底链：主域名候选全灭且配置了替身时，返回替身域名清单。
+// 🔴 必须要求该域名**本轮确实探过**（ranked 里存在这个键）。rank 对「探过但全灭」的域名
+//    会写入一个空数组，对「本轮压根没探」的域名则完全不建键。部分更新只探被点名的域名，
+//    若把「没探」误当「全灭」，就会白跑一轮兜底 DoH + 探测（实测每次多花 2~5s）。
+export function neededFallbacks(ranked, cfg) {
+  const list = [];
+  for (const [domain, alternatives] of Object.entries(cfg.fallbacks || {})) {
+    if (!ranked.has(domain)) { continue; }
+    const rs = ranked.get(domain) || [];
+    if (!rs.length && alternatives.length) { list.push(...alternatives); }
+  }
+  return [...new Set(list)];
+}

package/src/server.js

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2026 zmw
+// 内置 HTTP API：既是测试钩子也是状态面板数据源
+// GET  /api/status  最近一轮结果
+// POST /api/probe   立即触发一轮探测（跑完返回摘要）
+// GET  /api/hosts   当前生成的 hosts 块
+// GET  /api/config  当前生效配置
+import http from "node:http";
+import { runProbe } from "./probe.js";
+import { blockFromProbeResult } from "./health.js";
+
+const state = { results: null, block: "", at: null, probing: false };
+
+export function getState() { return state; }
+
+// run 可注入（默认真实 runProbe），供接口测试替身使用
+export async function probeNow(cfg, log, run = runProbe) {
+  if (state.probing) { throw new Error("已有探测在跑"); }
+  state.probing = true;
+  try {
+    const r = await run(cfg, log);
+    state.results = r;
+    state.at = r.at;
+    state.block = blockFromProbeResult(cfg, r);
+    return r;
+  } finally {
+    state.probing = false;
+  }
+}
+
+export function startServer(cfg, log, run = runProbe) {
+  const server = http.createServer((req, res) => {
+    const json = (code, obj) => { res.writeHead(code, { "content-type": "application/json; charset=utf-8" }); res.end(JSON.stringify(obj, null, 2)); };
+    if (req.url === "/api/status") {
+      if (!state.results) { return json(200, { ready: false, probing: state.probing }); }
+      const summary = [...state.results.ranked].map(([domain, rs]) => ({ domain, alive: rs.map((r) => ({ ip: r.ip, tcpMs: r.tcpMs, tlsMs: r.tlsMs, ttfb: r.ttfb, score: r.score })) }));
+      return json(200, { ready: true, at: state.at, probing: state.probing, domains: summary });
+    }
+    if (req.url === "/api/probe" && req.method === "POST") {
+      return probeNow(cfg, log, run).then((r) => {
+        const summary = [...r.ranked].map(([domain, rs]) => ({ domain, alive: rs.map((x) => ({ ip: x.ip, score: x.score })) }));
+        json(200, { at: r.at, domains: summary });
+      }).catch((e) => json(500, { error: String(e.message) }));
+    }
+    if (req.url === "/api/hosts") {
+      res.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
+      return res.end(state.block || "# 尚无结果，先 POST /api/probe\n");
+    }
+    if (req.url === "/api/config") { return json(200, cfg); }
+    res.writeHead(404, { "content-type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify({ error: "not found" }));
+  });
+  return new Promise((resolve) => {
+    server.listen(cfg.serve.port, cfg.serve.host, () => resolve(server));
+  });
+}