玩家工单、申诉与跨服处罚

← 玩家与账号 · 所有分区

当前文档对应 VexBot 0.6.30 / Bukkit 插件 0.5.5；这些功能从 Bot 0.6.0 起提供。游戏插件需要具备 managed_sanctions 能力；从当前面板下载通用 JAR 更新到游戏服务器。仍使用 Java 8 通用构建。

按需开启功能

服主进入 设置 → 功能开关，分别开启「白名单申请」「工单与申诉」「跨服处罚」。点击开关即保存，开启后显示对应的成员页入口；设置会持久保存，重启后保留。首次部署默认关闭，已有工单、处罚历史的旧部署继续保留其启用状态。

功能	关闭后的行为
白名单申请	停止新申请，保留已有申请、审核及执行记录
工单与申诉	停止新提交，保留已有工单和回复，已有工单仍可通过 API 处理
跨服处罚	停止新增并暂停未执行的封禁和踢出；已生效封禁不立即解除，到期或撤销继续按归属校验解封

重新开启后可继续管理历史记录。功能开关不改变团队权限：拥有对应管理权限的成员仅在开启后看到入口；集中开关由服主管理。白名单的申请要求、工单的数量限制在各自管理页中调整，不会因切换开关重置。

工单与申诉

玩家登录独立官网后，在「我的账号」中提交玩家问题或处罚申诉，管理员在 成员 → 工单与申诉 回复。

能力	行为
玩家查看	仅能查看本人提交的工单、管理员公开回复
管理回复	可以回复、写内部备注，或只修改状态
内部备注	只供有工单权限的管理员查看
状态	待处理、处理中、已解决、已关闭
结束工单	已解决或关闭后，玩家不能继续回复；管理员可重新开启
关联处罚	只能选择与本人已验证游戏身份关联的记录

面板可关闭新工单，或调整每人待处理数量上限（1–20，默认 5）。标题最多 100 字，消息最多 4000 字，每单最多 200 条消息，最多储存 10000 份工单；提交限每小时五次，玩家回复限五分钟二十次。保存时检查版本号，避免覆盖其他管理员的回复。

工单权限为 tickets.manage，处罚权限为 sanctions.manage，两者可独立授权。工单提交并不自动解封；管理员复核后需单独撤销处罚。

创建跨服处罚

1. 从玩家档案复制完整 UUID。
2. 进入 成员 → 跨服处罚，选择服务器、操作和原因。
3. 封禁可设置分钟数，0 表示永久；踢出只在一分钟内尝试。
4. 确认下发，查看每台服务器的执行状态。

仅按 UUID 匹配游戏身份，不凭同名猜测。服务器离线或未上报该 UUID 时保留等待状态；升级过插件并上报身份后再执行。在线模式、离线模式或代理 UUID 不同的身份不会自动合并。

「等待确认」表示命令已下发；收到游戏端成功结果后才标记执行成功。失败会间隔重试，最多十次；修复网络或核心问题后可点击手动重试。踢出请求过期后不会在玩家下一次登录时再次踢出。

到期与撤销

到期或手动撤销后逐服解除本条封禁。执行时会核对原生封禁原因中的处罚编号，保留其他插件、控制台或单服面板创建的独立封禁。已有独立封禁的服务器在创建时跳过，不覆盖它。

同一 UUID 在同一服不能同时创建两条生效跨服封禁；此前解除仍在等待确认时，新处罚先等待。生效封禁被外部解除时会重新应用；若想结束这条规则，请在跨服处罚中撤销。

极旧核心无法读取原生封禁原因时，自动解除会安全失败，需在游戏端核实后手动处理。自动解除需要 Bot 和该服恢复连接；Bot 关闭期间不能立即解除。其他独立封禁不会因申诉通过而自动清除。

自建网站 API

以下接口使用玩家登录得到的短期 Bearer Token，不使用管理令牌或后端 API 密钥。配置网站来源后可跨域使用。

方法与路径	作用
GET /api/v1/me/tickets?page=1	本人工单列表，每页 20 项
POST /api/v1/me/tickets	提交工单
GET /api/v1/me/tickets/{id}	本人详情与公开回复
POST /api/v1/me/tickets/{id}/reply	本人回复
GET /api/v1/me/services	本人绑定、白名单、单服处罚与跨服处罚记录

{"title":"登录问题","body":"进入生存服时无法完成认证","kind":"question","server":"survival","penalty_id":""}

申诉使用 kind: "appeal"，可带本人处罚记录的 penalty_id。回复提交 {"body":"补充说明","revision":1}，版本号取自最新详情。常见状态：401 登录失效、403 未授权/工单已结束、404 记录不存在或不属于本人、409 版本或数量冲突、429 请求过频。

浏览器 SDK 新增 tickets(token,page)、ticket(token,id)、createTicket(token,data)、replyTicket(token,id,body,revision)。示例：

const ticket = await client.createTicket(token, {
  title: '请求复核处罚', body: '请核实处罚发生时间与原因',
  kind: 'appeal', server: 'survival', penalty_id: selectedPenalty.id
});
await client.replyTicket(token, ticket.id, '补充说明', ticket.revision);

相关文档：官网与 API、团队权限。