后台改了菜单价格，几十家门店小程序还显示旧的：门店配置下发的版本号、缓存失效与灰度一致性实践

导读

连锁门店的后台经常要改配置：调价、下架沽清商品、调整营业时间、切换门店活动。运营在总部后台点了保存，以为全渠道立刻生效，实际却经常是另一番景象——有的门店小程序半小时后还挂着旧价格，有的明明下架了商品却还能下单。这类问题不报错、不告警，最后都是顾客到店核销时才爆发。这篇文章聊聊多门店配置下发为什么会"有的更新、有的没更新"，以及用版本号、缓存失效、灰度和对账把一致性做扎实的一套办法。

一、先看清一份配置要穿过多少层缓存

"改了不生效"几乎都是缓存问题，但缓存不止一层。一份门店配置从总部到顾客眼前，通常要经过：

• 总部数据库（权威数据源）
• 服务端的分布式缓存（Redis 一类）
• 网关或 CDN 对配置接口的缓存
• 门店收银/自助端的本地缓存
• 顾客小程序的本地存储和小程序容器缓存

任何一层还拿着旧值，最终展示就是旧的。很多团队只给缓存设了一个 TTL，觉得"过期总会更新"，问题在于 TTL 是被动的：最坏情况下，要等整整一个过期周期全网才收敛，而下架、改价这类操作往往要求分钟级甚至秒级生效，这个窗口期里旧价订单、下架商品下单都会真实发生。

二、给配置加版本号，让端侧能判断新旧

主动失效的前提是能比较"新旧"。建议每份配置带一个单调递增的整数版本号，再加一个内容指纹：

{
  "storeId": "S0108",
  "version": 2041,
  "checksum": "9f3c1a7e",
  "updatedAt": "2026-09-16T08:50:00+08:00",
  "menu": [
    { "skuId": "M1023", "name": "招牌套餐", "price": 3200, "status": "ON" },
    { "skuId": "M1056", "name": "季节限定", "price": 0, "status": "OFF" }
  ]
}

端侧拉取时走"版本协商"：先只问版本号，发现落后才拉全量，没落后就用本地缓存，既省流量又能明确判断该不该更新。

def get_config(store_id, client_version):
    latest = int(redis.get(f'cfg:ver:{store_id}') or 0)
    if client_version and int(client_version) >= latest:
        return {'changed': False, 'version': latest}   # 本地已是最新
    payload = redis.get(f'cfg:data:{store_id}')
    return {'changed': True, 'version': latest, 'data': json.loads(payload)}

版本号一定要在服务端用整数自增生成，别用各门店机器自己的时间戳——机器时钟不一致时，"新版本时间戳反而更小"的情况会让端侧把新配置当旧的丢掉。

光有版本号还不够，建议再带一个内容指纹。版本号回答的是"新还是旧"，指纹回答的是"内容对不对"。灰度回滚、或者某次发布中途被打断时，可能出现版本号涨了、内容却只更新了一半的情况；端侧拉到配置后自己算一遍指纹，和服务端给的值比对，对不上就丢弃重拉，能挡住这种半拉子数据。指纹就是对配置正文做一次哈希，算之前先把字段顺序固定下来做归一化，否则同样的内容因为字段排列不同，每次都会算出不同的值，反而误判。

三、变更走事件和灰度，别指望一次广播全员到位

配置保存后，靠"同步调用所有门店接口去推"既慢又脆，门店网络一抖就漏。更稳的做法是变更发事件、各端按自己的节奏追平：

• 保存配置时版本号自增、刷新服务端缓存，并往消息队列发一条变更事件。
• 在线的门店端通过长连接收到通知后主动拉取；不在线的端等重连或轮询时按版本号补齐缺口。
• 重要变更支持灰度：先放给几家试点门店，观察没有错误配置（比如价格被误改成 0）再全量。

def on_config_change(msg):
    store_id, version = msg['storeId'], msg['version']
    if msg.get('gray') and store_id not in msg['grayStores']:
        return                       # 非灰度门店，等全量指令
    local_ver = store_local_version(store_id)
    if version > local_ver:
        pull_and_apply(store_id, local_ver, version)   # 按版本缺口拉取
    ack(store_id, version)           # 回报已追到的版本，便于总部盘点谁还落后

对配置接口的缓存，也要让它能被主动作废，而不是只等过期。网关层对配置这类"版本协商"接口可以直接不缓存，或在变更时主动 purge：

location /api/config {
    proxy_cache_valid 200 10s;          # 只给很短的兜底缓存
    proxy_cache_key "cfg$arg_storeId";
    add_header X-Cfg-Version $upstream_http_x_cfg_version;
}

四、关键配置在交易前强校验，展示和成交分开口径

就算展示层偶尔落后，也不能让旧价、下架商品穿透到交易环节。要把"展示用配置"和"成交用配置"分开：

• 菜单图、描述这类展示数据可以容忍短时缓存，落后一点不影响成交。
• 价格、商品上下架状态、可售库存这类交易关键字段，下单前必须回源服务端再校验一次，以服务端此刻的值为准，端上缓存只用于展示。
• 服务端再做一道对账：定时扫描各门店端回报的版本号，落后超过阈值的门店主动告警，而不是等客诉。

def place_order(store_id, sku_id, client_price):
    # 成交口径：价格与状态永远以服务端实时值为准，不信端上
    sku = load_sku_authoritative(store_id, sku_id)
    if sku['status'] != 'ON':
        return {'ok': False, 'reason': '该商品已下架'}
    if client_price and int(client_price) != sku['price']:
        return {'ok': False, 'reason': '价格已变动，请刷新后重试'}
    return create_order(store_id, sku, sku['price'])

踩坑清单

• 坑1：只设 TTL 等被动过期。 最坏要等一个完整过期周期全网才收敛，下架商品在窗口期里照样能下单。交易敏感配置必须主动失效。
• 坑2：用各机器时间戳当版本号。 门店设备时钟一漂移，新版本被判成旧值直接丢弃。统一用服务端整数自增版本，必要时配内容指纹。
• 坑3：推送失败没有补偿。 当时离线的门店端漏了通知，没人知道它落后，直到重启或客诉才暴露。要有启动对账和版本缺口拉取，总部能看到每家门店追到了第几版。
• 坑4：版本号比较写错。 把版本当字符串比较会出现"10 < 9"，灰度中途又插一个新版本时顺序全乱、甚至回滚。版本用整数比较，灰度状态单独建模。
• 坑5：把小程序本地缓存当成成交依据。 端上缓存被当权威，旧价和下架商品一路放行到下单。展示可以读缓存，成交必须回源，价格和上下架以服务端实时值为准。

结语

多门店配置下发的一致性，核心不是"怎么把消息推得更快"，而是承认端侧网络不可靠、缓存必然存在，然后用版本号让每一端都能判断自己新不新，用事件和灰度让变更稳妥铺开，用对账让落后的门店主动浮出水面，最后在交易这道关口对价格和上下架做强校验。展示层允许短暂不一致，成交口径必须强一致，把这两件事分开，改价下架带来的客诉基本就能消掉。