팰월드 REST API: 추방, 차단, 공지, 강제 저장 사용법

전용 서버가 뜨고 나면 호스트는 언젠가 이런 일을 하게 돼요. 깽판 치는 사람을 추방하고, 재시작 전에 서버 전체에 공지하고, 멈추지 않고 강제 저장하기. 팰월드가 이런 일을 위해 마련한 공식 창구가 REST API예요. 옛 글이 안내하는 RCON은 지원 중단됐고 개발사는 앞으로 동작하지 않을 거라고 공지했어요. RCON을 전제로 한 절차는 건너뛰어도 돼요.

이 글은 API 켜기, 부르는 법, 할 수 있는 일, 그리고 절대 깨면 안 되는 보안 원칙 하나를 다뤄요. 서버 구축 자체는 구축 가이드에 있어요.

왜 더는 RCON이 아닌가

팰월드의 RCON에는 실제로 문제가 셋 있어서, 지원 중단이 변덕은 아니에요.

• 멀티바이트 글자가 잘려요. 한국어, 일본어, 중국어 플레이어 이름이 있으면 RCON 명령이 실패하거나 로그가 깨져요. 한국 서버라면 거의 확실히 겪어요.
• 인증이 약해요. 비밀번호가 평문으로 네트워크를 지나고, 포트가 노출돼 있으면 AdminPassword가 인터넷에 굴러다니는 상태예요.
• 돌아오는 건 문자열이에요. 접속자 수나 프레임률을 모니터링에 쓰려면 텍스트를 직접 파싱해야 해요.

REST는 HTTP와 JSON이라 셋 다 해결돼요.

켜는 법

PalWorldSettings.ini의 그 한 줄에 세 항목을 더하고(편집할 때의 함정은 설정 전체 해설에), 서버를 재시작해요.

RESTAPIEnabled=True
RESTAPIPort=8212
AdminPassword="충분히 긴 비밀번호"

AdminPassword는 API 비밀번호일 뿐 아니라 게임 안 관리자 명령의 비밀번호이기도 해요. 길게 잡고, ServerPassword와 같게 하지 마세요. 서버 비밀번호는 친구에게 주는 것이고 관리자 비밀번호는 주지 않는 것이에요.

인증은 HTTP Basic이고 사용자 이름은 항상 admin, 비밀번호는 위의 것이에요.

깨면 안 되는 원칙

8212 포트를 인터넷에 열지 마세요. 공식 REST API 문서에 있는 개발사의 말 그대로, 이 API는 "인터넷에 직접 노출되도록 설계되지 않았고" 노출하면 "서버가 무단으로 조작될 수 있어요". 서버 종료, 플레이어 추방, 그 밖의 많은 일을 할 수 있는데 방어는 Basic 인증 비밀번호 하나뿐이에요.

올바른 자세는 API를 로컬호스트에서만 듣게 하고 스크립트는 같은 머신에서 부르는 거예요. 정말 원격 관리가 필요하면 SSH 터널을 쓰거나, HTTPS와 출발지 IP 허용 목록을 갖춘 리버스 프록시를 앞에 두세요. 보안 그룹에서 8212가 0.0.0.0/0에 열려 있다면 설정 실수예요.

엔드포인트

전부 http://127.0.0.1:8212/v1/api/ 아래에 있고, 쓰기 계열은 JSON 본문을 담은 POST예요.

자주 쓰는 것들은 curl로 바로 시험해 볼 수 있어요.

PW='충분히 긴 비밀번호'
API='http://127.0.0.1:8212/v1/api'

# 누가 접속 중인지
curl -s -u "admin:$PW" "$API/players"

# 전체 공지
curl -s -u "admin:$PW" -X POST "$API/announce" \
     -H 'Content-Type: application/json' \
     -d '{"message":"Server restarts in 5 minutes"}'

# 강제 저장
curl -s -u "admin:$PW" -X POST "$API/save"

# 60초 뒤 정상 종료. 공지는 자동
curl -s -u "admin:$PW" -X POST "$API/shutdown" \
     -H 'Content-Type: application/json' \
     -d '{"waittime":60,"message":"Server is going down in 60 seconds"}'

추방과 차단은 이름이 아니라 userId로

추방과 차단의 대상은 플레이어의 userId이지 게임에 표시되는 이름이 아니에요. 이름은 언제든 바꿀 수 있지만 userId는 안 바뀌어요. 그래서 두 단계예요. GET /players로 상대의 userId를 찾고, 그걸 /kick이나 /ban에 넘겨요.

# 먼저 찾기
curl -s -u "admin:$PW" "$API/players"
# 그다음 차단
curl -s -u "admin:$PW" -X POST "$API/ban" \
     -H 'Content-Type: application/json' \
     -d '{"userid":"steam_7656119xxxxxxxxxx","message":"Banned for griefing"}'

크로스플레이 서버에서는 이 점이 더 중요해요. Xbox와 PS5 플레이어에겐 Steam ID가 없어서 옛 KickPlayer <SteamID> 명령이 닿지 않지만, userId는 모든 플랫폼에 공통인 식별자예요.

추방과 차단의 차이는, 추방은 이번 접속만 끊어서 바로 돌아올 수 있고, 차단은 /unban할 때까지 막아 둔다는 점이에요.

무엇에 쓰나

API의 진짜 가치는 curl을 손으로 치는 게 아니라 스크립트에 넣는 데 있어요.

• 세이브를 잃지 않는 예약 재시작: 공지, 저장, 종료, 시작을 cron 작업 하나로 이어요. 전체 절차는 메모리 누수와 예약 재시작에 있어요.
• 백업 전 기록: 세이브 디렉터리를 복사하기 전에 POST /save를 치면 복사하는 게 완전한 상태가 돼요(백업과 복원).
• 프레임률 모니터링: /metrics를 주기적으로 가져와서 서버 FPS가 오래 20 아래에 머물면 재시작 신호예요.

자주 묻는 질문

팰월드 전용 서버에서 추방이나 차단은 어떻게 하나요?

REST API를 켜고 AdminPassword를 설정한 뒤, /players로 상대의 userId를 찾아 /kick이나 /ban에 넘겨요. 대상은 반드시 userId예요. 표시 이름은 바꿀 수 있어서 기준이 안 돼요.

팰월드 RCON은 아직 쓸 수 있나요?

공식적으로 지원 중단됐고 앞으로의 빌드에서 동작하지 않을 예정이에요. 게다가 한글 같은 플레이어 이름을 잘라 버려요. 새로 세우는 서버는 처음부터 REST API를 쓰고 RCON에 시간을 쓰지 마세요.

친구가 관리를 도와주도록 REST API 포트를 열어도 되나요?

인터넷에는 열지 마세요. 지키는 건 비밀번호 하나인데 서버 종료, 추방, 월드 변경이 가능해요. 원격 접근은 SSH 터널이나 IP 허용 목록이 있는 리버스 프록시로 하세요.

서버를 멈추지 않고 강제 저장하려면?

POST /save예요. 메모리 위의 월드를 즉시 디스크에 기록하게 하고, 그다음 세이브 디렉터리를 복사해요. 기록 도중에 걸릴 확률을 낮출 뿐 없애진 못해서, 가장 안전한 백업은 여전히 서버를 멈추고 뜨는 거예요.

호스팅에선 API를 만질 일이 없어요

위의 모든 단계가 호스팅 서버에선 콘솔의 버튼이 돼요. KeepWorlds의 팰월드 전용 서버에서는 내 서버의 접속 중인 플레이어 패널에 지금 있는 사람이 나열되고, 깽판 치는 사람은 바로 추방이나 차단이에요. userId를 찾을 필요가 없고, 차단한 사람은 차단 목록에서 언제든 풀 수 있어요. 자동 백업 전에는 API로 강제 저장이 들어가고, 관리자 비밀번호는 저희가 관리하며, API 자체는 인터넷에서 닿지 않아요.