跳至主要内容

自我託管資源包

ResourcePackManager 內建一個小型 HTTP 伺服器。當 autoHost: true（預設）且 preferSelfHost: true（預設）時，外掛會嘗試以與 Minecraft 伺服器相同的 JVM 來託管合併後的資源包——無需外部檔案託管、無需獨立網頁伺服器、也無需手動貼上 URL。

本頁說明這條自我託管路徑如何運作、健全性檢查負責什麼、連接埠與主機名稱如何選擇，以及在預設值不適用時要設定哪些內容。

若你想透過 RSPM 之外的、自己現有的網頁伺服器託管 zip，請參閱疑難排解頁面中關於 autoHost: false 的章節。

交付決策樹​

當玩家加入時，RSPM 會依照下列優先順序選擇交付 URL：

  1. selfHostForce: true — 直接使用自我託管，無探測、無遠端上傳。主要用於測試自我託管路徑。會繞過所有其他旗標。
  2. preferSelfHost: true 且 selfHostEnabled: true 且不在網路模式 — 嘗試自我託管並執行三項健全性檢查（見下文）。若全部通過則確認使用自我託管；若有任何一項失敗，則回退至遠端路徑。
  3. 否則 — 將資源包上傳到 https://magmaguy.com/rsp/ 並公告該 URL。若上傳失敗或 SHA1 檢查回報 SESSION_NOT_FOUND，則回退至自我託管（假設 selfHostEnabled: true）。

取得 URL 後，在 1.20.3+ 上，RSPM 會使用 Minecraft 的多重資源包 API（因此能與其他伺服器發送的資源包共存），在更舊版本上則使用較舊的單一資源包方法。

三項健全性檢查​

當 preferSelfHost: true 時，RSPM 會在確認使用自我託管之前，依序執行下列檢查：

第 1 層 — 對解析後外部主機進行 heuristic 檢查​

若解析後的主機（見下方「外部主機偵測」）為 RFC1918（10.*、172.16-31.*、192.168.*）、loopback（127.*）、link-local（169.254.*），或未指定（0.0.0.0），自我託管不可能服務外部用戶端。立即略過並改用遠端託管。

這可揪出非常常見的「ipify 查詢失敗、回退到 LAN IP」失敗模式。

第 2 層 — 本機 self-probe​

對 http://127.0.0.1:<port>/rspm.zip 發出 HEAD 請求，驗證 HTTP 200 且主體非空。可揪出：

  • 連接埠綁定衝突（其他程式佔用了所選的連接埠）
  • 資源包檔案缺失（路由已註冊但 zip 尚未在磁碟上）
  • 路由註冊的錯誤

逾時設定相當積極（3 秒），以確保慢速探測不會拖累啟動。

第 3 層 — 外部可達性探測​

將公告的 URL 以 POST 方式送往 magmaguy.com 託管端的 POST /rsp/probe。託管端會從公開觀測點擷取該 URL（搭配 SSRF 防護與緊湊的逾時設定），並回報是否可達。

可揪出最常見的生產環境失敗模式：伺服器有公開 IP，但 HTTP 連接埠未在路由器或防火牆上轉送。第 2 層通過（伺服器在 127.0.0.1 有回應），但真實用戶端永遠下載不到資源包。

探測結果的決策政策：

  • reachable=true → 外部用戶端可連到我們的 URL。確認使用自我託管。
  • reachable=false → 外部用戶端連不到。拆除自我託管，改用遠端託管（從 magmaguy.com 普遍可達）。
  • 探測通訊本身失敗（IOException） → 無法以任一方式驗證。預設保留自我託管：以無法探測為由拒絕承諾會自相矛盾，因為遠端路徑同樣需要 magmaguy.com。

檢查仍無法偵測的情況​

NAT-hairpin 邊緣情況：連接埠對公開網際網路開放（第 3 層通過），但操作員自己的路由器不會將 LAN 內部流量繞回。外部用戶端正常，但操作員從同一台機器測試卻失敗。

目前的權宜做法：當你從主機機器測試而路由器不支援 hairpin 時，請設定 preferSelfHost: false 或 selfHostExternalHost: 127.0.0.1。

連接埠解析​

有兩個設定會相互影響：

  • selfHostPort — 明確的連接埠（任意正整數），或 -1（預設）以自動衍生。
  • networkHttpOffset-v2 — 僅在 selfHostPort = -1 時參考。會加到 Minecraft 伺服器連接埠上。預設 1。

預設值為 selfHostPort: -1 + networkHttpOffset-v2: 1，因此：

  • MC 連接埠 25565 → HTTP 連接埠 25566
  • MC 連接埠 25584 → HTTP 連接埠 25585

這會在單一主機網路上自動為各後端錯開 HTTP 連接埠，無需管理員設定——每個後端本就有唯一的 MC 連接埠，因此每個都會獲得唯一的 HTTP 連接埠。

為什麼偏移為 1？​

大多數共享 / 代管 Minecraft 託管（基於 Pterodactyl 的面板等）會為每個容器分配狹窄的連接埠範圍（通常只有 4–10 個埠）。較大的偏移會落在範圍外，主機防火牆會悄無聲息地擋掉 HTTP 連接埠。偏移為 1 即使在很緊的分配下也能容納。

具備完整連接埠控制權的自架管理員可將此值調高至任意值，但若你運行代理網路，也必須將代理的 network-http-offset-v2 調整為相符的值。

注意：RCON 衝突​

若你的主機預設在 MC port + 1 啟用 RCON，請選擇偏移 2 或 3 以避免連接埠衝突。請檢查 server.properties 中的 rcon.port=。

帶版本的設定鍵​

config.yml 中的設定字面上就叫做 networkHttpOffset-v2。v1 鍵為 networkHttpOffset，預設為 100——該預設值在共享 / 代管託管環境（每個遊戲容器只獲得 ~4–10 個連續連接埠）會出問題：MC + 100 落在範圍外，HTTP 伺服器在內部能綁定但主機防火牆會擋掉外部流量，導致代理永遠收到無聲的 CONNECT_FAILED。v2 改採預設 1，使 MC + 1 即使在最狹窄的容器分配下也能穩穩落在範圍內。

若你從 v1 升級，失效的 v1 鍵會作為無害的殘留留在你的設定中，直到你清理為止——RSPM 刻意不讀取它。

外部主機偵測​

selfHostExternalHost 控制用戶端在 URL 中看到的主機名稱。留空（預設）則會依下列優先順序自動偵測：

  1. api.ipify.org / checkip.amazonaws.com — 回傳此主機的公開 IPv4。每次 /rspm reload 會快取一次，避免反覆敲打 IP 服務。
  2. Bukkit.getIp() — 伺服器的綁定位址，需非空且非 0.0.0.0。通常是 LAN 位址。
  3. InetAddress.getLocalHost() — 盡力而為。
  4. localhost — 最後手段。位於本機之外的用戶端連不上。

若自動偵測落在無法路由的位址，且 preferSelfHost: true，第 1 層 heuristic 檢查會失敗，外掛會切換到遠端託管。

要獲得最可靠的自我託管設定，請將 selfHostExternalHost 明確設為你的公開主機名稱（例如 play.example.com）。這會完全略過 ipify/AWS 偵測，探測會針對該明確值執行。

設定參考​

# 內建 HTTP 伺服器是否可作為交付路徑使用。
# 為 false 時，無論其他旗標如何皆不會嘗試自我託管。
selfHostEnabled: true

# 自我託管 HTTP 伺服器的連接埠。
# -1（預設）= 自動衍生：HTTP 連接埠 = Minecraft 伺服器連接埠 + networkHttpOffset-v2。
# 設為任意正整數即可強制使用該明確連接埠。
selfHostPort: -1

# 當 selfHostPort = -1 時，加到 Minecraft 伺服器連接埠上的偏移量。
# 預設 1（MC 25565 -> HTTP 25566）。代理網路中必須與代理的 network-http-offset-v2 相符。
networkHttpOffset-v2: 1

# 用戶端用來連到自我託管伺服器的公開主機名稱或 IP。
# 留空則自動偵測（api.ipify.org / checkip.amazonaws.com）。
selfHostExternalHost: ""

# 先嘗試自我託管並執行三項健全性檢查，任一失敗則回退至遠端。
# 為 false 時使用舊順序：先進行遠端上傳，只有在上傳失敗時才嘗試自我託管。
preferSelfHost: true

# 跳過所有其他交付路徑並強制使用自我託管。
# 會繞過健全性檢查與遠端上傳。主要用於測試。
selfHostForce: false

後端 HTTP 伺服器路由​

內建 HTTP 伺服器一律在以下位址提供資源包 zip：

http://<host>:<port>/rspm.zip

在網路模式下（RSPM 位於 Velocity / BungeeCord / Waterfall 代理後方），會額外註冊兩個路由供代理外掛拉取：

http://<host>:<port>/bedrock.zip   # 轉換後的 Bedrock 資源包
http://<host>:<port>/mappings.json # Geyser 自訂對應 JSON

這三個路由皆以檔案為基礎：每次請求都會即時讀取檔案，因此重新混合後若覆寫到同一個 zip 路徑，無需重啟 HTTP 伺服器即可自動帶入。Bedrock 路由支援 If-Modified-Since，因此代理輪詢者在沒有變更時幾乎不耗頻寬。當底層檔案不存在時（例如首次混合完成前），所有路由都會乾淨地回傳 404。

驗證自我託管是否啟用​

/rspm status 會顯示：

  • Active delivery: SELF-HOSTED — 目前使用自我託管
  • Active delivery: REMOTE (magmaguy.com) — 目前使用遠端自動託管
  • URL: ... — 用戶端實際會看到的 URL
  • Resolved external host — selfHostExternalHost 解析後的結果
  • Public IP (auto-detected) — ipify/AWS 回報的內容（若有）
  • selfHostPort — 自動 vs 明確指定，以及解析後的值

若你預期使用自我託管但實際是遠端，啟動日誌會說明哪一項健全性檢查失敗以及原因。

常見錯誤​

  • 將 selfHostPort 設為任意值但忘了在代理上對應 — 在網路模式下，代理會以 mcPort + network-http-offset-v2 計算每個後端的 HTTP 連接埠。明確的 selfHostPort 會覆寫自動衍生，但代理不知道，因此仍會輪詢 mcPort + offset。在網路模式下，除非你願意配合協調，否則請保留 selfHostPort: -1。
  • 在 hairpin 失效的路由器下信任第 3 層探測 — 探測會從 magmaguy.com 觀測點執行，因此無法揪出「外部用戶端正常但操作員自己的 LAN 不會繞回」的情況。若不確定，請從行動網路上的手機測試。
  • 將 networkHttpOffset-v2 調整超過你的託管供應商連接埠範圍 — 症狀是代理端永遠收到無聲的 CONNECT_FAILED。提高偏移之前，請檢查 mcPort + offset 是否落在你容器分配的連接埠範圍內。