Syncmoney

插件

· 作者 misty4119

Minecraft 跨服经济同步插件

0 本站下载 0 关注 更新于 1 周前

最新 1.4.0 · 26.3 · Folia / Paper

一键开服(送7天)

Syncmoney

CI CodeQL

A Vault-compatible Minecraft economy with optional Redis-backed synchronization, administration, audit tools, and PlaceholderAPI support.

Overview

Syncmoney manages player balances, currency operations, and its own economy commands. It supports single-server SQLite economies, Redis-backed cross-server synchronization, relational persistence, and an optional CMI-authoritative currency sync mode. It does not replicate arbitrary permissions or third-party commands.

The current stable release is 1.4.0 and requires Java 25 or newer. Check the release page for official downloads and version-specific notes.

Key Features

  • Vault 1.7 economy compatibility and optional VaultUnlocked integration.
  • local SQLite, local_redis, and sync economy modes.
  • Redis Pub/Sub cross-server balance synchronization with version checks and echo suppression.
  • Optional MySQL, MariaDB, or PostgreSQL persistence for shared sync mode.
  • CMI-authoritative currency synchronization over Redis. CMI remains the economy authority in this mode.
  • Player balance, payment, leaderboard, and administration commands.
  • Transaction audit history, account safeguards, circuit-breaker tools, and Shadow Sync snapshots.
  • Optional embedded Web Admin with authenticated HTTP endpoints and server-sent events (SSE).
  • Separate PlaceholderAPI expansion and transaction events for internal telemetry.
  • Recovery records for accepted queued payments with ambiguous Redis outcomes; unresolved operations remain quarantined for administrator review.

Platform & Compatibility

Component Requirement or status
Server engine Paper-compatible servers. Minecraft 26.2–26.3 on Paper, Folia, and Canvas are the 1.4.0 target matrix. Plain Spigot is not supported.
Java runtime Java 25 or newer for Syncmoney 1.4.0.
Economy bridge Vault 1.7 or compatible VaultUnlocked for interoperability. Vault is optional. CMI mode does not register a Syncmoney economy provider.
Message broker Redis is required for local_redis, sync, and cmi modes.
Database Local SQLite for local; MySQL, MariaDB, or PostgreSQL for shared SQL persistence in sync.
Optional integrations PlaceholderAPI uses the separate SyncmoneyExpansion JAR. CMI mode requires CMI, CMILib, and Redis; obtain CMI and CMILib from their publishers and comply with their licenses.

The 1.4.0 target range is not a blanket guarantee for every mode or integration. The 1.4.0 release notes identify the exact server builds and scenarios exercised for this release. Validate upgrades on a staging server before changing production economy data.

The configuration schema has its own version and is separate from the plugin version. Back up configuration and economy data before upgrading.

Installation & Setup

  1. 备份你的数据。 停止服务器,并备份经济系统所使用的 Syncmoney 配置、SQLite 或 SQL 数据库以及 Redis 数据。
  2. 安装 JAR 文件。 从 1.4.0 发布页面 下载 Syncmoney-1.4.0.jar 并将其放入服务器的 plugins/ 目录中。移除旧版的 Syncmoney JAR 文件,以确保只加载一个版本。
  3. 安装模式依赖项。 local 模式使用 SQLite。local_redis 需要 Redis。sync 需要 Redis 和关系型数据库。cmi 需要 CMI、CMILib 和 Redis。Vault 或 VaultUnlocked 是用于 Syncmoney 管理经济模式的可选互操作性支持。
  4. 生成并编辑配置文件。 启动服务器一次,然后停止它。在 plugins/Syncmoney/config.yml 中为每个服务器设置一个唯一且非空的 server-name。
  5. 选择经济模式。 配置该模式所需的 Redis 和数据库连接。在使用 cmi 模式时,请保持 CMI 作为唯一的经济权威机构。
  6. 设置 PlaceholderAPI(可选)。 将 SyncmoneyExpansion-1.4.0.jar 安装到 plugins/PlaceholderAPI/expansions/ 中,然后运行 /papi reload。扩展版本必须与核心 JAR 文件匹配。
  7. 设置 Web Admin(可选)。 在启用 Web Admin 之前,替换掉随附的 API-key 占位符。CMI 同步专用模式不会启动 Web Admin。
  8. 在开启交易前进行验证。 确认配置的经济权威机构和所需服务已加载,然后在测试环境中测试所选模式。

经济模式

模式 (economy.mode) 存储与架构 适用环境
local 各服务器独立的 SQLite 存储。不需要 Redis 和共享 SQL。 独立服务器。
local_redis 基于 Redis 的余额,无共享 SQL 持久化。 使用 Redis 共享余额的网络。
sync Redis Pub/Sub 加上共享 SQL 持久化。 需要关系型存储的多服务器网络。
cmi CMI 仍作为货币权威;Redis 在各服务器间传递 CMI 余额更新。 已经使用 CMI 作为其经济系统的网络。禁用由 Syncmoney 管理的经济命令和服务。
auto 检测已安装的环境并推荐一种模式。 评估阶段。生产环境请显式设置一种模式。

在将现有的 Redis 经济切换至 local_redis 或 sync 之前,请将余额与共享模式的最大值 999999999999999999.99 进行核对。1.4.0 版本不会自动扫描、限制或迁移现有的 Redis 余额。

最小化独立配置 (local)

为每次安装使用不同的服务器名称。以下示例禁用了 Redis 和共享 SQL,同时保留本地 SQLite 存储:

server-name: "single-01"
pubsub-enabled: false
db-enabled: false
economy:
  mode: "local"
redis:
  enabled: false
database:
  enabled: false

共享网络配置 (sync)

启用 Redis Pub/Sub 和共享数据库。将所有参与服务器指向同一个 Redis 数据库和 SQL 架构,为每台服务器提供唯一的 server-name,并在各自的本地配置文件中提供连接凭据。

server-name: "survival-01"
pubsub-enabled: true
db-enabled: true
economy:
  mode: "sync"
redis:
  enabled: true
  host: "redis.example.net"
  port: 6379
database:
  enabled: true
  type: "mysql"
  host: "sql.example.net"
  port: 3306
  database: "syncmoney"

请在本地设置凭据;切勿公开它们。如需更多服务器特定设置,请编辑生成的配置文件并查阅 开发者指南。

可选模块与生命周期

可选模块在 plugins/Syncmoney/config.yml 中进行配置。

模块 配置开关 描述
全局熔断器 circuit-breaker.enabled 当达到配置的异常阈值时,停止受管理的经济操作。
玩家级保护 circuit-breaker.player-protection.enabled 添加玩家级别的速率限制和账户保护;它与全局熔断器开关是分开的。
转账守卫 transfer-guard.enabled 保护玩家免受跨服务器传输和传送过程中余额不一致的影响。
审计日志 audit.enabled 记录交易历史。清理、导出和 Redis 审计功能依赖于父级审计开关。
Shadow Sync shadow-sync.enabled 将数据镜像到辅助存储目标以生成快照;它不能替代数据库备份。
Discord webhooks discord-webhook.enabled 发送针对支持事件的配置通知。
Web Admin web-admin.enabled 当其安全配置有效时,启动嵌入式 HTTP 仪表板。

/syncmoney reload 仅对 display、pay、permissions、admin-permissions 和 debug 应用实时更改。对连接、经济权威、调度器所有权或模块构造的更改需要完全重启服务器。

CMI 模式为同步专用模式。它保持 CMI 作为经济权威,并仅启动其 CMI 余额同步路径及 /syncmoney version;它不注册 Syncmoney 的 Vault 提供程序或经济查询 API,并禁用 Syncmoney 钱包、转账、排行榜和管理模块。在 CMI 模式下,Syncmoney 余额、排名和排行榜占位符不可用。此模式不支持 /pay 和其他 Syncmoney 配对传输操作。

命令与权限

玩家命令

命令 描述 权限
/money 查看你的余额。 syncmoney.money (默认: true)
/money <player> 查看其他玩家的余额。 syncmoney.money.others (默认: op)
/pay <player> <amount> 向其他玩家发送金钱。 syncmoney.pay (默认: true)
/baltop [page] 查看余额排行榜。 syncmoney.money (默认: true)
/baltop me 查看你的排行榜位置。 syncmoney.money (默认: true)

在 CMI 模式下,这些由 Syncmoney 管理的经济命令不可用,因为 CMI 仍是经济系统的权威方。

管理命令

命令 描述 权限
/syncmoney admin give <player> <amount> 为玩家增加余额。 syncmoney.admin.give 或配置的管理员层级
/syncmoney admin take <player> <amount> 扣除玩家的余额。 syncmoney.admin.take 或配置的管理员层级
/syncmoney admin set <player> <amount> 设置玩家的余额。 syncmoney.admin.set 或配置的管理员层级
/syncmoney admin reset <player> 重置玩家的余额。 syncmoney.admin.set 或配置的管理员层级
/syncmoney audit <player> [page] 查看审计历史。 syncmoney.admin.audit
/syncmoney monitor [redis|cache|db] 查看系统和资源状态。 syncmoney.admin.monitor
/syncmoney migrate <cmi|local-to-sync> 运行显式的经济迁移。 syncmoney.admin
/syncmoney recovery list 列出等待恢复审查的排队转账。 syncmoney.admin.recovery 或 syncmoney.admin
/syncmoney recovery inspect <id> 检查一个被隔离的转账。 syncmoney.admin.recovery 或 syncmoney.admin
/syncmoney recovery reconcile <id> 使用精确的 Redis 操作收据进行对账。 syncmoney.admin.recovery 或 syncmoney.admin
/syncmoney version [full|save] 显示版本和支持诊断信息。 基础:公开;full/save:syncmoney.admin

其他管理子命令包括 breaker、debug、econstats、reload、shadow、sync-balance、test 和 web(如果已启用)。命令可用性取决于所选模式和模块配置。请检查 src/main/resources/plugin.yml 和该命令的具体权限以获取有效的访问规则。

管理员权限层级

在 config.yml 下的 admin-permissions 中配置层级。

层级 权限节点 默认每日限额
观察 syncmoney.admin.observe 仅查看;0 给予 / 0 扣除
奖励 syncmoney.admin.reward 100,000 给予 / 0 扣除
常规 syncmoney.admin.general 1,000,000 给予 / 1,000,000 扣除
完全 syncmoney.admin.full 无限经济操作

每日限额开关和层级限额均可配置。根权限 syncmoney.admin 和特定于命令的权限节点也在 src/main/resources/plugin.yml 中声明。

PlaceholderAPI 标识符

将 SyncmoneyExpansion-1.4.0.jar 与 1.4.0 核心 JAR 一起安装,即可使用以下 PlaceholderAPI 标识符:

占位符 描述
%syncmoney_balance% 你的数值余额。
%syncmoney_balance_formatted% 带有货币格式化的余额。
%syncmoney_balance_abbreviated% 缩写后的余额,例如 1.5K。
%syncmoney_balance_<player>% 指定玩家的余额。
%syncmoney_balance_formatted_<player>% 指定玩家的格式化余额。
%syncmoney_balance_abbreviated_<player>% 指定玩家的缩写余额。
%syncmoney_rank% / %syncmoney_my_rank% 你的排行榜排名。
%syncmoney_top_<n>% 排行榜第 n 名的余额。
%syncmoney_total_supply% 总货币供应量。
%syncmoney_total_players% 排行榜跟踪的账户数量。
%syncmoney_online_players% 在线玩家数量。
%syncmoney_version% 当前活动的 Syncmoney 版本。

全局和排名查找使用缓存的异步工作。缓存未命中不会阻塞服务器线程。Syncmoney 余额、排名和排行榜占位符在 CMI 模式下不可用。

Web 管理面板设置与安全

Web 管理面板是可选的,默认情况下处于禁用状态。启用后,它将提供嵌入式仪表板和经过身份验证的 REST 端点。

web-admin:
  enabled: true
  server:
    host: "127.0.0.1"
    port: 8080
  security:
    api-key: "change-me-in-production" # 在启用 Web 管理面板之前替换此值。
    cors-allowed-origins:
      - "https://admin.example.com"

空密钥或随附的占位符会禁用 Web 管理面板,但允许经济插件启动。CMI 同步模式不会启动此模块。

安全建议

  1. 绑定本地地址。 将 Web 管理面板保持在回环接口上,并使用带 HTTPS 的反向代理进行远程浏览器访问。
  2. 使用私有密钥。 将随附的 API-key 占位符替换为长随机值,切勿发布。
  3. 限制浏览器来源。 仅设置所需的 CORS 来源;在生产环境中不要使用 *。
  4. 限制网络访问。 对 HTTP 端口进行防火墙保护,并保护任何反向代理路由。
  5. 使用当前的实时端点。 仪表板使用 HTTP 和 /api/sse;/ws 始终响应 503 WEBSOCKET_UNAVAILABLE,并非 WebSocket 服务。

开发者集成

Vault 提供者访问

在 Syncmoney 管理的经济模式中,插件可以通过 Bukkit 的服务管理器发现 Vault 1.7 提供者:

RegisteredServiceProvider<Economy> registration =
    getServer().getServicesManager().getRegistration(Economy.class);

if (registration != null) {
    Economy economy = registration.getProvider();
    double balance = economy.getBalance(player);
}

当存在 VaultUnlocked 时,Syncmoney 还会注册其 Vault2 提供者。CMI 模式是纯同步模式,不注册 Syncmoney Vault 提供者或经济查询 API。

交易事件

AsyncPreTransactionEvent 在接受的存款和取款路径之前发送,可以取消操作。PostTransactionEvent 在结果已知后报告结果。这些事件类通过 Syncmoney 的内部事件总线分发;它们不是通过 Bukkit 的 PluginManager 事件注册传递的。在与内部事件行为集成之前,请参阅 开发者指南。

从源代码构建

1.4.0 目标使用 Java 25 和 Gradle 9.8.0。Java 21 和 Gradle 9.1.0 描述了保留的 1.3.2 基线。

# 核心插件、PAPI 扩展、API 消费者及验收制品
./gradlew test :syncmoney-papi-expansion:test shadowJar :syncmoney-papi-expansion:jar acceptanceJar

# Windows PowerShell
.\gradlew.bat test :syncmoney-papi-expansion:test shadowJar :syncmoney-papi-expansion:jar acceptanceJar

# Web 前端检查
cd syncmoney-web
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test:unit --run
pnpm build

核心 JAR 文件生成于 build/libs/;扩展 JAR 文件生成于 syncmoney-papi-expansion/build/libs/。修改 Web Admin 源码后,请在 syncmoney-web 目录下运行 pnpm build:embedded,并通过 WebAdminServer.extractIndividualFiles 审查生成的捆绑包。

发布与 CI 工作流

拉取请求和 main 分支更新会触发仓库内的 Java 和 Web 检查。CI 产物仅用于测试,并非公开的 GitHub Releases。

稳定版核心发布标签无前缀,例如 1.4.0;alpha 和 beta 标签为预发布版本。Web Admin 源码维护于此仓库中,并镜像至 Syncmoney-web;镜像使用对应的带 v 前缀的标签(如 v1.4.0)以及确定性源归档文件。请访问 GitHub 发布页面 获取官方 JAR 文件和特定版本的说明。

对于前端发布,请在 syncmoney-web 目录下运行 pnpm build:embedded,以便同步更新嵌入式发行版和 Java 提取列表。

故障排除与支持

  • 余额不同步: 确认每个节点都使用相同的 Redis 实例和数据库,启用了 Pub/Sub,且每个服务器都有唯一的 server-name。
  • 插件无法启动: 检查 server-name 是否为空,所需模式的依赖项是否已安装,以及在 cmi 模式下是否启用了 CMI。
  • 共享模式交易被拒绝: 在将现有网络切换为 local_redis 或 sync 之前,请检查是否存在高于共享模式最大值的存储 Redis 余额。
  • 配置更改未生效: 连接、模式、调度器和模块所有者的更改需要完全重启服务器。
  • Web Admin 无法启动: 替换内置的 API-key 占位符,并确保仅在支持该功能的模式下启用 Web Admin。
  • 报告问题: 请包含 /syncmoney version 输出、服务器软件构建版本、Java 版本以及脱敏后的日志/配置。请隐藏密码、API 密钥和 webhook URL。管理员可以使用 /syncmoney version full 进行只读后端探测,或使用 /syncmoney version save 写入脱敏报告。
  • GitHub Issues: 问题追踪器
  • 社区 Discord: 加入社区

许可证

本项目根据 Apache License 2.0 许可协议授权。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源