# Cloudreve-FoxPay

**Repository Path**: byusistudio/cloudreve-foxpay

## Basic Information

- **Project Name**: Cloudreve-FoxPay
- **Description**: byusistudio/cloudreve-foxpay
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-02
- **Last Updated**: 2026-08-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cloudreve-FoxPay

为 [Cloudreve](https://github.com/cloudreve/Cloudreve) 接入 [FoxPay](https://foxpay.top) 易支付（epay）聚合支付的中转服务。

Cloudreve 的自定义支付节点通过签名校验后向本服务发起下单 / 查单请求，本服务对接 FoxPay 完成支付，并在支付成功后异步回调 Cloudreve。

> 基于 Cloudreve 自定义支付协议（`/order` 接口 + HMAC-SHA256 签名）开发，替换原 AfdianPay 实现。

---

## 工作原理

```mermaid
sequenceDiagram
    participant CR as Cloudreve
    participant SVR as 本服务(FoxPay中转)
    participant FP as FoxPay
    CR->>SVR: POST /order (下单)
    SVR->>SVR: 生成签名URL (submit.php)
    SVR-->>CR: 返回支付跳转URL
    CR->>FP: 用户浏览器跳转至支付页面
    FP->>SVR: 异步通知 /foxpay/notify (sign + TRADE_SUCCESS)
    SVR->>SVR: 验签 + 金额校验 + 标记已支付
    SVR->>CR: GET notify_url 回调 (worker 指数退避重试)
    CR->>SVR: GET /order (查单)
    SVR-->>CR: PAID / UNPAID (本地DB, 丢通知时查FoxPay API自愈)
```

- **下单**：Cloudreve `POST /order` → 本服务组装 FoxPay 页面跳转支付 URL（`/xpay/epay/submit.php`）返回给 Cloudreve，用户浏览器跳转至 FoxPay 完成付款。
- **回调**：FoxPay 支付成功后异步通知本服务 `/foxpay/notify`，验签通过后标记订单已支付，并由后台 worker 指数退避回调 Cloudreve 的 `notify_url`。
- **查单**：Cloudreve `GET /order?order_no=` 查询订单状态。优先读本地 SQLite；本地未支付时自动调用 FoxPay 查单 API 补偿丢失的异步通知。

---

## 环境要求

- Python 3.9+（使用了 `tuple[bool, str]` 类型注解）
- 依赖见 [`src/requirements.txt`](src/requirements.txt)：

  ```text
  currencyconverter==0.18.15
  Flask==3.1.3
  gevent==25.9.1
  python-dotenv==1.2.1
  requests==2.32.5
  ```

---

## 安装

```bash
cd src
pip install -r requirements.txt
```

## 配置

编辑 [`src/.env`](src/.env)：

| 变量 | 必填 | 说明 |
|---|---|---|
| `SITE_URL` | 是 | Cloudreve 站点 URL，不带末尾斜杠，如 `https://demo.cloudreve.org` |
| `COMMUNICATION_KEY` | 是 | Cloudreve 通信密钥（与 Cloudreve 后台一致） |
| `PORT` | 是 | 本服务监听端口，默认 `35340` |
| `FOXPAY_PID` | 是 | FoxPay 商户 ID |
| `FOXPAY_KEY` | 是 | FoxPay 商户密钥（用于 MD5 签名） |
| `FOXPAY_NOTIFY_URL` | 是 | 本服务接收 FoxPay 异步通知的公网地址，如 `https://your-server/foxpay/notify` |
| `FOXPAY_API_URL` | 否 | FoxPay 接口域名，默认 `https://foxpay.top` |
| `FOXPAY_TYPE` | 否 | 支付方式：`alipay`/`wxpay`/`qqpay`/`bank`/`jdpay`/`paypal`，默认 `alipay` |
| `FOXPAY_DEVICE` | 否 | 设备类型：`pc`/`mobile`/`qq`/`wechat`/`alipay`，默认 `pc` |
| `FOXPAY_NAME` | 否 | 商品名称，默认 `VIP` |
| `FOXPAY_SITENAME` | 否 | 网站名称，留空不传 |

## 启动

```bash
cd src
python cloudreve_pay.py
```

启动后监听 `0.0.0.0:PORT`。请确保 `FOXPAY_NOTIFY_URL` 指向的公网地址能访问到本服务。

## Cloudreve 后台配置

在 Cloudreve 管理后台「支付 - 自定义支付」中：

- **网关地址**：`http(s)://<本服务地址>:<PORT>/order`
- **通信密钥**：与 `.env` 中 `COMMUNICATION_KEY` 一致
- **回调地址**：Cloudreve 会自带，无需在此配置

---

## 接口说明

| 方法 | 路径 | 说明 |
|---|---|---|
| `POST` | `/order` | Cloudreve 创建订单（HMAC-SHA256 签名校验），返回 FoxPay 支付跳转 URL |
| `GET` | `/order?order_no=` | Cloudreve 查询订单状态，返回 `{"code":0,"data":"PAID"/"UNPAID"}` |
| `GET/POST` | `/foxpay/notify` | 接收 FoxPay 支付结果异步通知，验签后返回 `success` |

### FoxPay 对接接口

| 用途 | FoxPay 接口 |
|---|---|
| 页面跳转支付（下单） | `POST /xpay/epay/submit.php` |
| 支付结果异步通知 | 回调 `/foxpay/notify`，参数含 `trade_status=TRADE_SUCCESS` |
| 查询单个订单（自愈） | `GET /xpay/epay/api.php?act=order` |

### 签名算法（MD5）

1. 过滤 `sign`、`sign_type` 和空值参数
2. 按参数名 ASCII 码升序排序
3. 拼接成 `a=b&c=d&e=f`（值不进行 URL 编码）
4. 末尾拼接商户密钥 `KEY`，做 MD5，结果为小写

```
sign = md5("a=b&c=d&e=f" + KEY)
```

---

## 数据存储

- 数据库文件：`src/foxpay.db`（SQLite，启用 WAL 模式）
- 表 `foxpay_order` 字段：`order_no`(PK)、`trade_no`、`money`、`notify_url`、`is_paid`、`notify_status`、`notify_attempts`、`notify_next_at`、`notify_last_at`、`notify_last_error`

回调 worker 重试策略：5s → 10s → 20s → 40s … 指数退避，最长 30 分钟，最多 20 次后放弃（`notify_status=3`）。

---

## 目录结构

```
Cloudreve-FoxPay/
├── README.md
└── src/
    ├── .env                # 配置文件（需自行填写）
    ├── cloudreve_pay.py    # Flask 主服务（Cloudreve 接口 + 通知路由）
    ├── foxpay.py           # FoxPay 对接（签名/下单/查单/回调worker/SQLite）
    └── requirements.txt    # Python 依赖
```

---

## 注意事项

- 金额单位：Cloudreve 传入分为单位，自动转换为元（最多两位小数）发给 FoxPay；支持非 CNY 货币经 `currencyconverter` 转换为 CNY。
- 默认最低支付金额 5 元（500 分），可在 [`cloudreve_pay.py`](src/cloudreve_pay.py) 的 `create_order` 中修改。
- `FOXPAY_NOTIFY_URL` 必须为公网可达地址，否则 FoxPay 无法回调。
- 若旧版生成过 `afdian_pay.db`，可删除（新版使用 `foxpay.db`，互不影响）。
- FoxPay 接口文档：https://foxpay.top/doc