release-runbook.md 3.7 KB

双地图发布、体检和回滚

更新:2026-10-26。本轮仅本地代码/测试,不执行SQL、部署、真实商家同步或流量切换。

后端配置

  • Google:继续配置既有 sys_googlemap_key,保证当前使用的Routes、矩阵和地址接口可用;新配置不写死密钥、不在日志输出。
  • 自部署:MAP_SELF_HOSTED_BASE_URL 经地图Nginx应含/api,直连Flask用实际服务根地址;读令牌MAP_SELF_HOSTED_READ_TOKEN对应地图MAP_READ_TOKEN,管理令牌MAP_SELF_HOSTED_ADMIN_TOKEN对应地图MAP_ADMIN_TOKEN。全部保留在服务端。
  • 外卖:默认自部署MAP_FOOD_DELIVERY_PROFILE=car,保留现有Google DRIVE距离口径;改motorcycle需另验实际价格及Google回滚后的差异。闪送按用户车型1/2选择,不受此默认项影响。
  • 默认连接2.5秒、读取18秒。地图矩阵整批约16秒预算,Nginx读取20秒;还须检查App网关总超时、实际门店数和并发,不以这些配置代替性能验收。
  • 本次后端只新增响应字段,不新增业务表/列,无新增后端DDL。地图仓库存量SQL按其updatesql/sql.md由开发者手工执行。

发布顺序与验收

  1. 地图保持一个API、两个车型OSRM引擎;核对数据集隔离、模型/路网文件,按地图发布检查清单发布,分别验证两车型真实算路。不能只检查健康接口200。
  2. 后端先保留GOOGLE发布。验证普通/v2/多店、自配送运费及闪送两点/多站点报价与建单;自取/堂食不新增地图依赖。支付方式、优惠/满额免运、骑手容量/接单范围、预约与履约状态继续原规则。
  3. 显式同步门店并按地图CLI重建搜索索引;详情见手动同步接口。更名、搬迁、停用分别核对稳定ID,不能把营业休息等同永久删除。
  4. 导出仅含稳定ID/WGS84坐标的存量门店/收货点样本,使用地图audit_routes.py分别体检两车型。网络/鉴权/5xx属于服务故障,不能计入坏地址。失败清单由业务确认修正和放量条件。
  5. 隔离/测试环境将sys_map_distance_source设置为唯一启用默认SELF_HOSTED,验证完整矩阵顺序、重复点、最大站点数、无路/吸附/越界/超时/令牌错误。外卖失败拒绝报价;闪送服务故障降级直线并估时,越界拒绝。不自动跨来源重试。
  6. 前端按接入文档改新选址及地图画面。旧App直连Google及旧地址接口兼容保留,只有算路来源切换不代表所有Google请求消失。
  7. 真实并发、P95/P99、车型法规、门牌/入口精度和App真机联调单独验收。前述本地单测不能代替真实OSRM/PostGIS或上线批准。

回滚

在平台字典管理将SELF_HOSTED默认改为N、GOOGLE改为唯一Y,保存后刷新缓存(后台保存通常已更新)。配置缺失、无默认、多默认或未知值均选GOOGLE。正式放量前保留Google有效配置并演练一次切回。

新报价、新下单和新选址请求恢复Google;已创建订单保留原距离、运费、促销和付款快照。报价与建单之间切换造成金额/批次指纹变化,按现有错误要求重新报价,不能静默改客户应付。店铺源表或地图DDL回滚按相应备份单独处理,改字典不恢复这些数据。

运维观察

日志关注提供方、接口、车型、耗时和结构化错误;不要采集完整地址、坐标、令牌、Key或原始上游响应。分别统计路线失败、闪送直线降级、外卖报价失败、新地址失败及金额变化。地图服务中断不影响数据库直线围栏、附近排序或已有订单状态操作。