📥 安装与依赖

环境要求

安装步骤

1. 将 AdventurePay.jar 放入 plugins/
2. 重启服务器，生成默认配置
3. 编辑 config.yml，填写支付网关密钥和回调地址
4. 将 API 密钥文件放入 plugins/AdventurePay/keys/
5. 配置防火墙放行回调端口 (默认 28880)
6. 执行 /apay reload

文件结构

plugins/AdventurePay/
├── config.yml          # 主配置
├── messages.yml        # 消息配置
├── keys/               # 支付密钥目录
│   ├── alipay_private_key.pem
│   ├── alipay_public_key.pem
│   └── wechat_private_key.pem
├── shops/              # 商品配置目录
│   └── *.yml           # 商品定义文件
└── data/               # SQLite 数据库

💳 支付网关

支付宝 (Alipay)

官方当面付模式 (official)

使用支付宝开放平台的当面付 API，需申请商户应用：

payment:
  alipay:
    enabled: true
    mode: official
    official:
      app-id: "你的应用APPID"
      private-key-file: "keys/alipay_private_key.pem"
      alipay-public-key-file: "keys/alipay_public_key.pem"
      sign-type: RSA2
      gateway: "https://openapi.alipay.com/gateway.do"

Hook 监控模式 (hook)

无需 API 密钥，通过预设收款码 + 金额匹配确认付款：

payment:
  alipay:
    enabled: true
    mode: hook
    hook:
      qrcodes:
        "1.00": "https://your-qrcode-url/1yuan.png"
        "10.00": "https://your-qrcode-url/10yuan.png"

微信支付 (WeChat)

Native 支付模式

payment:
  wechat:
    enabled: true
    mode: native
    native:
      app-id: "你的公众号APPID"
      mch-id: "商户号"
      api-v3-key: "APIv3密钥"
      mch-serial-no: "商户证书序列号"
      private-key-file: "keys/wechat_private_key.pem"

回调服务器

插件内置 HTTP 服务器接收支付平台回调通知：

callback-server:
  enabled: true
  port: 28880
  external-url: "http://公网IP:28880"
  ip-whitelist: []  # 限制回调来源IP

🪙 点券系统

配置

points:
  scale: 10                    # 1元 = 10点券
  names:                       # 商品名 (随机显示)
    - "冒险点券充值"
    - "游戏点券"
  limitation:
    range: "1-9999"            # 金额范围
    decimal-places: 2          # 小数位 (0=整数)
  modifiers: []                # 价格修饰器
  commands:                    # 成功后执行
    - "eco give {player} {points}"

使用方式

玩家执行 /apay points <alipay|wechat> <金额>，插件创建订单并展示二维码地图。扫码支付成功后自动执行配置的命令。

变量说明

🛒 商品系统

商品配置

在 shops/ 目录下创建 YAML 文件定义商品：

# shops/vip.yml
id: "monthly_vip"
display: "月度VIP"
names:                     # 支付平台显示名 (随机)
  - "游戏增值服务"
price: 30.00               # 原价
payment:
  alipay: true             # 允许支付宝
  wechat: true             # 允许微信
permission: null           # 购买权限 (null=不限)
limitation:
  type: per_player          # 限购类型
  count: 1                  # 限购数量
  deny-commands:            # 超限执行命令
    - "msg {player} 你已购买过此商品"
rewards:                   # 购买成功奖励
  - "lp user {player} parent add vip 30d"
  - "mail send {player} 恭喜购买VIP！"

价格修饰器

支持通过权限或条件修改商品价格（折扣/加价）：

• 全局修饰器在 config.yml 的 points.modifiers 中定义
• 商品级修饰器在商品配置中定义
• 多个修饰器按顺序叠加计算

📱 二维码地图

工作原理

插件将支付二维码渲染到 Minecraft 的地图物品上，自动放入玩家主手展示。玩家用手机扫描即可完成支付。

配置

map-item:
  id: 20070831               # 地图ID (避免冲突)
  name: "&a&l扫码支付"         # 地图物品名
  lore:
    - "&7请使用手机扫描二维码完成支付"
    - "&7按 &eQ键 &7可取消支付"
  colors:
    light:                    # 浅色区域
      base: 8
      modifier: 2
    dark:                     # 深色区域 (二维码)
      base: 29
      modifier: 3

🎫 CDK 兑换码系统

概览

完整的 CDK 兑换码管理系统，支持批量生成、分组管理、过期控制、每人限兑、铁砧 GUI 兑换等功能。

CDK 格式模板

cdk:
  server-name: "主服"
  default-format: "APAY-XXXX-XXXX-XXXX"

铁砧 GUI 兑换

玩家输入 /cdk 或 /acdk 打开铁砧界面，在重命名栏输入 CDK 码，点击结果槽即可兑换。

防暴力破解

cdk:
  failed-attempts:
    enabled: true
    max-attempts: 5      # 最大连续失败次数
    ban-duration: 10     # 封禁时长 (分钟)
    reset-duration: 10   # 失败记录重置时间

⌨️ CDK 命令

玩家命令

管理员命令

创建示例

# 创建10个VIP CDK，每个限用1次，每人限1次，7天过期
/acdk create vip_group APAY-XXXX-XXXX 10 1 true 7d lp user {player} parent add vip 30d

# 多命令用 ;; 分隔
/acdk create reward APAY-####-#### 50 0 false never eco give {player} 1000 ;; msg {player} 恭喜获得奖励！

🗄️ 数据库

存储类型

storage:
  type: sqlite              # sqlite 或 mysql
  mysql:
    host: localhost
    port: 3306
    database: adventurepay
    username: root
    password: ""
    table-prefix: "apay_"
    pool-size: 10

默认使用 SQLite，数据库文件位于插件目录。跨服场景建议切换到 MySQL。

🔒 安全机制

安全配置

security:
  sign-secret: "随机密钥"      # 订单签名密钥
  nonce-ttl: 300              # Nonce 有效时间 (秒)
  rate-limit: 30              # 每秒最大请求数
  order-prefix: "AP"          # 订单号前缀

安全特性

• 订单签名 — 每个订单使用 HMAC 签名防篡改
• Nonce 防重放 — 每个请求携带唯一 nonce，TTL 内不可重复
• IP 白名单 — 回调接口可限制来源 IP
• 接口限流 — 每秒最大请求数限制，防 DDoS
• CDK 防暴力 — 连续失败自动封禁

🏆 排行榜

配置

rank:
  top: 10              # 显示前几名
  refresh-interval: 300 # 刷新间隔 (秒)

使用

执行 /apay rank 查看充值排行榜。排行榜数据定时从数据库刷新，按累计充值金额排序。

⚙️ config.yml 完整配置

支付超时

payment:
  timeout: 300           # 支付超时 (秒)
  allow-increasing: false # 是否允许金额上浮

充值记录

log-book:
  lines-per-page: 12
  time-format: "MM-dd HH:mm"
  payment-types:
    alipay: "支付宝"
    wechat: "微信"

调试

debug: false
processing-logs: true    # 是否输出处理日志

⌨️ 命令列表 (apay)

🔐 权限节点

🔗 PlaceholderAPI 变量

📝 更新日志

v1.3.0 LATEST

• NEW CDK 铁砧 GUI — 玩家在铁砧界面输入 CDK 码兑换
• NEW CDK 导出功能 — /acdk export 导出到文件
• NEW CDK 追加 — /acdk add 向现有组追加 CDK
• IMPROVED 排行榜经验 — 排行榜支持经验值排序
• CONFIG softdepend — 新增 AdventureManage, AdventureMail

v1.2.0

• NEW CDK 兑换码系统 — 完整的 CDK 生命周期管理
• NEW 防暴力破解 — 连续失败自动封禁
• NEW 交易统计 — /apay stats 按日期范围统计

v1.1.0

• NEW 商品系统 — YAML 配置商品，支持限购/权限
• NEW PlaceholderAPI — 排行榜/商品价格变量
• IMPROVED QR 码地图 — 颜色可配置

v1.0.0

• NEW 初始版本 — 支付宝/微信双网关、点券充值、排行榜