docs: 修正蓝绿部署文档-端口按现有代码+环境独立数据库
This commit is contained in:
@@ -10,20 +10,42 @@
|
||||
|
||||
单实例部署的风险：部署期间用户请求失败（502/503）。
|
||||
|
||||
## 概念澄清
|
||||
|
||||
蓝绿部署是**同一环境内的两个实例**，不是跨环境：
|
||||
|
||||
```
|
||||
开发环境（dev.xmclassmate.top）
|
||||
├── 蓝色实例 :8080（当前活动）
|
||||
├── 绿色实例 :8081（空闲）
|
||||
└── 数据库 milkydata_dev（共享）
|
||||
|
||||
生产环境（xmclassmate.top）
|
||||
├── 蓝色实例 :4433（当前活动）
|
||||
├── 绿色实例 :4434（空闲）
|
||||
└── 数据库 milkydata（共享）
|
||||
```
|
||||
|
||||
每个环境独立维护自己的蓝绿实例，互不干扰。
|
||||
|
||||
## 蓝绿部署架构
|
||||
|
||||
以开发环境为例：
|
||||
|
||||
```
|
||||
OpenResty（反向代理）
|
||||
dev.xmclassmate.top
|
||||
│
|
||||
OpenResty proxy
|
||||
/ \
|
||||
蓝色环境 绿色环境
|
||||
127.0.0.1:8081 127.0.0.1:8082
|
||||
蓝色 (:8080 active) 绿色 (:8081 idle)
|
||||
rust-backend-blue rust-backend-green
|
||||
| |
|
||||
↓ ↓
|
||||
同一个 PostgreSQL（milkydata_dev）
|
||||
└──────────┬─────────────┘
|
||||
↓
|
||||
milkydata_dev（共享数据库）
|
||||
```
|
||||
|
||||
两个环境共享同一个数据库，但运行不同的代码版本。任何时候只有一个环境接收流量，另一个空闲。
|
||||
任何时候只有一个实例接收流量，另一个运行旧版本待命。
|
||||
|
||||
## 组件变更
|
||||
|
||||
@@ -31,138 +53,125 @@
|
||||
|
||||
```
|
||||
/etc/systemd/system/
|
||||
├── rust-backend-blue.service ← 端口 8081
|
||||
└── rust-backend-green.service ← 端口 8082
|
||||
├── rust-backend-dev-blue.service ← 端口 8080
|
||||
└── rust-backend-dev-green.service ← 端口 8081
|
||||
```
|
||||
|
||||
每个 service 文件与现有的 `rust-backend-dev.service` 结构一致，仅端口和描述不同。
|
||||
生产环境同理：
|
||||
|
||||
```
|
||||
/etc/systemd/system/
|
||||
├── rust-backend-blue.service ← 端口 4433
|
||||
└── rust-backend-green.service ← 端口 4434
|
||||
```
|
||||
|
||||
每个 service 配置与现有文件一致，仅端口和描述不同，且 `DATABASE_URL` 指向同一数据库。
|
||||
|
||||
### 新增 OpenResty 配置
|
||||
|
||||
由 1Panel 管理的 proxy 配置：
|
||||
|
||||
```
|
||||
# /www/sites/dev.xmclassmate.top/proxy/active-backend.conf
|
||||
# 由 deploy.sh 自动切换
|
||||
|
||||
# 蓝色环境
|
||||
location ^~ / {
|
||||
proxy_pass http://127.0.0.1:8081;
|
||||
proxy_pass http://127.0.0.1:8080; # ← deploy.sh 切换此端口
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
切换时只需替换这个文件中的端口号，然后 `nginx -s reload`。
|
||||
切换时 `sed` 替换端口号，然后 `nginx -s reload`。
|
||||
|
||||
### 新增脚本
|
||||
|
||||
```
|
||||
scripts/
|
||||
├── deploy-blue-green.sh ← 蓝绿部署主脚本
|
||||
└── switch-blue-green.sh ← 手动切换蓝绿
|
||||
└── switch-env.sh ← 手动切换/查看状态
|
||||
```
|
||||
|
||||
## 部署流程
|
||||
|
||||
```
|
||||
部署前： 蓝色=active(:8081) 绿色=idle(:8082)
|
||||
初始状态：蓝色(:8080)=active 绿色(:8081)=idle
|
||||
|
||||
步骤 1：部署到空闲环境（绿色）
|
||||
cargo build --release
|
||||
rsync 二进制 → 绿色目录
|
||||
systemctl restart rust-backend-green.service
|
||||
run_migrations
|
||||
① 编译新代码
|
||||
② 上传二进制到绿色目录
|
||||
③ systemctl restart rust-backend-dev-green.service
|
||||
④ 运行数据库迁移
|
||||
|
||||
步骤 2：验证绿色环境
|
||||
curl http://127.0.0.1:8082/health
|
||||
run_tests
|
||||
curl http://127.0.0.1:8081/health
|
||||
运行 9 项部署测试
|
||||
|
||||
步骤 3：切换流量
|
||||
修改 OpenResty proxy_pass → 127.0.0.1:8082
|
||||
sed 修改 OpenResty proxy_pass → 127.0.0.1:8081
|
||||
nginx -s reload
|
||||
|
||||
步骤 4：验证切换后
|
||||
curl https://dev.xmclassmate.top/health
|
||||
|
||||
部署后： 绿色=active(:8082) 蓝色=idle(:8081)
|
||||
← 下次部署时部署到蓝色
|
||||
结果：绿色(:8081)=active 蓝色(:8080)=idle
|
||||
下次部署时部署到蓝色
|
||||
```
|
||||
|
||||
## 切换脚本
|
||||
|
||||
`switch-blue-green.sh` 手动切换活动环境：
|
||||
|
||||
```bash
|
||||
# 查看当前活动环境
|
||||
./switch-blue-green.sh --status
|
||||
# → 当前活动: 蓝色 (127.0.0.1:8081)
|
||||
./scripts/switch-env.sh --status
|
||||
# → dev 环境: 蓝色 (127.0.0.1:8080)
|
||||
|
||||
# 切换到绿色
|
||||
./switch-blue-green.sh --switch green
|
||||
# → 修改 proxy_pass → 127.0.0.1:8082
|
||||
./scripts/switch-env.sh --env dev --switch green
|
||||
# → 修改 proxy_pass 127.0.0.1:8081
|
||||
# → nginx -s reload
|
||||
# → 验证健康检查
|
||||
# → 切换成功
|
||||
```
|
||||
|
||||
## deploy.sh 改造
|
||||
|
||||
现有 `deploy.sh` 增加 `--blue-green` 模式：
|
||||
|
||||
```bash
|
||||
./deploy.sh development --blue-green
|
||||
```
|
||||
|
||||
自动检测空闲环境并部署到该环境：
|
||||
|
||||
```
|
||||
1. 检查 8081 和 8082 哪个是空闲的
|
||||
2. 启动空闲环境的新版本
|
||||
3. 测试新版本
|
||||
4. 切换流量
|
||||
5. 停止旧版本
|
||||
```
|
||||
|
||||
## 数据库迁移注意事项
|
||||
|
||||
蓝绿部署中数据库是共享的，迁移需要考虑**向前兼容**：
|
||||
蓝绿部署中两个实例共享同一数据库（同一环境内的 milkydata 或 milkydata_dev），迁移脚本需要对**新旧两个版本的代码都兼容**：
|
||||
|
||||
| 迁移类型 | 是否兼容 | 说明 |
|
||||
|---------|---------|------|
|
||||
| `CREATE TABLE` | ✅ 安全 | 新旧代码都能运行 |
|
||||
| `ADD COLUMN` | ✅ 安全（需 DEFAULT 或 NULL） | 旧代码忽略新列 |
|
||||
| `RENAME COLUMN` | ❌ **不兼容** | 旧代码查询旧列名会失败 |
|
||||
| `DROP COLUMN` | ❌ 不兼容 | 旧代码查询被删列会失败 |
|
||||
| 迁移类型 | 兼容性 | 说明 |
|
||||
|---------|--------|------|
|
||||
| `CREATE TABLE` | ✅ | 新旧代码都能运行 |
|
||||
| `ADD COLUMN` | ✅ | 需 `DEFAULT` 或允许 `NULL` |
|
||||
| `RENAME COLUMN` | ❌ | 旧代码仍查旧列名 |
|
||||
| `DROP COLUMN` | ❌ | 旧代码查询被删列 |
|
||||
|
||||
对于不兼容的迁移（如列重命名 `010_rename_paid_fields.sql`），需要：
|
||||
对于不兼容的迁移（如列重命名），需要**三段式部署**：
|
||||
|
||||
```
|
||||
1. 先部署兼容旧列名的新代码（两个列名都支持）
|
||||
2. 再执行迁移重命名列
|
||||
3. 最后部署只支持新列名的代码
|
||||
第 1 步：部署兼容双列名的代码（is_paid 和 is_member 同时支持）
|
||||
第 2 步：执行迁移（重命名列）
|
||||
第 3 步：部署只支持新列名的代码
|
||||
```
|
||||
|
||||
这称为**三段式迁移**，需要代码层面同时兼容新旧列名。当前 `010` 迁移不符合蓝绿条件，需要在代码中添加兼容层后再启用蓝绿。
|
||||
当前代码已完成列重命名，若后续有类似变更需遵循此流程。
|
||||
|
||||
## 实施步骤
|
||||
## 实施优先级
|
||||
|
||||
| 阶段 | 内容 | 工作量 |
|
||||
|------|------|--------|
|
||||
| P1 | 创建两个 systemd service 文件（blue + green） | 小 |
|
||||
| P2 | 编写 `deploy-blue-green.sh` 和 `switch-blue-green.sh` | 中 |
|
||||
| P3 | 编写 OpenResty 配置切换逻辑（1Panel API 或 直接改文件） | 中 |
|
||||
| P4 | 改造现有 `deploy.sh` 支持 `--blue-green` | 中 |
|
||||
| P5 | 处理不兼容迁移（列重命名等）的三段式部署 | 大 |
|
||||
| P6 | 编写文档和回滚流程 | 小 |
|
||||
| P1 | 创建两个 systemd service 模板（blue + green） | 小 |
|
||||
| P2 | 编写 `deploy-blue-green.sh` + `switch-env.sh` | 中 |
|
||||
| P3 | 实现 OpenResty proxy 配置切换 | 中 |
|
||||
| P4 | 改造 `deploy.sh` 支持 `--blue-green` | 中 |
|
||||
| P5 | 处理不兼容迁移的三段式部署文档 | 小 |
|
||||
| P6 | 编写回滚文档 | 小 |
|
||||
|
||||
## 回滚流程
|
||||
## 回滚
|
||||
|
||||
```bash
|
||||
# 如果新环境有问题，立即切回旧环境
|
||||
./switch-blue-green.sh --switch blue
|
||||
# 新环境有问题 → 立即切回旧环境
|
||||
./scripts/switch-env.sh --env dev --switch blue
|
||||
|
||||
# 旧环境仍然是部署前的版本，无需重新部署
|
||||
# 修复问题后重新走蓝绿部署流程
|
||||
# 旧环境代码未变，即时恢复
|
||||
# 修复问题后重新部署到空闲环境
|
||||
```
|
||||
|
||||
## 建议
|
||||
## 当前是否实施
|
||||
|
||||
**当前项目规模（~100 日活）不需要蓝绿部署**。停机 3-5 秒的影响可以忽略。但如果是为了学习目的或为未来增长做准备，可以按 P1→P2 的顺序逐步实现。
|
||||
当前项目规模（~100 日活），部署停机约 3-5 秒，实际影响可忽略。建议**保留文档**，当需要时再按 P1→P2 逐步实施。
|
||||
|
||||
Reference in New Issue
Block a user