跳至主要内容

代理網路（BungeeCord / Waterfall / Velocity）

ResourcePackManager 可在代理網路上運作。後端外掛在每個後端執行，另一個獨立的代理外掛（Velocity 或 BungeeCord，不可兩者並存）則在代理上執行。這兩個元件會透過共用的 plugins/floodgate/key.pem 檔案自動互相辨識。

代理外掛的作用​

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

  1. 每 5 秒輪詢一次每個後端的小型 HTTP 伺服器以取得 /bedrock.zip 與 /mappings.json，並使用 If-Modified-Since，因此未變更的檔案幾乎不耗頻寬。
  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：從任一後端複製對應的代理 jar​

當後端的 RSPM 至少啟動過一次後，請查看：

plugins/ResourcePackManager/proxy-extension/

該資料夾會包含：

ResourcePackManager-Velocity.jar
ResourcePackManager-BungeeCord.jar
README.md  (再加上 9 個翻譯版的 README 檔案)

無論偵測到的網路拓撲為何，後端都會在每次啟動時解壓這兩個 jar，因此它們隨時可用。請只複製一個到代理的 plugins/ 資料夾：

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

不要同時安裝兩個——只裝對應的那一個。同時安裝兩個會在嘗試載入錯誤平台的那一邊產生啟動錯誤。

重新啟動代理。就這樣。

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

當所有後端都已上線時，首次合併通常會在約 10 秒內完成。

驗證是否運作​

代理主控台​

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

[ResourcePackManager] Network-key auto-derived from Floodgate key.pem ✓
[ResourcePackManager] NetworkSync starting (poll interval 5000 ms, ...)
[ResourcePackManager] Merged pack ready at .../merged/Bedrock.zip (sha1 ...)
[ResourcePackManager] Geyser mappings deployed to .../custom_mappings
[ResourcePackManager] ✔ Network resource pack is now ready (... KB, sha1ABCD1234)

在代理上執行 /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 幾乎適用於所有託管。完整的連接埠解析說明請參閱自我託管。

代理 plugins/ResourcePackManager/config.yml​

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

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

# 加到每個後端 Minecraft 連接埠上的偏移量，
# 用以推導出此代理會擊中的 HTTP 連接埠（/bedrock.zip 和 /mappings.json）。
# 預設 1。必須與每個後端的 networkHttpOffset-v2 一致。
network-http-offset-v2: 1

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

穩定性與合併節奏​

代理會等待 inbox 狀態在連續兩次輪詢中保持穩定後，才進行合併。在預設的 5 秒輪詢間隔下，這表示首次合併會在代理能看到至少一個後端產出內容的約 10 秒後發生。後續合併僅在 inbox 檔案的 SHA-1 集合變更時才會重新壓縮，因此長時間的靜置期幾乎不耗成本。

直接擷取 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 內部名稱），並確認 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 後，也要從任一後端的 plugins/ResourcePackManager/proxy-extension/ 重新複製對應的代理 jar 到代理，並重新啟動代理。後端會在每次啟動時重新產生這些 jar，因此它們會永遠與後端版本同步。

尚未支援的項目​

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