贝林入口管制

一个 Fabric 服务端模组，用于贝林进入控制，专为贝越成员服务器设计。

管理

English Description

Beilin Entry Control 是一款 Fabric 服务端模组，专为北越成员服务器设计。

该模组通过与北越 API（beiyue.us）通信来验证玩家访问权限。未经许可或存在活跃限制的玩家将被拒绝进入。

功能特性

  • 通过北越 API 实现统一访问控制
  • 通过 WebSocket 实现实时禁令与权限更新
  • 无持久化副作用（仅内存操作，不修改其他模组或游戏文件）

必要条件

  • 北越成员服务器访问权限
  • 已安装 Fabric API 的 Fabric 服务端
  • 由北越提供的有效 API 密钥

本项目主要面向中文用户。

Beilin Entry Control（北越统一入服控制系统）

Beilin Entry Control 配套的 Fabric 服务端模组，面向 北越成员服务器。本模组通过与 beiyue.us 通信来校验玩家权限、验证北越入服资格。

本项目同时包含 Beilin Data Portability 附属模组。若需要建筑数据导出功能，请另见 Beilin Data Portability。

功能概览

  • 统一入服控制
    玩家进入服务器时，模组会向 beiyue.us 发起权限校验请求。若玩家未获批北越入服资格，或存在一项/多项禁令，服务器将拒绝该玩家进入。

  • 跨服禁令即时生效
    模组通过 WebSocket 持续同步状态。即使玩家已进入服务器，一旦权限变化，相关限制也会立即生效。

  • 网络高可用保障
    系统采用 主从节点架构 来保障状态同步稳定性。当 WebSocket 主路径异常时，模组会自动切换至备用路径；若主、备路径同时失联，服务器将判定同步失效并 强制清场，确保禁令一经下达立即生效。

  • 无持久化副作用

    • 所有逻辑仅在内存中运行；
    • 仅读取本模组自身的配置文件；
    • 不会修改其他模组或 Minecraft 的配置；
    • 移除本模组后，服务器将立即恢复为原始逻辑。

前置条件

在安装和使用本模组之前，请确保满足以下条件：

  • 北越成员服务器身份
    本模组仅对北越成员服务器开放使用权限，非成员服务器暂不提供支持。

  • Minecraft 服务端环境
    服务器需运行 Fabric 服务端，并已正确安装 Fabric API，以确保模组能够正常加载和运行。

  • API 凭据获取
    该模组需要有效的 API 凭据。请向 Narek 获取专用的 apiKey，并按照配置说明将其添加至服务器配置文件中。

安装步骤

  1. 搭建 Fabric 服务端
    • 使用官方 Fabric Installer 搭建 Fabric 服务端。
  2. 放入模组文件
    • 将本模组的 .jar 文件放入服务器根目录下的 mods 文件夹。
  3. 首次启动服务器
    • 启动一次服务器，使模组完成初始化；
    • 此时会在 config 目录下生成配置文件 beilin-entry-control.json。
  4. 停止服务器
    • 关闭服务器进程，以便编辑配置文件。

配置说明

配置文件路径：config/beilin-entry-control.json

示例内容（仅示例，实际以生成文件为准）：

{
  "apiKey": "YOUR_API_KEY_HERE",
  "baseHost": "beiyue.us",
  "wsBackupDnsHost": "saas.wiki-beilin.org",
  "wsPrimaryProbeIntervalSec": 10,
  "useHttps": true,
  "useWss": true
}

  • apiKey（必填）

    • 向 Narek 申请获得的 API 密钥；
    • 首次生成时为占位值 "YOUR_API_KEY_HERE"，请务必替换；
    • 若缺失或为空，本模组会认为配置无效，拒绝正常工作。

  • baseHost

    • 与 API 通信的主机名；
    • 默认值为 "beiyue.us"；
    • 仅在特殊环境（如内网、测试环境）下需要修改。

  • wsBackupDnsHost

    • WebSocket 备用路径使用的 DNS 主机名；
    • 默认值为 "saas.wiki-beilin.org"；
    • 仅在特殊环境（如内网、测试环境）下需要修改。

  • wsPrimaryProbeIntervalSec

    • 当 WebSocket 处于备用路径时，探测主路径恢复的间隔秒数；
    • 默认值为 10；
    • 通常无需修改。

  • useHttps

    • 是否通过 https:// 访问 HTTP API；
    • 仅在特殊环境（如内网、测试环境）下需要修改。

  • useWss

    • 是否通过 wss:// 使用 WebSocket；
    • 仅在特殊环境（如内网、测试环境）下需要修改。

修改完成后，保存配置文件，然后重新启动服务器。

服务器白名单设置

本模组不会修改任何原版或 Fabric 白名单配置，需要服务器管理员手动调整白名单策略：

  • 若希望 仅通过 Beilin Entry Control 控制入服：

    • 请在 server.properties 中将 white-list 设为 false；
    • 或通过你习惯的方式关闭原版白名单；
    • 实际入服权限由 beiyue.us 决定。

  • 若仍需 配合原版白名单一起使用：

    • 也可以保留白名单开启状态；
    • 此时入服需要同时满足「持有有效的北越入服资格」与「在服务器白名单中」两个条件。

与 Portability 附属模组共存

Beilin Data Portability 是本项目的附属模组，用于建筑数据的可携带导出。它会复用 Beilin Entry Control 的 API 凭据和 WebSocket 推送通道，但不会替代入服控制逻辑。

  • 若只需要统一入服控制，仅安装 Beilin Entry Control 即可。
  • 若需要建筑导出功能，请同时安装 Beilin Entry Control 与 Beilin Data Portability。
  • Portability 的配置、索引存储、导出流程以及运维命令请查看 Beilin Data Portability。

升级与移除

  • 升级模组

    • 停止服务器；
    • 替换 mods 目录中的旧版本 .jar 为最新版本；
    • 保留原有的 config/beilin-entry-control.json，通常无需更改；
    • 重新启动服务器即可。

  • 移除模组

    • 停止服务器；
    • 从 mods 目录中删除本模组 .jar 文件；
    • 重新启动服务器；
    • 此时服务器将恢复为 原始入服逻辑，不再访问 beiyue.us API。

提示：如不再使用本模组，可根据需要手动删除 config/beilin-entry-control.json，这不会影响其他配置或存档。若服务器同时安装了 Beilin Data Portability，请一并参考 Beilin Data Portability 中的移除说明。

安全性与透明度说明

  • 本模组仅在内存中处理入服逻辑与事件，不主动写入任何数据文件。
  • 不会修改其他模组或 Minecraft 的配置文件，也不会改动世界存档结构。
  • 所有与 beiyue.us 的通信仅围绕入服控制、状态同步和导出任务推送相关接口进行。
  • 本模组会为 Beilin Data Portability 转发导出任务推送，但不会自行记录建筑数据或生成导出文件。

如有任何其他疑问，请联系 Narek。