以无头模式运行 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 Web 服务器分开。请保持本地访问。

阅读 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
• 独立应用模式