168 lines
5.1 KiB
Markdown
168 lines
5.1 KiB
Markdown
# 支付维护模式 Runbook
|
||
|
||
> 当支付宝支付失效时的应急操作手册。涵盖开启/关闭维护模式、切换到 Mock 支付、修复支付宝配置三种方案。
|
||
|
||
---
|
||
|
||
## 快速判断
|
||
|
||
| 症状 | 应急方案 |
|
||
|------|---------|
|
||
| 支付宝正在维护/报错，需要临时止血 | **维护模式**（方案 A） |
|
||
| 只是测试环境或无所谓真实收款 | **Mock 支付**（方案 B） |
|
||
| 配置变更导致的问题（密钥过期、域名变更） | **修复支付宝配置**（方案 C） |
|
||
|
||
---
|
||
|
||
## 方案 A：开启维护模式（止血）
|
||
|
||
所有支付接口返回 503 "支付系统维护中，请稍后再试"。
|
||
|
||
### 前置条件
|
||
|
||
SSH 免密码登录到 `root@1panel-server`。
|
||
|
||
```bash
|
||
ssh root@1panel-server
|
||
```
|
||
|
||
### ⚠️ 关键陷阱：生产服务器使用蓝绿部署
|
||
|
||
| Service | 端口 | 目录 | 是否承担生产流量 |
|
||
|---------|------|------|----------------|
|
||
| `rust-backend-green.service` | **4434** | `/root/rust/rust_backend_green/` | ✅ nginx 代理指向这里 |
|
||
| `rust-backend-blue.service` | 4433 | `/root/rust/rust_backend_blue/` | ❌ 备用 |
|
||
| `rust-backend.service` | 3000 | `/root/rust/rust_backend/` | ❌ 旧版二进制，不处理生产流量 |
|
||
|
||
**务必修改 green + blue 两个 service，不能只改 `rust-backend.service`**。
|
||
|
||
Nginx 配置位置：`/opt/1panel/apps/openresty/openresty/www/sites/xmclassmate.top/proxy/root.conf`
|
||
|
||
### 操作步骤
|
||
|
||
```bash
|
||
# 1. 在 green（当前活跃）和 blue（备用）中都添加
|
||
sed -i '/^\[Service\]/a Environment=PAYMENT_MAINTENANCE_MODE=true' /etc/systemd/system/rust-backend-green.service
|
||
sed -i '/^\[Service\]/a Environment=PAYMENT_MAINTENANCE_MODE=true' /etc/systemd/system/rust-backend-blue.service
|
||
|
||
# 2. 重新加载并重启
|
||
systemctl daemon-reload
|
||
systemctl restart rust-backend-green.service
|
||
systemctl restart rust-backend-blue.service
|
||
|
||
# 3. 验证
|
||
curl -s -w "\nHTTP %{http_code}\n" https://xmclassmate.top/payment
|
||
# 预期：HTTP 503 + HTML 中显示"支付系统维护中"
|
||
```
|
||
|
||
### 恢复
|
||
|
||
```bash
|
||
ssh root@1panel-server
|
||
sed -i '/PAYMENT_MAINTENANCE_MODE/d' /etc/systemd/system/rust-backend-green.service
|
||
sed -i '/PAYMENT_MAINTENANCE_MODE/d' /etc/systemd/system/rust-backend-blue.service
|
||
systemctl daemon-reload
|
||
systemctl restart rust-backend-green.service
|
||
systemctl restart rust-backend-blue.service
|
||
|
||
# 验证
|
||
curl -s -w "\nHTTP %{http_code}\n" https://xmclassmate.top/payment
|
||
# 预期：HTTP 200 + 套餐选择页 HTML
|
||
```
|
||
|
||
---
|
||
|
||
## 方案 B：切换到 Mock 支付（快速恢复可用）
|
||
|
||
### 原理
|
||
|
||
当代码检测到 `ALIPAY_*` 环境变量不存在时，自动启用 Mock 支付（无需配置 `MOCK_PAY_ENABLED=true`）。
|
||
|
||
### 操作步骤
|
||
|
||
```bash
|
||
ssh root@1panel-server
|
||
|
||
# 1. 编辑 green service，注释掉支付宝配置
|
||
systemctl edit rust-backend-green.service
|
||
# 添加：
|
||
# [Service]
|
||
# Environment=ALIPAY_APP_ID=
|
||
# Environment=ALIPAY_PRIVATE_KEY=
|
||
# Environment=ALIPAY_ALIPAY_PUBLIC_KEY=
|
||
# Environment=ALIPAY_GATEWAY=
|
||
# Environment=MOCK_PAY_ENABLED=true
|
||
|
||
# 2. 同样操作 blue service
|
||
systemctl edit rust-backend-blue.service
|
||
|
||
# 3. 重启
|
||
systemctl daemon-reload
|
||
systemctl restart rust-backend-green.service
|
||
systemctl restart rust-backend-blue.service
|
||
```
|
||
|
||
---
|
||
|
||
## 方案 C：修复支付宝配置
|
||
|
||
### 检查清单
|
||
|
||
1. 登录 [支付宝开放平台](https://open.alipay.com) 检查应用状态
|
||
2. 确认 RSA2 密钥对是否匹配（私钥与公钥配对）
|
||
3. 确认异步通知 URL（notify_url）在应用白名单中
|
||
4. 确认网关地址正确：
|
||
- 沙箱：`https://openapi-sandbox.dl.alipaydev.com/gateway.do`
|
||
- 正式：`https://openapi.alipay.com/gateway.do`
|
||
5. 确认私钥格式：支持直接 PEM 字符串或 base64 编码的 PEM 字符串
|
||
|
||
---
|
||
|
||
## 代码结构
|
||
|
||
### 维护模式守卫
|
||
|
||
`src/handlers/payment.rs`:
|
||
|
||
```rust
|
||
fn check_payment_maintenance() -> Result<(), AppError> {
|
||
if std::env::var("PAYMENT_MAINTENANCE_MODE").ok() == Some("true".to_string()) {
|
||
return Err(AppError::ServiceUnavailable("支付系统维护中，请稍后再试".to_string()));
|
||
}
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
### Mock 支付守卫
|
||
|
||
```rust
|
||
fn check_mock_payment_allowed(req: &HttpRequest) -> Result<(), AppError> {
|
||
// 规则 1：有支付宝配置时永不走 Mock
|
||
if AlipayConfig::from_env().is_some() {
|
||
return Err(AppError::BadRequest("真实支付已启用，Mock 支付不可用".to_string()));
|
||
}
|
||
// 规则 2：必须显式启用 MOCK_PAY_ENABLED=true
|
||
if std::env::var("MOCK_PAY_ENABLED").ok() != Some("true".to_string()) {
|
||
return Err(AppError::Forbidden("Mock 支付未启用".to_string()));
|
||
}
|
||
// 规则 3（可选）：如果设了 MOCK_PAY_KEY，验证请求头 X-Mock-Key
|
||
Ok(())
|
||
}
|
||
```
|
||
|
||
### 错误页面渲染
|
||
|
||
`src/error.rs` 中的 `ResponseError` 实现：`ServiceUnavailable` 返回 503 HTML 错误页。
|
||
|
||
---
|
||
|
||
## 相关文件
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `/etc/systemd/system/rust-backend-green.service` | 生产活跃服务（4434） |
|
||
| `/etc/systemd/system/rust-backend-blue.service` | 生产备用服务（4433） |
|
||
| `/etc/systemd/system/rust-backend.service` | 旧版服务（3000，不处理生产流量） |
|
||
| `src/handlers/payment.rs` | 支付处理器 + 维护模式守卫 |
|
||
| `src/error.rs` | 错误处理 + 503 页面渲染 |
|