Files

erio 34ad876626 docs: 合并重复的管理后台章节，保留集成说明中的完整列表

2026-03-14 04:09:02 +08:00

19 KiB

Raw Blame History

Sub2ApiPay

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

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

功能特性

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

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

ZPay 申请二维码

技术栈

类别	技术
框架	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
# 示例：仅使用 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 实例（如与其他服务共用）：

在 .env 中填写 DATABASE_URL
使用 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 及以上版本会自动拼接以下参数，无需手动添加：

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

管理后台

管理后台通过 URL 参数 token 鉴权（值为环境变量 ADMIN_TOKEN）。在 Sub2API 中集成时只需配置路径，无需附加任何查询参数——Sub2API 会自动拼接 token 等参数：

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

提示：若独立访问（不通过 Sub2API 跳转），需手动在 URL 后添加 ?token=YOUR_ADMIN_TOKEN。管理后台所有页面间共享同一个 token，进入任一页面后可通过侧边导航切换。

支付流程

用户选择充值 / 订阅套餐
       │
       ▼
  创建订单 (PENDING)
  ├─ 校验用户状态 / 待支付订单数 / 每日限额 / 渠道限额
  └─ 调用支付提供商获取支付链接
       │
       ▼
  用户完成支付
  ├─ EasyPay   → 扫码 / H5 跳转
  ├─ 支付宝官方 → PC 页面支付 / H5 手机网站支付
  ├─ 微信官方   → Native 扫码 / 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

19 KiB Raw Blame History Unescape Escape