订单状态与常见问题

订单状态

状态	说明
CREATED	已在本地创建，正在提交
WAITING_PAYMENT	等待玩家付款
PAID	已确认到账，等待发放
DELIVERY_PENDING	玩家不在线，等待上线发放
DELIVERING	正在执行奖励命令
COMPLETED	奖励已经发放完成
CANCELLED	玩家按 Q、执行 close 或系统取消
EXPIRED	5 分钟内未完成支付
FAILED	创建、地图读取或奖励执行出现异常
DELIVERY_UNKNOWN	发放过程中服务端重启，需要管理员重试

查询订单：

/gtpay status 订单号

管理员重试发放：

/gtpay retry 订单号

订单 5 分钟后结束

GTPay 的待支付订单有效时间固定为 5 分钟。

以下情况会结束订单：

• 5 分钟内没有到账。
• 玩家按 Q 取消。
• 玩家执行 /gtpay close。
• 本地收款码读取失败。
• 地图数据包无法发送。
• 系统返回取消、失败或过期。

结束后的订单不能继续支付，也不会继续占用分币金额。

游戏内没有二维码

按顺序检查：

1. config.yml 中 qrcode.display-in-map 是否为 true。
2. 当前渠道的收款码文件是否存在。
3. 文件名和 config.yml 是否一致。
4. 图片是否为 PNG/JPEG，是否小于 4 MB。
5. 图片是否放在 plugins/GTPay/qrcode/，而不是服务器根目录。
6. 执行 /gtpay reload 后重新创建订单。
7. 控制台是否出现地图包错误。

1.21.x 地图显示失败时，更新 GTPay 模块并重新启动服务端确认。收款码仍然放在本地 qrcode 文件夹，不填写图片 URL。

按 Q 没有取消

检查：

1. 当前手中是否仍然是 GTPay 付款地图。
2. 订单是否还处于 WAITING_PAYMENT。
3. 是否有其他插件拦截了丢弃事件。
4. 使用 /gtpay status 订单号 查看实际状态。

也可以直接执行：

/gtpay close

显示金额和输入金额不同

这是正常的分币识别规则。基础金额 10 元可能显示为：

10.00、10.01、10.02

只会根据当前仍在等待支付的订单占用最低可用分币。已完成订单不会继续占用。

如果出现 10.90、1.65 这类不符合规则的金额：

1. 不要继续支付该订单。
2. 记录订单号、基础金额、显示金额和创建时间。
3. 提交订单号和金额信息处理。

玩家支付后没有发放

执行：

/gtpay status 订单号

状态为 WAITING_PAYMENT

监听 App 没有上报到账，检查：

• App 是否显示连接成功。
• merchant_id 是否填错。
• monitor_key 是否属于当前服务器。
• 微信或支付宝通知是否正常显示。
• 实际支付渠道是否和订单渠道一致。
• 手机是否被系统省电策略停止。

状态为 PAID 或 DELIVERY_PENDING

说明到账已经确认。玩家上线后会自动继续发放；管理员也可以执行：

/gtpay retry 订单号

状态为 FAILED

检查 delivery_message 中的命令错误。最常见原因是：

• 点券插件命令写错。
• 权限插件命令版本不匹配。
• 命令参数中包含未替换的变量。
• 使用 [player] 或 [op] 命令时玩家已经离线。

收款码不能扫描

处理方式：

1. 直接用手机相机或对应支付 App 扫描原始 PNG，确认收款码本身有效。
2. 使用正方形图片，四周保留白边。
3. 不要压缩到过低分辨率。
4. 不要在图片上叠加文字、边框或服务器 Logo。
5. 确认微信订单使用微信码，支付宝订单使用支付宝码。

GUI 打不开

检查：

1. 文件是否位于 plugins/GTPay/gui/。
2. 命令中的文件名是否正确。
3. rows 是否在 1 到 6 之间。
4. 布局每行是否超过 9 个字符。
5. icons 字符是否和 layout 一致。
6. YAML 是否少了冒号、引号或缩进。

GUI 按钮不显示

检查按钮的：

• permission 是否配置了玩家没有的权限。
• material 是否存在；1.12 请提供 legacy-material。
• 礼包 ID 是否存在且已启用。
• GUI 文件是否保存后执行了 /gtpay reload。

累计赞助金额不对

累计赞助只统计已经确认到账的订单，不统计：

• WAITING_PAYMENT。
• CANCELLED。
• EXPIRED。
• FAILED。

同时检查：

1. 当前订单类型是否符合 count_topup、count_gifts。
2. 活动时间和时区是否正确。
3. 看的是否是正确的方案 ID。
4. 是否执行了 /gtpay reload。

分币识别金额不会计入累计赞助。例如输入 10 元、实际支付 10.01 元，累计仍然按 10.00 元计算。

多个区的累计赞助和排行没有同步

检查每台服务端：

1. storage.mode 是否都为 mysql 或都为 redis。
2. 连接地址、数据库、账号和密码是否指向同一个存储。
3. cluster-id 是否相同；使用 auto 时检查 5 台的 merchant_id 是否相同。
4. node-id 是否保持 auto，不要手动给 5 台填同一个节点 ID。
5. 修改存储配置后是否重启了 Minecraft 服务端。

默认同步间隔为 10 秒。跨服同步的是已完成订单、礼包限制、累计赞助金额、排行和奖励领取记录；待支付订单仍由创建它的服务端负责查询和发放。

使用 local 存储时不会同步。

管理页打不开

1. 在控制台执行 gtpay web open。
2. 使用同一台机器的浏览器打开控制台返回的地址。
3. 页面地址中的一次性 token 不要手工截断。
4. 页面长时间未操作后会自动关闭，需要重新执行 gtpay web open。
5. 端口冲突时修改 config.yml 的 web.port，关闭管理页后重新执行 gtpay web open。

仍然无法判断问题

提供以下信息给群主或管理员：

Minecraft 版本
GTCore 版本
GTPay 版本
订单号
订单状态
控制台相关报错

不要提供：

• server_key
• monitor_key
• 收款码原图
• 机器人私聊截图