docs: README重构 — EasyPay前置、支付宝/微信改称官方、集成说明增加管理后台端点

- GitHub About 双语描述 - "Stripe 国际信用卡" → "Stripe" - EasyPay 放在支付服务商最前面 - "支付宝直连" → "支付宝官方"、"微信支付直连" → "微信官方" - 集成到 Sub2API 章节重写：用户端页面 + 管理后台端点完整列表 - 管理后台集成无需带 query 参数 - "使用第三方聚合支付时" → "使用第三方平台时" - 中英文 README 同步更新
2026-03-14 03:53:20 +08:00
parent 886389939e
commit 6d01fcb822
2 changed files with 220 additions and 95 deletions
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@

 **语言 / Language**: 中文（当前）｜ [English](./README.en.md)

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

 ---

@@ -23,7 +23,7 @@ Sub2ApiPay 是为 [Sub2API](https://sub2api.com) 平台构建的自托管支付

 ## 功能特性

- **四渠道支付** — 支付宝官方直连、微信支付官方直连、EasyPay 易支付聚合、Stripe 国际信用卡
+- **四渠道支付** — EasyPay 易支付聚合、支付宝官方、微信官方、Stripe
 - **双计费模式** — 按量余额充值 + 套餐订阅，灵活适配不同业务场景
 - **自动到账** — 支付回调验签后自动调用 Sub2API 充值 / 订阅接口，全程无需人工
 - **订单全生命周期** — 超时自动取消、用户主动取消、管理员取消、退款
@@ -103,40 +103,13 @@ docker compose up -d --build

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

-> **支付宝直连 / 微信支付直连**与**EasyPay**可以共存。直连渠道直接对接官方 API，资金直达商户账户，手续费更低；EasyPay 通过第三方聚合平台代收，接入门槛更低。使用 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** 可以共存。官方渠道直接对接支付宝/微信 API，资金直达商户账户，手续费更低；EasyPay 通过第三方聚合平台代收，接入门槛更低。使用 EasyPay 时请尽量选择资金直接走支付宝/微信官方渠道，而非第三方代收的、不经过第三方中转的服务商。

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

@@ -151,7 +124,7 @@ PAYMENT_PROVIDERS=easypay

 > **注意**：支付渠道的安全性、稳定性及合规性请自行鉴别，本项目不对任何第三方支付服务商做担保或背书。
 >
-> **⚠️ 安全提示**：使用第三方聚合支付时，请尽量选择**资金直接走支付宝/微信官方渠道，而非第三方代收**的服务商，避免资金被卷款跑路。
+> **⚠️ 安全提示**：使用第三方平台时，请尽量选择**资金直接走支付宝/微信官方渠道，而非第三方代收**的服务商，避免资金被卷款跑路。

 | 变量                  | 说明                                                          |
 | --------------------- | ------------------------------------------------------------- |
@@ -163,6 +136,33 @@ PAYMENT_PROVIDERS=easypay
 | `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

 | 变量                     | 说明                                   |
@@ -182,7 +182,7 @@ PAYMENT_PROVIDERS=easypay
 | `MAX_RECHARGE_AMOUNT`            | 单笔最高充值金额（元）                   | `1000`                     |
 | `MAX_DAILY_RECHARGE_AMOUNT`      | 每日每用户累计最高充值（元，`0` = 不限） | `10000`                    |
 | `MAX_DAILY_AMOUNT_ALIPAY`        | 易支付支付宝渠道每日全局限额（可选）     | 由提供商默认               |
-| `MAX_DAILY_AMOUNT_ALIPAY_DIRECT` | 支付宝直连渠道每日全局限额（可选）       | 由提供商默认               |
+| `MAX_DAILY_AMOUNT_ALIPAY_DIRECT` | 支付宝官方渠道每日全局限额（可选）       | 由提供商默认               |
 | `MAX_DAILY_AMOUNT_WXPAY`         | 微信支付渠道每日全局限额（可选）         | 由提供商默认               |
 | `MAX_DAILY_AMOUNT_STRIPE`        | Stripe 渠道每日全局限额（可选）          | 由提供商默认               |
 | `ORDER_TIMEOUT_MINUTES`          | 订单超时分钟数                           | `5`                        |
@@ -295,13 +295,16 @@ docker compose exec app npx prisma migrate deploy

 ## 集成到 Sub2API

-在 Sub2API 管理后台可配置以下页面链接：
+假设本服务部署在 `https://pay.example.com`。

-| 页面     | 链接                                 | 说明                     |
-| -------- | ------------------------------------ | ------------------------ |
-| 充值页面 | `https://pay.example.com/pay`        | 用户充值入口             |
-| 我的订单 | `https://pay.example.com/pay/orders` | 用户查看自己的充值记录   |
-| 管理后台 | `https://pay.example.com/admin`      | 管理后台入口（仅管理员） |
+### 用户端页面
+
+在 Sub2API 管理后台的**充值设置**中配置以下链接，用户即可从 Sub2API 平台跳转到充值和订单页面：
+
+| 配置项   | URL                                  | 说明                        |
+| -------- | ------------------------------------ | --------------------------- |
+| 充值页面 | `https://pay.example.com/pay`        | 用户充值、购买订阅套餐入口  |
+| 我的订单 | `https://pay.example.com/pay/orders` | 用户查看自己的充值/订阅记录 |

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

@@ -313,6 +316,20 @@ Sub2API **v0.1.88** 及以上版本会自动拼接以下参数，无需手动添
 | `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，进入任一页面后可通过侧边导航切换。
+
 ---

 ## 管理后台
@@ -341,9 +358,9 @@ Sub2API **v0.1.88** 及以上版本会自动拼接以下参数，无需手动添
       │
       ▼
  用户完成支付
-  ├─ 支付宝直连 → PC 页面支付 / H5 手机网站支付
-  ├─ 微信直连   → Native 扫码 / H5 支付
  ├─ EasyPay   → 扫码 / H5 跳转
+  ├─ 支付宝官方 → PC 页面支付 / H5 手机网站支付
+  ├─ 微信官方   → Native 扫码 / H5 支付
  └─ Stripe    → Payment Element (PaymentIntent)
       │
       ▼
@@ -382,12 +399,12 @@ Sub2API **v0.1.88** 及以上版本会自动拼接以下参数，无需手动添

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

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

 ### 管理 API