Sub2ApiPay

语言 / Language: 中文（当前）｜ English

Sub2ApiPay 是为 Sub2API 平台构建的自托管支付网关。支持 EasyPay 易支付聚合、支付宝官方、微信官方和 Stripe 四种支付渠道，提供按量充值与套餐订阅两种计费模式，支付成功后自动调用 Sub2API 管理接口完成到账，无需人工干预。

---

目录

• 功能特性
• 技术栈
• 快速开始
• 环境变量
• 部署指南
• 集成到 Sub2API
• 支付流程
• API 端点
• 开发指南

---

功能特性

• 四渠道支付 — EasyPay 易支付聚合、支付宝官方、微信官方、Stripe
• 在线配置 — 支付服务商、凭证、限额、业务参数均可在管理后台实时配置，无需重启
• 多实例负载均衡 — 同一服务商支持多实例，按轮询或最小金额策略分流，支持单笔/日限额
• 双计费模式 — 按量余额充值 + 套餐订阅，灵活适配不同业务场景
• 自动到账 — 支付回调验签后自动调用 Sub2API 充值 / 订阅接口，全程无需人工
• 订单全生命周期 — 超时自动取消、用户主动取消、管理员取消、退款
• 限额控制 — 单笔上限、每日用户累计上限、每日渠道全局限额，多维度风控
• 安全设计 — Token 鉴权、RSA2 / MD5 / Webhook 签名验证、时序安全对比、完整审计日志
• 响应式 UI — PC + 移动端自适应，暗色 / 亮色主题，支持 iframe 嵌入
• 中英双语 — 支付页面自动适配中英文
• 管理后台 — 数据概览、订单管理（分页/筛选/重试/退款）、渠道管理、订阅管理

EasyPay 推荐：个人推荐 ZPay（https://z-pay.cn/?uid=23808）作为 EasyPay 服务商（链接含作者邀请码，介意可去掉）。ZPay 支持个人用户（无营业执照）每日 1 万元以内交易；拥有营业执照则无限额。支付渠道的安全性、稳定性及合规性请自行鉴别，本项目不对任何第三方支付服务商做担保或背书。

<details> <summary>ZPay 申请二维码</summary>

</details>

---

技术栈

| 类别 | 技术 | | ------ | --------------------------- | | 框架 | Next.js 16 (App Router) | | 语言 | TypeScript 5 + React 19 | | 样式 | TailwindCSS 4 | | ORM | Prisma 7（adapter-pg 模式） | | 数据库 | PostgreSQL 16 | | 容器 | Docker + Docker Compose | | 包管理 | pnpm |

---

快速开始

使用 Docker Hub 镜像（推荐）

无需本地安装 Node.js 或 pnpm，服务器上只需 Docker。

mkdir -p /opt/sub2apipay && cd /opt/sub2apipay

# 下载 Compose 文件和环境变量模板
curl -O https://raw.githubusercontent.com/touwaeriol/sub2apipay/main/docker-compose.hub.yml
curl -O https://raw.githubusercontent.com/touwaeriol/sub2apipay/main/.env.example
cp .env.example .env

# 填写必填环境变量
nano .env

# 启动（含自带 PostgreSQL）
docker compose -f docker-compose.hub.yml up -d

从源码构建

git clone https://github.com/touwaeriol/sub2apipay.git
cd sub2apipay
cp .env.example .env
nano .env
docker compose up -d --build

---

环境变量

完整模板见 .env.example。

核心（必填）

| 变量 | 说明 | | ----------------------- | ---------------------------------------------- | | SUB2API_BASE_URL | Sub2API 服务地址，如 https://sub2api.com | | SUB2API_ADMIN_API_KEY | Sub2API 管理 API 密钥 | | ADMIN_TOKEN | 管理后台访问令牌（自定义强密码） | | NEXT_PUBLIC_APP_URL | 本服务的公网地址，如 https://pay.example.com |

DATABASE_URL 使用自带数据库时由 Compose 自动注入，无需手动填写。

支付服务商与支付方式

支付服务商和支付参数支持两种配置方式，任选其一即可：

方式一：通过管理后台在线配置（推荐）

在管理后台的 支付配置 页面（/admin/payment-config）中，可以直接在界面上完成所有支付相关配置，无需修改环境变量或重启服务：

• 覆盖环境变量 — 开启后，数据库配置将覆盖环境变量。首次开启时会自动从环境变量导入现有配置
• 服务商管理 — 添加 / 编辑 / 删除支付实例，配置凭证、启用状态、渠道、负载均衡策略
• 多实例支持 — 同一服务商可创建多个实例，配合轮询或最小金额策略实现负载均衡
• 实例限额 — 每个实例可独立配置每个渠道的单笔最小 / 单笔最大 / 每日总限额
• 业务参数 — 充值金额范围、每日限额、订单超时、取消频率限制等均可在线调整

提示：通过管理后台修改的配置即时生效，无需重启容器。支付配置页面入口：Sub2API 管理后台 → 支付配置，或直接访问 https://pay.example.com/admin/payment-config?token=YOUR_ADMIN_TOKEN。

方式二：通过环境变量配置

适用于首次部署或偏好配置文件管理的场景。环境变量配置的值会作为默认值，可随时在管理后台覆盖。

第一步：通过 PAYMENT_PROVIDERS 声明启用哪些支付服务商（逗号分隔）：

# 可选值: easypay, alipay, wxpay, stripe
# 示例：仅使用 EasyPay 易支付聚合
PAYMENT_PROVIDERS=easypay
# 示例：同时启用支付宝官方 + 微信官方 + Stripe
PAYMENT_PROVIDERS=alipay,wxpay,stripe

支付宝官方 / 微信官方与 EasyPay 可以共存。官方渠道直接对接支付宝/微信 API，资金直达商户账户，手续费更低；EasyPay 通过第三方平台代收/转发官方，接入门槛更低。使用 EasyPay 时请尽量选择资金直接走转发官方直达自己账户的形式，而非第三方代收的服务商。

EasyPay（支付宝 / 微信支付聚合）

任何兼容易支付（EasyPay）协议的支付服务商均可接入。

| 变量 | 说明 | | --------------------- | ------------------------------------------------------------- | | EASY_PAY_PID | EasyPay 商户 ID | | EASY_PAY_PKEY | EasyPay 商户密钥 | | EASY_PAY_API_BASE | EasyPay API 地址 | | EASY_PAY_NOTIFY_URL | 异步回调地址，填 ${NEXT_PUBLIC_APP_URL}/api/easy-pay/notify | | EASY_PAY_RETURN_URL | 支付完成跳转地址，填 ${NEXT_PUBLIC_APP_URL}/pay/result | | EASY_PAY_CID_ALIPAY | 支付宝通道 ID（可选） | | EASY_PAY_CID_WXPAY | 微信支付通道 ID（可选） |

支付宝官方

直接对接支付宝开放平台，支持 PC 页面支付（alipay.trade.page.pay）和手机网站支付（alipay.trade.wap.pay），自动根据终端类型切换。

| 变量 | 说明 | | -------------------- | ---------------------------- | | ALIPAY_APP_ID | 支付宝应用 AppID | | ALIPAY_PRIVATE_KEY | 应用私钥（内容或文件路径） | | ALIPAY_PUBLIC_KEY | 支付宝公钥（内容或文件路径） | | ALIPAY_NOTIFY_URL | 异步回调地址 | | ALIPAY_RETURN_URL | 同步跳转地址（可选） |

微信官方

直接对接微信支付 APIv3，支持 Native 扫码支付和 H5 支付，移动端优先尝试 H5，自动 fallback 到扫码。

| 变量 | 说明 | | --------------------- | ------------------------------- | | WXPAY_APP_ID | 微信支付 AppID | | WXPAY_MCH_ID | 商户号 | | WXPAY_PRIVATE_KEY | 商户 API 私钥（内容或文件路径） | | WXPAY_CERT_SERIAL | 商户证书序列号 | | WXPAY_API_V3_KEY | APIv3 密钥 | | WXPAY_PUBLIC_KEY | 微信支付公钥（内容或文件路径） | | WXPAY_PUBLIC_KEY_ID | 微信支付公钥 ID | | WXPAY_NOTIFY_URL | 异步回调地址 |

Stripe

| 变量 | 说明 | | ------------------------ | -------------------------------------- | | STRIPE_SECRET_KEY | Stripe 密钥（sk_live_...） | | STRIPE_PUBLISHABLE_KEY | Stripe 可公开密钥（pk_live_...） | | STRIPE_WEBHOOK_SECRET | Stripe Webhook 签名密钥（whsec_...） |

Stripe Webhook 端点：${NEXT_PUBLIC_APP_URL}/api/stripe/webhook 需订阅事件：payment_intent.succeeded、payment_intent.payment_failed

业务规则

以下参数可通过环境变量设置默认值，也可在管理后台 支付配置 页面中在线修改（开启"覆盖环境变量"后生效）：

| 变量 | 说明 | 默认值 | | -------------------------------- | ---------------------------------------- | -------------------------- | | MIN_RECHARGE_AMOUNT | 单笔最低充值金额（元） | 1 | | MAX_RECHARGE_AMOUNT | 单笔最高充值金额（元） | 1000 | | MAX_DAILY_RECHARGE_AMOUNT | 每日每用户累计最高充值（元，0 = 不限） | 10000 | | MAX_DAILY_AMOUNT_ALIPAY | 易支付支付宝渠道每日全局限额（可选） | 由提供商默认 | | MAX_DAILY_AMOUNT_ALIPAY_DIRECT | 支付宝官方渠道每日全局限额（可选） | 由提供商默认 | | MAX_DAILY_AMOUNT_WXPAY | 微信支付渠道每日全局限额（可选） | 由提供商默认 | | MAX_DAILY_AMOUNT_STRIPE | Stripe 渠道每日全局限额（可选） | 由提供商默认 | | ORDER_TIMEOUT_MINUTES | 订单超时分钟数 | 5 | | PRODUCT_NAME | 充值商品名称（显示在支付页） | Sub2API Balance Recharge |

UI 定制（可选）

在充值页面右侧可展示客服联系方式、说明图片等帮助内容。

| 变量 | 说明 | | -------------------- | --------------------------------------------------------------- | | PAY_HELP_IMAGE_URL | 帮助图片地址（支持外部 URL 或本地路径，见下方说明） | | PAY_HELP_TEXT | 帮助说明文字，用 \n 换行，如 扫码加微信\n工作日 9-18 点在线 |

图片地址两种方式：

• 外部 URL（推荐，无需改 Compose 配置）：直接填图片的公网地址，如 OSS / CDN / 图床链接。

  PAY_HELP_IMAGE_URL=https://cdn.example.com/help-qr.jpg
  

• 本地文件：将图片放到 ./uploads/ 目录，通过 /uploads/文件名 引用。 需在 docker-compose.app.yml 中挂载目录（默认已包含）：

  volumes:
    - ./uploads:/app/public/uploads:ro
  

  PAY_HELP_IMAGE_URL=/uploads/help-qr.jpg
  

点击帮助图片可在屏幕中央全屏放大查看。

Docker Compose 专用

| 变量 | 说明 | 默认值 | | ------------- | ----------------------------------- | ---------------------------- | | APP_PORT | 宿主机映射端口 | 3001 | | DB_PASSWORD | PostgreSQL 密码（使用自带数据库时） | password（生产请修改） |

---

部署指南

方案一：Docker Hub 镜像 + 自带数据库

使用 docker-compose.hub.yml，最省事的部署方式：

docker compose -f docker-compose.hub.yml up -d

镜像：touwaeriol/sub2apipay:latest

方案二：Docker Hub 镜像 + 外部数据库

适用于已有 PostgreSQL 实例（如与其他服务共用）：

1. 在 .env 中填写 DATABASE_URL
2. 使用 docker-compose.app.yml（仅启动应用，不含 DB）：

docker compose -f docker-compose.app.yml up -d

方案三：从源码构建

适用于自定义修改后自行构建：

# 在构建服务器上
docker compose build
docker tag sub2apipay-app:latest touwaeriol/sub2apipay:latest
docker push touwaeriol/sub2apipay:latest

# 在部署服务器上
docker compose -f docker-compose.hub.yml pull
docker compose -f docker-compose.hub.yml up -d

端口与反向代理

默认宿主机端口为 3001（可通过 APP_PORT 修改）。建议使用 Nginx/Caddy 作反向代理并配置 HTTPS：

server {
    listen 443 ssl;
    server_name pay.example.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

数据库迁移

容器启动时自动执行 prisma migrate deploy，无需手动操作。如需手动执行：

docker compose exec app npx prisma migrate deploy

---

集成到 Sub2API

假设本服务部署在 https://pay.example.com。

用户端页面

在 Sub2API 管理后台的充值设置中配置以下链接，用户即可从 Sub2API 平台跳转到充值和订单页面：

| 配置项 | URL | 说明 | | -------- | ------------------------------------ | --------------------------- | | 充值页面 | https://pay.example.com/pay | 用户充值、购买订阅套餐入口 | | 我的订单 | https://pay.example.com/pay/orders | 用户查看自己的充值/订阅记录 |

Sub2API v0.1.88 及以上版本会自动拼接以下参数，无需手动添加：

| 参数