시작하기
사바쨩 설치와 구동, 기본 운영 절차 및 동작 방식을 안내합니다.
시작하기
이 문서는 사바쨩(Saba-chan)의 기본적인 설치와 실행, 서버 생성 절차를 다룹니다. 추가 연동이나 장애 대응은 디스코드 봇과 문제 해결 문서를 참고하십시오.
1. 다운로드 & 설치
요구 사항: Windows 10 또는 11 (64비트), Microsoft Edge WebView2 런타임(Windows 11과 최신 Windows 10에는 기본 포함), 인터넷 연결. 리눅스(x86_64)에는 한 줄 명령으로 설치합니다(아래 1.1). macOS(Apple 실리콘)는 소개 페이지에서 .dmg를 받아 앱을 응용 프로그램 폴더에 끌어 넣습니다. Apple 공증을 받지 않은 앱이라 처음 열 때 막히면 시스템 설정 > 개인정보 보호 및 보안에서 "그래도 열기"를 누릅니다.
- 웹사이트의 다운로드 버튼이나 GitHub Releases에서 설치 프로그램 **
saba-chan-installer.exe**를 다운로드합니다. - 설치 프로그램을 실행하고 설치 경로, 처음 받을 게임 모듈, 바로가기 옵션을 고른 뒤
설치를 누릅니다.- 기본 설치 경로는
C:\Program Files\Saba-chan입니다. 다른 파일이 들어 있는 폴더를 고르면 그 안에Saba-chan폴더를 만들어 설치합니다. - 게임 모듈은 나중에 앱에서 추가할 수도 있습니다.
- 기본 설치 경로는
- 설치 프로그램이 다음 항목을 구성합니다. 네트워크 연결 상태에 따라 수 분이 걸릴 수 있습니다.
- 서명된 최신 릴리스 정보를 확인하고 데몬, GUI, CLI, 로케일 등 구성 요소를 받아 배치 (파일마다 해시를 검사합니다). 설치 프로그램도 설치 폴더에 함께 두어, 나중에 업데이트를 적용하고 사바쨩을 제거할 때 씁니다
- 선택한 게임 모듈과 그 모듈에 필요한 익스텐션(예: SteamCMD) 설치
- 포터블 Python 다운로드 및
venv환경 생성 (사바쨩 전용 폴더에 설치하며 시스템 PATH는 바꾸지 않습니다) - 설치한 구성 요소 버전을
installed-manifest.json에 기록
- 설치가 끝나면
사바쨩 실행버튼으로 GUI를 실행합니다. 바탕화면이나 시작 메뉴 바로가기로도 실행할 수 있습니다.
설정, 게임 서버 파일, 월드, 백업은 %APPDATA%\saba-chan에 저장됩니다. 프로그램 폴더를 지워도 서버 데이터는 남습니다.
다시 설치하기: 설치가 중간에 실패했거나 파일이 손상된 경우 설치 프로그램을 다시 실행하십시오. 프로그램 파일을 다시 받고, 손상된 Python 런타임은 지운 뒤 다시 받습니다. 설정과 서버 데이터는 그대로 유지됩니다. 설치 프로그램이 현재 릴리스보다 오래된 경우 설치가 차단되므로 항상 최신 설치 프로그램을 받으십시오.
1.1 리눅스
리눅스(x86_64)에는 한 줄 명령으로 설치합니다. curl, unzip, sha256sum, python3이 필요합니다.
curl -fsSL https://raw.githubusercontent.com/WareAoba/saba-chan/main/install.sh | sh
- 화면이 있는 데스크톱이면 앱(GUI)까지 설치하고, 앱 메뉴에 사바쨩을 넣은 뒤 앱을 띄웁니다. Windows처럼 앱이 데몬을 켭니다. 앱 창에는 WebKitGTK가 필요합니다. 없으면 설치기가 설치 명령을 알려 줍니다(예:
sudo apt install libwebkit2gtk-4.1-0 libayatana-appindicator3-1). - 화면 없는 서버면 데몬과 CLI만 설치하고, 데몬을 systemd 사용자 서비스로 켭니다.
--gui·--no-gui로 직접 정할 수도 있습니다. - 설치기는 최신 정식 릴리스를 받아 릴리스 해시와 서명된 매니페스트로 파일을 확인한 뒤 설치하고,
~/.local/bin/saba-chan-cli를 만듭니다. 화면 없는 서버에서는 데몬을 systemd 사용자 서비스(saba-chan.service)로 켭니다.sh -s -- --dir <폴더> --modules <모듈…>로 설치 폴더와 모듈을 고릅니다. - 화면 없는 서버에서 로그인하지 않아도 부팅할 때 켜려면
sudo loginctl enable-linger $USER를 한 번 실행합니다. - 데이터 폴더는
~/.config/saba-chan입니다. - 화면 없는 리눅스 서버는 다른 PC의 앱에서 원격 데몬으로 다룹니다. 디스코드 연결과 원격 연결 켜기는 원격 데몬 장에 있습니다.
2. 사바쨩의 구조 이해하기
사바쨩의 내부 컴포넌트와 통신 구조는 다음과 같습니다.
- 데몬(
saba-core.exe): 사바쨩의 모든 기능을 수행하는 핵심 코어입니다. 서버 프로세스를 실행·관리하고 로그를 수집하며, 로컬127.0.0.1:57474에서만 HTTP API를 제공합니다. - GUI: 데몬 API를 호출하는 데스크톱 앱입니다.
- CLI: 데몬 API를 호출하는 명령줄 도구입니다. 인자 없이 실행하면 대화형 셸로 동작합니다.
- 러너(
saba-runner): 서버마다 붙는 작은 감시 프로세스입니다. 데몬이 다시 시작되어도 서버 콘솔과 로그를 이어 줍니다. - 서버쨩(릴레이 서버): 디스코드 봇이 동작하는 클라우드 서비스입니다. 페어링하면 데몬이 바깥으로 연결(long-polling)하여 디스코드 관리 명령을 전달받으며, 모든 요청은 페어링 때 받은 노드 토큰으로 HTTPS 위에서 인증됩니다. 서버쨩은 디스코드 명령과 결과, 서버 요약만 주고받고 게임 트래픽은 다루지 않으므로, 게임 접속을 위한 네트워크 설정은 별도로 필요합니다.
게임 서버는 사용자의 PC에서 실행됩니다. GUI와 CLI는 데몬에 요청만 보내고 직접 파일을 수정하거나 프로세스를 실행하지 않습니다.
GUI 창을 닫을 때 '인터페이스만 종료'를 선택하면 백그라운드에서 데몬과 게임 서버가 계속 실행됩니다. GUI를 다시 실행하면 데몬에 재연결되어 기존 서버 상태와 콘솔 로그를 이어받습니다. 데몬이 재시작된 경우에도 기존에 실행 중이던 서버 프로세스에 다시 연결(Re-attach)하여 상태를 추적합니다(단, PC 재부팅이나 정전 등으로 프로세스가 종료된 경우에는 복원되지 않습니다). 개별 게임 서버만 정지하려면 인터페이스에서
정지버튼을 눌러야 합니다.
3. 첫 서버 만들기 (GUI 기준)
사바쨩이 처음 실행되면 서버 목록이 비어 있고, '다음 할 일' 카드가 게임 모듈 설치와 첫 서버 만들기를 안내합니다. 게임 모듈이 하나도 없다면 먼저 앱의 사바 스토리지에서 모듈을 설치합니다. 다음 순서로 서버를 생성합니다.
- 서버 추가:
서버 추가를 누르고새 서버 만들기를 선택합니다. 쓰던 서버 폴더를 그대로 연결하려면기존 서버 가져오기를 선택합니다. - 게임 선택: 설치된 게임 모듈(공식 모듈: Minecraft, Palworld, Project Zomboid, Terraria) 중 하나를 선택합니다.
- 서버 구성: 서버 이름을 입력하고, 모듈이 묻는 항목(예: Minecraft 서버 종류)과 추천 설정을 고릅니다. 포트(게임이 접속을 받는 번호)는 다른 서버와 겹치지 않게 자동으로 정해집니다.
- 약관 동의: Minecraft처럼 약관(EULA) 동의가 필요한 게임은 원문을 확인하고 직접 체크해야 서버를 만들 수 있습니다. 사바쨩은 약관에 자동으로 동의하지 않습니다.
- 설치 시작:
서버 추가를 누르면 데몬이 다음 순서로 설치 작업을 처리합니다.- 모듈에 필요한 익스텐션 확인 (예: Palworld, Project Zomboid는 SteamCMD 필요). 필요한 익스텐션이 꺼져 있으면 설정 → 익스텐션에서 켜라는 안내가 나옵니다.
- 인스턴스 정보를
%APPDATA%\saba-chan\instances\<인스턴스 ID>\폴더에 저장 server.post_create훅 실행- 게임 서버 파일의 최신 버전을 받아 인스턴스 폴더의
server\에 배치 (Minecraft·Terraria는 공식 서버 파일 다운로드, Palworld·Project Zomboid는 SteamCMD). 진행률은 프로그레스 바에 표시됩니다.
- 시작:
시작버튼을 누르면 데몬이 약관 동의와 시작 전 점검을 확인하고,server.pre_start훅을 실행한 뒤 모듈의 실행 명령(get_launch_command)으로 프로세스를 띄웁니다. 서버 콘솔 출력은 GUI 콘솔에 실시간으로 표시됩니다.
모든 게임 명령은 데몬을 거쳐 stdin(서버 콘솔) → REST → RCON 순서로 전달됩니다. 콘솔이나 REST API(Palworld 등)가 있는 게임은 RCON을 끈 상태로 운영합니다. RCON만 지원하는 게임에서만 RCON을 쓰며, 이때 포트와 무작위 비밀번호는 데몬이 인스턴스마다 정하고 루프백(127.0.0.1)으로만 연결합니다.
4. 운영 중 알아 두어야 할 동작
4.1 정지 타임아웃
데몬이 직접 관리(managed)하는 프로세스에서 사용자가 정지를 실행하면 다음 순서로 프로세스 종료를 시도합니다. 관련 설정값은 src/supervisor/mod.rs에 정의되어 있습니다.
- Graceful stop: 모듈의
stop_command(예: Minecraftstop, Zomboidquit)를 서버 콘솔(stdin)로 보냅니다. 콘솔 입력이 없는 게임(Palworld)은 모듈이 REST API로 저장·종료를 요청합니다. 그 뒤 정지 대기 시간(서버의 사바쨩 탭에서 정한 값, 없으면module.toml의[config].stop_timeout, 그것도 없으면 30초) 동안 대기하고, 시간 초과 시 프로세스를 강제 종료한 뒤 2초간 추가 대기합니다. - Force kill: 강제 정지 시 즉시 프로세스 트리를 강제 종료한 뒤 최대 5초 동안 대기합니다.
- Stop cooldown: 정지 직후 30초 동안은 크래시 자동 감지를 멈춥니다. 정상 종료 중에 프로세스가 사라지는 것을 크래시로 잘못 보지 않게 하려는 것입니다.
4.2 크래시 처리
서버가 꺼지면 데몬은 종료 원인을 직접 끔, 게임 안에서 끔, 크래시, 이유 모름 중 하나로 판정하고 서버의 '최근 종료 기록'에 남깁니다. 비정상 종료 코드나 모듈이 지정한 크래시 흔적이 있을 때만 크래시로 판정하며, 흔적이 없으면 크래시로 보지 않습니다.
- 자동 재시작: 서버 화면 사바쨩 탭의 '자동 재시작'에서 켜고 끕니다.
크래시 나면 다시 켜기는 기본으로 켜져 있고,이유를 모를 때도 다시 켜기는 기본으로 꺼져 있습니다. 직접 끄거나 게임 안에서 끈 서버는 다시 켜지 않습니다. - 재시작 간격: 첫 재시작은 5초 뒤이며, 재시작할 때마다 대기 시간이 두 배로 늘어납니다. 10분 안에 3번을 넘으면 재시작을 멈추므로, 로그를 확인한 뒤 직접 다시 시작해야 합니다.
4.3 로그 위치
- GUI 로그:
%APPDATA%\saba-chan\logs\(GUI가 띄운 데몬의 출력도 함께 기록됩니다). 데몬 로그는 CLI의saba-chan-cli daemon logs로도 볼 수 있습니다. - 서버 콘솔 로그:
%APPDATA%\saba-chan\instances\<인스턴스 ID>\logs\. 러너로 실행한 서버는 실행마다sessions\아래에 파일을 만들고 기본 20개를 보관합니다. - 콘솔 화면: 데몬은 인스턴스마다 최근 10,000줄을 메모리에 보관하며, GUI는
consoleBufferSize(기본 2000줄) 한도 안에서GET /api/instance/:id/console?since=…엔드포인트를 커서 기반으로 폴링하여 표시합니다.