面向 Minecraft 1.7.10 Forge 的玩家会话代理：登录认证、协议转发、跨后端转服，以及供插件使用的玩家、服务器目录、富文本、命令补全、类型化事件和 Channel 消息服务。后端插件共享认证连接，通过 channel 与 proxy 或其他 backend 通信。空岛分配、实例唤醒和 Ban 数据存储由插件实现。

文档

文档索引：按运维、插件开发和架构主题浏览。
运行配置：认证模式、监听范围、入口后端和部署约束。
初次登录路由：候选顺序、插件接管、期限和安全重试边界。
插件开发：Proxy API、事件、命令、转服和初始选服。
玩家权限与 LuckPerms：统一权限接口、命令鉴权和原生平台插件。
后端 Bukkit 插件接入：共享宿主、API 依赖与 Channel 示例。
发布与依赖版本、架构与验证方法。

本机运行

需要 JDK 25。发行包不包含 Minecraft 后端；要完成玩家登录，需启动一个 Minecraft 1.7.10 后端，并让 initialRouting.servers 中至少一个名称能解析到它。

git submodule update --init --recursive
.\gradlew.bat check :proxy-core:installDist
.\proxy-core\build\install\moonbridge\bin\moonbridge.bat --config .\proxy-core\build\install\moonbridge\config\moonbridge.yml

默认配置为 OFFLINE，仅监听 127.0.0.1:25577，后端为 127.0.0.1:25565。公开部署使用 ONLINE_BUNGEE，并限制玩家直连后端。详见运行配置。

随附配置的入口候选为 lobby，地址为 127.0.0.1:25565。如果后端名称或地址不同，请编辑发行包 config/moonbridge.yml 中的 backends 和 initialRouting.servers，并确保候选列表按想要的顺序列出明确入口。空候选列表在没有选服插件时会拒绝登录。

若运行已解压的发行包，从发行包目录启动：

.\bin\moonbridge.bat --validate-config .\config\moonbridge.yml
.\bin\moonbridge.bat --config .\config\moonbridge.yml

在 Linux/macOS 上将 moonbridge.bat 换成 moonbridge。发行包根目录包含 README、docs/ 和按记录日期归档的 smoke/results/、benchmarks/results/；历史记录只证明各自写明的提交和环境。

后端插件开发

服务器安装 moonbridge-backend-bukkit JAR（插件名 MoonBridgeBackend）。业务插件对 backend-bukkit-api 使用 compileOnly / provided，并通过 BukkitMessagingService 获取共享消息服务；无需依赖宿主实现或创建网络连接。源码当前的 0.1.0-SNAPSHOT 仅是本地开发构件版本；发布依赖应使用发布工作流提供的不可变版本。API 与完整示例见后端插件接入。

本次改名统一使用 dev.moonbridge 包名、moonbridge 启动命令和 moonbridge.yml 配置文件。现有插件需要重新编译，Bukkit 插件依赖声明和宿主配置目录改用 MoonBridgeBackend。历史验收记录保留当时的名称与构件路径。

验证状态

MoonBridgeBackend 后端宿主与独立 API 已通过两个真实 Uranium / Java 8 服务端的注册、通信、主线程回调、插件停用、重连及注销/租约验收，见改名与独立 API 验收记录。这是无玩家、隔离服务端上的功能验收，不代表生产容量测试。

最新初次路由专项记录包含自动化测试，以及通过实际 ProxyMain 连接真实 Java 8 Uranium 后端的协议探针结果；未进行本分支的完整模组包玩家视觉验收，见路由验收记录。2026-09-26 Prism 记录是当日代码和环境下的历史真实客户端及配对测量，不应视作当前路由改动的完整模组包证明，见历史验收记录。生产容量仍需按部署环境测量。已知 Uranium 候选服登录停滞的调查见记录及 Uranium #585。

生产权限存储统一使用 MariaDB 13.0.2；默认配置、已有数据边界与实际双实例验收入口见 MariaDB 权限数据库。