💰【PluginTools&PluginPayment】Halo 木因（@Lywq）插件踩坑实操手册
适用对象：
木因授权中心 https://auth.muyin.site/下的两款 Halo 插件
PluginTools（Tools 工具箱） — 文章付费阅读 / 限制阅读
PluginPayment（支付插件） — 支付能力（易支付 / 支付宝 / 微信等）
本文档基于真实踩坑整理，重点关注配置中容易报错的地方。按「现象 → 根因 → 解决」组织，可直接当排查手册查用。
〇、先说清两款插件的关系与整体依赖链
付费阅读功能是「Tools 工具箱」和「支付插件」配合完成的：
文章设置（限制阅读方式=付费访问）
│
▼
Tools 工具箱（限制阅读节点 + 付费弹窗）
│ 调用
▼
支付插件（易支付 / 支付宝官方 / 微信）
│ 依赖
▼
① 插件授权（auth.mayin.site 在线/离线）
② Halo 外部访问地址（external-url）
③ 支付回调域名（公网可访问）
这条链上任何一环断了，付费阅读就跑不通。 所以下面按依赖顺序排查。
一、授权环节（两个插件都会遇到）
坑 1：明明建了授权，却报「未查询到授权信息」
报错特征：
PluginAuthManager$AuthException: 插件【PluginTools-2.3.2】未查询到授权信息！授权域名：192.168.5.178:8081
根因： 授权校验用的域名，不是浏览器地址栏的域名，而是 Halo 的「外部访问地址（external-url）」。你建授权时绑定的域名和它不一致，就查不到授权。
解决：
建授权时，授权域名要和 Halo 外部访问地址完全一致（含协议、不含端口）
要么改 Halo 外部访问地址，要么改授权记录里的授权域名，两边对齐
坑 2：外部访问地址还是内网 IP
Halo 后台默认可能配成 http://192.168.5.178:8081（内网 IP）。这会连锁引发授权失败、回调地址错误、插件配置校验失败。
解决：
后台 → 设置 → 系统设置 → 外部访问地址 → 改成公网域名，如
https://blog.seguzhixue.top注意：
https://前缀 + 不要带端口概览页顶部若出现「访问地址与配置不一致」警告，就是这个问题没改对
坑 3：授权中心域名可能整体不可用
现象： 配置全对，但授权还是失败。
诊断： 授权中心 auth.mayin.site 曾出现**公网 DNS 无法解析（NXDOMAIN）**的情况。用 nslookup auth.mayin.site 或 curl -I https://auth.mayin.site/ 验证。
解决：
优先用离线授权：授权中心 → 下载证书 → Halo 插件里选「离线授权」上传证书
联系作者 @Lywq 反馈授权中心状态
坑 4：授权成功后，功能节点/设置仍不出现
授权只是第一步，插件前端扩展（编辑器节点等）的注册还依赖插件配置完整初始化，见「五、Tools 工具箱」一节。
二、支付回调域名（支付插件的「地基」）
坑 5：通用设置里「支付回调域名」报「不得留空」或填了不生效
根因： 回调域名是支付插件拼接 notify_url 的基地址。它不是易支付的接口地址，而是你自己博客的公网域名。
解决：
支付插件 → 通用设置 → 支付回调域名 填：
https://blog.seguzhixue.top同时确认 Halo 外部访问地址也是这个域名（两者要保持一致）
坑 6：回调地址一直是内网 IP，改不过来
现象： 测试页里回调地址还是 http://192.168.5.178:8081/apis/...。
根因： 通用设置没保存成功（可能被必填校验卡住），或外部访问地址没改。
解决：
先改 Halo 外部访问地址为域名
支付插件通用设置填回调域名并确认保存无报错
验证标志：测试页回调地址变成
https://blog.seguzhixue.top/apis/...
三、易支付配置
坑 7：易支付没有「官方注册入口」
易支付是一套开源程序（彩虹易支付），不是官方产品，本身不收钱、没有统一注册入口。你需要找一家跑易支付的「服务商/发卡平台」注册成子商户，才能拿到商户号、密钥、接口地址。
拿到三件套（商户中心）：
接口地址（平台站点域名）
商户号 PID（纯数字）
商户 MD5 密钥
⚠️ 易支付属第四方/聚合支付，存在二清合规与跑路风险。别充大额余额、别长期滞留资金、能日结就日结。 个人博客小额打赏可用，大额建议支付宝当面付等官方渠道。
坑 8：易支付参数填写对照表
坑 9：接口地址结尾多一个斜杠
https://pays.1660.net.cn/ ❌ → 会拼出 //submit.php，部分易支付程序直接拒绝。结尾不要带 /。
坑 10：回调域名需要平台「审核/白名单」
很多易支付平台要求回调域名先过白名单审核，审核通过前发起支付/回调会被拒。加了域名后看状态是「审核中」→ 等审核通过（或联系客服催）。
坑 11：发起支付方式别选「API 接口支付」
现象： 换 API 模式后「支付发起失败」，或微信渠道报 404。
根因：
API 模式（
/mapi.php）是服务器对服务器请求，很多小易支付站不保障 mapi 接口，或返回格式插件解析不了API 模式下微信渠道还会触发插件自己渲染二维码页，而
/pay/qrcode/路由未注册 → 404（见坑 12）
解决： 用「页面跳转支付」，浏览器直接跳易支付收银台，兼容性最好。
坑 12：微信支付报 404 / 没有二维码
报错特征：
No static resource pay/qrcode/2026093012565313077/
根因： 插件 bug。同一套配置下支付宝渠道正常、微信渠道 404，说明不是参数问题，而是插件对微信渠道的实现缺陷——它想在自己博客渲染二维码页，但 /pay/qrcode/ 路由没注册进 Halo。
解决：
重启插件（停用→启用）排除偶发
检查应用市场是否有插件新版本（文档显示曾「修复易支付-微信支付发起支付失败的问题」）
带报错日志找作者 @Lywq 反馈
过渡期：支付宝照常用，微信用「收款码图片」顶上
坑 13：没有二维码 / 弹窗一直转圈
现象： 测试弹窗里一直「加载中」，不出二维码。
根因： 「页面跳转支付」返回的是整个收银台网页，不是二维码图片；易支付站普遍禁止被 iframe 内嵌（X-Frame-Options），所以弹窗里永远转圈。
解决： 点弹窗底部「跳转新页面支付」，新标签页打开收银台扫码。这是测试页的展示局限，不影响前台真实用户（他们本来就是跳收银台）。
坑 14：支付成功跳回的是主页，不是文章页
根因： 这是测试订单，成功返回地址（return_url）填的是主页。正式场景里，发起支付的插件（付费阅读）会自己传文章页/结果页作为返回地址。
重点区分两个地址：
return_url（同步跳转）：付完浏览器跳哪，只是体验
notify_url（异步回调）：支付平台服务器通知插件「钱到了」，这才是真正确认支付
订单状态判定： 回「支付管理 → 订单列表」看是否变「已支付」——秒变=回调通；1分钟内变=轮询兜底生效；一直待支付=查回调/签名。
坑 15：订单金额被加手续费
现象： 下 ¥1.00 的单，收银台显示 ¥1.05。
根因： 易支付平台的手续费转嫁给了付款人（5%）。
解决： 去易支付平台设置，把「手续费承担方」改成商户承担；改不了就对比其他平台（行业常见 1%~3%，5% 偏高）。
四、支付宝官方（当面付）
坑 16：「电脑网站支付」「手机网站支付」个人签不了
这两个产品要求企业/个体工商户资质。个人主体（截图里写「个人」）签不下来。
解决： 选 「当面付」（alipay.trade.precreate），个人可签，也是 Halo 支付插件默认对应的产品。
坑 17：公私钥三个「钥」别搞混
这是支付宝配置最高频的坑：
记忆：私钥自己留（填插件），公钥给平台（上传），平台还你一个支付宝公钥（填插件）。
坑 18：已有应用复用 vs 新建
已有应用可以复用，不用新建。只需确认三件事：
有没有签「当面付」（没有就补签）
加签方式是「公钥模式」（证书模式要改成公钥模式）
应用状态是「已上线」（不是「开发中」）
坑 19：支付宝参数填写对照表
支付宝官方对域名备案要求不如微信严格，未备案一般可用——这是没备案时优先上支付宝的原因。
五、Tools 工具箱（付费阅读）
坑 20：编辑器里找不到「限制阅读内容/限制阅读分割」节点
这是本次最隐蔽的坑。 现象：插件已授权成功、其他插件的自定义节点（分栏、视频等）都正常显示，唯独 Tools 的「限制阅读」节点在编辑器里找不到。
排查顺序（按命中率）：
斜杠命令：正文空行敲
/限制，斜杠菜单会过滤出节点（比翻"+"菜单快）插件设置标签逐个翻：Tools 设置页顶部标签栏里找「模板设置」
✅ 根因：「模板设置 → 兼容 PJAX」开关未开启
最终根因： Tools 的「模板设置 → 兼容 PJAX」开关没开启，导致插件前端脚本（bundle.js）初始化不完整，编辑器扩展节点（限制阅读内容/分割/下载信息）没有注册。
解决： 打开「兼容 PJAX」开关 → 保存 → 回编辑器 Ctrl+F5 强刷 → 节点出现。
💡 教训：插件功能经常互相耦合，一个开关的字面名字（“兼容 PJAX”）和它的实际影响范围（编辑器节点注册）可能完全对不上。排查插件「功能开关找不到」时，把插件自己的设置标签逐个翻完。
坑 21：改完配置没效果 → 必须强刷
编辑器扩展靠 bundle.js 注入，改完插件配置后浏览器里的旧页面还在用旧缓存。
解决： 改完配置 → Ctrl+F5 强制刷新编辑器页面（或退出后台重登）。
六、通用排查心法（速查）
「其他插件正常、唯独这个插件异常」→ 问题锁定在该插件自身，先翻它自己的设置，别去动系统
Halo 插件问题先查三件事：插件授权状态、Halo 外部访问地址、插件配置是否保存成功
改配置 → 保存 → 强刷（Ctrl+F5）→ 验证，四步缺一不可
看日志：Halo 后台「概览 → 系统日志」或
docker logs <容器名>，搜关键词（易支付 / qrcode / payment / 插件名）版本匹配：Tools 2.3.2 要求 Halo ≥ 2.24.0，版本不匹配会导致编辑器扩展 API 对不上
别在聊天里截图暴露密钥：MD5 密钥、应用私钥都等于收款钥匙，泄露后立即去平台重置
七、完整验证闭环（配置完必做）
发一篇带「限制阅读分割」的文章，文章设置里选「付费访问」+ 金额
前台打开文章 → 看付费弹窗是否正常
点支付 → 跳收银台 → 付 0.01/0.01 元
回「支付管理 → 订单列表」看订单是否自动变「已支付」
确认付费后文章隐藏内容正常解锁
以上全部通过，付费阅读链路才算正式可用。
文档整理时间：2026-09-30
适用：Halo 2.24+ / Tools 2.3.2 / 支付插件（木因）