以無頭模式執行 Social Stream Ninja

可以 — 使用一般 Linux AppImage

下載一般 Linux 應用程式，並賦予執行權限。在沒有桌面的 VPS 上，僅啟動 AppImage 還不夠：請使用虛擬顯示器和 --ssapp-headless-control 旗標。下列步驟會讓聊天擷取在中斷 SSH 和伺服器重新啟動後繼續執行。

無頭模式會隱藏 SSApp 的 Electron 視窗，但來源頁面仍是真實的瀏覽器視窗。因此 Linux 需要 Xvfb 之類的虛擬顯示器。這並不是一個只在背景執行的小型聊天常駐程式。

開始之前

• 使用 Ubuntu 22.04+、Debian 12+ 或類似的 Linux 發行版。
• 小型設定至少預留 2 GB 記憶體；多個來源視窗需要更多記憶體。
• 選擇一個持久的設定檔目錄，用於儲存設定、來源、工作階段和瀏覽器資料。
• 安排一次桌面或 VNC 工作階段，用於登入及其他私人設定。

無需登入的公開來源 URL 最容易遠端操作。OAuth、CAPTCHA、密碼、Cookie 和帳號設定仍需人工完成。

1. 安裝 Xvfb 和 AppImage

sudo apt-get update
sudo apt-get install -y xvfb x11-utils xauth curl
sudo mkdir -p /opt/socialstream
sudo mv ./YOUR_DOWNLOADED_FILE.AppImage /opt/socialstream/socialstreamninja.AppImage
sudo chmod 755 /opt/socialstream/socialstreamninja.AppImage

從下列位置下載目前的 Linux AppImage： Social Stream Ninja 下載頁面。選擇與你的伺服器架構相符的下載項目（uname -m），然後替換 YOUR_DOWNLOADED_FILE.AppImage 為其準確檔名。無需取出原始碼，也無需單獨安裝 Node。

2. 準備設定檔並登入一次

設定程序和背景服務使用相同帳號及資料目錄。建立專用帳號：

id ssapp >/dev/null 2>&1 || sudo useradd --system --create-home --home-dir /var/lib/ssapp --shell /usr/sbin/nologin ssapp
sudo install -d -o ssapp -g ssapp -m 700 /var/lib/ssapp
sudo apt-get install -y x11vnc
sudo -u ssapp Xvfb :99 -screen 0 1920x1080x24 -nolisten tcp -extension GLX

保持該終端機執行。在第二個 SSH 終端機中，以可見方式在該虛擬顯示器上開啟 SSApp：

sudo -u ssapp env DISPLAY=:99 SSAPP_USER_DATA_DIR=/var/lib/ssapp SSAPP_HEADLESS_CONTROL=0 \
  /opt/socialstream/socialstreamninja.AppImage --ozone-platform=x11 --no-hwa

在第三個 SSH 終端機中啟動暫時性 VNC 存取，並限制為僅伺服器本身可存取：

sudo -u ssapp x11vnc -display :99 -localhost -rfbport 5900 -nopw -forever

在自己的電腦上開啟 SSH 通道：

ssh -N -L 5900:127.0.0.1:5900 you@your-server

將 VNC 檢視器連接到 localhost:5900。設定 Social Stream 工作階段 ID 和選用密碼，新增來源並完成所有登入。啟用 自動啟用 ，用於希望隨 SSApp 啟動的來源。複製聊天停駐面板和精選疊加畫面連結，以供之後使用。

設定完成後結束 SSApp，然後在對應終端機按 Ctrl+C 停止 VNC、通道和 Xvfb。不要同時使用同一設定檔執行設定程序和服務。VNC 連接到已處於無頭模式的執行個體時，通常會顯示空白畫面，因為它的視窗被隱藏。

使用 SSAPP_USER_DATA_DIR，而非 Chromium 的 --user-data-dir。請在 VPS 上完成登入；從其他作業系統複製的瀏覽器 Cookie 可能無法解密。

3. 以無頭模式啟動應用程式

sudo -u ssapp env SSAPP_USER_DATA_DIR=/var/lib/ssapp xvfb-run -a -s "-screen 0 1920x1080x24 -nolisten tcp -extension GLX" \
  /opt/socialstream/socialstreamninja.AppImage \
  --ozone-platform=x11 --ssapp-headless-control --no-hwa

此 --ssapp-headless-control 旗標會隱藏應用程式視窗。這個前景指令會在你停止它時結束；如需無人值守執行，請使用下方的 systemd 服務。主要應用程式仍然需要 Xvfb； --ozone-platform=headless 不能取代虛擬顯示器。

4. 從另一台電腦控制

在無頭應用程式和遠端控制器上使用相同的 Social Stream 工作階段 ID 和選用密碼。一般傳輸方式是 WebRTC。如果環境不適合它，請使用 Social Stream 的託管 WebSocket 伺服器模式。

支援的遠端控制可新增、啟動、停止、重新啟動、靜音和隱藏公開來源。它們不會遠端完成登入、OAuth、CAPTCHA、Cookie、憑證或其他私人帳號設定。

參閱 工作階段、密碼、轉送與伺服器模式 ，適用於遠端控制器已連線但訊息或指令未到達的情況。

使用 systemd 持續執行

先按 Ctrl+C 停止前景應用程式。建立 /etc/systemd/system/ssapp.service 帶有 sudo nano /etc/systemd/system/ssapp.service 並貼上下列單元設定：

[Unit]
Description=Social Stream Ninja (headless)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=ssapp
StateDirectory=ssapp
WorkingDirectory=/opt/socialstream
Environment=SSAPP_USER_DATA_DIR=/var/lib/ssapp
ExecStart=/usr/bin/xvfb-run -a -s "-screen 0 1920x1080x24 -nolisten tcp -extension GLX" /opt/socialstream/socialstreamninja.AppImage --ozone-platform=x11 --ssapp-headless-control --no-hwa
Restart=on-failure
RestartSec=10
KillSignal=SIGTERM
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now ssapp
journalctl -u ssapp -f

服務使用第 2 步建立的帳號和設定檔。它會在開機時啟動，並在應用程式故障後重新啟動。如果變更了安裝路徑，請更新 ExecStart 使其相符。

供 VPS 上指令碼使用的選用 HTTP API

無頭模式不會啟用控制 API。要為服務啟用它，請執行 sudo systemctl edit ssapp 並儲存下列覆寫設定：

[Service]
Environment=SSAPP_CONTROL_API=1

sudo systemctl daemon-reload
sudo systemctl restart ssapp
curl -sS http://127.0.0.1:17777/api/v1/capabilities
curl -sS http://127.0.0.1:17777/api/v1/status

手動啟動時，加入 --ssapp-control-api 到應用程式指令中。在 SSH shell 中執行下列指令， 在 VPS 上。此 API 刻意不使用權杖，並且僅繫結至 127.0.0.1；它與你的 Owncast 或 Rocket.Chat 網頁伺服器分開。請保持本機存取。

閱讀 ssappVersion, apiVersion，以及 capabilities 中支援的平台。例如，如果支援 Twitch，可新增一個來源（將 CHANNEL_NAME):

curl -sS http://127.0.0.1:17777/api/v1/command \
  -H 'Content-Type: application/json' \
  -d '{"action":"addSource","value":{"target":"twitch","username":"CHANNEL_NAME","autoActivate":true}}'

curl -sS http://127.0.0.1:17777/api/v1/command \
  -H 'Content-Type: application/json' \
  -d '{"action":"getSources","value":{}}' 

複製來源穩定的 id ，從傳回的來源清單中複製，並替換 SOURCE_ID ，參見下文。新增來源後，它會保持未啟用狀態； autoActivate 控制之後的應用程式啟動。

curl -sS http://127.0.0.1:17777/api/v1/command \
  -H 'Content-Type: application/json' \
  -d '{"action":"startSource","value":{"sourceId":"SOURCE_ID"}}'

curl -sS http://127.0.0.1:17777/api/v1/command \
  -H 'Content-Type: application/json' \
  -d '{"action":"getSourceDiagnostics","value":{"sourceId":"SOURCE_ID"}}'

curl -sS http://127.0.0.1:17777/api/v1/command \
  -H 'Content-Type: application/json' \
  -d '{"action":"stopSource","value":{"sourceId":"SOURCE_ID"}}' 

檢查 ok 和 payload 在每個回應中的值；失敗時傳回 error。變更後讀取狀態。如果請求逾時，請先檢查狀態再重試。變更來源的連線欄位前先停止該來源。重新載入、移除和關閉指令需要 confirm: true.

curl -N http://127.0.0.1:17777/api/v1/events 會持續追蹤 Server-Sent Events 資料流，直到按 Ctrl+C。參閱 API 與 MCP 指南 ，查看完整參考。這些是應用程式／來源控制項；精選聊天訊息等疊加畫面動作應使用 Social Stream 停駐面板和 Social Stream 指令.

供 VPS 上 AI 用戶端使用的選用 MCP

MCP 讓相容的 AI 用戶端把 SSApp 控制項作為工具呼叫。啟用上述 API，並保持主要應用程式服務執行。在下列位置執行的用戶端中註冊此設定： 在 VPS 上:

{
  "mcpServers": {
    "social-stream": {
      "command": "/opt/socialstream/socialstreamninja.AppImage",
      "args": ["--ssapp-mcp", "--ozone-platform=headless"],
      "env": {
        "SSAPP_CONTROL_URL": "http://127.0.0.1:17777"
      }
    }
  }
}

設定位置取決於用戶端。此設定透過標準輸入／輸出啟動單獨的轉接器，不會啟動主要擷取應用程式。家用電腦上的用戶端會指向自己的 localhost，而不是你的 VPS。從其他電腦操作時，請使用 Social Stream 的一般遠端控制。

封裝的轉接器從 SSApp 0.4.7 起提供；0.4.14 及更新版本即使在應用程式可用之前，也會公布完整工具集。實際可用能力仍決定哪些呼叫能成功。無需另外安裝 Node。此處的無頭 Ozone 旗標僅適用於 MCP 轉接器；主要應用程式仍需使用 Xvfb。

嘗試： 「呼叫 ssapp_get_capabilities，再呼叫 ssapp_get_status 和 ssapp_list_sources。告訴我哪些來源正在擷取，以及是否有來源回報錯誤。」 工具還涵蓋來源啟動／停止、診斷、擷取事件、擷圖和獲准的應用程式視窗互動。私人登入和 CAPTCHA 仍需人工完成。

請參閱 本機控制 API 與 MCP 指南 ，瞭解選用的代理技能、版本相容性和更多控制項。

Owncast、Rocket.Chat 與精選訊息

只要資源足夠，就可將 SSApp 與 Owncast 和 Rocket.Chat 執行在同一台 VPS 上。僅安裝 SSApp 不會自動連接 Rocket.Chat，也不會將疊加畫面放進視訊。

Supported chat source → SSApp → Social Stream dock / featured overlay
                                           ↓
Video input → server broadcaster renders overlays → Owncast → viewers

本指南檢查的原始碼樹中沒有內建 Rocket.Chat 連接器。將這些訊息送入 Social Stream 需要單獨的整合。設定視訊疊加畫面前，先確認訊息能到達停駐面板。

使用設定時複製的停駐面板和精選疊加畫面 URL，保持相同工作階段／密碼和傳輸方式。在停駐面板中選取擷取到的訊息，將其設為精選。伺服器上的串流程式需要具備瀏覽器來源繪製能力，才能將這些頁面疊加到視訊上，再把合成的直播串流傳送給 Owncast。參閱 Owncast 的串流說明。SSApp 不是這個視訊串流程式。

將疊加畫面放在網站嵌入式播放器上方是另一種方式：它只顯示在該網頁上，不屬於其他播放器或錄影所接收的視訊。Owncast 提供了下列文件： 嵌入視訊和聊天.

如果要關閉家用電腦，視訊來源、串流程式、聊天擷取和任何 Rocket.Chat 整合都必須能獨立於它持續執行。視訊繪製和編碼的資源需求，應與 SSApp 的聊天擷取記憶體分開規劃。

無人值守前檢查完整工作流程

1. 在已連線的聊天中傳送一則真實訊息，並確認它到達 Social Stream 停駐面板。
2. 將該訊息設為精選，並確認精選疊加畫面發生變化。使用 Owncast 時，還需在實際觀眾視訊中驗證。
3. 中斷 VNC 和 SSH，然後在幾分鐘內繼續傳送訊息。擷取應繼續執行。
4. 執行 sudo systemctl restart ssapp，然後確認相同的工作階段和來源重新出現，且自動啟用的來源能收到新訊息。
5. 在維護時段重新啟動 VPS，並重複訊息檢查。僅憑程序正在執行或 API 回應成功，無法證明聊天擷取正常。

使用 sudo systemctl status ssapp 和 sudo journalctl -u ssapp -n 100 --no-pager ，查看服務狀態和最近記錄。要主動停止，請使用 sudo systemctl stop ssapp.

更新時，先停止服務，備份 /var/lib/ssapp，在相同路徑替換 AppImage，然後重新啟動服務。在新版通過訊息檢查之前，請保留舊執行檔。

疑難排解

相關指南

• 本機伺服器和服務說明
• 本機控制API和MCP
• 獨立應用程式模式