兑换码Fabric版

兑换码Fabric版

一个服务端的Minecraft Fabric模组，可为你的服务器添加强大的兑换码系统。

杂项

RedemptionCodeFabric

概述

RedemptionCodeFabric 是用于 Minecraft Fabric 服务器（1.20.1）的兑换码模组。它允许服务器管理员生成和分发兑换码，玩家可通过兑换码获取物品、经验或权限等级。模组支持七种不同的兑换码类型，涵盖从一次性奖励到周期性每日奖励等多种使用场景。

仅需在服务器端安装此模组；客户端无需安装即可连接。不过，当客户端也安装该模组时，消息会通过 Minecraft 内置的翻译系统显示，以获得更好的体验。

功能

七种兑换码类型 — ONCE、PERMANENT、PERSONAL、GLOBAL_UNLIMITED、GLOBAL_LIMIT、TIMED 和 CYCLE，涵盖从一次性使用到周期性奖励的各种需求。

灵活的奖励 — 给予物品（含 NBT 数据）、经验点数/等级或临时权限等级。您甚至可以将手中物品直接设置为奖励。

三种存储后端 — 数据可持久化至本地 JSON 文件、MySQL 数据库或 Redis。若配置的后端不可达，将自动回退至文件存储。

内置网页管理面板 — 基于浏览器的管理员界面，带有登录认证。可在浏览器中创建、查看和删除兑换码，浏览操作日志，检查服务器状态并查看配置。

生产级连接池 — 模仿 HikariCP 的自定义 SQL 连接池，具有弹性池大小、连接生命周期管理、空闲超时回收、泄漏检测、保活心跳及优雅关闭功能。

异步 I/O 架构 — 所有阻塞 I/O 操作（SQL、Redis、文件、网页）均在专用线程池上运行，确保 Minecraft 服务器主线程永不被阻塞。

热重载配置 — 可通过 /rcode reload 命令或网页面板在运行时更改并重载设置。Web 服务器、SQL 连接池和 Redis 连接池均可动态重新初始化。

国际化支持 — 服务器端消息会根据系统语言（中文和英文）自动适配。客户端安装模组后，消息则使用 Minecraft 的翻译系统。

详细操作日志 — 每次生成、兑换和删除操作都会记录时间戳、执行者信息和详细内容，便于审计。

兑换码类型

类型 描述
ONCE 任何单个玩家仅能兑换一次。
PERMANENT 总使用次数无限制；每个玩家可任意次兑换。
PERSONAL 限制给特定玩家（通过 UUID、名称或 @selector）；可兑换一次。
GLOBAL_UNLIMITED 每位玩家可兑换一次；无全局上限。
GLOBAL_LIMIT 共享的全局使用限制。可选择性地限制给匹配特定标签或计分板排名的玩家（前 N 名或后 N 名）。
TIMED 仅在指定的时间窗口内有效；每位玩家可兑换一次。
CYCLE 重复的时间窗口（例如每天）。每个周期内每位玩家可兑换一次。

奖励类型

格式 描述 示例
item@<id>{nbt} 给予一个物品，可附带 NBT 数据。 item@minecraft:diamond_sword{Enchantments:[{id:"sharpness",lvl:5}]}
[hand] 捕捉生成时主手中持有的物品。 [hand]
exp@<数量>P 给予经验点数。 exp@100P
exp@<数量>L 给予经验等级。 exp@5L
permissions@<等级> 授予临时权限等级（需管理员联系）。 permissions@2

如果未指定后缀，则默认为经验点数。

命令

所有命令均通过 CommandRegistrationCallback 在服务器端注册。基础命令为 /rcode。

玩家命令

/rcode redeem <code>

兑换一个兑换码。所有玩家可用。

操作员命令（权限等级 2+）

/rcode generate <type> [options] <reward>

生成一个新的兑换码。若未指定自定义兑换码字符串，则会生成一个随机的 16 位字母数字兑换码。

示例：

# 一次性兑换码，自动生成 ID
/rcode generate once item@minecraft:diamond 64

# 永久兑换码，自定义 ID
/rcode generate permanent code MYCODE exp@10L

# 指定玩家的个人兑换码
/rcode generate personal Steve item@minecraft:netherite_sword

# 全局有限兑换码（标签为 "vip" 的前 3 名玩家）
/rcode generate global_limit tag vip 3 item@minecraft:elytra

# 全局有限兑换码（计分板 "score" 的后 5 名玩家）
/rcode generate global_limit scoreboard score -5 item@minecraft:gold_ingot 32

# 定时兑换码（从 2025-01-01 到 2025-12-31 有效）
/rcode generate timed 2025-01-01_00-00-00 2025-12-31_23-59-59 exp@100P

# 周期兑换码（每天，从现在开始）
/rcode generate cycle 0-0-0_0-0-0 86400 item@minecraft:golden_apple

在 generate 命令末尾添加 cover 可以覆盖已存在的兑换码：

/rcode generate once code MYCODE item@minecraft:diamond cover

时间格式： yyyy-MM-dd_HH-mm-ss。使用 0-0-0_0-0-0 或 0 表示“立即开始”。

删除一个兑换码。

/rcode delete <code>

显示兑换码的详细信息，包括类型、奖励、使用统计以及已兑换的玩家。在线玩家显示名称；离线玩家显示 UUID。

/rcode info <code>

管理员命令（权限等级 4）

/rcode reload

热重载配置文件并重新初始化所有 I/O 资源（SQL 连接池、Redis 连接池、Web 服务器）。

网页管理面板

在配置文件中启用网页面板：

web.enabled=true
web.port=8080

面板提供：

  • 登录页面 (index.html) — 使用用户名/密码进行认证（在配置文件中设置）。
  • 管理仪表盘（自定义路径，首次运行时自动生成）— 完整的管理界面，包括：
    • 服务器状态概览（在线玩家、总兑换码数、存储后端、模组版本）
    • 兑换码管理（列表、创建、查看详情、删除）
    • 带分页的操作日志浏览器
    • 在线玩家列表（含 UUID、Ping、IP 和标签）
    • 计分板目标查看器
    • 配置查看器（敏感值被屏蔽）
    • 热重载按钮

出于安全考虑，管理面板路径在首次启动时随机生成。您可以在配置文件的 web.adminPath 下找到它。密码也会自动生成并存储在 web.password 中。

当 web.sendUrlToOP=true 时，操作员在加入服务器时会通过聊天收到面板 URL。

存储后端

在 redemptioncodefabric.properties 中配置存储后端：

# 选项：file、sql、redis
datastore.type=file

文件（默认）— 将兑换码和日志作为 JSON 文件存储在模组的配置目录中。无需任何设置。

SQL (MySQL) — 需要运行中的 MySQL 服务器。表（redemption_codes、operation_logs）会在首次连接时自动创建。连接参数：

sql.host=localhost
sql.port=3306
sql.user=admin
sql.password=
sql.database=redemptioncode

Redis — 需要运行中的 Redis 服务器。兑换码以 Redis 哈希形式存储，并附带基于集合的索引。如果 Redis 不可用，将回退到文件存储。

redis.host=localhost
redis.port=6379
redis.password=
redis.database=0

SQL 和 Redis 连接均使用重试逻辑（3 次尝试，间隔 2 秒）。如果所有尝试均失败，模组会自动回退到文件存储，并向在线操作员发出警告。

连接池

使用 SQL 后端时，Simple 连接池提供生产级的连接管理：

特性 描述
弹性池大小 在 minIdle 和 maxPoolSize 之间按需伸缩
连接生命周期 超过 maxLifetime 的连接在释放时会被淘汰
空闲超时回收 超过 idleTimeout 的空闲连接会被移除（维持 minIdle）
泄漏检测 当连接持有时间超过 leakDetectionThreshold 时发出警告
保活心跳 定期使用 isValid() 验证空闲连接
借用验证 每个连接在分配前都会进行验证
获取超时 当池满时，最多等待 connectionTimeout 毫秒
优雅关闭 停止维护、清空空闲连接、等待正在使用的连接，然后强制关闭
初始化 SQL 在每个新连接上执行 connectionInitSql

所有连接池参数均可在属性文件的 pool.* 命名空间下进行配置。

配置

配置文件位于 config/redemptioncodefabric/redemptioncodefabric.properties。首次启动时会自动创建，包含分类好的章节和注释。

# ── 数据存储 ──────────────────────────────────────────
datastore.type=file

# ── 日志记录 ────────────────────────────────────────────
log.redemption.history=true
log.max.entries=20000

# ── Web 服务器 ─────────────────────────────────────────
web.enabled=false
web.url=http://localhost
web.port=8080
web.user=admin
web.password=<auto-generated>
web.adminPath=<auto-generated>
web.sendUrlToOP=true

# ── SQL (MySQL) ────────────────────────────────────────
sql.host=localhost
sql.port=3306
sql.user=admin
sql.password=
sql.database=redemptioncode
sql.url=jdbc:mysql://localhost:3306/redemptioncode?useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true

# ── Redis ──────────────────────────────────────────────
redis.host=localhost
redis.port=6379
redis.password=
redis.database=0

# ── 连接池 ────────────────────────────────────
pool.maxPoolSize=10
pool.minIdle=2
pool.connectionTimeout=30000
pool.idleTimeout=600000
pool.maxLifetime=1800000
pool.leakDetectionThreshold=60000
pool.keepaliveTime=300000
pool.validationTimeout=5000
pool.connectionInitSql=

依赖项

  • Minecraft 1.20.1
  • Fabric Loader >= 0.18.4
  • Fabric API
  • Java >= 17
  • MySQL Connector/J 9.7.0（已捆绑，shaded）
  • Jedis 5.2.0（已捆绑，shaded）

许可证

本项目基于 GNU General Public License v3.0 许可。

第三方依赖项许可证请参阅 CREDITS.md。

链接