Skip to content

AI 应用总被问「为什么我这边用不了」?用 IP 归属地做地区可用性控制(Node.js 实现) ​

做 AI 产品的团队,早晚都要处理一类需求:这个功能在哪些国家/地区开放。

原因五花八门:模型授权只覆盖部分区域、生成式 AI 服务要按属地做合规登记、目标市场要分批灰度、某些地区的支付渠道还没打通。运营给的方案通常是「加个地区判断」,但真做起来,第一句问的都是同一个问题——判断用户在哪,拿什么判断?

账号注册地?用户可以随便选。手机号国家码?很多产品根本不要手机号。设备语言和时区?语言写着 zh-CN、时区却在 Los Angeles 的用户比比皆是。剩下最稳定的信号,还是每次请求都会带上的那个东西:请求来源 IP。

这篇用 Node.js 写一个可以直接挂到网关上的地区守卫中间件,零依赖(Node 18+ 自带 fetch)。

一、先说清楚:地区控制有两种失败,代价不一样 ​

任何基于 IP 的地区控制,都会遇到两类错误:

  • 误拦(false block):真实用户被挡在门外,工单直接进客服,转化损失立刻发生。绝大多数是代理、企业出口、运营商漫游导致的归属地偏移。
  • 误放(false allow):本该受限的流量进来了,代价取决于合规压力——如果是备案或模型授权要求,这可能不是"少赚点"而是"要整改"。

这两类的处理方式完全不同,所以方案里必须有一个显式开关:不可用的时候是放行还是拦截(fail-open / fail-closed)。这件事最好不要让写代码的人临时拍脑袋,而是让产品合规的同学在策略文件里写清楚。

二、方案:策略外置 + 缓存 + 显式降级 ​

整体结构是这样:

请求 → 取真实 IP → 查归属地(缓存优先) → 读地区策略 → 放行 / 返回 451
                                          ↑
                                   region-policy.json(可热更新,不重启)

几个设计取舍:

策略必须外置。 开放哪些地区、屏蔽哪些地区,这些会随着商务和合规的节奏一直变。写死在代码里,每周都要发一次版。放进一个 JSON 文件,进程每 30 秒看一下 mtime,运营改完就生效。

缓存是硬需求,不是优化。 IP 归属地是日级数据,同一个用户一天里的多次请求没必要重复查。内存里放一个 Map,TTL 24 小时,加上上限淘汰,免费版 60 次/分钟的限制在中等流量下基本碰不到。

用 country_code 做判断,别用国家中文名。 接口会同时返回 country("中国")和 country_code(cn),后者是稳定的短码,写进策略文件不会有编码和大小写问题。

出口机房要单独说。 有一部分"看起来在目标市场、实际是代理或云服务器"的流量。免费版能拿到 isp,但判断一个 IP 是家庭宽带、企业专线还是 IDC 机房,要用 VIP 版的 ip_type(ISP / BUS / IDC)。对 AI 产品来说,IDC 段流量往往意味着"通过服务器中转调用",是地区策略最容易被绕开的地方,值得单独记为可疑而不是直接放行。

三、Node.js 实现:一个零依赖的地区守卫 ​

策略文件长这样(region-policy.json,跟脚本放同一目录):

json
{
  "allow": ["cn", "sg", "my", "th"],
  "block": ["us", "ru"],
  "blockDatacenter": false,
  "failMode": "open"
}

failMode 就是前面说的开关:open = 查不到归属地就放行(保可用性),closed = 查不到就拦(保合规)。

下面是完整代码,保存为 region-guard.mjs,node region-guard.mjs 就能跑:

js
// region-guard.mjs —— AI 应用按 IP 归属地做地区可用性控制
// 运行: node region-guard.mjs        (Node 18+,零依赖)
// 自测: curl -H 'X-Real-IP: 8.8.8.8' http://127.0.0.1:8099/api/chat
import http from 'node:http';
import fs from 'node:fs';
import { fileURLToPath } from 'node:url';

const IP9_ENDPOINT = 'https://ip9.com.cn/get';
const POLICY_FILE = fileURLToPath(new URL('./region-policy.json', import.meta.url));
const CACHE_TTL = 24 * 3600 * 1000;
const CACHE_MAX = 50000;

// 是否信任 X-Forwarded-For:只有前面确实挂了自己的反向代理时才打开
const TRUST_XFF = process.env.TRUST_XFF === '1';
const PRIVATE_RE = /^(10\.|127\.|169\.254\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|::1$|f[cd][0-9a-f]{2}:)/i;

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

// ---------- 1. 地区策略:热加载 ----------
let policy = { allow: ['cn'], block: [], blockDatacenter: false, failMode: 'open' };
let policyMtime = 0;

function loadPolicy() {
  try {
    const st = fs.statSync(POLICY_FILE);
    if (st.mtimeMs === policyMtime) return;
    const raw = JSON.parse(fs.readFileSync(POLICY_FILE, 'utf8'));
    policy = { ...policy, ...raw };
    policyMtime = st.mtimeMs;
    console.log(`[policy] allow=${policy.allow.join(',')} block=${policy.block.join(',')} failMode=${policy.failMode}`);
  } catch (err) {
    console.warn('[policy] 读取失败,沿用上一版策略:', err.message);
  }
}
loadPolicy();
setInterval(loadPolicy, 30000).unref();

// ---------- 2. 归属地查询 + 内存缓存 ----------
const geoCache = new Map();   // ip -> { row, at }

function cacheGet(ip) {
  const hit = geoCache.get(ip);
  if (!hit) return undefined;
  if (Date.now() - hit.at > CACHE_TTL) { geoCache.delete(ip); return undefined; }
  return hit.row;
}

function cacheSet(ip, row) {
  if (geoCache.size >= CACHE_MAX) {
    let dropped = 0;
    for (const key of geoCache.keys()) {          // 简单淘汰:先扔最早写入的一批
      geoCache.delete(key);
      if (++dropped >= 5000) break;
    }
  }
  geoCache.set(ip, { row, at: Date.now() });
}

/** 返回 { country, prov, city, isp, type } 或 null;type 只有 VIP 版才给值 */
async function lookupGeo(ip, retry = 1) {
  const cached = cacheGet(ip);
  if (cached !== undefined) return cached;

  try {
    const url = `${IP9_ENDPOINT}?ip=${encodeURIComponent(ip)}`;
    const res = await fetch(url, { signal: AbortSignal.timeout(3000), headers: { accept: 'application/json' } });
    const payload = await res.json();

    if (payload.ret === 429) {                    // 触发限速,退避后重试一次
      if (retry > 0) { await sleep(1000); return lookupGeo(ip, retry - 1); }
      console.warn('[geo] 429 限速,放弃本次查询');
      return null;
    }
    if (payload.ret !== 200 || !payload.data?.ip) return null;   // 非法 IP 返回 400

    const d = payload.data;
    const row = {
      country: d.country_code || '',              // 用短码做策略匹配
      prov: d.prov || '',
      city: d.city || '',
      isp: d.isp || '',
      type: d.ip_type || '',                      // ISP / BUS / IDC —— VIP 版字段
    };
    cacheSet(ip, row);
    return row;
  } catch (err) {
    if (retry > 0) { await sleep(200); return lookupGeo(ip, retry - 1); }
    console.warn('[geo] 查询失败:', err.name);
    return null;
  }
}

// ---------- 3. 取客户端真实 IP ----------
function clientIp(req) {
  for (const header of ['cf-connecting-ip', 'x-real-ip']) {   // 只能由自己的边缘节点写入
    const value = req.headers[header];
    if (value && !PRIVATE_RE.test(String(value).trim())) return String(value).trim();
  }
  if (TRUST_XFF) {
    for (const part of String(req.headers['x-forwarded-for'] || '').split(',')) {
      const ip = part.trim();
      if (ip && !PRIVATE_RE.test(ip)) return ip;
    }
  }
  return req.socket.remoteAddress || '';
}

function maskIp(ip) {
  const parts = ip.split('.');
  return parts.length === 4 ? `${parts[0]}.${parts[1]}.x.x` : ip.split(':').slice(0, 3).join(':') + '::x';
}

// ---------- 4. 决策与响应 ----------
function decide(country, type) {
  if (policy.block.includes(country)) return { action: 'block', reason: `${country} 在屏蔽名单` };
  if (policy.blockDatacenter && type === 'IDC') return { action: 'block', reason: '机房 IP 流量' };
  if (policy.allow.includes(country)) return { action: 'pass', reason: `${country} 已开放` };
  return { action: 'block', reason: `${country} 暂未开放` };
}

function deny451(res, ip, reason, country) {
  res.writeHead(451, { 'content-type': 'text/html; charset=utf-8' });
  res.end(`<!doctype html><html lang="zh-CN"><head><meta charset="utf-8">
<title>当前地区暂未开放</title></head><body style="font-family:system-ui;padding:48px;max-width:640px;margin:auto">
<h2>当前地区暂未开放</h2>
<p>我们检测到您的访问来源地区(${country || '未知'})暂不在服务范围内,如您认为这是误判,可以提交申诉。</p>
<p style="color:#888;font-size:13px">参考编号:${maskIp(ip)} · ${new Date().toISOString()}</p>
</body></html>`);
}

function logLine(fields) {
  console.log(JSON.stringify({ t: new Date().toISOString(), ...fields }));
}

/** 地区守卫中间件:http.createServer 与 Express/Koa 都能直接用 */
async function regionGuard(req, res, next) {
  const ip = clientIp(req);
  const geo = await lookupGeo(ip);

  if (!geo) {                                   // 查不到归属地:走策略里声明的降级方向
    logLine({ ip: maskIp(ip), country: '', action: policy.failMode === 'closed' ? 'block' : 'pass', reason: '归属地不可用', path: req.url });
    if (policy.failMode === 'closed') return deny451(res, ip, '归属地不可用', '');
    return next();
  }

  const { action, reason } = decide(geo.country, geo.type);
  logLine({ ip: maskIp(ip), country: geo.country, prov: geo.prov, city: geo.city, type: geo.type || undefined, action, reason, path: req.url });
  if (action === 'pass') return next();
  return deny451(res, ip, reason, geo.country);
}

// ---------- 5. 演示:把它挂在 AI 接口前面 ----------
const server = http.createServer((req, res) => {
  regionGuard(req, res, () => {
    if (req.url.startsWith('/api/chat')) {
      res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
      res.end(JSON.stringify({ ok: true, msg: '模型接口正常返回' }));
      return;
    }
    res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' });
    res.end('AI 应用站点首页');
  });
});

server.listen(8099, () => console.log('listening on http://127.0.0.1:8099'));

自测走一遍(策略文件里 us 在屏蔽名单、cn 在开放名单):

text
$ node region-guard.mjs
[policy] allow=cn,sg,my,th block=us,ru failMode=open
listening on http://127.0.0.1:8099

$ curl -i -H "X-Real-IP: 116.21.44.33" http://127.0.0.1:8099/api/chat
HTTP/1.1 200 OK
{"ok":true,"msg":"模型接口正常返回"}
# 服务端日志
{"t":"2026-10-12T01:22:41.882Z","ip":"116.21.x.x","country":"cn","prov":"广东","city":"广州","action":"pass","reason":"cn 已开放","path":"/api/chat"}

$ curl -i -H "X-Real-IP: 8.8.8.8" http://127.0.0.1:8099/api/chat
HTTP/1.1 451 Unavailable For Legal Reasons
<h2>当前地区暂未开放</h2>
# 服务端日志
{"t":"2026-10-12T01:22:43.104Z","ip":"8.8.x.x","country":"us","prov":"","city":"","action":"block","reason":"us 在屏蔽名单","path":"/api/chat"}

451 Unavailable For Legal Reasons 这个状态码值得单独用——它不是 403,也不是 404,语义上就是"因法律/监管原因不可用"。监控里把 451 跟其他 4xx 分开看,能直观看出地区策略影响了多少流量。

四、几个容易踩的地方 ​

X-Forwarded-For 是可伪造的,别默认信。 地区控制最典型的绕过方式,就是自己构造 X-Forwarded-For: <目标国家的 IP>。上面代码里只有 TRUST_XFF=1 的时候才读这个头,平时只认 cf-connecting-ip、x-real-ip 这类由自家边缘节点写入的头。如果你的网关前面有 Nginx,务必让它把自己的 $remote_addr 追加到 XFF 尾部,而不是直接透传客户端的值。

代理用户一定要留申诉入口。 企业出口、校园网、运营商漫游都可能让归属地偏离真实位置。451 页面上给一个申诉链接(甚至一个"继续访问"的临时验证),比让用户去微博吐槽要省钱得多。

别把地区判断当成身份判断。 IP 归属地是城市级的网络位置,不是用户国籍、不是常住地、更不是身份凭证。拿它来判"能不能用某个功能"没问题,拿它来判"是不是同一个人"迟早出事。

策略生效前先跑观察模式。 上线新地区策略时,先把 failMode 和 block 逻辑做成"只记日志不拦截"跑一周,看看被拦的流量里有多少是正常用户。这一周的数据决定你要不要给某些 ISP 出口开白名单。

兜底和灰度比策略本身更重要。 AI 产品的地区开放基本是分批的:先给一两个市场开灰度、跑一段时间再放量。这类节奏用策略文件改 allow 就够了,不需要动代码;如果你想让灰度更细(比如只对某个城市开放内测),接口返回里还有 prov、city、big_area 可以用。

日志里的 IP 是个人信息。 上面 logLine 只写了脱敏后的网段,决策日志里保留的是 country / city 这种粗粒度结果,够复盘用,不用长期留完整 IP。

总结 ​

AI 应用的地区可用性控制,技术难度不在判断逻辑上——country_code 在不在白名单里,一行代码的事。真正的成本在边界上:可信来源、缓存与限速、查不到归属地时往哪边倒、以及给误判用户留一条申诉的路。

归属地查询这层,GET https://ip9.com.cn/get?ip=<IP> 就能拿到需要的字段:country_code、prov、city、isp、经纬度等,免费版不用注册、60 次/分钟/IP、IPv4 和 IPv6 都支持;要区分家庭宽带和机房出口(ip_type),或者需要 ip_asn 做出口聚类,那是 VIP 版的能力,具体口径看 https://www.ip9.com.cn。