马格努斯

马格努斯

一个模块化、高性能且具备弹性的 Minecraft Fabric 服务器同步套件。具备实时物品栏同步、跨服务器聊天和全局玩家管理功能。

管理

Magnus(服务端)

构建状态 Minecraft 版本 Fabric Kotlin GitHub 发布 Modrinth 版本 CurseForge 版本 PostgreSQL Redis Trivy 许可证

一套面向 Minecraft Fabric 服务器的模块化、高性能且高弹性的同步套件。具备实时物品栏同步、跨服聊天和全局玩家管理功能。

功能特性

核心同步

  • 多服务器同步:同步物品栏、末影箱、生命值、饥饿值、经验值和药水效果。
  • 高性能:使用 Redis 实现亚毫秒级数据读取。
  • 持久化:使用 PostgreSQL 进行永久可靠的存储。
  • 容错能力:
    • 断路器:自动检测数据库故障。
    • 本地回退:当数据库宕机时将数据保存到磁盘。
    • 自动恢复:“The Janitor”服务会在数据库恢复上线后自动还原数据。

模块

模块 描述
物品栏同步 同步物品栏、末影箱、生命值、饥饿值、经验值和药水效果的核心功能。默认启用。
全局聊天 通过 Redis 发布/订阅在所有服务器间同步聊天消息。采用纯文本格式,以兼容 LuckPerms、Stylist 等。
全局玩家列表 通过心跳机制维护全局玩家数量。提供 /glist 命令。
会话锁定 在同步期间锁定玩家会话,防止并发登录。玩家将被置于队列中,直到其数据安全转移完毕。

安全

功能 默认值 描述
消息签名 ✅ 启用 HMAC-SHA256 防止消息注入攻击
自动生成密钥 ✅ 首次运行时生成 32 字节的加密密钥
防重放 30 秒 超过 30 秒的消息将被拒绝
载荷大小限制 64KB 防止通过超大消息发起 DoS 攻击
SSL/TLS 支持 可选 加密 Redis 连接

配置

Magnus 需要 PostgreSQL 数据库和 Redis 实例才能运行。

  1. 生成配置:启动一次服务器,在 config/magnus.json 生成默认配置文件。
  2. 编辑配置:停止服务器并打开 config/magnus.json:
{
    "postgresUrl": "jdbc:postgresql://your-db-host:5432/magnus",
    "postgresUser": "your_user",
    "postgresPass": "your_password",
    "redisHost": "your-redis-host",
    "redisPort": 6379,
    "redisPass": null,
    "serverName": "survival",
    "enableInventorySync": true,
    "enableGlobalChat": false,
    "enableGlobalPlayerList": false,
    "enableSessionLock": false,
    "enableMessageSigning": true,
    "messageSigningSecret": "auto-generated-on-first-run",
    "redisSsl": false
}
  1. 启动:重启服务器。Magnus 会自动验证连接并创建所需的数据库架构。

[!IMPORTANT] 多服务器设置:将第一台服务器的 messageSigningSecret 复制到所有其他服务器。所有服务器必须使用相同的密钥。

配置选项

选项 默认值 描述
serverName "default" 此服务器的唯一标识符(例如 "survival"、"lobby")
enableInventorySync true 启用物品栏/玩家数据同步。大厅服务器请禁用。
enableGlobalChat false 启用跨服聊天同步
enableGlobalPlayerList false 启用全局玩家列表和 /glist 命令
enableSessionLock false 启用会话锁定以防止并发登录
enableMessageSigning true 启用 HMAC 消息签名(推荐)
redisSsl false 为 Redis 连接启用 SSL/TLS

命令

命令 描述
/glist 显示总玩家数量及按服务器分组的玩家(需要 enableGlobalPlayerList)

架构

详细的流程图和行为文档: