문제 해결

사바쨩 운영 중 자주 마주치는 문제와, 실제 코드 동작 기준의 해결 절차.

문제 해결

이 문서는 사용자가 겪는 실제 증상별로 데몬 코드가 어떻게 동작하는지와 해결 절차를 정리합니다. 명령 예시와 경로는 Windows 기준입니다. 리눅스에서는 데이터 폴더가 ~/.config/saba-chan입니다.


1. 데몬이 뜨지 않음 / GUI가 연결되지 않음

1.1 포트 충돌 / 데몬이 이미 실행 중

데몬(saba-core)의 기본 포트는 57474이며 127.0.0.1에만 열립니다.

  • 데몬은 PC당 하나만 실행됩니다. 이미 데몬이 떠 있으면 새로 띄운 데몬은 바로 종료하고, GUI·CLI는 떠 있는 데몬에 연결합니다.
  • 다른 프로그램이 포트를 쓰고 있으면 데몬은 2초 간격으로 10번 다시 시도한 뒤 종료합니다.
# Windows: 누가 쓰는지 확인
Get-NetTCPConnection -LocalPort 57474 | Select-Object OwningProcess
Get-Process -Id <pid>
  • 데몬이 살아 있는지는 토큰 없이 http://127.0.0.1:57474/health로 확인할 수 있습니다. saba-chan-cli daemon status도 같은 정보를 보여 줍니다.
  • 응답이 없는 데몬이 남아 있다면 saba-chan-cli daemon stop으로 끄세요. 그래도 남으면 Stop-Process -Name saba-core -Force.
  • 포트 변경이 필요하면 config.json의 gui.ipcPort를 수정한 뒤 재기동합니다. 또는 SABA_IPC_PORT=57480 같이 환경변수를 넣습니다.

1.2 IPC 토큰 불일치

데몬은 켜질 때마다 .ipc_token을 새로 만듭니다. GUI와 CLI는 인증이 실패(401)하면 토큰 파일을 다시 읽고 한 번 더 시도하므로 보통은 저절로 해결됩니다.

그래도 "인증 실패" 가 반복된다면:

  • GUI와 데몬이 같은 데이터 폴더를 보고 있는지 확인합니다. SABA_DATA_DIR 이나 SABA_TOKEN_PATH를 한쪽에만 넣었다면 토큰 파일 위치가 달라집니다.
  • GUI를 완전히 종료한 뒤 다시 실행합니다.

2. 서버 시작/정지가 이상하게 동작

2.1 정지를 눌렀는데 한동안 아무 반응 없음

정상일 수 있습니다. 데몬은 다음 순서로 처리합니다.

  1. 콘솔이 있는 서버는 모듈의 stop_command를 콘솔(stdin)로 보냅니다. Palworld처럼 콘솔이 없는 게임은 모듈이 REST로 저장·종료를 요청합니다.
  2. 서버가 스스로 꺼지기를 기다립니다. 기본 30초이며, 모듈이 module.toml의 [config] stop_timeout으로 바꾸고, 사용자는 서버 화면 사바쨩 탭의 정지 대기 시간으로 서버마다 바꿀 수 있습니다. 월드가 커서 저장이 오래 걸리면 늘리세요.
  3. 그래도 살아 있으면 강제 종료합니다.
  4. 정지 후 30초 동안은 크래시 감지를 하지 않습니다.

매번 강제 종료까지 간다면 서버가 정지 명령을 받지 못하는 것입니다. 서버 콘솔에서 정지 명령이 찍히는지 확인하세요. 예: Minecraft stop, Zomboid quit.

2.2 서버가 계속 다시 켜짐

서버가 꺼지면 데몬이 종료 원인을 직접 끔 / 게임 안에서 끔 / 크래시 / 알 수 없음으로 판정합니다. 자동 재시작은 기본적으로 크래시일 때만 동작하고, 대기 시간이 5초부터 두 배씩 늘고, 10분 안에 3번을 넘으면 재시작을 멈춥니다.

해결:

  • 서버 화면의 "최근 종료 기록" 에서 판정 결과를 확인합니다.
  • 다시 켜지 않게 하려면 서버 화면 사바쨩 탭의 "자동 재시작" 에서 "크래시 나면 다시 켜기" 를 끕니다. "이유를 모를 때도 다시 켜기" 를 켜 두었다면 그것도 확인하세요.
  • 서버 콘솔 기록(instances\<id>\logs\)에서 크래시 원인을 확인합니다. Java OOM(OutOfMemoryError)이면 메모리 설정을 늘리세요.

2.3 시작할 때 "포트 충돌" 오류

시작 전 점검에서 그 서버의 포트를 실행 중인 다른 인스턴스나 다른 프로그램이 쓰고 있는 것이 확인된 경우입니다. 대개 이전 프로세스가 남아 있거나, 같은 포트를 다른 게임 서버가 쓰는 중입니다.

  • 해당 포트를 쓰는 프로세스를 확인한 뒤 종료합니다.
  • 불가능하면 인스턴스 설정에서 포트를 바꾸고 다시 시작합니다.
  • 검사 자체는 GUI 설정의 "포트 충돌 검사"(gui.portConflictCheck)로 끌 수 있지만 권장하지 않습니다.

2.4 "약관 동의가 필요합니다" (Minecraft EULA 등)

모듈이 약관을 선언한 게임(예: Minecraft EULA)은 사용자가 원문을 읽고 동의해야 서버를 켤 수 있습니다. 동의하지 않으면 시작이 agreement_required로 막힙니다.

  • GUI에서 서버를 켜면 나오는 동의 창에서 원문을 읽고 체크한 뒤 "동의하고 켜기" 를 누릅니다.
  • 디스코드에서는 동의할 수 없습니다. PC의 사바쨩에서 한 번 동의하면 그 뒤로는 디스코드에서도 켤 수 있습니다.

2.5 서버 설정 저장이 거부됨

  • unknown_setting: 인스턴스 공통 항목도, 그 모듈이 선언한 설정도 아닌 키입니다. 오타이거나 다른 게임의 설정입니다.
  • validation_failed / invalid_format: 값의 범위나 형식이 모듈 선언과 다릅니다. 오류에 표시된 항목을 고치세요.
  • "설정은 저장했지만 게임 설정 파일에 쓰지 못했어요": 설정은 저장됐지만 모듈이 게임 설정 파일을 고치지 못했습니다. 게임 파일이 다른 프로그램에 잠겨 있지 않은지 확인하고 다시 저장하세요.

2.6 확인되지 않은 구성요소가 실행되지 않음

공식 카탈로그에서 받지 않았거나 받은 뒤 파일이 바뀐 모듈·익스텐션은 "확인 안 됨" 으로 표시됩니다. 사바쨩은 이들을 백신으로 검사하지 않습니다. Windows에서는 AppContainer, 리눅스에서는 bubblewrap으로 격리해 실행하고, 격리할 수 없는 환경(bubblewrap이 없거나 쓸 수 없는 리눅스, macOS)에서는 현재 파일에 대해 사용자가 동의한 뒤에만 실행합니다. 실행이 막히면 다음 코드 중 하나가 표시됩니다.

코드뜻해결
launch_outside_instance모듈이 서버 폴더 밖의 프로그램을 실행하려 함모듈 출처를 확인하세요
sandbox_unavailable이 PC에서 격리 환경을 준비하지 못함아래 참고

sandbox_unavailable 일 때 GUI는 "격리 없이 실행할까요?" 를 묻습니다. 믿을 수 있는 구성요소일 때만 허용하세요. 허용하면 그 구성요소는 내 계정 권한으로 모든 파일과 네트워크에 접근할 수 있습니다. 동의는 이 PC에서만 할 수 있고, 구성요소 파일이 바뀌면 다시 묻습니다. 동의는 GUI 설정 → 고급의 "격리 없이 돌리기" 에서 취소할 수 있습니다.

가장 확실한 방법은 모듈·익스텐션을 공식 카탈로그에서 다시 설치하는 것입니다. 확인된 구성요소는 이 검사를 거치지 않습니다.


3. 설치·업데이트 관련

3.1 설치가 중간에 실패

  • 인스톨러가 멈추면 오류 화면에 원인 코드(fetch_failed, download_failed, extract_failed, elevation_failed, installer_outdated)와 로그 경로가 표시됩니다. 로그는 %TEMP%\saba-chan-installer.log에 남습니다.
  • installer_outdated는 인스톨러가 최신 릴리스보다 오래됐다는 뜻입니다. 최신 인스톨러를 받아 실행하세요.
  • 네트워크 문제라면 연결을 확인한 뒤 다시 시도를 누르거나 인스톨러를 다시 실행합니다.
  • Python 런타임 준비는 실패해도 설치를 멈추지 않습니다. 사바쨩을 처음 실행할 때 데몬이 다시 준비하고, 인스톨러를 다시 실행하면 손상된 런타임을 지우고 새로 받습니다.

3.2 서버 설치 진행이 보이지 않거나 멈춤 (모듈 개발자용)

서버 설치 진행은 GET /api/provision-progress/:name으로 볼 수 있습니다.

  • 모듈/익스텐션이 진행을 stderr에 PROGRESS:{json} 형식으로 찍는지 확인합니다.
  • JSON이 유효한지 확인합니다(message 안의 큰따옴표·개행 이스케이프).
  • 성공한 진행 정보는 5초 뒤 사라지므로, 너무 늦게 폴링하면 이미 비어 있을 수 있습니다. 실패한 정보는 사용자가 닫을 때까지 남고, 새로 만들던 서버였다면 닫을 때 그 인스턴스가 지워집니다.

3.3 업데이트가 적용되지 않음

업데이트는 서버쨩이 제공하는 서명된 릴리스 정보로 확인하고, 파일마다 해시를 검사한 뒤 적용합니다. 서명이나 해시가 맞지 않으면 적용하지 않습니다.

  • 업데이트 뒤 "업데이트하지 못한 항목이 있어요" 알림이 뜨면 눌러서 실패한 항목을 확인합니다.
  • GUI 설정에서 업데이트를 다시 확인하고 적용합니다.
  • 데몬·GUI·설치 프로그램 자신을 바꾸는 업데이트는 데몬이 종료된 뒤 설치 프로그램(saba-chan-installer)이 적용합니다. 적용 중에는 사바쨩을 다시 실행하지 마세요.
  • 그래도 안 되면 사바쨩을 종료하고 updates\ 폴더를 비운 뒤 다시 시도합니다.

4. 디스코드 봇 / 클라우드 페어링

4.1 봇이 반응 없음

  • 접두사(기본 사바쨩) 바로 뒤에 공백을 두고 서버 이름과 명령을 씁니다. 예: 사바쨩 minecraft status.
  • GUI에서 페어링이 완료되어 .node_token이 저장된 상태여야 합니다.
  • 사바쨩(데몬)이 켜져 있어야 합니다. 봇은 클라우드에서 돌지만, 명령은 이 PC의 데몬이 실행합니다.
  • 데몬이 서버쨩에 연결하지 못하면 GUI 설정 → 고급의 "진단 정보" 에서 최근 경고를 확인합니다. "older than relay minimum" 이 보이면 사바쨩을 업데이트하세요.
  • 디스코드 서버에 공식 봇이 초대되어 있는지, 봇이 잠자기 상태가 아닌지 확인하세요. 잠자기 상태라면 /사바쨩 기상으로 깨웁니다.

4.2 페어링 코드가 "expired"

페어링 코드는 5분 동안만 유효합니다. GUI에서 새 코드를 발급하세요.

4.3 서버쨩 연결이 401로 거부됨

오류원인해결
TOKEN_REPLACED다른 곳에서 페어링하며 다시 연결로 이 PC를 골라 이 PC의 토큰이 교체됨이 PC를 계속 쓰려면 다시 페어링
INVALID_TOKEN / NODE_NOT_FOUND.node_token이 잘못됐거나 서버에서 삭제됨다시 페어링 (기존 토큰은 무효화)
MISSING_TOKEN / INVALID_TOKEN_FORMAT토큰 파일이 없거나 형식이 깨짐다시 페어링

4.4 노래하는 사바쨩 명령어가 먹히지 않음

  • GUI 디스코드 화면의 그 디스코드 서버 설정에서 노래하는 사바쨩이 켜져 있는지 확인합니다.
  • 명령을 친 사람이 디스코드 음성 채널에 먼저 들어가 있어야 합니다. 봇이 음성 채널에 들어가지 못하면 봇의 채널 권한을 확인하세요.
  • 재생은 공식 음악 서버가 처리하므로 사용자 PC에 ffmpeg/yt-dlp가 없어도 됩니다.

4.5 원격 데몬에 붙지 못함

보이는 말조치
그 PC가 원격 연결을 열지 않았어요서버 PC에서 설정 → 연결 → 원격 데몬의 원격 연결 받기가 꺼져 있습니다. 켜고 저장합니다
원격 데몬에 닿지 못했어요서버 PC와 그 PC의 사바쨩이 켜져 있고 인터넷에 연결돼 있는지 확인합니다. 바로 닿지 않으면 사바쨩 클라우드를 거쳐 붙으므로 포트포워딩이 꼭 필요하지는 않습니다
이 PC가 디스코드에 연결돼 있지 않아요두 PC 모두 같은 디스코드 계정으로 페어링합니다
원격 데몬이 이 PC를 더는 받지 않아요서버 PC에서 연결을 끊었습니다. 내 PC에서 연결을 다시 누릅니다
포트를 이미 쓰고 있어요다른 프로그램이 같은 포트를 씁니다. 포트를 바꿉니다
그 PC에서 직접 해야 하는 일이에요업데이트, 자동 실행처럼 원격으로 할 수 없는 일입니다

4.6 사바쨩 웹 링크가 열리지 않음

  • 링크는 한 번만, 5분 안에 열 수 있습니다. /사바쨩 웹으로 새 링크를 받습니다.
  • PC에 연결하지 못했어요가 나오면 PC의 사바쨩이 켜져 있고 최신 버전인지 확인합니다.
  • PC 없이 연 링크에서는 서버·모듈·PC 메뉴가 잠겨 있습니다. 앱을 설치하고 /사바쨩 연결을 한 뒤 새 링크를 받습니다.
  • 탭을 닫거나 새로 고치면 세션이 끝납니다. 이것은 정상 동작입니다.

5. 데이터·설정 복구

5.1 config.json이 깨짐

  • 데몬은 깨진 config.json을 config.json.corrupt-<시각>으로 옮기고 config.json.bak(직전 정상본)에서 자동으로 복구합니다.
  • .bak도 없거나 깨졌다면 기본값으로 시작합니다. 이때 디스코드 연동 설정 등 모든 설정이 기본값이 되므로, 옮겨진 .corrupt- 파일에서 필요한 값을 GUI로 다시 입력하세요.
  • 서버 목록(instances\)과 .node_token은 config.json과 별개라 그대로 유지됩니다.

5.2 전체 초기화

1. 사바쨩 GUI · CLI · 데몬 종료
2. %APPDATA%\saba-chan 폴더를 통째로 백업 후 삭제
3. 사바쨩 실행 → 기본 상태로 리빌드

주의: 서버를 기본 위치에 설치했다면 게임 서버 파일과 백업이 %APPDATA%\saba-chan\instances\ 안에 있으므로 함께 삭제됩니다. 서버 폴더를 직접 지정해 이 폴더 밖에 설치한 경우에만 게임 파일이 남습니다.


6. 로그 어디서 보나요

위치내용
%APPDATA%\saba-chan\logs\saba-chan-*.logGUI 로그. GUI가 띄운 데몬의 출력도 함께 남음
GUI 데몬 콘솔 창데몬 로그 (메모리 버퍼, 최근 10,000줄)
GUI 설정 → 문제 해결 → 진단 정보데몬 상태와 최근 경고·오류. 비밀번호와 토큰은 들어가지 않음
%APPDATA%\saba-chan\instances\<id>\logs\서버 콘솔 기록 (console.log, sessions\)
GUI 콘솔 탭인스턴스별 게임 서버 출력
%APPDATA%\saba-chan\audit.log서버 시작·정지·명령 기록 (출처 포함, 비밀값은 가림)
%TEMP%\saba-chan-installer.log인스톨러 로그

데몬 로그 수준은 데몬을 직접 실행할 때 RUST_LOG 환경변수로 바꿀 수 있습니다(기본 info).


7. 이슈 리포트 체크리스트

새 이슈를 열기 전에 다음 정보를 확인·첨부해 주세요.

  1. 사바쨩 버전 (saba-chan-cli version, 또는 GUI 진단 정보).
  2. 재현 단계.
  3. 관련 로그 (시간대 기준으로 자른 발췌). GUI 진단 정보의 "복사" 결과도 도움이 됩니다.
  4. 운영체제 / 빌드 (Windows 10 x64 21H2 등).
  5. 토큰 파일(.ipc_token, .node_token)과 그 내용은 절대 첨부하지 마세요.

리포지토리: