跳到正文
本頁目錄

連接服務器

機器人加入基岩版專用服務器(BDS)時的服務器設置、版本、賬號和傳輸層。從零寫第一個機器人(獲取代碼、編寫、運行):見教程 你的第一個 bedboo 機器人。

服務器設置

從 minecraft.net 獲取的受支持 BDS(默認版本是 1.26.51.1)需要在 server.properties 中設置:

properties
# 机器人默认通过 RakNet 加入(BDS 1.26.51 及更新版本默认使用 nethernet;见下文“传输层”)
transport=raknet
# 离线机器人(auth: 'offline')没有 Xbox Live 身份
online-mode=false
# 或者保持为 true,并把机器人的名字加入 allowlist.json
allow-list=false
server-port=19132
# 可选:允许机器人执行命令(bot.chat('/time set day'))
allow-cheats=true
屬性 值 原因
transport raknet,或在 createBot 中使用 transport: 'nethernet' 時為 nethernet RakNet 是客戶端的默認傳輸層
online-mode auth: 'offline' 時為 false;true 需要 auth: 'microsoft' 離線機器人沒有 Xbox Live 身份
allow-list false,或把機器人的名字加入 allowlist.json 否則機器人會被踢出
server-port 傳給 createBot 的 port

online-mode=false 允許任何人以任意名字加入:請把這樣的服務器放在私有網絡中,或者使用 online-mode=true 配合 Microsoft 賬號。在 transport=raknet 且 enable-lan-visibility=true 時,BDS 還會額外綁定 19132/19133 端口;在同一臺主機上運行多個服務器時請關閉它。

啟動服務器,等待日誌中出現 Server started.。緊隨其後的 TRANSPORT TYPE ERROR … not set to NetherNet 信息塊是 BDS 在提示原版客戶端可能很快需要 NetherNet;RakNet 客戶端可以正常連接。

其他版本

服務器不是 1.26.51 時,把它的 BDS 版本或協議族傳給 createBot:

js
const bot = bedboo.createBot({ host: '127.0.0.1', port: 19132, username: 'Bot', version: '1.26.62.1' })
// bot.version === '1.26.60',bot.protocolVersion === 2225

各協議族、其 BDS 版本以及每個 BDS 默認的傳輸層列在支持的版本中。bedboo 不認識的版本會拋出 ERR_BEDBOO_VERSION,並列出支持的版本。機器人的代碼在所有版本上都相同。

權限、作弊與命令

  • bot.chat('/…') 發送的是命令請求(基岩版沒有通過聊天輸入的命令)。命令需要 allow-cheats=true 和管理員權限:在 BDS 上 玩家無法給自己 op,因此請在服務器控制台中給機器人 op(op Bot),或者設置 default-player-permission-level=operator。
  • 命令結果以 message 事件的形式到達(基岩版的 command_output,每行一個)。
  • /give、/replaceitem、/tp 等命令的效果對機器人可見,與 Java 版一致(playerCollect、forcedMove……)。

Microsoft(Xbox Live)賬號

對於 online-mode=true 的服務器,請使用擁有 Minecraft 的 Microsoft 賬號:

js
const bot = bedboo.createBot({
  host: 'my.server.example',
  port: 19132,
  username: 'me@example.com', // 令牌缓存使用的名字
  auth: 'microsoft',
  profilesFolder: './.auth-cache' // 可选;选项与 mineflayer 相同(prismarine-auth)
})

首次運行會打印一個設備碼鏈接(可以用 onMsaCode 自行處理);之後令牌會被緩存。遊戲內名稱為該賬號的玩家代號(gamertag)。 auth: 'mojang' 在基岩版上不存在,會拋出錯誤。

傳輸層:RakNet 或 NetherNet

BDS 1.26.51 及更新版本默認使用 NetherNet(WebRTC 數據通道),RakNet 需通過 transport=raknet 啟用;1.26.40 和 1.26.45 仍默認 RakNet。Mojang 已表示將移除 RakNet;BDS 1.26.60 至 1.26.63.1 仍提供它。除非另行指定,bedboo 都通過 RakNet 連接,因為 bedrock-protocol 支持它已有多年。要使用 NetherNet,請以 transport=nethernet 啟動 BDS,並將傳輸層傳給 createBot:

js
const bot = bedboo.createBot({ host: '127.0.0.1', port: 19132, username: 'Bot', transport: 'nethernet' })
  • 信令走的是服務器端口上的 HTTP(POST http://<host>:<port>/v1/join/<id>),因此在 enable-lan-visibility=false 時也能工作,也可以通過轉發 server-port(TCP)端口使用;之後的媒體流走 UDP(BDS 的 server-udp-ports)。 bedrock-protocol 的其他信令模式也會透傳,但測試較少:局域網發現(UDP 7551,需要 enable-lan-visibility=true),使用 nethernet: { signalling: 'lan' };以及 Xbox 信令,使用 nethernet: { signalling: 'services', networkId } + auth: 'microsoft'。
  • 服務器密鑰。 BDS 會用一個身份密鑰對應答進行簽名。在明文 HTTP 上沒有任何機制為該密鑰背書,因此默認接受任意密鑰, 這與 RakNet 提供的信任程度相同。可以固定密鑰以拒絕冒充者:nethernet: { serverKey: 'sha256:<hex>' }; nethernet: { onServerKey: (fingerprint, url) => true | false } 讓你自行決定(並展示可用於固定的指紋)。HTTPS 信令 URL(nethernet: { url: 'https://…' })通過 TLS 獲得信任。
  • 機器人的 API 在兩種傳輸層上完全相同。詳情:連接與版本。

故障排查

現象 原因
Connect timed out 主機或端口錯誤、服務器的 transport 與機器人不一致,或防火牆丟棄了 UDP(RakNet)/ TCP(NetherNet 信令)
登錄後立即 kicked allow-list=true 但機器人不在 allowlist.json 中,或 online-mode=true 卻使用 auth: 'offline'(reason 會說明是哪一種)
以客戶端 / 服務器版本過舊為由被踢出 服務器的協議族與機器人的 version 不同(其他版本)
RakNet 後端加載失敗 不是 x64,或依賴是在工作區之外安裝的(缺少 raknet-native 補丁)
命令被拒絕 在控制台給機器人 op,並開啟作弊(allow-cheats=true)
NetherNet:Untrusted Nethernet server key serverKey 固定值與服務器的密鑰不匹配(或 onServerKey 返回了 false)
NetherNet:fetch failed(ECONNREFUSED) 服務器運行的是 RakNet,或 BDS 無法打開 TCP 信令監聽(此時日誌中沒有 Accepting clients on … 一行;端口被其他進程佔用)

更多值得了解的 BDS 行為(加入流程、區塊加載、控制台輸出)彙總在 BDS 筆記中。