@routerhub/agent-rules 1.5.158 → 1.5.159

package/AGENTS.base.md

@@ -460,6 +460,23 @@
 - ⚠️ **部署生产前必须通读一遍部署脚本再执行，禁止盲跑。** 部署脚本是多人接力的产物，其中任何一行环境值（PROJECT / 服务名 / Nacos namespace / 数据库 / 域名 / 后端 Host / VPC / 密钥名）都可能被中途改错、与线上真实环境脱节——脚本能跑、能编译、甚至能部署成功，但连的是错环境。执行前逐行核对脚本配置与线上实际（`gcloud config get-value project`、`gcloud run services list`、Nacos 配置），对不上 → 先改脚本或停下来问，禁止带着疑似错误的配置直接部署（呼应「环境配置禁止推断」）。
 - ⚠️ **部署脚本必须内置「环境自检」：在真正执行部署动作之前，先自动校验脚本配置与线上环境一致，不一致即中止（abort），禁止在环境未验证的情况下执行 deploy。** 校验项至少包括：① PROJECT 与 `gcloud config get-value project` 一致；② 目标 Cloud Run 服务真实存在；③ Nacos namespace / 库名与线上一致；④ 前端代理的后端 Host（BACKEND_RUN_HOST）指向本环境后端，而非 Dockerfile 默认值或他环境。**目标脚本若没有自检逻辑，执行者必须先补上再跑——禁止「无自检的脚本直接部署」。** 参照 agent-rules 自身 `release.sh` 的「规则漂移检查」（发版前强制校验规则已同步、未同步即中止），把「人记得校验」升级为「脚本强制校验」。
 
+### 🚨 上线安全四环铁律（部署生产 / 切流量必守）
+
+上线（部署生产、切流量、更新线上版本）的唯一不可接受后果是：**新版本有问题直接接流量，把原本正常服务顶崩**。上线必须走完以下四环，缺一不可；任何一环未过即中止，禁止带着未验证的环节继续。这里的核心是「你叫我怎样就怎样」行不通——**上线动作必须等校验全部通过才执行**。
+
+**环1 · 部署前环境对账**（详见「⚠️ 环境配置禁止推断」章节）
+- 脚本配置（PROJECT / 服务名 / Nacos namespace / 数据库 / 域名 / 后端 Host）与线上实际逐项对账（`gcloud config get-value project`、`gcloud run services list`、Nacos），对不上 → 先改脚本或停下问，禁止带疑似错误配置部署。
+
+**环2 · 部署前脚本通读 + 脚本自检**（详见上方「部署规则」两条铁律）
+- 通读一遍部署脚本再执行，禁止盲跑；脚本须内置「环境自检」（PROJECT 一致 / 目标服务存在 / Nacos 与库一致 / 后端 Host 非默认值），不一致即 abort；无自检先补上再跑。
+
+**环3 · 部署中先下不发（防「一上去就崩」的关键）**
+- 部署必须 `--no-traffic`（新 revision 保持 0% 流量），用 revision 临时 URL 验证新版本：日志无 ERROR、连对本环境库、关键接口 200、核心功能可跑通。**验证通过之前，禁止把流量切到新版本；禁止让 `gcloud run deploy` 默认把 100% 流量切到新 revision。**
+
+**环4 · 切流量渐进 + 全程可回滚**
+- 后端渐进切流量（5% → 观察 → 50% → 100%）；前端静态资源验证后一次性切。
+- 切流量前记录当前线上 revision 号；任何一步验证不过，`update-traffic --to-revision <旧版>` 秒切回，恢复线上原状后再排查。
+
 ## ⚠️ 配置中心变更生效铁律
 
 - ⚠️ **修改外部配置中心（如 Nacos）的配置后，若应用是启动时一次性拉取、没有热更新监听，必须显式重启/重新部署服务才能生效**。发布配置后如果验证发现"没生效"，先确认服务是否已经重启到最新版本，再去怀疑配置内容本身写错了——顺序反了会在"配置到底对不对"上来回排查，白白浪费时间。

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
 
+## [1.5.159] - 2026-08-29
+
+### Added
+
+- **「部署规则」新增「🚨 上线安全四环铁律」（部署生产 / 切流量必守）**：把此前分散的上线相关规则整合为一条完整的上线流程，并补上最关键的**环3「先下不发」**与**环4「渐进切流 + 可回滚」**——
+  1. **环1 部署前环境对账**（整合 v1.5.157）：脚本配置与线上实际逐项对账，对不上停下问。
+  2. **环2 部署前脚本通读 + 自检**（整合 v1.5.158）：禁止盲跑，脚本内置环境自检不一致即 abort。
+  3. **环3 部署中先下不发**（新增，防「一上去就崩」的关键）：部署必须 `--no-traffic`，用 revision 临时 URL 验证新版本健康（日志/连库/接口/核心功能），验证通过前禁止切流量，禁止让 `gcloud run deploy` 默认切 100% 流量。
+  4. **环4 切流量渐进 + 全程可回滚**（新增）：后端 5%→50%→100% 渐进切流，前端验证后一次切；切流前记录旧 revision 号，任何一步不过 `update-traffic --to-revision` 秒切回。原因：之前规则只覆盖「配置错/盲跑」，但「脚本配置全对、新版本本身有 bug 一上去就把原服务顶崩」这一最要命场景，必须靠「不接流量先验证 + 可秒回滚」才能兜住。
+
 ## [1.5.158] - 2026-08-29
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.158",
+  "version": "1.5.159",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {

package/rules/global.md

@@ -460,6 +460,23 @@ name: "通用规则"
 - ⚠️ **部署生产前必须通读一遍部署脚本再执行，禁止盲跑。** 部署脚本是多人接力的产物，其中任何一行环境值（PROJECT / 服务名 / Nacos namespace / 数据库 / 域名 / 后端 Host / VPC / 密钥名）都可能被中途改错、与线上真实环境脱节——脚本能跑、能编译、甚至能部署成功，但连的是错环境。执行前逐行核对脚本配置与线上实际（`gcloud config get-value project`、`gcloud run services list`、Nacos 配置），对不上 → 先改脚本或停下来问，禁止带着疑似错误的配置直接部署（呼应「环境配置禁止推断」）。
 - ⚠️ **部署脚本必须内置「环境自检」：在真正执行部署动作之前，先自动校验脚本配置与线上环境一致，不一致即中止（abort），禁止在环境未验证的情况下执行 deploy。** 校验项至少包括：① PROJECT 与 `gcloud config get-value project` 一致；② 目标 Cloud Run 服务真实存在；③ Nacos namespace / 库名与线上一致；④ 前端代理的后端 Host（BACKEND_RUN_HOST）指向本环境后端，而非 Dockerfile 默认值或他环境。**目标脚本若没有自检逻辑，执行者必须先补上再跑——禁止「无自检的脚本直接部署」。** 参照 agent-rules 自身 `release.sh` 的「规则漂移检查」（发版前强制校验规则已同步、未同步即中止），把「人记得校验」升级为「脚本强制校验」。
 
+### 🚨 上线安全四环铁律（部署生产 / 切流量必守）
+
+上线（部署生产、切流量、更新线上版本）的唯一不可接受后果是：**新版本有问题直接接流量，把原本正常服务顶崩**。上线必须走完以下四环，缺一不可；任何一环未过即中止，禁止带着未验证的环节继续。这里的核心是「你叫我怎样就怎样」行不通——**上线动作必须等校验全部通过才执行**。
+
+**环1 · 部署前环境对账**（详见「⚠️ 环境配置禁止推断」章节）
+- 脚本配置（PROJECT / 服务名 / Nacos namespace / 数据库 / 域名 / 后端 Host）与线上实际逐项对账（`gcloud config get-value project`、`gcloud run services list`、Nacos），对不上 → 先改脚本或停下问，禁止带疑似错误配置部署。
+
+**环2 · 部署前脚本通读 + 脚本自检**（详见上方「部署规则」两条铁律）
+- 通读一遍部署脚本再执行，禁止盲跑；脚本须内置「环境自检」（PROJECT 一致 / 目标服务存在 / Nacos 与库一致 / 后端 Host 非默认值），不一致即 abort；无自检先补上再跑。
+
+**环3 · 部署中先下不发（防「一上去就崩」的关键）**
+- 部署必须 `--no-traffic`（新 revision 保持 0% 流量），用 revision 临时 URL 验证新版本：日志无 ERROR、连对本环境库、关键接口 200、核心功能可跑通。**验证通过之前，禁止把流量切到新版本；禁止让 `gcloud run deploy` 默认把 100% 流量切到新 revision。**
+
+**环4 · 切流量渐进 + 全程可回滚**
+- 后端渐进切流量（5% → 观察 → 50% → 100%）；前端静态资源验证后一次性切。
+- 切流量前记录当前线上 revision 号；任何一步验证不过，`update-traffic --to-revision <旧版>` 秒切回，恢复线上原状后再排查。
+
 ## ⚠️ 配置中心变更生效铁律
 
 - ⚠️ **修改外部配置中心（如 Nacos）的配置后，若应用是启动时一次性拉取、没有热更新监听，必须显式重启/重新部署服务才能生效**。发布配置后如果验证发现"没生效"，先确认服务是否已经重启到最新版本，再去怀疑配置内容本身写错了——顺序反了会在"配置到底对不对"上来回排查，白白浪费时间。