同一个 IP 一生只查一次：三级读取、双桶限流，和一道只拦花钱请求的人机验证

curl -s "https://ipure.art/api/lookup?ip=8.8.8.8"

{
  "ip": "8.8.8.8",
  "queriedAt": "2026-08-20T02:17:06.141Z",
  "risk": { "purity": 78, "level": "neutral", "confidence": "medium" },
  "source": "cache",
  "stale": true
}

curl -s "https://ipure.art/api/lookup?ip=185.220.101.1"

{ "error": "需要完成人机验证后才能发起新的检测", "code": "verification_required" }

进程内缓存（6h）  →  SQLite 历史库（永久）  →  实时查询所有数据源

cacheTtlMs: Number(process.env.IPURE_CACHE_TTL_MS ?? 6 * 60 * 60 * 1000),
dbPath: process.env.IPURE_DB_PATH ?? "./data/ipure.db",

export type RateBucket = "query" | "fresh" | "refresh";
 
const BUCKET_MAX: Record<RateBucket, () => number> = {
  query:   () => config.rateLimit.max,        // 30 次/分钟
  fresh:   () => config.rateLimit.freshMax,   // 10 次/分钟
  refresh: () => config.rateLimit.refreshMax, //  5 次/分钟
};

// 两个桶各自独立计数，否则严格的 refresh 上限会被普通查询挤占掉。
const bucketKey = `${bucket}:${key}`;

/**
 * 计数器走 singleton 注册表，否则页面和 API 各记一份，实际放行量会翻倍。
 */

/**
 * 商业数据源的每日配额守门。
 *
 * 目的很直接：**永远不产生计划外的费用**。免费额度用完后继续调用，
 * 轻则被拒，重则进入按量计费。所以到达上限就停用该源，
 * 报告里如实标注"当日配额已用尽"，其它数据源照常工作。
 *
 * 计数按 UTC 日期分桶并持久化 —— 内存计数一次重启就清零，
 * 而供应商那边的额度不会跟着重置。
 */

/** 留出的安全边际：用到 95% 就停手，避免边界竞态把额度打穿。 */
const SAFETY_RATIO = 0.95;

} catch {
  // 计数读不出来时放行：宁可多调一次，也不要因为存储故障让整个源失效。
  return { used: 0, limit: dailyLimit, remaining: effective, exhausted: false };
}

/**
 * 这次查询会不会真实消耗数据源配额？
 *
 * 人机验证据此决定拦不拦：只有会花钱的请求才值得让用户过一道验证，
 * 读库返回的报告不该有任何摩擦 —— 那既伤体验，也会让爬虫撞上验证页，
 * 而报告页正是站点的主要流量入口。
 */
export async function willCostQuota(input, opts = {}): Promise<boolean> {
  const ip = parseIp(input);
  // 非法输入根本走不到查询；保留地址会短路，不碰任何外部源。
  if (!ip || ip.isBogon) return false;
 
  if (opts.refresh) return true;
  if (cacheGet<LookupResult>(`lookup:${ip.normalized}`)) return false;
 
  try {
    return (await getStore().get(ip.normalized)) === null;
  } catch {
    // 存储不可用时按"会花钱"处理，宁可多验一次也不放过真实查询。
    return true;
  }
}

export async function needsHumanCheck(ip: string): Promise<boolean> {
  if (!turnstileEnabled()) return false;
  const jar = await cookies();
  if (isVerifyTokenValid(jar.get(VERIFY_COOKIE_NAME)?.value)) return false;
  return willCostQuota(ip);
}

} catch (e) {
  // 只读文件系统、权限不足等情况下降级：少了历史沉淀，
  // 但查询功能完整，不能因为存储不可用就让整个站不能用。
  //
  // 但必须喊出来。这个状态下站点看起来一切正常，只是重启后历史清零、
  // sitemap 退化成只剩首页 —— 一条 warn 混在日志里没人会注意。
  // /api/health 在这个状态下返回 503，容器会显示 unhealthy。
  console.error(
    `[store] sqlite unavailable (...), falling back to memory — ` +
      `history will NOT persist across restarts`,
  );
  return createMemoryStore();
}