설정 파일 가이드
사바쨩의 데이터 폴더와 설정 파일 config.json, 인스턴스 폴더, 토큰 파일을 코드를 기준으로 설명합니다.
설정 파일 가이드
사바쨩의 설정과 상태는 데이터 폴더 %APPDATA%\saba-chan (= C:\Users\<이름>\AppData\Roaming\saba-chan) 아래에 저장됩니다. 이 문서는 그 안의 파일들이 실제 코드에서 어떻게 쓰이는지를 정리하고, 손으로 편집해도 되는 파일과 건드리면 안 되는 파일을 구분해 설명합니다.
모든 기능은 데몬(saba-core)이 맡고, GUI·CLI는 데몬의 로컬 HTTP API만 부릅니다. 그래서 설정도 되도록 GUI·CLI에서 바꾸는 것이 안전합니다. 데몬이 설정을 저장하면서 형식을 검사하기 때문입니다.
1. 폴더 구조
- config.json모든 사용자 설정 (네임스페이스별)모든 사용자 설정 (네임스페이스별)
- config.json.bak직전 정상본 (자동 복구용)직전 정상본 (자동 복구용)
- .ipc_token데몬 ↔ GUI/CLI 인증 토큰 (데몬이 켜질 때마다 새로 만듦)데몬 ↔ GUI/CLI 인증 토큰 (데몬이 켜질 때마다 새로 만듦)
- .node_token디스코드(서버쨩) 연결 토큰. 페어링 때 데몬이 저장디스코드(서버쨩) 연결 토큰. 페어링 때 데몬이 저장
- instances\서버 인스턴스서버 인스턴스
- order.json목록 순서목록 순서
- <id>\
- instance.json인스턴스 정보인스턴스 정보
- settings.json모듈별 게임 설정 값모듈별 게임 설정 값
- logs\서버 콘솔 기록서버 콘솔 기록
- backups\백업백업
- server\기본 설치 위치 (게임 서버 파일)기본 설치 위치 (게임 서버 파일)
- modules\설치된 게임 모듈설치된 게임 모듈
- extensions\설치된 익스텐션설치된 익스텐션
- logs\GUI 로그 (saba-chan-<시각>.log)GUI 로그 (saba-chan-<시각>.log)
- audit.log서버 시작·정지·명령 기록 (비밀값은 가림)서버 시작·정지·명령 기록 (비밀값은 가림)
- updates\업데이트 스테이징업데이트 스테이징
- installed-manifest.json설치된 구성요소 버전설치된 구성요소 버전
- 포터블 Python 런타임(
python-standalone\,python-env\)은 설치 폴더에 쓸 수 있으면 설치 폴더에, 아니면 이 데이터 폴더에 생깁니다. - 이 밖에 데몬이 스스로 관리하는 파일(
daemon.lock,scan-verdicts.json,sandbox-temp\등)도 있습니다. 손대지 마세요. - 환경변수
SABA_DATA_DIR로 데이터 루트 자체를 바꿀 수 있지만, 보통은 권장하지 않습니다.
2. config.json: 모든 설정이 들어가는 파일
사용자 설정은 config.json 한 파일에 네임스페이스(최상위 키)별로 들어갑니다.
| 네임스페이스 | 내용 | 바꾸는 곳 |
|---|---|---|
gui | GUI 동작·테마·언어·데몬 포트 | GUI 설정 화면 |
relay | 디스코드 연동 (접두사, 별명, 디스코드 서버별 설정) | GUI 디스코드 화면 |
updates | 업데이트 확인 주기·자동 다운로드·업데이트 채널(channel) | GUI 설정 화면 |
remote | 원격 데몬: 원격 포트, 짝지은 PC | GUI 설정 → 연결 → 원격 데몬 |
boot | 마지막으로 고른 부트 모드 (GUI / CLI / 데몬만) | 부트 선택기 |
extensions | 켜진 익스텐션 목록 enabled, 익스텐션별 설정 settings | GUI 설정 → 익스텐션 |
chatbot | 말하는 사바쨩(AI 대화) 설정 | GUI 디스코드 화면 |
sandbox | 확인되지 않은 구성요소를 격리 없이 돌리기로 한 동의 | 실행 차단 안내 창, 설정 → 고급 |
cli 등 | 각 클라이언트 전용 설정 | 해당 클라이언트 |
저장과 자동 복구
- 저장은 임시 파일에 쓴 뒤 교체하는 원자적 방식이며, 교체 직전의 정상본을
config.json.bak으로 남깁니다. config.json이 깨져 읽을 수 없으면 데몬이config.json.corrupt-<시각>으로 옮겨 두고.bak에서 복구합니다.gui·relay에 알 수 없는 키를 넣으면 저장할 때 버려집니다.
3. gui: GUI / 데몬 공통 설정
데몬은 기동할 때 SABA_IPC_PORT 환경변수가 없으면 gui.ipcPort를 읽고, 그것도 없으면 기본값 57474를 씁니다. 나머지 키는 주로 GUI가 읽습니다.
| 키 | 타입 | 기본값 | 설명 |
|---|---|---|---|
ipcPort | number | 57474 | 데몬 HTTP API 포트 (항상 127.0.0.1에만 열림) |
autoRefresh | boolean | true | GUI 상태 자동 갱신 |
refreshInterval | number (ms) | 2000 | GUI 상태 폴링 주기. 너무 낮추면 CPU 사용률 상승 |
consoleBufferSize | number | 2000 | GUI 콘솔이 보관하는 줄 수 |
portConflictCheck | boolean | true | 서버를 켜기 전에 포트 충돌을 검사 |
language | string | OS 추론값 | 언어 (ko, en, ja, de, es, fr, pt-BR, ru, zh-CN, zh-TW). 모듈·디스코드 응답 언어에도 쓰임 |
theme | string | 없음 (GUI는 auto) | "dark" / "light" / "auto" |
osNotifications | boolean | true | 크래시, 예기치 않은 시작·종료를 OS 알림으로도 보냄 |
daemonView | string | 없음 (switch) | 원격 데몬이 있을 때 서버 목록 모양. "switch" 고른 데몬만, "unified" 모든 데몬 합쳐 보기 |
mainDaemon | string | 없음 (이 PC) | 앱을 열면 먼저 볼 원격 데몬의 PC id(메인 데몬) |
이 밖에 색상·글꼴 배율·창 크기 같은 외형 키가 있으며, GUI 설정 화면에서 바꾸는 값이 그대로 저장됩니다.
4. relay: 디스코드 연동
디스코드 봇은 서버쨩에서만 동작하므로 사용자 PC에 봇 프로세스나 봇 토큰이 없습니다. 이 네임스페이스는 GUI에서 편집하는 접두사·부르는 말·디스코드 서버별 설정을 보관하며, 데몬이 페어링 이후 서버쨩에 동기화합니다.
| 키 | 타입 | 기본값 | 설명 |
|---|---|---|---|
prefixes | string | [] | 디스코드 서버마다 접두사를 따로 정하지 않았을 때 쓰는 채팅 명령 접두사 목록(10개까지, 각각 공백 없는 1~32자). 디스코드 서버별 접두사는 nodeSettings에 들어가고, 앱의 디스코드 서버 → 봇 설정 탭에서 바꿉니다. 비어 있으면 그 디스코드 서버의 봇 언어(따로 정하지 않았으면 PC 앱 언어) 기본값(한국어 사바쨩, 일본어 サバちゃん, 그 밖 Saba-chan)을 씀. 글자로 끝나는 접두사 뒤에는 공백(또는 쉼표·쌍점)이 와야 명령으로 인식됨 |
serverWords | object | {} | 서버(인스턴스 ID)마다 그 서버와 명령을 부르는 말 {words, commands}. 서버 화면의 디스코드 탭에서 바꿉니다 |
newGuildInstances | string | "auto" | 페어링 코드로 새로 연결한 디스코드 서버에 이 PC의 서버를 모두 바로 열지(auto), 나중에 고를지(manual) |
nodeSettings | object | {} | 디스코드 서버별 설정 (허용 인스턴스, 명령 권한, 언어·접두사·슬래시 명령 모양·노래하는 사바쨩·읽어주는 사바쨩·되묻기 설정 등) |
cloud | object | relayUrl, hostId. 페어링 때 채워짐 |
예전의 전역 별명(
moduleAliases,commandAliases,instanceAliases)은 데몬이 켜질 때serverWords로 옮기고 비웁니다.
nodeSettings안의 권한·디스코드 설정은 전용 화면(API)으로만 바뀌며, 봇 설정을 통째로 저장해도 덮어쓰지 않습니다.
명령어 문법
사바쨩 <서버 이름 또는 별명> <명령어> [인자…]
사바쨩 minecraft start사바쨩 마크 stop(별명)사바쨩 palworld status사바쨩 list: 서버 목록,사바쨩 help: 도움말
서버마다 기본 명령 start·stop·status가 있고, 그 밖의 명령은 모듈이 정의합니다. 노래하는 사바쨩 등 추가 기능은 서버쨩 측 봇이 제공합니다.
remote: 원격 데몬
내 다른 PC가 이 데몬에 붙는 원격 포트와, 이 PC가 붙는 원격 데몬 목록입니다. 앱의 설정 → 연결 → 원격 데몬이나 saba-chan-cli remote로 바꾸고, 설정 내보내기에는 들어가지 않습니다. 사용법은 원격 데몬. relay와 따로 config.json의 최상위 키에 저장됩니다.
| 키 | 타입 | 기본값 | 설명 |
|---|---|---|---|
enabled | boolean | true | 원격 포트를 엽니다 |
port | number | 57480 | 원격 포트 (TLS) |
address | string | 없음 | 내 다른 PC가 닿을 공인 IP나 호스트 이름. 비우면 서버쨩을 거쳐서만 붙습니다 |
transport | string | "direct" | 연결 방식. 지금은 "direct"만 있으니 그대로 둡니다 |
clients | array | [] | 이 데몬에 짝 맺은 PC (토큰은 해시만 저장) |
daemons | array | [] | 이 PC가 붙는 원격 데몬 |
5. instances\: 서버 인스턴스
GUI에서 만든 서버는 instances\<id>\ 폴더 하나씩으로 저장됩니다. <id>는 UUID입니다.
instance.json: 이름, 모듈, 실행 파일·작업 폴더, 포트, REST 접속 정보, 예약 작업, 익스텐션 데이터(extension_data) 등.settings.json: 모듈이 선언한 게임 설정 값 (예: 최대 인원, 난이도).order.json: GUI 목록 순서.
// instances\<id>\instance.json (일부)
{
"id": "3f6c…",
"name": "내 마크 서버",
"module_name": "minecraft",
"working_dir": null,
"port": 25565,
"extension_data": {}
}
- RCON은 모듈이
supported = ["rcon"]으로 선언한 게임(콘솔도 REST API도 없는 게임)에만 쓰며, 이때 데몬이 인스턴스마다 포트와 무작위 비밀번호를 정하고 루프백(127.0.0.1)으로만 연결합니다. 그 밖의 게임 명령은 서버 콘솔(stdin)로 보내고, Palworld는 REST API를 씁니다. 예전 파일에 남은 RCON 키는 불러올 때 지워집니다. extension_data는 익스텐션 전용 저장 공간입니다. 예를 들어 SteamCMD로 설치하는 모듈은 여기에 설치 방식과 앱 정보가 들어갑니다.- 서버 설정을 저장할 때(GUI 서버 설정,
PATCH /api/instance/:id) 인스턴스 공통 항목도, 모듈이 선언한 설정도 아닌 키는unknown_setting오류로 거부됩니다. - 인스턴스를 삭제하면
instances\<id>\폴더 전체가 지워집니다. 기본 설치 위치(server\)의 게임 서버 파일과backups\도 함께 지워집니다.
이 파일들은 데몬이 실행 중이지 않을 때만 손으로 수정하세요. 실행 중 편집하면 데몬 메모리와 어긋나고, 다음 저장 때 덮어써집니다.
6. 토큰 파일 (.ipc_token / .node_token)
| 파일 | 포맷 | 생성 시점 | 사용처 |
|---|---|---|---|
.ipc_token | UUID v4 (한 줄) | 데몬이 켜질 때마다 새로 생성 | GUI / CLI / 모듈·익스텐션 (로컬 API 호출) |
.node_token | sbn_<hostId>.<secret> | 디스코드 페어링이 끝나면 데몬이 저장 | 데몬의 서버쨩 연결 |
IPC 토큰
데몬 API는 127.0.0.1에서만 열리고, /health를 뺀 모든 요청에 X-Saba-Token 헤더가 필요합니다.
GET /api/servers HTTP/1.1
Host: 127.0.0.1:57474
X-Saba-Token: <.ipc_token 파일 내용>
- 데몬이 다시 켜지면 토큰도 바뀝니다. GUI와 CLI는 인증이 실패하면 토큰 파일을 다시 읽으므로 따로 할 일은 없습니다.
- 토큰 파일 위치는
SABA_TOKEN_PATH로 바꿀 수 있습니다.
노드 토큰
.node_token은 이 PC를 디스코드 봇(서버쨩)에 연결하는 비밀값입니다. 데몬이 서버쨩에 HTTPS로 보내 인증합니다. 누구에게도 보여 주지 말고, 유출이 의심되면 GUI에서 다시 페어링하세요. 다시 페어링하면 예전 토큰은 무효가 됩니다.
7. 익스텐션·격리 설정 (extensions / sandbox)
extensions.enabled: 켜진 익스텐션 ID 목록.extensions.settings: 익스텐션별 설정 값{ "<id>": { "<키>": 값 } }. 데몬 APIPUT /api/extensions/:id/config로 바뀝니다.sandbox.unisolated: 격리 환경을 준비하지 못한 구성요소를 격리 없이 돌리기로 한 동의. 구성요소 파일의 지문으로 저장되며, 파일이 하나라도 바뀌면 다시 묻습니다. GUI 설정 → 고급의 "격리 없이 돌리기" 또는saba-chan-cli sandbox revoke <구성요소>로 취소할 수 있습니다.
8. 주요 환경변수
| 변수 | 대상 | 설명 |
|---|---|---|
SABA_IPC_PORT | 데몬 / CLI | gui.ipcPort를 덮어씀 |
SABA_DAEMON | CLI | 명령을 보낼 원격 데몬. --daemon <이름>과 같음 |
SABA_DATA_DIR | 데몬 | 데이터 루트 자체를 재지정 (고급) |
SABA_TOKEN_PATH | 데몬 | IPC 토큰 파일 경로 |
SABA_MODULES_PATH / SABA_EXTENSIONS_DIR / SABA_INSTANCES_PATH | 데몬 | 모듈·익스텐션·인스턴스 폴더 재지정 |
RUST_LOG | 데몬 | 로그 필터 (기본 info) |
SABA_IPC_URL | 모듈/익스텐션 서브프로세스 | 데몬 API 주소. 데몬이 자식 프로세스에 주입 |
SABA_LANG | 모듈/익스텐션 서브프로세스 | 현재 언어 (gui.language) |
PYTHONPATH | 모듈/익스텐션 서브프로세스 | 모듈·익스텐션 경로가 결합되어 주입됨 |
SABA_ENABLED_EXTENSIONS | 모듈/익스텐션 서브프로세스 | 활성 익스텐션 ID 목록 (, 구분) |
PYTHONIOENCODING | 모듈/익스텐션 서브프로세스 | 항상 utf-8 |
PYTHONUNBUFFERED | 모듈/익스텐션 서브프로세스 | 1: stdout 즉시 flush |
잘못 건드려서 망가졌다 싶으면 데몬을 종료한 뒤 해당 파일을 지우고 다시 실행하면 대부분 기본값으로 재생성됩니다. config.json을 지우면 모든 설정과 디스코드 연동 설정이 초기화되므로, 먼저 config.json.bak으로 되돌려 보는 것이 좋습니다. instances\ 폴더는 지우지 마세요. 서버 목록과 기본 위치에 설치한 게임 파일이 함께 사라집니다.