Social Stream Ninja 헤드리스 실행

네 — 일반 Linux AppImage를 사용하세요

일반 Linux 앱을 다운로드하고 실행 가능하게 설정하세요. 데스크톱이 없는 VPS에서는 AppImage만 실행해서는 부족합니다. 가상 디스플레이와 다음을 사용하세요: --ssapp-headless-control 플래그를 사용하세요. 아래 단계는 SSH 연결을 끊거나 서버를 재부팅한 뒤에도 채팅 캡처를 유지합니다.

헤드리스 모드는 SSApp의 Electron 창을 숨기지만 소스 페이지는 여전히 실제 브라우저 창입니다. 따라서 Linux에는 Xvfb 같은 가상 디스플레이가 필요합니다. 작은 백그라운드 전용 채팅 데몬이 아닙니다.

시작하기 전

• Ubuntu 22.04+, Debian 12+ 또는 비슷한 Linux 배포판을 사용하세요.
• 작은 설정에는 최소 2GB 메모리를 확보하고 소스 창이 여러 개면 더 많이 확보하세요.
• 설정, 소스, 세션, 브라우저 데이터용 영구 프로필 디렉터리를 선택하세요.
• 로그인 및 비공개 설정을 위해 최초 데스크톱 또는 VNC 세션을 계획하세요.

로그인이 필요 없는 공개 소스 URL이 원격 운영에 가장 쉽습니다. OAuth, CAPTCHA, 비밀번호, 쿠키, 계정 설정에는 여전히 사람이 필요합니다.

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에서 로그인을 완료하세요. 다른 운영체제에서 복사한 브라우저 쿠키는 복호화되지 않을 수 있습니다.

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, 쿠키, 자격 증명 또는 다른 비공개 계정 설정을 원격으로 완료하지는 않습니다.

참고: 세션, 비밀번호, 릴레이 및 서버 모드 에서 원격 컨트롤러는 연결되지만 메시지나 명령이 도착하지 않는 문제를 확인하세요.

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 셸에서 실행하세요: 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 는 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"
      }
    }
  }
}

설정 위치는 클라이언트에 따라 다릅니다. 이는 표준 입력/출력으로 별도 어댑터를 실행하며 기본 캡처 앱을 시작하지 않습니다. 집 컴퓨터의 클라이언트는 VPS가 아니라 자신의 localhost를 가리킵니다. 다른 컴퓨터에서는 Social Stream의 일반 원격 제어를 사용하세요.

포함된 어댑터는 SSApp 0.4.7부터 사용할 수 있습니다. 0.4.14 이상은 앱을 사용할 수 있기 전에도 전체 도구 목록을 알립니다. 실제 호출 가능 여부는 여전히 실시간 capabilities가 결정합니다. 별도 Node 설치는 필요하지 않습니다. 여기의 헤드리스 Ozone 플래그는 MCP 어댑터에만 적용됩니다. 기본 앱에는 Xvfb를 유지하세요.

시도: 'ssapp_get_capabilities를 호출한 다음 ssapp_get_status와 ssapp_list_sources를 호출하세요. 어떤 소스가 캡처 중이고 오류를 보고하는 소스가 있는지 알려 주세요.' 도구는 소스 시작/중지, 진단, 캡처 이벤트, 스크린샷, 승인된 앱 창 상호작용도 지원합니다. 비공개 로그인과 CAPTCHA에는 여전히 사람이 필요합니다.

다음을 참조하세요: 로컬 제어 API 및 MCP 가이드 에서 선택적 에이전트 스킬, 버전 호환성, 추가 제어를 확인하세요.

Owncast, Rocket.Chat, 강조 메시지

자원이 충분하면 Owncast와 Rocket.Chat이 있는 같은 VPS에서 SSApp을 실행할 수 있습니다. 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
• 독립 실행형 앱 모드