马格努斯

Magnus（服务端）

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

功能特性

核心同步

• 多服务器同步：同步背包、末影箱、生命值、饥饿值、经验值、药水效果。
• 高性能：使用 Redis 实现亚毫秒级数据检索。
• 持久性：使用 PostgreSQL 进行永久可靠的存储。
• 容错性：
  • 熔断器：自动检测数据库故障。
  • 本地回退：数据库宕机时将数据保存到磁盘。
  • 自动恢复：“管理员”（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 将自动验证连接并创建必要的数据库架构。

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

配置选项

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

命令

命令	描述
/glist	显示总玩家数并按服务器分组的玩家列表（需要启用 enableGlobalPlayerList）

架构

详细的流程图表和行为文档：

• 核心同步流程 - 数据同步和容错
• 全局聊天流程 - 跨服务器聊天消息
• 全局玩家列表流程 - 玩家列表心跳和 /glist
• 会话锁定流程 - 登录队列和会话锁定
• 消息安全流程 - HMAC 签名和重放防护
• 服务器生命周期流程 - 启动和关闭流程