跳至主要內容

代理網路（BungeeCord / Waterfall / Velocity）

ResourcePackManager 可在代理網路上運作。只有一個 jar——ResourcePackManager.jar——你會在每個後端以及代理上安裝同一個 jar。在後端上它以後端角色執行（合併、託管、推送、轉換）；在 Velocity 或 BungeeCord/Waterfall 代理上，同一個 jar 會自動偵測平台載入器並以代理角色執行（網路端 Bedrock 交付）。這兩種角色會透過共用的 plugins/floodgate/key.pem 檔案自動互相辨識——沒有獨立的代理 jar、沒有需要解壓的 proxy-extension、也沒有需要貼上的金鑰。

本頁通篇的「代理外掛」一詞，是指同一個 ResourcePackManager.jar 以代理角色執行的簡稱。

代理外掛的作用​

代理外掛的工作是Bedrock 資源包的合併與交付。在擁有多個後端的網路中，每個後端會產出自己的 Bedrock 資源包（其合併後 Java 資源包的轉換版本）。代理外掛會：

  1. 每 5 秒輪詢一次每個後端的小型 HTTP 伺服器以取得 /bedrock.zip 與 /mappings.json，並使用 If-Modified-Since，因此未變更的檔案幾乎不耗頻寬。每個後端都會通報它實際綁定的確切 HTTP 連接埠，因此代理通常會自動連到正確的連接埠（請參閱後端 HTTP 連接埠解析）。
  2. 等待 inbox 狀態穩定——一旦相鄰兩次輪詢觀察到相同的檔案雜湊集合，就立即合併。
  3. 將每個後端的 Bedrock 資源包合併為單一的網路級資源包。
  4. 將合併後的 Geyser 自訂對應檔複製到代理的 plugins/Geyser-*/custom_mappings/。
  5. 在 Bedrock 用戶端連線時，透過 Geyser 的 SessionLoadResourcePacksEvent 提供合併後的資源包。

代理外掛只對 Bedrock 玩家有用。 網路上的 Java 資源包交付仍由各後端透過一般的 setResourcePack / addResourcePack API 處理——Java 用戶端會看到所在後端所選擇發送的資源包。若你的網路為純 Java，則不需要代理外掛。

設定——兩個步驟​

步驟 1：在代理與每個後端上安裝 Floodgate​

代理上需要 Floodgate 來讓 Bedrock 玩家完成認證。RSPM 透過 Floodgate 的 plugins/floodgate/key.pem 來衍生網路身份識別——該檔案必須在代理與每個後端上逐位元組相同。Floodgate 本來就要求這樣以用於 Bedrock 認證，因此如果你網路上的 Bedrock 玩家目前能正常運作，這部分就已完成。

若你尚未安裝 Floodgate，請在每個元件上安裝它，然後在繼續之前將其中一份正本的 key.pem 複製到所有其他元件。

步驟 2：將 ResourcePackManager.jar 複製到代理​

只有一個 jar。你安裝在 Bukkit/Paper 後端上的 ResourcePackManager.jar，同時也是代理外掛——它在單一 shaded jar 中一併打包了 Velocity 與 BungeeCord/Waterfall 的實作，並會自動偵測它正在哪個平台上執行。沒有需要解壓的、各平台分開的代理 jar。

將同一個 ResourcePackManager.jar 複製到代理的 plugins/ 資料夾：

代理軟體使用此 jar
VelocityResourcePackManager.jar
BungeeCordResourcePackManager.jar
Waterfall（Bungee 分支）ResourcePackManager.jar

你隨時可以在後端執行 /rspm status 來確認這一點；Proxy deployment 區段會印出 Network proxy jar: ResourcePackManager.jar 以及 Use the same jar on Bukkit/Paper, Velocity, and BungeeCord/Waterfall.

重新啟動代理。就這樣。

刻意沒有設定可編輯、也沒有金鑰需要貼上。代理外掛會在啟動時讀取代理上的 plugins/floodgate/key.pem，並從中衍生網路身份識別。由於 Floodgate 本來就要求該檔案在每個後端與代理上一致，因此衍生出的金鑰會自動與每個後端相符。

代理的第一次輪詢約在啟動後 2 秒觸發，之後每 5 秒一次。結合單一週期的穩定性閘門，當代理能看到至少一個已在產出內容的後端後，首次合併約在 7 秒後發佈。

驗證是否運作​

代理主控台​

重啟後約 10 秒內（假設後端正在運行），你應該會看到：

[ResourcePackManager] Network-key auto-derived from Floodgate key.pem ✓
[ResourcePackManager] NetworkSync starting (poll interval 5000 ms, network-http-offset 1 - endpoint announcements preferred, fallback HTTP port = mcPort + offset)
[ResourcePackManager] NetworkSync: inbox stabilized — merging 2 Bedrock zip(s) and 2 mappings file(s) across 2 backend(s).
[ResourcePackManager] Merged Bedrock pack published at .../merged/Bedrock.zip (sha1=...).
[ResourcePackManager] ✔ Network resource pack is now ready (... KB, sha1 ABCD1234)

在代理上執行 /rspm status​

會印出快照：後端清單、各後端各路徑的擷取結果（200 / 304 / 404 / CONNECT_FAILED）、連續空輪詢計數、目前合併後資源包的路徑 + 大小、network-http-offset，以及代理上 Floodgate / Geyser 的存在狀態。需要 resourcepackmanager.command.status 或 resourcepackmanager.*。主控台一律具備兩種權限；若你想讓玩家執行該指令，可透過權限外掛授予其中一種。輸出不會揭露任何機密（網路金鑰會被遮罩、不含認證 token），因此放寬授權是安全的。

在後端執行 /rspm status​

Deploy mode 行應顯示 network-backend。Network key 行應顯示遮罩過的金鑰（最後 4 個字元可見）——與代理上遮罩過的金鑰比對，確認兩邊一致。

Bedrock 用戶端​

透過 Bedrock 連線。應該會在進入世界前看到資源包下載提示。自訂物品會以其原本設計的模型顯示，而非顯示為單純的盔甲架。

設定參考​

後端 plugins/ResourcePackManager/config.yml​

網路模式為自動偵測——沒有 networkMode: true 旗標需要設定。偵測訊號（滿足任一即可）：

  1. Floodgate 存在、Geyser-Spigot 不存在 — Bedrock-via-proxy 情境的最強訊號。
  2. spigot.yml: settings.bungeecord: true — 舊版 BungeeCord / Waterfall IP 轉發開關。
  3. paper-global.yml: proxies.velocity.enabled: true — 現代的 Velocity 轉發。

專為網路模式而言唯一重要的選項是 networkHttpOffset-v2，它控制代理會在每個後端輪詢的後備 HTTP 連接埠（即在後端通報其實際綁定的連接埠之前，代理所猜測的連接埠）。預設 1 幾乎適用於所有託管。完整的連接埠解析說明請參閱自我託管。

正常運作下，每個後端會自動向代理通報其真實的 HTTP 連接埠（透過 magmaguy.com 端點註冊表），因此偏移量只會在啟動 / 失敗時作為後備被參考。請參閱下方的後端 HTTP 連接埠解析。

代理 plugins/ResourcePackManager/config.yml​

代理外掛會在首次啟動時寫入最小化的預設設定：

# 強制用戶端接受資源包（拒絕則踢出）。預設：false。
force-resource-pack: false

# 在某個後端通報其真實的 ResourcePackManager HTTP 連接埠「之前」，
# 加到該後端 Minecraft 連接埠上的「後備」偏移量，用以推導出此代理會擊中
# 的 HTTP 連接埠（/bedrock.zip 和 /mappings.json）。預設 1。
# 正常運作下，後端會通報它實際綁定的確切連接埠，因此此值僅在啟動時
# 或通報失敗時使用——但若它「確實」被使用，則應與每個後端的
# networkHttpOffset-v2 一致。
network-http-offset-v2: 1

刻意沒有 network-key 條目——該選項在預發行階段已被淘汰，因為手動貼上是設定錯誤的主要來源（錯字會悄無聲息地破壞代理↔後端的連結）。金鑰會從 plugins/floodgate/key.pem 自動衍生。

後端 HTTP 連接埠解析​

代理需要知道要在每個後端的哪個 HTTP 連接埠上輪詢 /bedrock.zip 與 /mappings.json。它會依下列順序解析該連接埠：

  1. 後端通報的端點（優先）。 每個後端會將它實際綁定的確切 HTTP 連接埠上傳到 magmaguy.com 端點註冊表，並以網路金鑰為鍵。在每次輪詢時，代理會刷新此清單，並依 Minecraft 連接埠（在可用時也含主機）將後端通報的連接埠與伺服器清單條目比對。這表示無論管理員在後端設定了明確的 selfHostPort，或其後端自動落在 mcPort + 1，都會以相同方式處理——代理會使用後端實際綁定的任何連接埠。
  2. mcPort + network-http-offset-v2（後備）。 僅在沒有可比對的通報時使用（例如在任何後端通報之前的首次輪詢，或端點註冊表短暫無法連線時）。這就是為什麼若你倚賴後備，兩邊的偏移量仍應一致。

代理刻意不會以連接埠掃描後端作為後備——這在主機看來像是濫用行為。當直接擷取完全無法運作時，中繼路徑（見下文）才是根本的答案。

代理上的 /rspm status 會逐後端顯示所選的連接埠，以及它是來自通報或偏移量後備。

穩定性與合併節奏​

代理會等待 inbox 狀態穩定後才進行合併：首次輪詢設定基準的檔案雜湊集合，下一次觀察到相同集合的輪詢便會觸發合併（單一週期的穩定性閘門）。在約 2 秒的初始延遲與 5 秒的輪詢間隔下，這表示首次合併會在代理能看到至少一個後端產出內容的約 7 秒後發生。後續合併僅在 inbox 檔案的 SHA-1 集合變更時才會重新壓縮，因此長時間的靜置期幾乎不耗成本。

後端會將其 bedrock.zip 寫入暫存檔後再原子化重新命名，因此 /bedrock.zip 路由一律提供完整的 zip——代理永遠不必防範讀到寫到一半的內容，這也是閘門只需單一週期而非兩個週期的原因。

直接擷取 vs 中繼回退​

預設路徑是直接擷取：代理對每個後端發出 http://<backend-host>:<mcPort + offset><path> 的 HTTP GET 請求。

若代理無法直接連到後端的 HTTP 連接埠（在共享 / 代管 Minecraft 託管環境中常見，MC 連接埠對外開放但相鄰埠被防火牆擋掉），後端會將其 bedrock.zip 與 mappings.json 推送到 magmaguy.com 上以網路命名空間（從 Floodgate 金鑰衍生）區分的中繼端點。當直接擷取硬性失敗時，代理會從中繼端點列出並下載。

兩條路徑會餵入同一個合併步驟，因此操作員不需要選擇——直接擷取是優先選項（對 magmaguy.com 零頻寬成本），中繼會在需要時透明地接手。

中繼在伺服器端的 TTL 為 30 分鐘。後端每 25 分鐘推送一次以維持條目存活；乾淨關機會立即刪除條目，而非等到 TTL 過期。

常見問題疑難排解​

啟動時出現「Floodgate key.pem missing」​

代理外掛找不到 plugins/floodgate/key.pem 而進入閒置狀態。沒有它，RSPM 就無法連結到任何後端。

修復方式：在代理上安裝 Floodgate，然後確保代理上的 plugins/floodgate/key.pem 與每個後端的同名檔案逐位元組相同。Floodgate 預設會為每次安裝自動產生不同的金鑰——請從任一後端複製一份正本的 key.pem 到所有其他元件，然後重新啟動所有元件。

約 20 秒後出現「No merged pack content」警告​

在連續 4 次空輪詢週期後，代理會記錄一次性的多行警告，列出它輪詢過的每個後端、嘗試過的 URL，以及結果。該警告會說明最常見的修復方式：

  • 每個後端皆顯示 CONNECT_FAILED — 代理完全無法連到後端的 HTTP 連接埠。請檢查 velocity.toml / config.yml 中設定的位址是否為代理實際可達的位址（而非代理網路中無法解析的 Docker 內部名稱），並確認後端的 HTTP 連接埠在代理與後端之間是開放的。該警告會印出它為每個後端嘗試的確切 HTTP host:port，以及該連接埠是來自後端的通報或 mcPort + networkHttpOffset-v2 後備。若你無法開放該連接埠（代管託管），請參閱上方的中繼回退章節——後端應該會自動上傳到中繼。
  • 每個後端皆顯示 NOT_FOUND_404 — 後端正在運作但未產生 Bedrock 資源包。請在每個後端執行 /rspm status；Bedrock Pack 診斷區塊會告訴你原因（最常見：合併後的資源包中沒有物品定義，或首次混合週期尚未完成）。

該警告在每次「卡住」期間只會觸發一次。當至少一個後端開始重新回傳內容時，會記錄一行 NetworkSync: recovered。

首次代理啟動時 Bedrock 玩家看不到自訂模型​

Geyser 只在代理啟動時才會註冊其自訂物品表。如果代理在任何後端產出 Bedrock 資源包之前啟動，Geyser 會在空對應表的狀態下運行，並維持整個工作階段不變。

修復方式：在後端記錄了首次的 Merged Bedrock pack published 行之後，重新啟動代理一次。RSPM 會在每次代理啟動時預先佈署前次執行的對應檔，因此這個問題僅會在全新安裝時出現——之後的啟動都會在 Geyser 掃描前就準備好對應內容。

代理啟動時出現「Duplicate bedrock_identifier」警告​

兩個後端為同一個基礎物品發出了相同的 Bedrock 識別碼。後寫入者勝出；若只需要其中一個後端提供該物品則無害。若兩個後端都應在同一個基礎物品下託管不同的自訂物品，請重新命名其中一個來源 Java 模型，使自動產生的雜湊值不同。

Bedrock 玩家已連線但看不到資源包​

當有 Bedrock 工作階段在 RSPM 沒有可用資源包的情況下載入時，代理會向所有線上 Java 玩家發出一則聊天橫幅：

⚠ [RSPM] Bedrock player Alice connected before the resource pack was ready — they're seeing plain armor stands instead of custom models. Tell them to disconnect and reconnect; the pack will load on their next session. (Cause: ...)

Bedrock 玩家本人也會收到一則彈窗，代理主控台也會收到橫幅。若你需要更深入調查，可啟用除錯串流（Velocity 與 BungeeCord 皆可）：

/rspm debug bedrock on

這會開啟 GeyserBinder 發出的詳盡 [RSPM-BedrockDebug] 日誌行。重現問題後，再關閉它：

/rspm debug bedrock off

此設定會在代理重啟時重置為關閉，因此不會意外被遺留為開啟。

在網路上更新 RSPM​

升級後端 RSPM jar 後，也要將同一個 ResourcePackManager.jar 重新複製到代理的 plugins/ 資料夾，並重新啟動代理。每個後端與代理使用的都是同一個 jar，因此請讓所有元件保持在相同版本。

尚未支援的項目​

  • 透過代理外掛在網路上提供 Java 資源包。 Java 用戶端會直接透過一般 API 從各後端接收資源包。代理端沒有 Java 資源包混合器。
  • 跨後端的 Java 資源包合併。 每個後端的 Java 資源包是獨立的。若玩家切換後端，會收到新後端的資源包。
  • 網路金鑰的即時重新設定。 金鑰綁定到 Floodgate 的 key.pem。變更它需要重新啟動代理與每個後端（這正是輪替 Floodgate 金鑰時無論如何都要做的事）。