245 lines
6.5 KiB
Markdown
245 lines
6.5 KiB
Markdown
# 蓝绿部署（新服务器）
|
||
|
||
> **服务器**：47.109.203.92 (Aliyun, Debian 13)
|
||
> **nginx**：原生 nginx（非 Docker/OpenResty）
|
||
> **PostgreSQL**：Docker 容器 `postgres:17.6-alpine`
|
||
> **部署用户**：`deploy`（有 sudo 权限）
|
||
|
||
## 域名与环境映射
|
||
|
||
```
|
||
域名 环境 后端端口 数据库
|
||
────────────────────────────────────────────────────
|
||
dev.xmclassmate.top 开发/测试 :8080 milkydata_dev
|
||
xmclassmate.top 生产 :4433 / :4434 milkydata
|
||
```
|
||
|
||
> **原则**：两个域名永远指向各自的环境，不互换。生产采用蓝绿部署实现零停机。
|
||
|
||
## 当前问题
|
||
|
||
单实例部署时存在停机时间：
|
||
|
||
```
|
||
停止服务 → 上传新代码 → 重启服务 → 跑迁移
|
||
↑
|
||
3-5 秒停机
|
||
```
|
||
|
||
## 开发环境（dev.xmclassmate.top）
|
||
|
||
保持单实例，无需蓝绿：
|
||
|
||
```
|
||
dev.xmclassmate.top
|
||
│
|
||
nginx → :8080（单实例）
|
||
│
|
||
milkydata_dev
|
||
```
|
||
|
||
开发环境不需要蓝绿的原因：
|
||
|
||
| 原因 | 说明 |
|
||
|------|------|
|
||
| 停机时间可接受 | 仅开发者使用，重启 3-5 秒无影响 |
|
||
| 简化运维 | 少维护一套 systemd service |
|
||
| 快速迭代 | 直接 `deploy.sh development` 部署 |
|
||
|
||
## 生产环境（xmclassmate.top）— 蓝绿部署
|
||
|
||
### 架构
|
||
|
||
```
|
||
xmclassmate.top
|
||
│
|
||
nginx proxy（直接路由）
|
||
/ \
|
||
蓝色 :4433 绿色 :4434
|
||
(active) (idle)
|
||
\ /
|
||
milkydata（共享）
|
||
```
|
||
|
||
任何时候只有一个实例接收流量，另一个运行旧版本待命，切换零停机。
|
||
|
||
### 组件
|
||
|
||
**systemd service：**
|
||
|
||
```
|
||
/etc/systemd/system/
|
||
├── rust-backend-blue.service ← :4433
|
||
└── rust-backend-green.service ← :4434
|
||
```
|
||
|
||
两个 service 的 `DATABASE_URL` 都指向 `milkydata`，仅端口不同。
|
||
|
||
**nginx proxy 配置：**
|
||
|
||
```
|
||
# /www/sites/xmclassmate.top/proxy/root.conf
|
||
location ^~ / {
|
||
proxy_pass https://127.0.0.1:4433; # deploy.sh 切换此端口
|
||
}
|
||
```
|
||
|
||
> 生产环境使用 HTTPS proxy（`proxy_pass https://...`），因为后端自身处理 TLS。
|
||
|
||
切换时 `sed` 替换端口，`sudo nginx -s reload`。
|
||
|
||
### 部署流程
|
||
|
||
```
|
||
初始：蓝色(:4433)=active 绿色(:4434)=idle
|
||
|
||
步骤 1：部署到空闲环境（绿色）
|
||
① cargo build --release
|
||
② rsync 二进制 → 绿色目录
|
||
③ systemctl restart rust-backend-green.service
|
||
④ 运行数据库迁移
|
||
|
||
步骤 2：验证绿色环境
|
||
curl http://127.0.0.1:4434/health
|
||
run_tests
|
||
|
||
步骤 3：切换流量
|
||
sed 修改 proxy_pass → 127.0.0.1:4434
|
||
nginx -s reload
|
||
|
||
步骤 4：验证
|
||
curl https://xmclassmate.top/health
|
||
|
||
结果：绿色(:4434)=active 蓝色(:4433)=idle
|
||
下次部署到蓝色
|
||
```
|
||
|
||
### 切换脚本
|
||
|
||
```bash
|
||
./scripts/switch-env.sh --switch green
|
||
# 或切回蓝色
|
||
./scripts/switch-env.sh --switch blue
|
||
# 查看当前状态
|
||
./scripts/switch-env.sh --status
|
||
```
|
||
|
||
### 回滚
|
||
|
||
```bash
|
||
./scripts/switch-env.sh --env prod --switch blue # 即时恢复旧版本
|
||
```
|
||
旧环境代码未变，无需重新部署。
|
||
|
||
## 数据库
|
||
|
||
| 环境 | 数据库 | 说明 |
|
||
|------|--------|------|
|
||
| 开发 | `milkydata_dev` | 单实例直连 |
|
||
| 生产 | `milkydata` | 蓝绿实例共享，名称不变 |
|
||
|
||
> 生产库 `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. 数据库兼容性（迁移注意事项）
|
||
|
||
蓝绿共享数据库，迁移需向前兼容：
|
||
|
||
| 迁移类型 | 兼容 | 说明 |
|
||
|---------|------|------|
|
||
| `CREATE TABLE` | ✅ | 新旧代码均可运行 |
|
||
| `ADD COLUMN` | ✅ | 需 `DEFAULT` 或允许 `NULL` |
|
||
| `RENAME COLUMN` | ❌ | 旧代码查询旧列名会失败 |
|
||
| `DROP COLUMN` | ❌ | 旧代码查询被删列会失败 |
|
||
|
||
不兼容的迁移需要三段式部署。
|
||
|
||
## 实施优先级
|
||
|
||
| 阶段 | 内容 | 工作量 |
|
||
|------|------|--------|
|
||
| P1 | 创建 blue + green 两个 systemd service | 小 |
|
||
| P2 | 编写 `deploy-blue-green.sh` + `switch-env.sh` | 中 |
|
||
| P3 | 实现 OpenResty proxy 配置切换 | 中 |
|
||
| P4 | 改造 `deploy.sh` 支持 `--blue-green` | 中 |
|
||
| P5 | 不兼容迁移的三段式部署文档 | 小 |
|
||
| P6 | 回滚文档 | 小 |
|
||
|
||
## 生产上线待办
|
||
|
||
| # | 步骤 | 说明 | 状态 |
|
||
|---|------|------|------|
|
||
| 1 | 数据迁移 | 已完成 | ✅ |
|
||
| 2 | 准备生产 service 文件 | 已完成 | ✅ |
|
||
| 3 | 部署新代码到 `:4433` 和 `:4434` | 已完成 | ✅ |
|
||
| 4 | `env.ts` 设 `CURRENT_ENV = 'production'` | 已完成 | ✅ |
|
||
| 5 | 微信开发者工具上传小程序 | 已完成 | ✅ |
|
||
| 6 | 确认 nginx `proxy_pass` 指向 :4433 | 已完成 | ✅ |
|
||
|
||
## 实施状态
|
||
|
||
蓝绿部署已实施并运行中：
|
||
|
||
| 组件 | 状态 |
|
||
|------|------|
|
||
| Blue service (:4433) | ✅ 运行中，当前活跃 |
|
||
| Green service (:4434) | ✅ 运行中，待命中 |
|
||
| `deploy.sh production --target blue/green` | ✅ 已支持 |
|
||
| `switch-env.sh --switch blue/green` | ✅ 自动切换 nginx proxy |
|
||
| nginx 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
|
||
```
|