sub2apipay/README.md

Sub2ApiPay

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

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

---

目录

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

---

功能特性

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

---

技术栈

类别	技术
框架	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 自动注入，无需手动填写。

支付服务商与支付方式

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

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

支付宝直连 / 微信支付直连与EasyPay可以共存。直连渠道直接对接官方 API，资金直达商户账户，手续费更低；EasyPay 通过第三方聚合平台代收，接入门槛更低。

支付宝直连

直接对接支付宝开放平台，支持 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	异步回调地址

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

支付提供商只需兼容易支付（EasyPay）协议即可接入，例如 ZPay（https://z-pay.cn/?uid=23808）等平台（链接含本项目作者的邀请码，介意可去掉）。

ZPay 申请二维码

注意：支付渠道的安全性、稳定性及合规性请自行鉴别，本项目不对任何第三方支付服务商做担保或背书。

变量	说明
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（可选）

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

在 Sub2API 管理后台可配置以下页面链接：

页面	链接	说明
充值页面	https://pay.example.com/pay	用户充值入口
我的订单	https://pay.example.com/pay/orders	用户查看自己的充值记录
管理后台	https://pay.example.com/admin	管理后台入口（仅管理员）

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

参数	说明
user_id	Sub2API 用户 ID
token	用户登录 Token（有 token 才能查看订单历史）
theme	light（默认）或 dark
lang	界面语言，zh（默认）或 en
ui_mode	standalone（默认）或 embedded（iframe 嵌入）

---

管理后台

访问：https://pay.example.com/admin?token=YOUR_ADMIN_TOKEN

模块	路径	说明
总览	/admin	聚合入口，卡片式导航到各管理模块
订单管理	/admin/orders	按状态筛选、分页浏览、订单详情、重试/取消/退款
数据概览	/admin/dashboard	收入统计、订单趋势、支付方式分布
渠道管理	/admin/channels	配置 API 渠道与倍率，支持从 Sub2API 同步
订阅管理	/admin/subscriptions	管理订阅套餐与用户订阅

---

支付流程

用户选择充值 / 订阅套餐
       │
       ▼
  创建订单 (PENDING)
  ├─ 校验用户状态 / 待支付订单数 / 每日限额 / 渠道限额
  └─ 调用支付提供商获取支付链接
       │
       ▼
  用户完成支付
  ├─ 支付宝直连 → PC 页面支付 / H5 手机网站支付
  ├─ 微信直连   → Native 扫码 / H5 支付
  ├─ EasyPay   → 扫码 / H5 跳转
  └─ Stripe    → Payment Element (PaymentIntent)
       │
       ▼
  支付回调（RSA2 / MD5 / Webhook 签名验证）→ 订单 PAID
       │
       ▼
  自动调用 Sub2API 充值 / 订阅接口
  ├─ 成功 → COMPLETED，余额到账 / 订阅生效
  └─ 失败 → FAILED（管理员可重试）

---

API 端点

所有 API 路径前缀为 /api。

公开 API

用户侧接口，通过 URL 参数 user_id + token 鉴权。

方法	路径	说明
GET	/api/user	获取当前用户信息
GET	/api/users/:id	获取指定用户信息
POST	/api/orders	创建充值 / 订阅订单
GET	/api/orders/:id	查询订单详情
POST	/api/orders/:id/cancel	用户取消待支付订单
GET	/api/orders/my	查询当前用户的订单列表
GET	/api/channels	获取渠道列表（前端展示用）
GET	/api/subscription-plans	获取在售订阅套餐列表
GET	/api/subscriptions/my	查询当前用户的订阅状态
GET	/api/limits	查询充值限额与支付方式可用状态

支付回调

由支付服务商异步调用，签名验证后触发到账流程。

方法	路径	说明
GET	/api/easy-pay/notify	EasyPay 异步回调（GET 方式）
POST	/api/alipay/notify	支付宝直连异步回调
POST	/api/wxpay/notify	微信支付直连异步回调
POST	/api/stripe/webhook	Stripe Webhook 回调

管理 API

需通过 token 参数传递 ADMIN_TOKEN 鉴权。

方法	路径	说明
GET	/api/admin/orders	订单列表（分页、状态筛选）
GET	/api/admin/orders/:id	订单详情（含审计日志）
POST	/api/admin/orders/:id/cancel	管理员取消订单
POST	/api/admin/orders/:id/retry	重试失败的充值 / 订阅
POST	/api/admin/refund	发起退款
GET	/api/admin/dashboard	数据概览（收入统计、趋势）
GET	/api/admin/channels	渠道列表
POST	/api/admin/channels	创建渠道
PUT	/api/admin/channels/:id	更新渠道
DELETE	/api/admin/channels/:id	删除渠道
GET	/api/admin/subscription-plans	订阅套餐列表
POST	/api/admin/subscription-plans	创建订阅套餐
PUT	/api/admin/subscription-plans/:id	更新订阅套餐
DELETE	/api/admin/subscription-plans/:id	删除订阅套餐
GET	/api/admin/subscriptions	用户订阅记录列表
GET	/api/admin/config	获取系统配置
PUT	/api/admin/config	更新系统配置
GET	/api/admin/sub2api/groups	从 Sub2API 同步渠道分组
GET	/api/admin/sub2api/search-users	搜索 Sub2API 用户

---

开发指南

环境要求

• Node.js 22+
• pnpm
• PostgreSQL 16+

本地启动

pnpm install
cp .env.example .env
# 编辑 .env，填写 DATABASE_URL 和其他必填项
pnpm prisma migrate dev
pnpm dev

常用命令

pnpm dev                      # 开发服务器（热重载）
pnpm build                    # 生产构建
pnpm test                     # 运行测试
pnpm typecheck                # TypeScript 类型检查
pnpm lint                     # ESLint 代码检查
pnpm format                   # Prettier 格式化

pnpm prisma generate          # 生成 Prisma 客户端
pnpm prisma migrate dev       # 创建迁移（开发）
pnpm prisma migrate deploy    # 应用迁移（生产）
pnpm prisma studio            # 可视化数据库管理

---

License

MIT