LatticeProxy

📖 简介

LatticeProxy 是一个基于 Velocity 的高性能 Minecraft 群组代理，用于连接多个 Minecraft 服务器，实现玩家在不同服务器之间的无缝切换。

🚀 安装部署

系统要求

• Java 17 或更高版本（推荐 Java 21）
• Windows / Linux / macOS
• 至少 512MB 内存（推荐 1GB+）
• 稳定的网络连接

下载与安装

# 1. 下载 LatticeProxy
# 从 GitHub Releases 下载最新版本
# https://github.com/your-repo/LatticeProxy/releases

# 2. 创建服务器目录
mkdir LatticeProxy
cd LatticeProxy

# 3. 放置 JAR 文件
# 将下载的 LatticeProxy.jar 放入目录

# 4. 首次运行（生成配置文件）
java -jar LatticeProxy.jar

目录结构

LatticeProxy/
├── LatticeProxy.jar          # 代理主程序
├── LatticeProxy.toml         # 代理配置文件
├── serverconfig.yml          # 服务器启动配置
├── message.yml               # 消息配置
├── velocity.toml             # Velocity 兼容配置
├── plugins/                  # 插件目录
├── logs/                     # 日志目录
├── lobby/                    # 大厅服务器目录
│   └── server.jar
├── survival/                 # 生存服务器目录
│   └── server.jar
└── start.bat / start.sh      # 启动脚本

启动方式

# Windows
start.bat

# Linux/Mac
chmod +x start.sh
./start.sh

# 手动启动
java -jar LatticeProxy.jar

⚙️ 代理配置

LatticeProxy.toml

这是代理的核心配置文件，控制代理的基本行为。

# 代理绑定配置
bind = "0.0.0.0:25566"

# 最大玩家数
max-players = 500

# 服务器 MOTD（消息 of the day）
motd = "&bSoftCloudMC - 最有趣的我的世界服务器"

# 是否显示服务器图标
show-max-players = true

# 玩家转发模式
# none: 不转发玩家信息
# legacy: 使用旧版转发
# modern: 使用现代转发（推荐）
player-info-forwarding-mode = "modern"

# 默认登录服务器（玩家首次连接时进入的服务器）
try = ["lobby"]

# 服务器列表
[servers]
  # 大厅服务器
  [servers.lobby]
  address = "127.0.0.1:30001"
  motd = "&a大厅服务器"
  try = true
  
  # 生存服务器
  [servers.survival]
  address = "127.0.0.1:30002"
  motd = "&6生存服务器"
  
  # 小游戏服务器
  [servers.minigames]
  address = "127.0.0.1:30003"
  motd = "&d小游戏服务器"

配置项说明

🖥️ 服务器设置

配置后端服务器

每个后端服务器都需要配置为"代理模式"，以接受来自代理的连接。

1. Paper/Spigot 服务器

编辑 spigot.yml：

settings:
  bungeecord: true  # 启用 BungeeCord 兼容模式

如果使用 Velocity 现代转发，编辑 paper-global.yml：

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "your-secret-key"  # 与代理配置中的密钥一致

2. 设置服务器端口

编辑每个服务器的 server.properties：

# 大厅服务器
server-port=30001

# 生存服务器
server-port=30002

# 小游戏服务器
server-port=30003

serverconfig.yml

配置自动启动的服务器列表：

# 默认登录服务器
try:
  - "lobby"

# 服务器列表
servers:
  # 代理本身（必须第一个）
  - name: "LatticeProxy"
    directory: "."
    jar: "LatticeProxy.jar"
    jvm_args: "-Xms256M -Xmx512M"
    auto_restart: true

  # 大厅服务器
  - name: "lobby"
    directory: "lobby"
    jar: "server.jar"
    jvm_args: "-Xms1G -Xmx2G"
    auto_restart: true

  # 生存服务器
  - name: "survival"
    directory: "survival"
    jar: "server.jar"
    jvm_args: "-Xms2G -Xmx4G"
    auto_restart: false

启动顺序

1. 启动 LatticeProxy 代理
2. 启动所有后端服务器
3. 等待服务器完全启动（看到 "Done!" 消息）
4. 玩家即可连接

🎮 玩家连接

连接方式

玩家只需连接到代理的 IP 和端口即可。

# 玩家连接地址
服务器地址: your-server.com:25566
# 或
服务器地址: 123.45.67.89:25566

连接流程

1. 玩家在 Minecraft 中添加服务器
2. 输入代理的 IP 和端口（如 your-server.com:25566）
3. 代理接收连接
4. 代理根据配置将玩家路由到默认服务器（如 lobby）
5. 玩家进入服务器

服务器切换

玩家可以在游戏中切换到其他服务器：

# 使用 /server 命令
/server survival
/server minigames
/server lobby

# 查看可用服务器
/server

在线模式

LatticeProxy 支持正版验证：

• 在线模式 - 玩家需要正版账号登录
• 离线模式 - 允许盗版玩家连接（不推荐）

在 LatticeProxy.toml 中配置：

# 在线模式（推荐）
online-mode = true

# 离线模式
online-mode = false

💻 命令使用

控制台命令

在代理控制台中可以执行以下命令：

游戏内命令

玩家在游戏中可以使用的命令：

命令示例

# 向大厅服务器发送消息
lobby-say 欢迎来到大厅服务器！

# 向所有服务器广播
/hh 服务器将于 10 分钟后维护

# 查看服务器状态
status

# 重启生存服务器
restart survival

# 玩家切换服务器
/server survival
/server lobby

🔌 插件开发

LatticeProxy 兼容 Velocity 插件生态，你可以使用现有的 Velocity 插件或开发自己的插件。

安装插件

1. 下载 Velocity 兼容的插件 JAR 文件
2. 将 JAR 文件放入 plugins/ 目录
3. 重启代理

推荐插件

开发自定义插件

LatticeProxy 提供 API 用于开发自定义插件：

import com.latticeproxy.api.event.Subscribe;
import com.latticeproxy.api.event.connection.PostLoginEvent;
import com.latticeproxy.api.plugin.LatticeProxyPlugin;
import com.latticeproxy.api.proxy.ProxyServer;

public class MyPlugin implements LatticeProxyPlugin {
    private ProxyServer server;

    @Override
    public void onInitialize(ProxyServer server) {
        this.server = server;
        
        // 注册事件监听
        server.getEventManager().register(this, this);
        
        server.getLogger().info("插件已加载！");
    }

    @Subscribe
    public void onPostLogin(PostLoginEvent event) {
        String playerName = event.getPlayer().getUsername();
        server.getLogger().info("玩家登录: " + playerName);
    }
}

🔧 问题排查

常见问题

Q: 玩家无法连接到代理？

检查：

• 代理是否正在运行
• 防火墙是否允许代理端口（默认 25566）
• 玩家是否使用了正确的 IP 和端口
• 查看控制台是否有错误日志

Q: 玩家连接后被踢出？

可能原因：

• 后端服务器未启动
• 服务器地址配置错误
• 转发模式不匹配（legacy/modern）
• 在线模式配置冲突

Q: 无法切换到其他服务器？

检查：

• 目标服务器是否正在运行
• 服务器是否在 LatticeProxy.toml 中配置
• 玩家是否有权限切换到该服务器

Q: 玩家信息显示为 "Steve" 或 "Not authenticated"？

解决方案：

• 确保代理和后端服务器的转发模式一致
• 检查 player-info-forwarding-mode 配置
• 后端服务器需要配置 bungeecord: true 或 Velocity 转发

Q: 服务器崩溃后没有自动重启？

检查：

• serverconfig.yml 中 auto_restart 是否设置为 true
• 查看控制台日志确认崩溃原因

日志查看

# 查看实时日志
tail -f logs/latest.log

# 查看代理日志
cat logs/latticeproxy.log

# 查看特定服务器日志
cat logs/lobby.log

调试模式

启用调试模式以获取更详细的日志：

# 启动时添加参数
java -jar LatticeProxy.jar -Ddebug=true