From f330d3a5b3d7704e2acdf94f4de33403f952205c Mon Sep 17 00:00:00 2001 From: milky0217 Date: Sun, 7 Jun 2026 16:49:22 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0BLUE-GREEN-DEPLOY.md-?= =?UTF-8?q?=E9=99=90=E5=88=B6&=E6=B3=A8=E6=84=8F=E4=BA=8B=E9=A1=B9+?= =?UTF-8?q?=E6=95=B0=E6=8D=AE=E5=BA=93=E5=90=8D=E7=A7=B0+=E5=AE=9E?= =?UTF-8?q?=E6=96=BD=E7=8A=B6=E6=80=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/BLUE-GREEN-DEPLOY.md | 84 ++++++++++++++++++++++++++++++++++----- 1 file changed, 74 insertions(+), 10 deletions(-) diff --git a/docs/BLUE-GREEN-DEPLOY.md b/docs/BLUE-GREEN-DEPLOY.md index 7cb6c90..183da84 100644 --- a/docs/BLUE-GREEN-DEPLOY.md +++ b/docs/BLUE-GREEN-DEPLOY.md @@ -6,7 +6,7 @@ 域名 环境 后端端口 数据库 ──────────────────────────────────────────────────── dev.xmclassmate.top 开发/测试 :8080 milkydata_dev -xmclassmate.top 生产 :4433 / :4434 milkydata_dev +xmclassmate.top 生产 :4433 / :4434 milkydata ``` > **原则**：两个域名永远指向各自的环境，不互换。生产采用蓝绿部署实现零停机。 @@ -53,7 +53,7 @@ xmclassmate.top 蓝色 :4433 绿色 :4434 (active) (idle) \ / - milkydata_dev（共享） + milkydata（共享） ``` 任何时候只有一个实例接收流量，另一个运行旧版本待命，切换零停机。 @@ -68,7 +68,7 @@ xmclassmate.top └── rust-backend-green.service ← :4434 ``` -两个 service 的 `DATABASE_URL` 都指向 `milkydata_dev`，仅端口不同。 +两个 service 的 `DATABASE_URL` 都指向 `milkydata`，仅端口不同。 **OpenResty proxy 配置：** @@ -127,11 +127,54 @@ location ^~ / { | 环境 | 数据库 | 说明 | |------|--------|------| | 开发 | `milkydata_dev` | 单实例直连 | -| 生产 | `milkydata_dev` | 蓝绿实例共享，名称不变 | +| 生产 | `milkydata` | 蓝绿实例共享，名称不变 | -> 当前开发与生产共用 `milkydata_dev`。后续建议拆分为 `milkydata_prod`。 +> 生产库 `milkydata`，开发库 `milkydata_dev`，两者独立。 -## 迁移注意事项 +## 限制与注意事项 + +### 1. 部署只能部署到非活动端口 + +每次部署必须部署到**当前空闲的环境**，绝不能直接部署到正在接收流量的端口。 + +``` +正确流程： + Green(:4434) 活动中 → 部署到 Blue(:4433) → 测试 → 切到 Blue(:4433) + Blue(:4433) 活动中 → 部署到 Green(:4434) → 测试 → 切到 Green(:4434) + +错误： + Green(:4434) 活动中 → 直接部署到 Green(:4434) ← ❌ 会产生停机 +``` + +**原因**：部署过程涉及服务重启（~3-5 秒），如果直接部署到活动中环境， +会导致在此期间的用户请求失败。 + +### 2. 代码只能通过 deploy.sh 部署 + +禁止手动 `rsync` + `systemctl restart` 部署。必须使用统一脚本： + +```bash +# 正确 +./deploy.sh production --target blue --yes + +# 错误 +cargo build --release && rsync ... systemctl restart ← ❌ +``` + +**原因**： +- 自动备份旧版本，支持回滚 +- 自动运行数据库迁移 +- 自动验证服务健康 +- 自动切换代理（零停机） +- 自动记录部署日志 +- 跳过手动操作的遗漏风险 + +### 3. 部署后先验证再切换 + +`deploy.sh --skip-tests` 跳过了部署后的自动测试。建议仅在开发/快速迭代时使用， +生产环境应让测试跑完再切换。 + +### 4. 数据库兼容性（迁移注意事项） 蓝绿共享数据库，迁移需向前兼容： @@ -159,13 +202,34 @@ location ^~ / { | # | 步骤 | 说明 | 状态 | |---|------|------|------| -| 1 | 数据迁移 `milkydata` → `milkydata_dev` | 已完成 | ✅ | +| 1 | 数据迁移 | 已完成 | ✅ | | 2 | 准备生产 service 文件（填入实际密钥） | 待完成 | ⬜ | | 3 | 部署新代码到 `:4433` | 待完成 | ⬜ | | 4 | `env.ts` 设 `CURRENT_ENV = 'production'` | 已完成 | ✅ | | 5 | 微信开发者工具上传小程序 | 待完成 | ⬜ | -| 6 | 1Panel 确认 `proxy_pass` 指向 `:4433` | 待完成 | ⬜ | +| 6 | 1Panel 确认 `proxy_pass` 指向 `:4433` | 已完成 | ✅ | -## 当前是否实施 +## 实施状态 -当前暂未实施蓝绿。先实现 P1-P2 后启用。 +蓝绿部署已实施并运行中： + +| 组件 | 状态 | +|------|------| +| Blue service (:4433) | ✅ 运行中，ConfigID `71ba8887` | +| Green service (:4434) | ✅ 运行中，活动中 | +| `deploy.sh --target blue\|green` | ✅ 已支持 | +| `switch-env.sh --switch blue\|green` | ✅ 自动切换 | +| OpenResty proxy | ✅ 指向活动中环境 | + +### 下次部署流程 + +```bash +# 1. 查看当前活动中环境 +./scripts/switch-env.sh --status + +# 2. 部署到空闲环境（假设 green 活动中 → 部署到 blue） +./deploy.sh production --target blue --yes + +# 3. 部署完成后自动切换流量到 blue +# deploy.sh 自动调用 switch-env.sh --switch blue +```