milky/asd-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 蓝绿部署仅用于生产环境,开发保持单实例

Browse Source
This commit is contained in:
milky0217
2026-05-31 13:43:36 +08:00
parent 6c7c940b3e
commit dd784ab608
1 changed files with 54 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
docs/BLUE-GREEN-DEPLOY.md
View File

@@ -12,21 +12,28 @@
## 概念澄清 ## 概念澄清
蓝绿部署是**同一环境内的两个实例**，不是跨环境： 蓝绿部署仅用于**生产环境**，开发环境保持单实例：
``` ```
开发环境（dev.xmclassmate.top） 开发环境（dev.xmclassmate.top） — 单实例，无需蓝绿
├── 蓝色实例 :8080（当前活动） └── 实例 :8080
├── 绿色实例 :8081（空闲） └── 数据库 milkydata_dev
└── 数据库 milkydata_dev ← 蓝绿共享，名称不变
生产环境（xmclassmate.top） 生产环境（xmclassmate.top） — 蓝绿部署
├── 蓝色实例 :4433（当前活动） ├── 蓝色实例 :4433（当前活动）
├── 绿色实例 :4434（空闲） ├── 绿色实例 :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` | | 生产 | `milkydata` | `DATABASE_URL=postgres://.../milkydata` |
两个实例的 service 文件中 `DATABASE_URL` 配置为完全相同的值。切换蓝绿时只改端口，不改数据库连接。 两个蓝绿实例的 service 文件中 `DATABASE_URL` 配置为完全相同的值。切换蓝绿时只改端口，不改数据库连接。
## 蓝绿部署架构
以开发环境为例：
```
dev.xmclassmate.top
│
OpenResty proxy
/ \
蓝色 (:8080 active) 绿色 (:8081 idle)
rust-backend-blue rust-backend-green
| |
└──────────┬─────────────┘
↓
milkydata_dev（共享数据库）
```
任何时候只有一个实例接收流量，另一个运行旧版本待命。
## 域名与蓝绿的关系 ## 域名与蓝绿的关系
@@ -64,30 +52,38 @@
``` ```
用户访问 OpenResty（域名不变） 后端实例 用户访问 OpenResty（域名不变） 后端实例
dev.xmclassmate.top ──→ dev.xmclassmate.top ──→ :8080（蓝）或 :8081（绿）
xmclassmate.top ──→ xmclassmate.top ──→ :4433（蓝）或 :4434（绿） xmclassmate.top ──→ xmclassmate.top ──→ :4433（蓝）或 :4434（绿）
``` ```
切换时 OpenResty 内部的 `proxy_pass` 指向的目标端口变更，**用户无感知**： 切换时 OpenResty 内部的 `proxy_pass` 指向的目标端口变更，**用户无感知**：
``` ```
切换前：dev.xmclassmate.top ──→ proxy_pass 127.0.0.1:8080 ← 蓝色活动 切换前：xmclassmate.top ──→ proxy_pass 127.0.0.1:4433 ← 蓝色活动
切换后：dev.xmclassmate.top ──→ proxy_pass 127.0.0.1:8081 ← 绿色活动 切换后：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 ### 新增 systemd service（生产环境）
```
/etc/systemd/system/
├── rust-backend-dev-blue.service ← 端口 8080
└── rust-backend-dev-green.service ← 端口 8081
```
生产环境同理：
``` ```
/etc/systemd/system/ /etc/systemd/system/
@@ -95,17 +91,17 @@ xmclassmate.top ──→ xmclassmate.top ──→ :4433（蓝）
└── rust-backend-green.service ← 端口 4434 └── rust-backend-green.service ← 端口 4434
``` ```
每个 service 配置与现有文件一致，仅端口和描述不同，且 `DATABASE_URL` 指向同一数据库。 每个 service 配置与现有 `rust-backend.service` 一致，仅端口和描述不同，且 `DATABASE_URL` 指向 `milkydata`。
### 新增 OpenResty 配置 ### 新增 OpenResty 配置
由 1Panel 管理的 proxy 配置： 由 1Panel 管理的 proxy 配置：
``` ```
# /www/sites/dev.xmclassmate.top/proxy/active-backend.conf # /www/sites/xmclassmate.top/proxy/active-backend.conf
location ^~ / { 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 ← 手动切换/查看状态 └── switch-env.sh ← 手动切换/查看状态
``` ```
## 部署流程 ## 部署流程（生产环境）
``` ```
初始状态：蓝色(:8080)=active 绿色(:8081)=idle 初始状态：蓝色(:4433)=active 绿色(:4434)=idle
步骤 1：部署到空闲环境（绿色） 步骤 1：部署到空闲环境（绿色）
① 编译新代码 ① 编译新代码
② 上传二进制到绿色目录 ② 上传二进制到绿色目录
③ systemctl restart rust-backend-dev-green.service ③ systemctl restart rust-backend-green.service
④ 运行数据库迁移 ④ 运行数据库迁移
步骤 2：验证绿色环境 步骤 2：验证绿色环境
curl http://127.0.0.1:8081/health curl http://127.0.0.1:4434/health
运行 9 项部署测试 运行 9 项部署测试
步骤 3：切换流量 步骤 3：切换流量
sed 修改 OpenResty proxy_pass → 127.0.0.1:8081 sed 修改 OpenResty proxy_pass → 127.0.0.1:4434
nginx -s reload nginx -s reload
步骤 4：验证切换后 步骤 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 ```bash
# 查看当前活动环境 # 查看当前活动环境
./scripts/switch-env.sh --status ./scripts/switch-env.sh --status
# → dev 环境: 蓝色 (127.0.0.1:8080) # → 生产环境: 蓝色 (127.0.0.1:4433)
# 切换到绿色 # 切换到绿色
./scripts/switch-env.sh --env dev --switch green ./scripts/switch-env.sh --env prod --switch green
# → 修改 proxy_pass 127.0.0.1:8081 # → 修改 proxy_pass 127.0.0.1:4434
# → nginx -s reload # → nginx -s reload
# → 验证健康检查 # → 验证健康检查
``` ```
## 数据库迁移注意事项 ## 数据库迁移注意事项
蓝绿部署中两个实例共享同一数据库（同一环境内的 milkydata 或 milkydata_dev），迁移脚本需要对**新旧两个版本的代码都兼容**： 蓝绿部署中两个实例共享同一数据库（`milkydata`），迁移脚本需要对**新旧两个版本的代码都兼容**：
| 迁移类型 | 兼容性 | 说明 | | 迁移类型 | 兼容性 | 说明 |
|---------|--------|------| |---------|--------|------|
@@ -196,7 +192,7 @@ scripts/
```bash ```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` | | 生产 | `xmclassmate.top` | `milkydata` | `:4433` | `:4434` |
## 当前是否实施 ## 当前是否实施