YuPay 安装部署
YuPay 是微信支付与支付宝官方商户直连插件，不需要第三方代收。安装重点不是“把 jar 放进去”这么简单，而是要准备好商户资料、证书、公网回调地址和安全检查。
环境要求
| 检查项 | 要求 |
|---|---|
| Java | JDK 8 及以上 |
| 服务端 | Bukkit/Spigot/Paper 及常见衍生端 |
| 当前版本 | 1.5.0.0 |
| 必要网络 | 服务端需要能访问微信支付/支付宝接口；支付平台需要能访问你的回调地址 |
| 数据库 | 单服可用 SQLite；群组服、跨服发奖或多实例回调建议 MySQL |
| 软依赖 | Vault、PlaceholderAPI、PlayerPoints、ProtocolLib |
软依赖不是全部必装：
| 插件 | 作用 |
|---|---|
Vault | 使用主流经济插件发放赞助点数或货币。 |
PlayerPoints | 使用点券类经济奖励。 |
PlaceholderAPI | 在菜单、计分板、聊天里显示赞助金额、排行和卡密状态。 |
ProtocolLib | 地图二维码输出模式需要。没有它时建议使用 link 或 text 输出。 |
部署步骤
- 将发布版
YuPay-版本.jar放入服务端plugins/目录。 - 启动一次服务端，让插件生成
plugins/YuPay/config.yml、语言文件、数据目录和证书目录。 - 停服或执行
/yp reload前，先在config.yml中完成支付渠道、回调、数据库和奖励配置。 - 把微信/支付宝所需证书文件放到 YuPay 数据目录下对应位置。
- 确认公网域名或 IP 能访问回调端口，云服务器安全组和系统防火墙都已放行。
- 重启服务端，执行
/yp health full检查数据库、依赖、支付渠道和回调状态。 - 使用小额订单完整测试：创建订单、扫码支付、回调入账、奖励发放、订单查询、退款申请和管理员审核。
安装命令
安装命令
首次启动后在 plugins/YuPay/config.yml 填写微信支付或支付宝官方商户参数支付资料准备
微信支付
| 资料 | 配置项 | 获取位置 |
|---|---|---|
| 商户号 | wechat.mchid | 微信支付商户平台，账户中心 -> 商户信息 |
| AppID | wechat.appid | 微信公众平台或小程序/服务号后台 |
| 商户 API 证书序列号 | wechat.serial-no | 微信支付商户平台，账户中心 -> API 安全 |
| 商户私钥 | wechat.private-key-path | API 证书生成后的 apiclient_key.pem |
| 微信支付平台公钥 | wechat.public-key-path | 商户平台下载或按官方流程获取 |
| 平台公钥 ID | wechat.public-key-id | 微信支付平台公钥信息 |
| API v3 密钥 | wechat.api-v3-key | 商户平台，API 安全 -> APIv3 密钥 |
| 支付回调地址 | wechat.notify-url | 你的公网 HTTP/HTTPS 地址 |
| 退款回调地址 | wechat.refund-notify-url | 建议与支付回调分开路径 |
支付宝
| 资料 | 配置项 | 说明 |
|---|---|---|
| 应用 ID | alipay.app-id | 支付宝开放平台应用信息 |
| 应用私钥 | alipay.merchant-private-key | 去掉 BEGIN/END PRIVATE KEY 头尾 |
| 支付宝公钥 | alipay.alipay-public-key | 公钥模式使用 |
| 应用公钥证书 | alipay.app-cert-path | 证书模式使用 |
| 支付宝公钥证书 | alipay.alipay-cert-path | 证书模式使用 |
| 支付宝根证书 | alipay.alipay-root-cert-path | 证书模式使用 |
| 异步通知地址 | alipay.notify-url | 必须公网可访问 |
| 同步返回地址 | alipay.return-url | 玩家支付完成后的浏览器返回地址 |
支付宝推荐使用证书模式；如果你使用公钥模式，请确认公钥与应用私钥是一组。
回调地址要求
YuPay 内置回调服务默认监听：
yaml
callback:
host: "0.0.0.0"
port: 8080上线前确认：
notify-url和refund-notify-url指向公网可访问地址，而不是内网地址或localhost。- 云服务器安全组、系统防火墙、面板防火墙都已放行回调端口。
- 如果使用反向代理，必须允许支付平台的
POST请求原样转发到 YuPay。 - 支付回调和退款回调建议使用不同路径，方便审计和排查。
- 排查阶段可以打开
callback.access-log: true，稳定后再关闭减少日志量。
单服与群组服部署
| 场景 | 建议 |
|---|---|
| 单服 | 使用默认 SQLite 即可，回调和发奖都在同一服务端完成。 |
| 多子服但只在主服收款 | 主服部署 YuPay 并处理回调，其他服通过命令或外部系统联动。 |
| 群组服跨服发奖 | 使用 MySQL，所有子服配置不同 cross-server.server-id，并共享同一 shared-secret。 |
| 多实例接收回调 | 必须使用 MySQL，并确认订单与发奖流程具备幂等性。 |
上线前检查
- 至少启用一个支付渠道，并确认示例商户号、示例密钥、示例回调地址都已替换。
pay.min-amount、pay.max-amount、pay.max-daily-amount符合服务器赞助规则。- 奖励命令不要包含危险的全服 OP、权限组误授予或重复发放风险。
logging.mask-sensitive、logging.mask-ip、api.audit-log建议保持开启。- 生产服上线前备份
plugins/YuPay/与数据库。 - 完成小额支付、取消后到账、奖励失败重试、退款申请、直接退款和卡密核销测试。
常用检查命令
text
/yp health summary
/yp health full
/yp orders
/yp order abnormal
/yp audit security 50如果健康检查提示支付渠道不可用，优先检查商户参数、证书路径、回调地址和服务器出站网络。