diff --git a/docs/BLUE-GREEN-DEPLOY.md b/docs/BLUE-GREEN-DEPLOY.md index fa329e9..0170785 100644 --- a/docs/BLUE-GREEN-DEPLOY.md +++ b/docs/BLUE-GREEN-DEPLOY.md @@ -12,21 +12,28 @@ ## 概念澄清 -蓝绿部署是**同一环境内的两个实例**，不是跨环境： +蓝绿部署仅用于**生产环境**，开发环境保持单实例： ``` -开发环境（dev.xmclassmate.top） - ├── 蓝色实例 :8080（当前活动） - ├── 绿色实例 :8081（空闲） - └── 数据库 milkydata_dev ← 蓝绿共享，名称不变 +开发环境（dev.xmclassmate.top） — 单实例，无需蓝绿 + └── 实例 :8080 + └── 数据库 milkydata_dev -生产环境（xmclassmate.top） +生产环境（xmclassmate.top） — 蓝绿部署 ├── 蓝色实例 :4433（当前活动） ├── 绿色实例 :4434（空闲） - └── 数据库 milkydata ← 蓝绿共享，名称不变 + └── 数据库 milkydata（蓝绿共享，名称不变） ``` -每个环境独立维护自己的蓝绿实例和独立数据库，互不干扰。 +开发环境不需要蓝绿的原因： + +| 原因 | 说明 | +|------|------| +| 停机时间可接受 | 开发环境只有开发者使用，重启 3-5 秒无影响 | +| 简化运维 | 少维护一套 systemd service 和 nginx 配置 | +| 快速迭代 | 直接 `deploy.sh development` 部署即可，无需切换步骤 | + +生产环境使用蓝绿部署实现零停机发布。 ### 数据库与蓝绿的关系 @@ -34,29 +41,10 @@ | 环境 | 数据库 | 蓝绿实例共同连接 | |------|--------|----------------| -| 开发 | `milkydata_dev` | `DATABASE_URL=postgres://.../milkydata_dev` | +| 开发 | `milkydata_dev` | 单实例，无需蓝绿 | | 生产 | `milkydata` | `DATABASE_URL=postgres://.../milkydata` | -两个实例的 service 文件中 `DATABASE_URL` 配置为完全相同的值。切换蓝绿时只改端口，不改数据库连接。 - -## 蓝绿部署架构 - -以开发环境为例： - -``` - dev.xmclassmate.top - │ - OpenResty proxy - / \ - 蓝色 (:8080 active) 绿色 (:8081 idle) - rust-backend-blue rust-backend-green - | | - └──────────┬─────────────┘ - ↓ - milkydata_dev（共享数据库） -``` - -任何时候只有一个实例接收流量，另一个运行旧版本待命。 +两个蓝绿实例的 service 文件中 `DATABASE_URL` 配置为完全相同的值。切换蓝绿时只改端口，不改数据库连接。 ## 域名与蓝绿的关系 @@ -64,30 +52,38 @@ ``` 用户访问 OpenResty（域名不变） 后端实例 -dev.xmclassmate.top ──→ dev.xmclassmate.top ──→ :8080（蓝）或 :8081（绿） xmclassmate.top ──→ xmclassmate.top ──→ :4433（蓝）或 :4434（绿） ``` 切换时 OpenResty 内部的 `proxy_pass` 指向的目标端口变更，**用户无感知**： ``` -切换前：dev.xmclassmate.top ──→ proxy_pass 127.0.0.1:8080 ← 蓝色活动 -切换后：dev.xmclassmate.top ──→ proxy_pass 127.0.0.1:8081 ← 绿色活动 +切换前：xmclassmate.top ──→ proxy_pass 127.0.0.1:4433 ← 蓝色活动 +切换后：xmclassmate.top ──→ proxy_pass 127.0.0.1:4434 ← 绿色活动 ``` -小程序前端的 `env.ts` 中 `CURRENT_ENV` 指向的域名（`dev.xmclassmate.top` 或 `xmclassmate.top`）**无需修改**。 +小程序前端的 `env.ts` 中 `CURRENT_ENV=production` 指向 `xmclassmate.top`，蓝绿切换时**无需修改**。 + +## 蓝绿部署架构（生产环境） + +``` + xmclassmate.top + │ + OpenResty proxy + / \ + 蓝色 (:4433 active) 绿色 (:4434 idle) + rust-backend-blue rust-backend-green + │ │ + └──────────┬─────────────┘ + ↓ + milkydata（共享数据库） +``` + +任何时候只有一个实例接收流量，另一个运行旧版本待命。 ## 组件变更 -### 新增 systemd service - -``` -/etc/systemd/system/ -├── rust-backend-dev-blue.service ← 端口 8080 -└── rust-backend-dev-green.service ← 端口 8081 -``` - -生产环境同理： +### 新增 systemd service（生产环境） ``` /etc/systemd/system/ @@ -95,17 +91,17 @@ xmclassmate.top ──→ xmclassmate.top ──→ :4433（蓝） └── rust-backend-green.service ← 端口 4434 ``` -每个 service 配置与现有文件一致，仅端口和描述不同，且 `DATABASE_URL` 指向同一数据库。 +每个 service 配置与现有 `rust-backend.service` 一致，仅端口和描述不同，且 `DATABASE_URL` 指向 `milkydata`。 ### 新增 OpenResty 配置 由 1Panel 管理的 proxy 配置： ``` -# /www/sites/dev.xmclassmate.top/proxy/active-backend.conf +# /www/sites/xmclassmate.top/proxy/active-backend.conf location ^~ / { - proxy_pass http://127.0.0.1:8080; # ← deploy.sh 切换此端口 + proxy_pass http://127.0.0.1:4433; # ← deploy.sh 切换此端口 ... } ``` @@ -120,29 +116,29 @@ scripts/ └── switch-env.sh ← 手动切换/查看状态 ``` -## 部署流程 +## 部署流程（生产环境） ``` -初始状态：蓝色(:8080)=active 绿色(:8081)=idle +初始状态：蓝色(:4433)=active 绿色(:4434)=idle 步骤 1：部署到空闲环境（绿色） ① 编译新代码 ② 上传二进制到绿色目录 - ③ systemctl restart rust-backend-dev-green.service + ③ systemctl restart rust-backend-green.service ④ 运行数据库迁移 步骤 2：验证绿色环境 - curl http://127.0.0.1:8081/health + curl http://127.0.0.1:4434/health 运行 9 项部署测试 步骤 3：切换流量 - sed 修改 OpenResty proxy_pass → 127.0.0.1:8081 + sed 修改 OpenResty proxy_pass → 127.0.0.1:4434 nginx -s reload 步骤 4：验证切换后 - curl https://dev.xmclassmate.top/health + curl https://xmclassmate.top/health -结果：绿色(:8081)=active 蓝色(:8080)=idle +结果：绿色(:4434)=active 蓝色(:4433)=idle 下次部署时部署到蓝色 ``` @@ -151,18 +147,18 @@ scripts/ ```bash # 查看当前活动环境 ./scripts/switch-env.sh --status -# → dev 环境: 蓝色 (127.0.0.1:8080) +# → 生产环境: 蓝色 (127.0.0.1:4433) # 切换到绿色 -./scripts/switch-env.sh --env dev --switch green -# → 修改 proxy_pass 127.0.0.1:8081 +./scripts/switch-env.sh --env prod --switch green +# → 修改 proxy_pass 127.0.0.1:4434 # → nginx -s reload # → 验证健康检查 ``` ## 数据库迁移注意事项 -蓝绿部署中两个实例共享同一数据库（同一环境内的 milkydata 或 milkydata_dev），迁移脚本需要对**新旧两个版本的代码都兼容**： +蓝绿部署中两个实例共享同一数据库（`milkydata`），迁移脚本需要对**新旧两个版本的代码都兼容**： | 迁移类型 | 兼容性 | 说明 | |---------|--------|------| @@ -196,7 +192,7 @@ scripts/ ```bash # 新环境有问题 → 立即切回旧环境 -./scripts/switch-env.sh --env dev --switch blue +./scripts/switch-env.sh --env prod --switch blue # 旧环境代码未变，即时恢复 # 修复问题后重新部署到空闲环境 @@ -219,7 +215,7 @@ scripts/ | 环境 | 域名 | 数据库 | 当前端口 | 蓝绿备选端口 | |------|------|--------|---------|-------------| -| 开发 | `dev.xmclassmate.top` | `milkydata_dev` | `:8080` | `:8081` | +| 开发 | `dev.xmclassmate.top` | `milkydata_dev` | `:8080` | 无（单实例） | | 生产 | `xmclassmate.top` | `milkydata` | `:4433` | `:4434` | ## 当前是否实施