自建收款回调系统 V免签 VMQFox 部署教程：个人微信/支付宝收款秒回调
适用版本：VMQFox Backend 2.3.5（2026-08 核对）
这是什么
VMQFox 是一个自建收款回调系统：监听手机上的微信/支付宝收款通知，自动匹配订单并回调你的网站。适合个人、自用、测试场景。
注意：它不是微信/支付宝官方商户接口，不适合多商户生产环境。
工作原理
你的网站创建订单 → VMQFox 分配收款码 → 用户扫码付款
→ 手机收到收款通知 → 监控端推送到 VMQFox
→ 匹配订单 → 回调 notifyUrl / 跳转 returnUrl环境要求
| 组件 | 要求 |
|---|---|
| PHP | ≥ 8.2（需 bcmath、curl、pdo_mysql、mbstring，允许 proc_open） |
| 数据库 | MySQL 5.7+ |
| 识别工具 | zbarimg、OpenCV、ZXing-C++、Tesseract（Docker 镜像已内置） |
| 内存 | 建议 ≥ 4GB（与宝塔共存时） |
一键部署（Docker Compose）
git clone https://github.com/LeoChen-CoreMind/vmqfox-backend.git
cd vmqfox-backend
cp .env.docker.example .env.docker编辑 .env.docker，修改以下 4 个值（全部用随机值）：
ADMIN_USERNAME=你的管理员账号
ADMIN_PASSWORD=你的长随机密码
VMQ_DB_PASSWORD=数据库密码
VMQ_DB_ROOT_PASSWORD=数据库root密码启动：
docker compose --env-file .env.docker config # 检查配置
docker compose --env-file .env.docker up -d --build
访问：
- 前端/后台：
http://服务器IP:3006 - 后端 API：
http://服务器IP:8000
首次启动自动初始化管理员账号，无默认 admin/admin。
宝塔部署要点
- 运行目录指向
public/（不是项目根目录）。 - 伪静态选 ThinkPHP。
- 必须移除 PHP 禁用函数中的
proc_open并重启 PHP-FPM，否则二维码识别全部显示"未检测到"。 - 执行
composer install --no-dev --optimize-autoloader后访问/install/完成网页安装。 - 生成
runtime/install.lock后无法重复安装。
二维码使用
- 后台上传微信/支付宝收款码，自动识别金额和内容（可手动修改）。
- 每次最多 20 张，同金额冲突可选择替换/逐个确认/放弃。
- 提高识别率：上传原图、保留四周白边、避免压缩和反光。
监控端（二选一，不能同时开）
方案 A：APK 监控端（普通设备）
安装旧版 VmqApk，授予通知监听权限，加入省电白名单。
方案 B：KernelSU 模块（推荐）
适用：arm64-v8a + Android 15（API 35）+ KernelSU。
- 从下方下载地址获取
vmq-ksu-v1.0.0-arm64-api35.zip和同名.sha256文件。 - 校验 SHA256 一致后，在 KernelSU 管理器选择"从本地安装"，刷入并重启设备。
- 打开模块 WebUI，填写服务地址和通信密钥，开启监听。
KSU 模块和 APK 不能同时运行，否则同一笔收款会被重复推送。
对接你的网站
- 新版接口：
POST /api/order/create创建订单，完整文档见部署后的/api.html。 - 旧版接口兼容：
/createOrder、/getOrder、/checkOrder。 - 回调验签需要
VMQFOX_COMMUNICATION_KEY，其值必须与后台通讯密钥一致。
常见问题
Q：装了 zbarimg 仍显示"未检测到"？
A：宝塔禁用函数里移除 proc_open 并重启 PHP-FPM。
Q：提示 bcmul 未定义？
A：安装 PHP BCMath 扩展并重启 PHP-FPM。
Q：微信码识别失败？
A：换原图上传，保证白边完整；识别失败可手动填金额。
Q：收款后没回调？
A：检查监控端心跳、通知权限、通信密钥是否一致。
安全建议
- 随机管理员账号 + 长随机密码
- 数据库用最小权限专用账号
- 生产环境关闭 DEBUG，全程 HTTPS
- MySQL/Redis 不暴露公网端口
- 定期备份数据库和二维码配置
下载地址
- 后端源码：
- KSU 监控模块（最新版）：
- 前端源码：https://github.com/hulisang/vmqfox-frontend
- 旧版监控 APK：https://github.com/szvone/VmqApk
