Skip to content

新功能先给三个城市上线:用 IP 归属地做按城市灰度发布(Node.js 完整实现) ​

去年改版结算页,我们按老规矩上了 5% 随机用户灰度。跑到第三天,数据看着挺正常:整体转化率掉 0.3 个点,在噪声范围内。第四天客服群炸了——成都的用户下不了单,提示"配送地址不在服务范围"。

原因很简单:新结算页换了门店匹配逻辑,取的是城市 + 区县,而成都那批门店的区县编码是两套历史数据,一套是"武侯区",一套是"510107"。随机 5% 用户摊到全国,成都只分到几十个人,样本小到根本看不出问题;问题在城市维度上是 100% 复现的。

那次之后我们把灰度维度改了:先放城市,再放比例。这篇讲怎么用 IP 归属地判断来的访客在哪个城市,然后把功能只开给指定城市的指定比例用户。

一、为什么按城市灰度,而不是随机百分比 ​

随机百分比的好处是样本无偏,坏处是它假设用户彼此独立。但很多功能的问题恰恰出在"同一个城市的用户共享同一份配置"上:

  • 门店、库存、配送范围、区域价格,都是按城市/区县配的,错一个编码,整个城市都错;
  • 本地生活、票务、院线这类业务,同城用户的请求会打到同一批边缘节点,配置下发不同步也是整片整片地出问题;
  • 出了问题,客服、运营、BD 是分城市对接的,你说"5% 用户受影响",他们没法判断要不要通知商户;你说"成都全量受影响",他们立刻能动。

按城市灰度还有个附带好处:出问题的信号更早、更干净。同一个城市几十万请求,指标波动已经不是噪声了。

当然按城市也有代价:城市内的用户多样性不足,如果新功能对"新老用户"敏感,光看一个城市会得出错误结论。所以实战里两个维度一般叠着用——城市选范围,比例控风险。

二、方案:三层规则,一次查 IP 只做一件事 ​

规则设计成这样:

killed?            → 全量回稳定版(一行配置关掉,不重启)
uid 分桶 >= 比例?  → 稳定版(这一步不查 IP)
城市不在名单?      → 稳定版
否则               → 新版本

第二行是关键。分桶在前、查城市在后,意味着只有 10% 的请求会真的去打一次归属地接口。按 10% 放量算,接口调用量直接少一个数量级,免费版 60 次/分钟的频率限制也就没那么紧张了。

分桶用什么?必须用 uid 或设备 ID,绝对不能用 IP。IP 一变(切 4G、换 WiFi、出差),用户就会从 A 组跳到 B 组,一会儿新页一会儿旧页,埋点数据全废。用 uid 做 hash,同一个用户永远落在同一个桶里,放量从 10% 提到 30% 时,原来那 10% 的用户还在里面,不会重排。

城市判断这一层要做三件事:缓存、超时、降级。缺一个都会在生产上出事。

三、Node.js 实现 ​

零依赖,Node 18+ 直接跑(要 fetch)。整份代码一个文件,node gray.js 就能起服务。

javascript
// gray.js —— 按城市灰度放量:IP 只用来判城市,分桶永远用 uid
const http = require('http');
const crypto = require('crypto');

const RULE = {
  feature: 'checkout_v2',
  version: 'v2.3.1',
  cities: ['杭州', '成都', '武汉'],        // 第一批放量城市
  percent: Number(process.env.PCT || 10), // 城市内放量比例,0~100
  killed: false,                          // 总开关:出问题一条命令关掉
};

const CACHE_TTL = 6 * 3600 * 1000;
const cache = new Map();                   // ip -> {city, at}

async function cityOf(ip) {
  const hit = cache.get(ip);
  if (hit && Date.now() - hit.at < CACHE_TTL) return hit.city;
  const ac = new AbortController();
  const timer = setTimeout(() => ac.abort(), 400);   // 灰度判定的预算:400ms
  try {
    const url = 'https://ip9.com.cn/get?ip=' + encodeURIComponent(ip);
    const resp = await fetch(url, {
      signal: ac.signal,
      headers: { 'User-Agent': 'gray/1.0' },
    });
    const body = await resp.json();
    const d = body && body.ret === 200 ? (body.data || {}) : {};
    const city = (d.city || '').trim() || null;      // 境外 IP / 保留地址这里是空
    cache.set(ip, { city, at: Date.now() });
    return city;
  } catch (e) {
    // 失败只缓存 1 分钟,别让一次抖动把某个 IP 钉死在"无城市"上
    cache.set(ip, { city: null, at: Date.now() - CACHE_TTL + 60 * 1000 });
    return null;
  } finally {
    clearTimeout(timer);
  }
}

function bucket(uid) {
  const h = crypto.createHash('sha1').update(String(uid)).digest();
  return h.readUInt32BE(0) % 100;    // 0~99,同一个 uid 永远同一个桶
}

async function decide(req) {
  if (RULE.killed) return { on: false, why: 'killed' };
  const uid = req.headers['x-uid'] || '';
  if (!uid) return { on: false, why: 'no_uid' };

  const b = bucket(uid);
  if (b >= RULE.percent) return { on: false, why: 'out_of_bucket', bucket: b };

  const ip = (req.headers['x-forwarded-for'] || '').split(',')[0].trim()
          || req.socket.remoteAddress || '';
  const city = await cityOf(ip);
  if (!city) return { on: false, why: 'no_city', bucket: b };
  if (!RULE.cities.includes(city)) return { on: false, why: 'city_out', city, bucket: b };
  return { on: true, why: 'in_city', city, bucket: b };
}

if (require.main === module) {
  const server = http.createServer(async (req, res) => {
    if (req.url.startsWith('/debug')) {          // 手工核验城市用
      const u = new URL(req.url, 'http://x');
      const city = await cityOf(u.searchParams.get('ip') || '');
      return res.end(JSON.stringify({ city }));
    }
    if (req.url.startsWith('/api/checkout')) {
      const d = await decide(req);
      res.setHeader('X-Release', d.on ? RULE.feature + ':' + RULE.version : 'stable');
      res.end(JSON.stringify({ variant: d.on ? 'v2' : 'v1', ...d }));
      console.log([new Date().toISOString(), RULE.feature, d.why, d.city || '-',
        'uid=' + (req.headers['x-uid'] || '-'), 'bucket=' + d.bucket].join(' | '));
      return;
    }
    res.end('ok');
  });
  server.listen(8099, () => console.log('listen 8099'));
}

module.exports = { decide, bucket, cityOf, RULE };

起来之后拿几个真实 IP 试一下(PCT=100 是为了跳过桶过滤,直接看城市判断):

bash
PCT=100 node gray.js
curl -s -H 'X-UID: u-a' -H 'X-Forwarded-For: 223.5.5.5'      localhost:8099/api/checkout
curl -s -H 'X-UID: u-b' -H 'X-Forwarded-For: 61.139.2.69'    localhost:8099/api/checkout
curl -s -H 'X-UID: u-c' -H 'X-Forwarded-For: 114.114.114.114' localhost:8099/api/checkout
curl -s -H 'X-UID: u-d' -H 'X-Forwarded-For: 8.8.8.8'        localhost:8099/api/checkout
curl -s -H 'X-UID: u-e' -H 'X-Forwarded-For: 1.2.4.8'        localhost:8099/api/checkout

实际输出:

223.5.5.5       -> {"variant":"v2","on":true,"why":"in_city","city":"杭州","bucket":10}
61.139.2.69     -> {"variant":"v2","on":true,"why":"in_city","city":"成都","bucket":35}
114.114.114.114 -> {"variant":"v1","on":false,"why":"city_out","city":"南京","bucket":57}
8.8.8.8         -> {"variant":"v1","on":false,"why":"no_city","bucket":24}
1.2.4.8         -> {"variant":"v1","on":false,"why":"no_city","bucket":28}

8.8.8.8 和 1.2.4.8 都进了 no_city,原因不一样:前者是境外 IP,country 有值但 prov、city 都是空串;后者是国内骨干网段,接口返回 ret=200 但省市为空。这两种都得落回稳定版——判断不出城市,就不要把人拉进灰度,这是原则,不是优化。

四、上线前必须想清楚的六件事 ​

1. 城市漂移会让极少数用户来回跳。 运营商出口调整、用户切网络,都可能让同一个人的 IP 城市变。因为分桶用 uid,这类用户最多是"桶在、城市变",表现是偶尔被判 city_out。可接受,但阈值别卡太死——比如别做成"只允许杭州",用 ['杭州','成都','武汉'] 这种列表,边缘城市(绍兴、德阳)的用户本来就算不进来,不影响。

2. 页面别让 CDN 缓存。 这是最容易忽略的一条:灰度结果由后端算,如果页面被边缘缓存,A 用户渲染出的新页会被发给 B 用户。带灰度的页面要么整体不缓存,要么把灰度判断放到边缘函数里做,缓存 key 带上 variant。

3. 灰度期间冻结定价和结算规则。 灰度是验证功能,不是验证价格。同时改两个变量,出了问题你分不清是代码还是配置。

4. 埋点必须带上 variant 和 city。 否则第二天想看"成都是不是比杭州差",只能靠猜。推荐直接透传 X-Release 头到前端,前端在事件里带上。

5. 观察窗别太短。 城市级放量 10% 的话,24 小时基本能覆盖一个完整的日活周期;要看到转化这类滞后指标,给 48 小时。低于 12 小时的结论基本不可信。

6. 回滚要一行搞定。 killed: true 这种开关得能热更新(配置中心推送或定时拉取),而不是改代码重新发布。我们现在的做法是开关放在 Redis,decide() 开头读一个本地缓存的布尔值,1 秒刷新一次。

还有个常被问的问题:查 IP 会不会拖慢接口?上面代码给了 400ms 预算,超时就直接放弃、落稳定版。实际压测下来,缓存命中率 90% 以上时 P99 增加不到 5ms;冷启动那一下会吃满 400ms,所以首次放量前用真实 IP 预热一遍缓存比较稳。

总结 ​

按城市灰度解决的不是"怎么少影响用户",而是"出了问题怎么在两小时内定位"。城市是一个业务和用户都能听懂的单位,运营能据此通知商户,客服能据此回话,技术能据此复现。

要落地,最小改动是三步:给请求加上城市判断(IP 归属地接口一行地址就能查,返回 prov、city、isp,中国城市覆盖足够做灰度名单)、把桶换成 uid hash、把原来的百分比开关改成"城市 × 比例"。剩下的是运维纪律——开关、埋点、冻结窗口。

接口用法就是 GET https://ip9.com.cn/get?ip=<ip>,免费版不注册、支持 IPv4/IPv6,注意 60 次/分钟的频率限制,所以缓存和"先分桶后查 IP"这两个设计别省。要区县粒度或想区分家庭宽带和机房出口(area、ip_type 是 VIP 能力),去 IP9 官网 看说明。高并发网关场景如果嫌 Node 的单线程不够,这套判断逻辑挪到 Go 或 Java 里也是同样的结构。