Discord 機器人 & 雲端中繼

Saba-chan Discord 機器人設定,以及不需連接埠轉發即可控制伺服器的雲端中繼配對流程。

Discord 機器人 & 雲端中繼

Saba-chan Discord 機器人是 在雲端中繼伺服器上營運的官方機器人。你不需要自己執行機器人程序或管理 Discord 權杖。請將官方機器人邀請到你的 Discord 伺服器,再用 Saba-chan 應用程式提供的代碼配對一次。


1. 運作方式

雲端
Discord用聊天下指令
Discord 中繼Saba-chan 機器人 · 雲端
你的電腦
Saba-chan 常駐程式你的電腦
遊戲伺服器你的電腦
  1. 1
    Saba-chan 常駐程式Discord 中繼

    等待新指令(長輪詢)

  2. 2
    DiscordDiscord 中繼

    輸入指令 /saba … 或聊天

  3. 3
    Discord 中繼Saba-chan 常駐程式

    轉交指令

  4. 4
    Saba-chan 常駐程式

    檢查權限

  5. 5
    Saba-chan 常駐程式遊戲伺服器

    啟動 · 主控台指令

  6. 6
    Saba-chan 常駐程式Discord 中繼

    傳送結果

  7. 7
    Discord 中繼Discord

    回覆結果

由你的電腦主動連出並取回指令,所以不需要在路由器上開放連接埠。請求使用配對時發放的權杖簽章。常駐程式每 60 秒向中繼回報伺服器清單和狀態。
  • 機器人本身在 中繼伺服器內部 執行。你的電腦上不會安裝任何與機器人相關的東西。
  • 遊戲伺服器在你的電腦上執行。你電腦上的 Saba-chan 常駐程式會以 長輪詢 向外連線到中繼伺服器,取得指令並將結果傳回。
  • 常駐程式會依 stdin(伺服器主控台)→ REST → RCON 的順序傳送遊戲指令。Palworld 使用其 REST API。只有僅支援 RCON 的遊戲才會使用 RCON,且只透過迴路位址(127.0.0.1)連線。
  • 常駐程式 ↔ 中繼伺服器之間的流量只有 從你的電腦發出的 HTTPS。不需要在路由器設定連接埠轉發。
  • 音樂在中繼端處理,不經過你的電腦,因此即使電腦關機也能運作。

2. 配對

配對會在中繼伺服器上註冊 主機(Saba-chan 常駐程式) 與 節點(Discord 伺服器)。只要輸入一次代碼就能完成。

2.1 流程圖

你的電腦
GUI 應用程式你的電腦
Saba-chan 常駐程式你的電腦
雲端
Discord 中繼Saba-chan 機器人 · 雲端
Discord斜線指令
  1. 1
    GUI 應用程式Saba-chan 常駐程式

    請求配對碼

  2. 2
    Saba-chan 常駐程式Discord 中繼

    申請發放配對碼

  3. 3
    Discord 中繼Saba-chan 常駐程式

    配對碼 + 輪詢密鑰(5 分鐘有效)

  4. 4
    Saba-chan 常駐程式GUI 應用程式

    顯示配對碼

  5. 5
    DiscordDiscord 中繼

    /saba connect code:…

  6. 6
    Discord 中繼

    登記電腦 · 發放節點權杖

  7. 7
    GUI 應用程式Saba-chan 常駐程式

    每 3 秒檢查狀態

  8. 8
    Saba-chan 常駐程式Discord 中繼

    檢查狀態(附輪詢密鑰)

  9. 9
    Discord 中繼Saba-chan 常駐程式

    已連線 + 節點權杖(僅一次)

  10. 10
    Saba-chan 常駐程式

    儲存權杖 · 開始連線中繼

  11. 11
    Saba-chan 常駐程式GUI 應用程式

    顯示「已連線」

即使別人看到配對碼,沒有輪詢密鑰也拿不到權杖。權杖只發放一次,由常駐程式而不是 GUI 儲存。在 Discord 伺服器中連線需要「管理伺服器」權限。
  • 配對代碼為 32 個字元,pollSecret 為 48 個字元。代碼的有效時間為 5 分鐘。
  • 權杖 只會回傳一次(原子交換)。權杖一到,由常駐程式(而非 GUI)將它儲存到 .node_token 並開始中繼連線。應用程式只把輪詢密鑰交給你電腦上的常駐程式,常駐程式再透過標頭(而非 URL)把它傳給中繼伺服器。
  • 即使有人看到你的配對代碼,沒有 pollSecret 也無法攔截權杖。
  • 一個 Discord 帳號可以連線多台電腦。用已經有電腦的帳號連線時,會出現 作為新電腦連接 和選擇以前電腦的 重新連接 按鈕。重新連線後,那台電腦以前的令牌將失效。一個 Discord 伺服器也可以接入多人的電腦(Discord 連動)。

2.2 應用程式端步驟

  1. 在 Saba-chan 應用程式中開啟 Discord → 連線,然後按下 連線 Discord 伺服器。
  2. 若官方 Saba-chan 機器人還不在你的 Discord 伺服器中,請先用 邀請機器人 邀請它。
  3. 畫面上會顯示連線代碼與要輸入的指令。按下 複製,然後在 Discord 頻道中輸入 /saba connect code:<代碼>(應用程式可能顯示韓文名稱 /사바쨩 연결 코드:<代碼>;兩者是同一個指令)。
  4. 只有在該 Discord 伺服器中擁有 管理伺服器 權限的成員可以執行此指令。若在與機器人的私訊中傳送,則不需要 Discord 伺服器,只會將電腦連到你的帳號。
  5. 若是第一次使用的 Discord 帳號,機器人會先引導你註冊。按 註冊 後在網站上確認條款並完成註冊,該回覆就會變成連線確認。在你同意之前,不會連接電腦。
  6. 當機器人顯示詢問是否連線的按鈕時,按 連線。如果輸入的是別人給的代碼,那個人的電腦會連到你的帳號,因此只有在代碼是你直接從 Saba-chan 應用程式取得時才按。
  7. 應用程式會每 3 秒透過常駐程式確認狀態,常駐程式儲存 .node_token 後即切換為「已連線」。

配對完成後,常駐程式會自動與中繼伺服器維持長輪詢連線。若在應用程式中關閉 命令轉送 開關,你的電腦就不再接收 Discord 指令,機器人也不會回應。

2.3 不用代碼連線其他 Discord 伺服器

如果你的 Discord 帳號已經配對過,可以在其他 Discord 伺服器中只執行 /saba connect(不帶代碼)。

  • 機器人會立即將連結到你帳號的所有電腦連到該 Discord 伺服器。不需要在電腦上另外接受,也不必選擇電腦。
  • 若是第一次使用的帳號,會先註冊。註冊後該 Discord 伺服器也會登錄到 Saba-chan,沒有連線的電腦時會成為沒有電腦的伺服器(§2.5)。已註冊的帳號若沒有電腦,則會請你改用配對代碼連線。
  • 以這種方式連線的 Discord 伺服器,一開始看不到任何遊戲伺服器。請在電腦的 Saba-chan 應用程式中選擇要用在該 Discord 伺服器的伺服器。
  • 以配對代碼連線的 Discord 伺服器,會遵循應用程式 Discord 連線畫面中的 在新的 Discord 伺服器立即開放我的伺服器 設定。開啟時所有伺服器立即可見,關閉時則自行挑選。
  • 與使用代碼時相同,你需要 管理伺服器 權限。若該 Discord 伺服器已連接其他電腦,不會被奪走,而是把你的電腦一併接上。

2.4 解除配對

  • 在應用程式中按下 中斷連線 → 常駐程式會停止命令轉送並刪除 .node_token。這台電腦會與所有 Discord 伺服器中斷連線。
  • 若只要分離一個 Discord 伺服器,請在該伺服器中執行 /saba disconnect。只有連線者或 Discord 伺服器擁有者可以使用,且該伺服器的頻道指定也會一併移除。

2.5 沒有電腦的 Discord 伺服器

沒有安裝 Saba-chan 應用程式的人,也可以邀請機器人來使用會唱歌的 Saba-chan、會說話的 Saba-chan、會朗讀的 Saba-chan、伺服器管理指令與遊戲戰績。

  • 設定儲存在中繼伺服器上。Discord 伺服器擁有者或擁有 管理伺服器 權限的成員可以變更語言、會說話的 Saba-chan 與會唱歌的 Saba-chan 頻道指定、表情符號放大、會說話的 Saba-chan 設定及會朗讀的 Saba-chan 設定。可透過 Discord 的 /saba 指令或 Saba-chan 網頁 進行,第一次變更時會先註冊。
  • 沒有 Saba-chan 等級(權限階梯)與遊戲伺服器指令。通知、遊戲聊天與狀態板頻道是由電腦傳送的,因此無法指定。
  • 之後連接電腦時,會原樣繼承設定,從那時起設定的原本就改由該電腦保管。
  • 聽音樂、聊天等一般成員的使用不需要註冊。

3. 機器人斜線指令

這些是官方機器人根指令底下的指令。在設定為韓文以外語言的 Discord 用戶端中,根指令顯示為 /saba,子指令為英文名稱;韓文則為 /사바쨩。未連接電腦的 Discord 伺服器只會顯示 connect、assign、language、settings、reading、web、big-emoji、help,並且由 Discord 伺服器擁有者或擁有管理伺服器權限的成員取代「節點擁有者」使用。其他斜線指令(/tts、/record、/clear 等)請見 指令。

指令使用者動作
/saba status任何人顯示連線到此伺服器的電腦及各遊戲伺服器的狀態(CPU、RAM)
/saba connect [code]管理伺服器權限以配對代碼連線。代碼留空則將你帳號的所有電腦連到此伺服器(§2.3)。第一次使用須先註冊
/saba disconnect連線者或伺服器擁有者將此伺服器與其電腦中斷連線
/saba permission <level> [user]節點擁有者選擇使用者時,給予該成員指令等級(等級清單中的 解除 會移除個別等級,使其回到預設等級);留空則設定沒有個別等級之成員的預設等級(初始為 User)。等級清單是此伺服器的權限階梯
右鍵點成員 → 應用程式 → 變更 Saba-chan 等級節點擁有者從清單中選擇該成員的指令等級(也有 解除)。與 /saba permission 相同。只有擁有管理伺服器權限的人看得到這個選單
/saba sleep節點擁有者讓機器人在此伺服器進入睡眠(忽略所有訊息)
/saba wake節點擁有者喚醒機器人
/saba assign kind:<會說話的 Saba-chan|會唱歌的 Saba-chan|通知|遊戲聊天|狀態板>節點擁有者、伺服器擁有者將此頻道指定為會說話的 Saba-chan 頻道(可多個,最多 20 個;會說話的 Saba-chan 只在這些頻道說話)、會唱歌的 Saba-chan 頻道(一個;一般訊息會被刪除,因此會要求確認)、通知頻道(一個;伺服器當機、更新、備份與排程重新啟動的通知,當機通知還附有 重新啟動 按鈕)、遊戲聊天頻道(一個;轉送遊戲伺服器內的聊天)或狀態板頻道(一個;每個已開啟的伺服器一張狀態卡片)。詳情請見 指令 的頻道功能。一個頻道只能有一種用途;再次執行相同種類會將其移除。也可以在應用程式的 Discord 伺服器 → 伺服器管理 分頁的 Saba-chan 指定 中變更
/saba language <language>節點擁有者機器人在此伺服器回覆所用的語言(Auto = 跟隨已連結應用程式的語言)
/saba settings節點擁有者變更此伺服器上會說話的 Saba-chan 的設定(開/關、執行指令前確認、網頁搜尋、記憶、工具包、呼叫詞)。只有你看得到
/saba reading節點擁有者此伺服器會朗讀的 Saba-chan 的音量、速度、音高與稱呼名字設定。只有你看得到
/saba big-emoji state:<On|Off>節點擁有者、伺服器擁有者把只含一個自訂表情符號的訊息換成大圖重新發送(預設關閉)
/saba web任何人(自己的帳號)Saba-chan 網頁的一次性連結(5 分鐘)。有電腦時包含該電腦,沒有電腦時只含你所管理 Discord 伺服器的設定。只有你看得到
/saba help任何人顯示 Saba-chan 的使用方法與指令清單(只有你看得到)
/mysaba web任何人(自己的帳號)與 /saba web 相同。在任何伺服器或私訊中都能用
/mysaba my-pcs任何人(自己的電腦)列出連線到你 Discord 帳號的電腦,改名或刪除(只有自己能看到)
/mysaba agent任何人(自己的帳號)查看並中斷連到你 Discord 帳號的 AI 代理(遠端 MCP)。沒有時會顯示要填入代理的網址。私訊中也可用,只有自己能看到(連接 AI 代理)
/saba update連線電腦的人檢查連線到此伺服器的電腦上的 Saba-chan 更新,點確認按鈕後應用程式

/mysaba 是關於你自己帳號的指令,因此不會出現在伺服器成員的指令清單中。連接電腦後,用機器人顯示的 安裝到我的帳號 按鈕把 Saba-chan 安裝到你的 Discord 帳號,之後在任何伺服器或私訊中都只有你看得到。在與機器人的私訊中,不安裝也能使用 /saba web、/saba my-pcs、/saba agent。

在已連接電腦的 Discord 伺服器中,權限、睡眠、語言、會唱歌的 Saba-chan 與會朗讀的 Saba-chan 設定的原本儲存在你電腦上的 Saba-chan 中,因此這些指令在你的電腦開著時才會生效(沒有電腦的伺服器見 §2.5)。相同的設定也可以在應用程式的 Discord 伺服器畫面中變更。權限在 實例 分頁點選伺服器後開啟的 各等級指令、各成員等級 畫面;會唱歌的 Saba-chan 與會朗讀的 Saba-chan 在各自的分頁;語言、前綴與斜線指令樣式在 機器人設定 分頁。一次讓所有 Discord 伺服器睡眠,則在 Discord → 連線 畫面中進行。

3.1 各伺服器的斜線指令與動作選單

配對後,機器人會在每個 Discord 伺服器註冊額外的指令。

  • /<伺服器名稱> command:<指令> arg1:… arg2:…:每個遊戲伺服器實例一個指令。Discord 指令清單中每個伺服器只會顯示一行。點選 command 欄位,就會列出該伺服器可用的指令(啟動、停止、狀態、動作、模組指令),輸入文字可依名稱篩選。參數欄位會依所選指令顯示選項清單、是/否、數字範圍或輸入說明。
  • 指令清單中不會出現以你的等級不能用的指令,以及不符合伺服器目前狀態的指令(已開啟的伺服器的啟動、已關閉的伺服器的停止),你最近在該伺服器用過的指令會排在前面。實際能否使用仍由 Saba-chan 應用程式重新判斷。
  • 動作:Saba-chan 應用程式開放給 Discord 的動作(重新啟動、備份等)也會列在同一個指令清單中。需要確認的動作會顯示將要變更的內容,並且必須由提出請求的人按下執行按鈕。Saba-chan 應用程式的更新不在任務選單中,請用 /saba update。
  • 玩家:遊戲支援時,伺服器的指令清單中會有 玩家 指令,顯示目前線上人數和名字。
  • 還原備份:從清單中選擇要還原的備份(輸入文字可篩選)。伺服器正在執行時會先詢問,按 停止並繼續 會先停止伺服器再還原。還原是危險操作,執行前會再確認一次。只有發出請求的人能按按鈕。
  • 啟動完成通知:透過 /<伺服器名稱> 斜線命令、通知上的 重啟 按鈕或會說話的 Saba-chan 啟動或重新啟動伺服器後,伺服器可以接受連線時會在同一頻道通知。最終沒能啟動時,會用一行說明原因。
  • 只會顯示該伺服器允許的實例(應用程式的 Discord 伺服器 → 實例 分頁)。

4. 聊天指令(前綴)

配對完成後,你可以在 Discord 文字頻道中使用以前綴為基礎的指令操作伺服器。

Saba-chan <server> <command> [args…]

預設前綴是 Saba-chan。你可以在應用程式的 Discord 伺服器 → 機器人設定 分頁的 指令前綴 中,依各 Discord 伺服器變更或新增。

<server> 可以是實例名稱、伺服器別名,或模組名稱或別名。所有模組共用的指令:

指令說明
start啟動伺服器。範例:Saba-chan minecraft start
stop停止伺服器
status查詢狀態

稱呼伺服器與指令的詞,在應用程式的伺服器畫面 → Discord 分頁中設定。完整指令清單請參考 指令 文件。


5. 權限等級

等級為 擁有者(3)> 管理員(2)> 使用者(1)> 訪客(0)> 禁止(-1)。等級是累積的,上層等級可以使用下層等級能使用的所有指令。

  • 擁有者 是連線該伺服器的人(節點擁有者)。他們可以使用所有指令,且無法被降級。
  • 每個指令都有風險等級(安全、注意、危險),在預設方案下,所需等級為 安全 = 訪客、注意 = 使用者、危險 = 管理員。在應用程式的 Discord 伺服器 → 實例 分頁點選伺服器,在 各等級指令 階梯中選擇方案(寬鬆、預設、嚴格),或把指令標籤移到其他等級。成員等級與預設等級在同一處的 各成員等級 設定,並同時套用到該 Discord 伺服器的所有伺服器。
  • 說明、清單只要不是禁止,任何人都能使用。禁止 的成員無法使用包括會唱歌的 Saba-chan、會說話的 Saba-chan 在內的所有機器人功能。
  • 經由會說話的 Saba-chan 發出的請求不能超過 會說話的 Saba-chan 上限(預設為訪客)。

再確認:執行前是否要以確認按鈕詢問請求者,在應用程式的 Discord 伺服器 → 機器人設定 分頁的 再確認 卡片(或 saba-chan-cli bot confirm)中設定。直接對機器人提出的請求(前綴、斜線指令)預設只詢問危險的指令;會說話的 Saba-chan 預設詢問所有指令;兩者都可從 所有指令、注意以上、僅危險指令、不詢問 中選擇。可以在權限畫面的標籤編輯視窗中,更改每個指令用於再確認的風險等級(所需等級不會改變)。會說話的 Saba-chan 選出的管理作業,無論設定如何都一定會詢問。確認按鈕只有發出請求的人能按。


6. 音樂功能

音樂播放由與中繼伺服器一同運作的 官方音樂伺服器(music-server) 處理。

  • 執行 Saba-chan play … 之類的指令時,機器人會將其交給音樂伺服器,由音樂伺服器將音訊串流到 Discord 語音頻道。
  • 你不需要在電腦上安裝 ffmpeg/yt-dlp。
  • 音樂指令在任何頻道都能使用。若用 /saba assign kind:會唱歌的 Saba-chan 設定了會唱歌的 Saba-chan 頻道,就可以在該頻道不加前綴輸入指令(或只輸入搜尋詞),並會顯示播放器畫面。
  • 會唱歌的 Saba-chan 預設為開啟;可在應用程式的 Discord 伺服器 → 會唱歌的 Saba-chan 分頁中關閉。開啟的伺服器會有 /music 斜線指令(指令 第 5 節)。

7. 會說話的 Saba-chan(AI 對話)

  • 會說話的 Saba-chan 必須先在應用程式中註冊 API 金鑰,並依各 Discord 伺服器開啟才能運作(在 Discord 伺服器畫面的 會說話的 Saba-chan 分頁或 /saba settings;新伺服器預設為關閉)。金鑰只有你的電腦與中繼伺服器知道,絕不會顯示在 Discord 中。
  • 要使用的工具(操作遊戲伺服器、網頁搜尋、LoL、TFT、PUBG 戰績、楓之谷角色、多款遊戲搜尋、生活資訊、圖片生成)也依各 Discord 伺服器開啟。在應用程式共用選單中以 全域允許的工具 封鎖的工具,在任何伺服器都不會使用。沒有開啟遊戲伺服器工具時,它不會操作伺服器。
  • 會說話的 Saba-chan 只在以 /saba assign kind:會說話的 Saba-chan 指定的頻道中說話。在其他頻道中,即使被呼叫也不會回應。
  • 會說話的 Saba-chan 只能使用模組或擴充功能對它開放的動作。其他請求一律拒絕。
  • 查詢會立即執行。會變更內容的動作會先建立計畫,並依再確認階段(§5,預設為所有指令)經過確認按鈕;管理類動作一定會經過確認按鈕。確認按鈕只有發出請求的人能按。
  • 執行權限不會超過會說話的 Saba-chan 上限(§5)。
  • 會說話的 Saba-chan 開啟時,常駐程式無法辨識的聊天指令會由會說話的 Saba-chan 轉換為精確的指令,再嘗試一次。
  • 向會說話的 Saba-chan 詢問日誌,它會讀取伺服器日誌,包括以前的執行紀錄。要求以檔案提供時,會不經過 AI 直接附上 .log 檔案(最多 4 MiB,超出時保留最新部分;IP、密鑰和路徑會被遮蓋)。

8. 安全模型

  • 常駐程式會透過 HTTPS,將配對取得的節點權杖(sbn_{hostId}.{secret})放在 Authorization: Bearer 標頭中傳送。中繼伺服器會將此權杖與其儲存的 Argon2 雜湊比對。
  • 中繼伺服器絕不儲存權杖本身,而是與 Argon2 雜湊比對。
  • 常駐程式不接受任何傳入連線。遊戲伺服器密碼不會傳送到中繼伺服器。

9. 疑難排解

症狀原因 / 解決方法
機器人沒有回應確認前綴(預設 Saba-chan)以及其後有空格。機器人必須在伺服器中、配對必須完成,且應用程式中的 命令轉送 必須開啟。也請確認機器人沒有被 /saba sleep 設為睡眠
Saba-chan … start → 找不到伺服器第一個詞是伺服器(實例名稱/別名或模組名稱/別名),第二個詞是指令。若你執行同一款遊戲的多個伺服器,請使用實例名稱或伺服器別名
配對代碼已過期代碼的有效時間為 5 分鐘,現已過期。請在應用程式中取得新代碼
應用程式一直在等待確認 /saba connect 斜線指令確實已執行,且你擁有管理伺服器權限
Discord 指令傳不到電腦在其他地方配對時用 重新連接 選了這台電腦,這台電腦以前的連線就會中斷。請再次為這台電腦配對

更詳細的疑難排解流程請參考 疑難排解 文件。