如何設定投票獎勵(Votifier、VotingPlugin 等)

每一款獎勵外掛都需要您做兩件事:一是得知有人投了票,二是投票發生時要執行的動作。本文將介紹這兩方面 - 本站提供的配套外掛、用於即時發放的 Votifier,以及如果您已經在使用 VotingPlugin、SuperVotes 或其他獎勵外掛該怎麼辦。

方案 A:VoxelRank 外掛(推薦)

配套外掛直接與本站的 API 通訊。不需要 Votifier - 它透過定期輪詢尚未領取的投票來運作,因此即使在 NAT 後面也能正常運作,並會在伺服器關閉期間補齊所有遺漏的投票。Votifier 同樣可用,作為即時發放的選用附加項(見方案 B)。

1. 從您的儀表板下載 jar 檔案(一旦建置完成,您的伺服器卡片上就會出現下載按鈕),或直接從 /download/plugin 下載。
2. 將其放入 plugins/,啟動伺服器一次。這會產生 plugins/VotingSite/config.yml。
3. 開啟您伺服器的編輯頁面 → 獎勵與投票分頁,複製那裡顯示的 API金鑰。
4. 將其貼到 config.yml 中的 site.api-key(同時確認 site.url 指向本站),然後執行 /votingsite reload。
5. 透過設定 config.yml 中的 mode 來決定投票該如何送達給您:
   • poll(預設)- 外掛自行拉取尚未領取的投票。不需要再安裝其他任何東西。
   • votifier - 投票一經產生,本站就立即推送。需要 NuVotifier 或其他 Votifier 監聽器(見下方方案 B)。
   • both - 以 Votifier 推送為主,輪詢作為保底,憑投票 id 去重,不會重複發放。
6. 在 rewards.commands(如果需要,還有 milestones 和 vote-party)中填入投票時應觸發的主控台指令。
7. 測試一下:/votingsite testvote <player> 可以模擬一次投票,不需等待真實投票。/votingsite status 會顯示目前模式、API金鑰是否被接受,以及目前已發放了多少票的獎勵。

玩家使用 /voxelrank vote 取得自己的投票連結和票數統計 - 而不是 /vote,本外掛刻意從不佔用這個指令(兩個外掛爭搶同一個指令,正是獎勵在悄無聲息中失效的典型原因 - 參見 config.yml 中對此的說明)。

方案 B:透過 NuVotifier 實現即時發放

如果 poll 模式對您來說已經夠用,可以跳過這部分 - 它並非必需。當輪詢帶來的那幾分鐘延遲確實成為問題,或者您更想執行一個專門的獎勵外掛而不是本站自帶的外掛時,再來設定它。

NuVotifier 是原版 Votifier 目前仍在積極維護的分支 - 原始專案如今基本已無人維護,因此「安裝 Votifier」在實際操作中就是指安裝 NuVotifier(或 VotifierPlus 等相容分支)。

1. 將 NuVotifier 的 jar 檔案放入 plugins/,重新啟動伺服器。在 Bukkit/Spigot/Paper 伺服器上,出於向後相容,它仍沿用經典的資料夾名稱 plugins/Votifier/ - 這是 NuVotifier 自己的資料夾,並不是舊外掛的殘留 - 首次啟動時會在其中產生一個 config.yml 以及 rsa/ 資料夾中的一對金鑰。
2. 從 plugins/Votifier/config.yml 中取得您的憑證:v2權杖(建議)會在 tokens: 區段的 default 鍵下自動產生 - 原樣複製即可。如果您比較想用舊方法,v1公開金鑰位於 plugins/Votifier/rsa/public.key;對應的 private.key 請保留在伺服器同一資料夾中,切勿分享給任何人。
3. 檢查 NuVotifier 正在監聽的 port(預設為 8192),確保它已在您的防火牆或主機面板中開放 - 這是與一般 Minecraft 連接埠不同的獨立連接埠,大多數主機不會自動開放它。
4. 在您伺服器的編輯頁面 → 獎勵與投票分頁中,填入 Votifier 主機(您伺服器的位址)和該連接埠,然後貼上第 2 步中的 v2 權杖或 v1 金鑰。如果兩者都填寫,只會使用其中一個 - v2 優先。
5. 直接在該分頁上點擊發送測試投票。這會向表單中目前填寫的主機/連接埠/金鑰/權杖發送一個真實的 Votifier 封包 - 不需要事先儲存 - 並立即回報 NuVotifier 是否接受了它。如果失敗,NuVotifier 自身的主控台日誌(預設 debug: true)會顯示連線是否至少到達了外掛,藉此快速區分是「金鑰錯誤」還是「連接埠被阻擋」。
6. 儲存後投出一次真實的票,確認獎勵是立即到帳,而不是等到下一次輪詢。

在底層,當設定了 v2 權杖時,本站會發送一個標準的 VOTIFIER 2 交握,攜帶經 HMAC 簽署的 JSON 負載;否則會退回到經典的、經 RSA 加密的 v1 資料區塊 - 這與任何相容 Votifier 的監聽器早已使用的協定完全相同,沒有任何本站專屬的內容。

已經在使用 VotingPlugin 了嗎?

如果您的伺服器已經執行了 VotingPlugin,就不需要再安裝我們的外掛了 - 也不需要手動把本站加進去,因為 VotingPlugin 已經為它維護了一個預設集。

以管理員身分(或擁有 VotingPlugin.Commands.AdminVote.VotePresets 權限)在遊戲內執行:

/av VotePresets

VotingPlugin 會從其自身的 VotingPlugin-Presets 儲存庫下載目前的預設集清單,讓您從中選擇一個 - VoxelRank 也在其中 - 然後詢問該預設集所需的數值:顯示名稱、您列表的投票 URL、投票間隔等等。或者直接使用您自己的投票連結跳過選擇:

/av VotePresets https://voxelrank.com/server/your-slug/vote

請包含 https://;VotingPlugin 會自動將主機名稱與正確的預設集比對,而不必讓您在清單中尋找。

無論哪種方式,它都會在 VoteSites.yml 的 VoteSites: 下寫入或更新對應項目 - ServiceSite、VoteURL、合理的預設間隔,以及如果站點還沒有的話,一個佔位的顯示物品或感謝訊息 - 然後自動為您重新載入投票站點。檔案中已有的其他內容都不會被更動。如果您是在修改一個已經建立的設定,而不是新增一個,請先備份 VoteSites.yml,並在向玩家宣傳之前檢查寫入的內容 - 尤其是獎勵部分,因為預設集只是一個起點,而不是一份完成的設定。

VotingPlugin 仍然需要自己的 Votifier 連線才能真正接收投票 - 請將它指向與上方方案 B 相同的 NuVotifier 設定。它還需要伺服器能夠存取 GitHub(raw.githubusercontent.com)才能取得預設集;如果 /av VotePresets 回報沒有可用的預設集,那是伺服器上的網路或防火牆問題,而不是預設集缺失。作為備用方案,/av gui 或直接編輯 VoteSites.yml 仍然有效 - ServiceSite 必須精確符合 VoxelRank.com,您可以在一次真實投票或管理員測試投票之後,用 /av servicesites 來確認。

其他獎勵外掛

在使用比 VotingPlugin 更輕量的外掛嗎?SuperVotes 和 SuperbVote 都是輕量級的 Votifier 監聽器,各自擁有自己的 vote-party 和獎勵指令系統。它們都不像 VotingPlugin 那樣按站點維護預設集 - 將其中任一個指向上方「獎勵與投票」分頁中相同的 Votifier 主機、連接埠和 v2 權杖(或 v1 金鑰),然後像設定任何其他投票一樣設定它的獎勵即可。

疑難排解

• 執行 /votingsite testvote 沒有任何反應。 先檢查 /votingsite status - 如果 API金鑰未被接受,投票(無論真實還是測試)就無處可去。請從編輯頁面重新複製,並確認結尾沒有多餘的空格。
• Votifier 推送始終沒有送達,但輪詢正常運作。 通常被阻擋的是 Votifier 連接埠,而不是 API - 大多數主機預設開放出站 HTTP 流量,但不會開放任意的額外入站連接埠。與其和防火牆死磕,不如把 mode: both(或單獨執行另一個獎勵外掛的監聽器)作為合理的長期備用方案。
• 獎勵已觸發,但遊戲內什麼都沒出現。 獎勵指令是在主控台執行的,因此只有玩家親自輸入才能生效的指令(沒有權限、沒有 op)會悄悄失敗。請先在主控台測試完全相同的指令。
• VotingPlugin 日誌記錄「invalid service site」,或始終無法比對投票。 ServiceSite 的值必須逐字元比對(大小寫除外)。請用 /av servicesites 核實,而不是根據本站的網域名稱去猜測。
• /av VotePresets 提示沒有可用預設集,或某個 URL 無法比對任何內容。 它是在執行時從 GitHub 下載預設集清單的,所以幾乎總是伺服器自身的網路 - 防火牆、代理伺服器、DNS,或 GitHub 發生故障 - 阻擋了 raw.githubusercontent.com,而不是 VoxelRank 被從清單中移除的訊號。按 URL 比對還需要包含 https:// 的完整位址;僅有主機名稱是無法辨識的。
• 「獎勵與投票」分頁中的設定似乎沒有儲存。 這些設定只對已認領的列表生效 - 參見伺服器列表中的「聲稱」篩選項。已匯入但未被認領的項目還沒有擁有者可以為其設定獎勵;請先認領它。

快速問答

我到底需不需要 Votifier?

不需要。poll 模式(VoxelRank 外掛的預設模式)不用安裝任何其他東西就能運作 - Votifier 只是縮短了投票與獎勵之間的延遲,並且如果您更想改用 VotingPlugin、SuperVotes 或 SuperbVote,它是唯一的接入方式。

我可以同時使用我們的外掛和 VotingPlugin 嗎?

同一份獎勵不行 - 請選擇其中一個來真正執行獎勵指令,否則一次投票可能會被支付兩次。Votifier 本身可以同時通知多個監聽器,所以這屬於「不要為同一份獎勵設定兩次」的規則問題,而不是技術上的限制。

我的主機不允許我為 Votifier 開放額外的連接埠。

請使用 VoxelRank 外掛的 poll 模式。它只會發起出站請求,因此沒有任何連接埠需要開放。VotingPlugin 以及類似的獎勵外掛沒有對應的輪詢模式 - 它們需要一個入站的 Votifier 連接埠。

需要協助嗎?

在上面的某個步驟卡住了,或者有些地方和您的伺服器實際傳送的內容對不上?聯絡我們 - 關於投票/獎勵問題最快的聯絡方式就列在那裡。