asd-backend/docs/MAINTENANCE-MODE-RUNBOOK.md

支付维护模式 Runbook

当支付宝支付失效时的应急操作手册。涵盖开启/关闭维护模式、切换到 Mock 支付、修复支付宝配置三种方案。

---

快速判断

症状	应急方案
支付宝正在维护/报错，需要临时止血	维护模式（方案 A）
只是测试环境或无所谓真实收款	Mock 支付（方案 B）
配置变更导致的问题（密钥过期、域名变更）	修复支付宝配置（方案 C）

---

方案 A：开启维护模式（止血）

所有支付接口返回 503 "支付系统维护中，请稍后再试"。

前置条件

SSH 免密码登录到 root@1panel-server。

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

操作步骤

# 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 中显示"支付系统维护中"

恢复

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）。

操作步骤

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. 登录 支付宝开放平台 检查应用状态
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:

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 支付守卫

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 页面渲染