Yu Plugin Hub

切换深色模式

YuPay 配置说明 ​

YuPay 的主配置位于 plugins/YuPay/config.yml。第一次启动后先不要急着开放给玩家，建议按“基础支付 -> 回调 -> 数据库 -> 奖励 -> 退款 -> 安全审计”的顺序配置。

配置总览 ​

区块用途
startup-check启动自检，检查配置、数据库、依赖和回调地址。
pay默认支付方式、订单标题、单笔/单日金额限制、待支付订单过期。
api其他插件调用 YuPayApi 的授权与审计。
wechat微信支付商户号、AppID、证书、公钥、API v3 密钥和回调。
alipay支付宝应用、私钥、公钥/证书、回调和性能参数。
callbackYuPay 内置回调服务器端口、线程、访问日志和请求限制。
databaseSQLite / MySQL、连接池、迁移和表名。
cross-server群组服跨服发奖队列和 shared-secret。
economyVault / PlayerPoints 奖励类型与赞助兑换比例。
reward发奖快照，保证补发时按订单创建时的配置执行。
commands命令别名、支付锁期间允许命令、支付成功奖励命令。
refund退款开关、取消后到账处理和平台状态同步。
logging调试日志、敏感信息脱敏和安全审计日志。
language中文/英文语言文件映射。
library动态依赖完整性校验。

基础支付 ​

yaml
pay:
  default-method: "wechat"
  order-subject: "赞助-{player}-{amount}元"
  min-amount: 0.01
  max-amount: -1
  max-daily-amount: -1
  pending-expire:
    enabled: true
    minutes: 15
    check-interval-seconds: 60
    batch-size: 100
配置建议
default-method默认支付渠道，必须是已启用且配置正确的 wechat 或 alipay。
order-subject会显示在支付平台订单标题里，建议包含玩家名和金额。
min-amount建议保留最小金额，避免误触或无意义订单。
max-amount高额赞助服建议设置单笔上限，超额走人工确认。
max-daily-amount需要风控时设置单日累计上限。
pending-expire.minutes建议保持 15 分钟，和常见支付平台订单窗口一致。

微信支付 ​

yaml
wechat:
  enabled: false
  mchid: "1234567890"
  appid: "wx1234567890abcdef"
  serial-no: "444F4864EA9B344B..."
  private-key-path: "apiclient_key.pem"
  public-key-path: "pub_key.pem"
  public-key-id: "PUB_KEY_ID_011..."
  api-v3-key: "your-api-v3-key-here"
  notify-url: "https://pay.example.com/pay/wechat/notify"
  refund-notify-url: "https://pay.example.com/pay/wechat/refund/notify"

配置要点：

  • 新安装默认 enabled: false，替换真实商户信息后再启用。
  • 私钥、公钥文件路径相对 YuPay 的证书目录；文件名可以自定义，但配置要一致。
  • api-v3-key 必须是 32 位 API v3 密钥，不是商户平台登录密码。
  • notify-url 和 refund-notify-url 必须公网可访问，且能被微信平台 POST。

支付宝 ​

yaml
alipay:
  enabled: false
  mode: "public_key"
  app-id: "your-alipay-app-id"
  merchant-private-key: "your-merchant-private-key"
  notify-url: "https://pay.example.com/pay/alipay/notify"
  return-url: "https://pay.example.com/return"
  alipay-public-key: "your-alipay-public-key"
  app-cert-path: "appCertPublicKey.crt"
  alipay-cert-path: "alipayCertPublicKey_RSA2.crt"
  alipay-root-cert-path: "alipayRootCert.crt"

mode 可选：

模式适合场景
public_key配置简单，适合先快速验证。
cert安全性更高，正式服推荐。

应用私钥需要去掉 -----BEGIN PRIVATE KEY----- 和 -----END PRIVATE KEY-----。证书模式下，三个证书文件都要放到配置指定的位置。

回调服务器 ​

yaml
callback:
  host: "0.0.0.0"
  port: 8080
  io-threads: 2
  worker-threads: 8
  read-timeout-ms: 10000
  write-timeout-ms: 10000
  max-body-size: 65536
  allowed-ips: []
  access-log: false
  ledger:
    enabled: true
    save-raw-body: false
    save-body-hash: true

建议：

  • host: "0.0.0.0" 表示监听全部网卡，适合大多数服务器。
  • port 要与支付平台回调 URL、反向代理和防火墙一致。
  • allowed-ips 留空表示不启用白名单；正式服可按支付平台官方 IP 段配置。
  • ledger.enabled 建议开启，用于记录回调流水；save-raw-body 默认关闭，避免保存敏感原文。

数据库 ​

yaml
database:
  type: "sqlite"
  mysql:
    host: "localhost"
    port: 3306
    database: "minecraft"
    username: "root"
    password: "password"
    jdbc-params: "useSSL=false&useUnicode=true&characterEncoding=UTF-8&autoReconnect=true"
  connection-pool:
    enabled: true
    max-pool-size: 10
    min-idle: 5
类型建议
SQLite单服、低并发、快速部署。
MySQL群组服、跨服发奖、多实例回调、长期运营。

表名位于 database.table-names。如果同一个库里部署多个环境，可以配置 prefix 避免冲突。

跨服发奖 ​

yaml
cross-server:
  enabled: false
  server-id: "lobby-1"
  reward-routing:
    mode: "PLAYER_ONLINE"
    target-server: "lobby-1"
    fallback-server: "lobby-1"
    player-online-fallback-seconds: 0
  queue:
    poll-interval-ticks: 40
    batch-size: 32
    max-attempts: 5
    lease-seconds: 60
  security:
    require-shared-secret: true
    shared-secret: "CHANGE_ME_TO_A_LONG_RANDOM_SECRET"

跨服启用前必须先切到 MySQL。所有子服的 shared-secret 保持一致，server-id 必须各不相同。

路由模式含义
LOCAL当前服直接发奖。
SERVER固定交给 target-server 发奖。
PLAYER_ONLINE玩家在哪个子服在线，就由哪个子服发奖。
ANY任意在线子服都可领取任务。

经济与奖励 ​

yaml
economy:
  enabled: true
  type: "vault"
  rate: 100.0

commands:
  enabled: true
  on-success:
    - "give {player} diamond 1"
  on-single-achieved:
    - amount: 50
      commands:
        - "say {player} 单笔赞助达到50元"
  on-total-achieved:
    - total: 100
      commands:
        - "lp user {player} parent set vip"
  on-refund:
    - "say {player} 的订单 {order} 已退款 {amount} 元，请管理员核查"

可用变量：

变量含义
{player}玩家名
{amount}赞助金额，单位元
{points}按 economy.rate 换算后的奖励数量
{order}订单号，退款命令中常用

奖励建议：

  • 高价值权限组不要直接放在 on-success，建议按单笔或累计档位发放。
  • 命令奖励需要幂等，避免补发时造成重复不可逆操作。
  • reward.snapshot.enabled 建议保持开启，后续补发会按订单创建时的奖励快照执行。

二维码输出 ​

yaml
qrcode:
  default-output-mode: "map"
  api-url: "https://api.qrserver.com/v1/create-qr-code/?size=200x200&data="
  text-qr-size: 12
  text-black-char: "██"
输出模式说明
map地图二维码，体验最好，需要 ProtocolLib。
link发送支付链接或二维码链接，兼容性最好。
text聊天文本二维码，适合没有地图二维码条件的环境。

API 授权 ​

YuPay 默认要求调用方插件显式声明来源，建议只给可信插件开放创建订单、查询订单、退款或重试奖励等能力。

yaml
api:
  enabled: true
  require-plugin-declaration: true
  audit-log: true
  default-permissions:
    create-order: false
    cancel-order: false
    query-order: false
    refund-order: false
    retry-reward: false
    no-reward-order: false
    expire-orders: false
  allowed-plugins:
    ExampleShop:
      create-order: true
      cancel-order: true
      query-order: true
      refund-order: false
      retry-reward: false
      no-reward-order: true
      expire-orders: false

更多接入写法见 插件间 API。

退款 ​

yaml
refund:
  enabled: true
  auto-refund-cancelled-paid: false
  status-sync:
    enabled: true
    initial-delay-seconds: 60
    interval-seconds: 300
    batch-size: 30
    query-unknown: false

建议：

  • enabled 关闭后，API 和管理员命令不会主动发起平台退款。
  • auto-refund-cancelled-paid 建议保持关闭，取消后到账先进入异常订单人工审核。
  • status-sync 建议开启，让平台退款状态定时刷新到本地。

日志与安全审计 ​

yaml
logging:
  debug: false
  mask-sensitive: true
  mask-ip: true
  max-message-length: 1000
  save-callback-body: false
  mask-callback-body-before-save: true
  security-audit:
    enabled: true
    file: "logs/security-audit.log"
    echo-console: false

生产服建议：

  • debug 保持关闭。
  • mask-sensitive、mask-ip 保持开启。
  • 不保存回调请求体原文，只保存 hash 与长度即可满足追溯。
  • 需要排查 API 拒绝、回调异常或退款问题时，查看 logs/security-audit.log。

费率说明 ​

YuPay 不参与代收，不抽取中间商费用。实际支付通道费率由微信支付、支付宝官方商户通道决定，通常为 0.2%-0.6%；如需永久 0.2% 费率，请联系作者。