# 支付维护模式 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 页面渲染 |