84 行
2.6 KiB
Markdown
84 行
2.6 KiB
Markdown
# Capay 一站式加密货币支付平台（自托管模板）
|
||
|
||
本仓库提供：
|
||
- 统一商户开通（简单 Merchant API）
|
||
- x402 Facilitator（EVM/Solana）配置模板
|
||
- BTCPay / Keagate 对接占位
|
||
- Webhook 聚合 `/payments/webhook`
|
||
- 低开销交易跟踪（免费套餐默认低频轮询）
|
||
- Nginx 反向代理与 HTTPS（Let's Encrypt）示例
|
||
|
||
## 目录结构
|
||
```
|
||
app/ # 统一业务 API
|
||
infra/nginx/sites-enabled/ # Nginx 配置
|
||
infra/docker/ # BTCPay/Keagate 占位
|
||
x402/facilitator/ # x402 配置模板
|
||
```
|
||
|
||
## 快速开始（App）
|
||
```bash
|
||
cd app
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
服务默认监听 `:3001`（可在 `app/.env` 修改）。
|
||
|
||
### 免费套餐低频监控
|
||
在 `app/.env` 中已设置：
|
||
- `TX_POLL_INTERVAL_MS=180000`（3 分钟）
|
||
- `MAX_TX_CHECK_PER_CYCLE=20`
|
||
- `MIN_CONFIRMATIONS=1`
|
||
|
||
交易跟踪采用“待确认 tx 列表 + 轮询 receipt”的低开销方式。
|
||
支持多个 Alchemy 免费 key：使用 `ALCHEMY_API_KEYS=key1,key2`，系统会按轮询周期进行轮转调用，降低单 key 的频率。
|
||
|
||
## API 说明（简化版）
|
||
### 1) 开通商户
|
||
`POST /merchants`
|
||
```json
|
||
{ "name": "Acme", "email": "ops@acme.com", "webhookUrl": "https://merchant.example.com/webhook" }
|
||
```
|
||
返回：`merchantId`、`apiKey`、`webhookSecret`
|
||
|
||
### 2) 创建订单
|
||
`POST /payments/orders`
|
||
Headers: `x-merchant-id`, `x-api-key`
|
||
```json
|
||
{ "amount": "9.99", "currency": "USD", "network": "evm:ethereum", "asset": "USDC", "description": "API Access" }
|
||
```
|
||
返回：订单信息与 `paymentRequirementsBase64`。
|
||
|
||
### 3) 追踪链上交易（低开销）
|
||
`POST /payments/track`
|
||
Headers: `x-merchant-id`, `x-api-key`
|
||
```json
|
||
{ "orderId": "ORD123", "txHash": "0x...", "network": "evm:ethereum" }
|
||
```
|
||
|
||
### 4) Webhook 聚合入口
|
||
`POST /payments/webhook`
|
||
- `X-Source: keagate | btcpay | x402`
|
||
- Keagate 校验：`x-keagate-sig`（sha512 HMAC）
|
||
- BTCPay 校验：`btcpay-sig`（sha256 HMAC）
|
||
- x402 校验：`x402-sig`（sha256 HMAC）
|
||
|
||
## Nginx + HTTPS（免费）
|
||
配置在：`infra/nginx/sites-enabled/capay.conf`
|
||
|
||
证书建议使用 certbot（Let’s Encrypt）：
|
||
```bash
|
||
apt-get update && apt-get install -y certbot python3-certbot-nginx
|
||
certbot --nginx -d capay.hao.work -d pay.capay.hao.work -d btc.capay.hao.work -d doge.capay.hao.work
|
||
```
|
||
|
||
## x402 Facilitator
|
||
配置文件在：`x402/facilitator/`，已绑定 `pay.capay.hao.work`，并写入 Alchemy ETH RPC。
|
||
|
||
## 生产建议
|
||
- 把 `.env` 中的密钥替换为强随机值
|
||
- 生产环境建议使用数据库（PostgreSQL/MySQL）替换本地 JSON
|
||
- 重要订单建议提高 `MIN_CONFIRMATIONS`
|
||
- Webhook 需做好幂等与重试
|