# Zibll VMQFox Bridge 插件使用说明

> 子比主题无缝对接 VMQFox（V免签二开版）支付网关，无需修改主题任何文件。

—

## 一、插件简介

Zibll VMQFox Bridge 是一个专为子比主题用户设计的桥接插件，用于将 VMQFox（V免签二开版）支付网关接入子比主题的支付系统。

### 核心特性

– 兼容 VMQFox Go v2 协议，支持微信、支付宝
– 无需修改子比主题文件，升级主题不影响
– 独立对账表，订单数据可追溯
– 支持金额校验、签名验证、防重放
– 使用 REST API 回调，绕过主题对 admin-post.php 的登录拦截
– 支持并发锁，防止重复下单

### 适用场景

– 子比主题 + VMQFox 搭建的虚拟商品/资源站
– 原版 V免签用户想切换到 VMQFox 二开版
– 需要稳定、可维护的支付对接方案

—

## 二、环境要求

| 项目 | 要求 |
|—|—|
| 子比主题 | 任意版本（支付模块需完整） |
| PHP | 7.4 及以上 |
| WordPress | 5.0 及以上 |
| VMQFox 后端 | Go v2 协议，支持 /api/order/create 接口 |
| 站点协议 | 必须 HTTPS（插件会校验） |
| 固定链接 | 建议使用非朴素模式，例如 /%post_id%.html |

—

## 三、安装步骤

### 1. 安装插件

将 zibll-vmqfox-bridge 文件夹上传到：

/wp-content/plugins/zibll-vmqfox-bridge/

确保主文件名为 zibll-vmqfox-bridge.php，然后在 WordPress 后台“插件”页面启用。

启用时插件会自动创建对账表 wp_zvfb_orders，如果创建失败会提示“无法创建 VMQFox 对账表”，此时需要检查数据库用户是否有建表权限。

### 2. 配置子比主题支付通道

进入“子比主题设置 → 支付设置”，找到“V免签（vmqphp）”通道，填写：

| 配置项 | 填写内容 |
|—|—|
| 网关地址（apiurl） | 你的 VMQFox 后端地址，例如 https://vmq.fpser.com |
| 通讯密钥（key） | VMQFox 后台的通讯密钥 |

注意：网关地址必须是 HTTPS，插件会做协议校验，HTTP 地址会被拒绝。

### 3. 配置 VMQFox 后台

VMQFox 后台无需修改全局 notifyUrl 配置，因为：

– 每笔订单的 notifyUrl 由插件在建单时通过 API 参数传入
– VMQFox 会把 notifyUrl 按订单独立存储
– 所以支持一个 VMQFox 对接多个站点

你只需要确认：

– VMQFox 的通讯密钥与子比主题里填的一致
– VMQFox 的建单接口 /api/order/create 可正常访问

### 4. 验证配置

在子比前台用微信或支付宝下一笔 0.01 元的测试订单，观察：

– 是否弹出支付二维码
– 支付成功后，子比后台订单状态是否变为“已支付”
– VMQFox 后台该订单的 state 是否变为 1 或 2

—

## 四、工作原理

用户在子比下单
↓
子比调用 vmqphp 通道
↓
插件 route() 把通道改成 zvfb_v2
↓
插件 create() 向 VMQFox 建单
传入 notifyUrl = /wp-json/zvfb/v1/notify
↓
VMQFox 生成支付二维码
↓
用户扫码付款
↓
VMQFox 监控端识别收款
↓
VMQFox 回调 notifyUrl（REST API）
↓
插件 verified() 验签
↓
插件 settle() 对账 + 调用 ZibPay::payment_order()
↓
子比订单状态更新为已支付

### 为什么用 REST API 而不是 admin-post.php

子比主题的 zib_no_entry_backstage 函数会挂在 admin_init 上，把未登录的 admin-post.php 请求 302 重定向到首页，导致 VMQFox 的回调请求被拦截。

REST API 走的是 rest_api_init 钩子，不经过 admin_init，因此不受主题这个限制影响，是最干净的解决方案。

—

## 五、数据表说明

插件启用时会自动创建对账表 wp_zvfb_orders：

| 字段 | 说明 |
|—|—|
| id | 自增主键 |
| order_hash | 订单号的 SHA256，用于索引 |
| pay_id | VMQFox 返回的支付 ID（520 前缀） |
| method | 支付方式：wechat / alipay |
| price | 订单原始金额 |
| local_price | 站点本地金额 |
| really_price | 实际支付金额（含金额浮动） |
| param | 支付方式 \| 跳转 URL |
| redirect_url | VMQFox 支付页地址 |
| done | 是否已完成对账：0 未完成 / 1 已完成 |
| created_at | 创建时间（UTC） |

排查订单问题时，可以直接查这张表：

SELECT * FROM wp_zvfb_orders ORDER BY id DESC LIMIT 10;

—

## 六、常见问题排查

### 问题 1：支付成功后，子比订单状态仍是“未支付”

排查顺序：

1. 检查对账表最新记录的 done 字段
– done = 1：对账成功，问题在子比订单状态更新环节
– done = 0：对账失败，继续看第 2 步

2. 检查 VMQFox 订单表的 notify_url 字段

登录 VMQFox 数据库执行：

USE vmqfox;
SELECT id, pay_id, notify_url, state FROM orders ORDER BY id DESC LIMIT 5;

– 如果 notify_url 是 https://你的域名/wp-json/zvfb/v1/notify：地址正确
– 如果还是 admin-post.php?action=zvfb_notify：插件代码没生效，检查 OPcache 或 Redis 缓存

3. 检查 VMQFox 的 state 字段
– state = 0：监控端没识别到收款，检查安卓监控端 App
– state = 1 或 2：已收款，问题在回调环节

### 问题 2：VMQFox 后台显示“通知失败”

常见原因：

– 回调地址被防火墙、WAF 或 CDN 拦截
– 站点不是 HTTPS
– 主题或安全插件拦截了 admin-post.php（本插件已通过 REST API 规避）
– 签名算法不匹配（确认插件和 VMQFox 用同一密钥）

### 问题 3：请求返回 302 重定向

说明请求被主题或插件重定向了。本插件已改用 REST API，正常情况下不会再出现 302。如果仍有 302，检查：

– 是否有其他安全插件拦截 /wp-json/
– Nginx 伪静态规则是否完整，例如 try_files $uri $uri/ /index.php?$args;

### 问题 4：请求返回 404

– Nginx 直接返回 404：伪静态规则缺失，检查 Nginx 配置
– WordPress 返回 404：REST 路由未注册，检查插件是否启用

—

## 七、注意事项

### 1. 密钥安全

插件使用的通讯密钥与 VMQFox 后台一致。请勿把密钥泄露到公开场合，包括论坛帖子、截图、日志文件。如果怀疑泄露，立即在 VMQFox 后台更换密钥，并同步更新子比主题配置。

### 2. 订单号规则

– 子比订单表的 order_num 是原始订单号（2610 前缀）
– VMQFox 的 pay_id 是支付通道订单号（520 前缀）
– 插件会以 520 前缀的 pay_id 作为对账主键，这是正常设计，不要混淆

### 3. 金额浮动

VMQFox 支持金额浮动（同一金额的订单会被分配不同尾数），插件会把：

– price：站点原始金额
– really_price：实际支付金额（含浮动尾数）

对账时以 really_price 为准，对账成功后回传给子比的仍是 local_price（站点原始金额），保证订单金额一致。

### 4. 插件更新

– 本插件不依赖主题文件，子比主题升级不影响
– 升级子比主题后，建议重新下一次测试订单验证
– 升级前建议备份 zibll-vmqfox-bridge.php

### 5. 旧订单处理

插件改动前已经创建、notify_url 仍是 admin-post.php 的旧订单：

– VMQFox 不会再重试成功
– 如果用户已付款但子比订单状态未更新，需要手动把子比订单状态改为已支付
– 建议用户重新下单

—

## 八、技术支持

如果遇到问题，可以在帖子下方回复，附上以下信息以便快速定位：

1. 子比订单号（order_num）
2. VMQFox 订单号（pay_id）
3. 对账表记录（wp_zvfb_orders 中对应的行）
4. VMQFox 订单记录（vmqfox.orders 中对应的行）
5. 错误现象（截图或文字描述）
6. Nginx / PHP 错误日志（如有）

请勿在公开场合贴出通讯密钥、完整支付链接或包含敏感信息的日志。

—

## 九、插件下载

插件打包命令（在子比服务器上执行）：

cd /www/wwwroot/www.fpser.com/wp-content/plugins/
tar -czf /root/zibll-vmqfox-bridge-v1.0.0.tar.gz zibll-vmqfox-bridge/

打包完成后，用 SFTP 工具（WinSCP / FileZilla）从服务器下载：

/root/zibll-vmqfox-bridge-v1.0.0.tar.gz

—

## 十、更新日志

### v1.0.0

– 初始版本
– 支持 VMQFox Go v2 协议
– 支持微信、支付宝
– 支持 REST API 回调，绕过子比主题 admin-post.php 拦截
– 支持金额校验、签名验证、防重放
– 支持并发锁
– 修复：主题 admin_init 拦截导致回调 302 的问题
– 修复：旧订单使用 admin-post.php 回调地址的问题

—

祝使用愉快！如果这个插件帮你解决了问题，欢迎在帖子下方点个赞，让更多遇到同样问题的站长看到。