Minecraft 26.2 서버 관리 프로토콜 3.0.0 안전하게 사용하기

RCON과 무엇이 다른가

RCON은 say, save-all, whitelist 같은 기존 콘솔 명령을 자동화할 때 단순합니다. 관리 프로토콜은 JSON-RPC 2.0과 WebSocket을 사용하며, 요청마다 id와 메서드, 매개변수가 분리됩니다. 플레이어 접속이나 게임 규칙 변경 알림도 연결을 유지한 클라이언트로 받을 수 있습니다.

26.2의 프로토콜 3.0.0은 월드가 전부 올라오기 전부터 관리 서버를 시작합니다. 이때 rpc.discover와 서버 상태 알림은 사용할 수 있지만 월드가 필요한 메서드는 아직 준비되지 않았다는 오류를 돌려줄 수 있습니다. 자동화 프로그램은 포트가 열렸다는 이유만으로 게임 월드까지 준비됐다고 판단하면 안 됩니다.

server.properties를 localhost 전용으로 설정

먼저 외부 공개 없이 같은 서버에서만 접속하도록 host를 127.0.0.1로 고정합니다. 기본 포트 0은 기동할 때마다 빈 포트를 고르므로 자동화에는 불편합니다. 아래 예제는 25585를 명시합니다. TLS는 localhost 한정 실습을 위해 끄지만 인증 토큰은 그대로 필요합니다.

management-server-secret에는 영문 대소문자와 숫자로만 된 정확히 40글자를 넣습니다. 빈 값이면 서버가 생성할 수 있지만, 서비스에서 재사용할 클라이언트라면 직접 생성해 비공개 설정 파일에 보관하는 편이 관리하기 쉽습니다. 이 토큰을 Git 저장소, 브라우저 JavaScript, 스크린샷에 넣지 마세요.

# 먼저 40글자 토큰을 생성하고 출력값을 안전한 곳에 복사
tr -dc 'A-Za-z0-9' </dev/urandom | head -c 40; echo

# server.properties
management-server-enabled=true
management-server-host=127.0.0.1
management-server-port=25585
management-server-secret=[위에서_만든_40글자_토큰으로_교체]
management-server-tls-enabled=false
status-heartbeat-interval=10

대괄호가 들어간 예시 문자열은 유효한 토큰이 아닙니다. 반드시 생성한 40글자 영숫자로 교체한 뒤 서버를 재시작하세요.

먼저 rpc.discover로 현재 스키마 확인

릴리스마다 메서드와 매개변수가 달라질 수 있으므로 블로그의 메서드 목록보다 현재 서버의 rpc.discover 응답을 기준으로 삼습니다. websocat 같은 WebSocket 클라이언트에 Authorization Bearer 헤더를 넣어 연결한 뒤 아래 JSON 한 줄을 보냅니다.

응답에는 현재 빌드가 지원하는 메서드, 알림과 매개변수 스키마가 들어 있습니다. 이를 파일로 보관하면 서버 업데이트 전후에 스키마가 어떻게 바뀌었는지도 비교할 수 있습니다.

# TOKEN 값은 화면 공유나 셸 기록에 남지 않도록 주의
read -rsp 'Management token: ' TOKEN; echo
websocat -H="Authorization: Bearer ${TOKEN}" ws://127.0.0.1:25585

# 연결된 뒤 보내기
{"jsonrpc":"2.0","id":1,"method":"rpc.discover"}

화이트리스트 요청과 준비 상태 처리

1.21.9의 공식 예제는 minecraft:allowlist/add 메서드로 이름 배열을 보냅니다. 26.2 서버에서도 먼저 rpc.discover에서 같은 메서드와 매개변수 형식이 있는지 확인한 뒤 호출해야 합니다. 성공 응답과 오류 응답 모두 id가 같으므로 자동화 프로그램은 요청별 결과를 정확히 연결할 수 있습니다.

월드 로딩 중 메서드 오류가 오면 무한히 빠르게 재시도하지 말고 서버 상태 알림을 기다리거나 간격을 늘려 재시도합니다. 연결 종료, 인증 실패, 메서드 없음, 서버 미준비를 서로 다른 오류로 기록해야 나중에 원인을 찾기 쉽습니다.

{"jsonrpc":"2.0","id":2,"method":"minecraft:allowlist/add","params":[[{"name":"PLAYER_NAME"}]]}

# 포트가 외부 주소에 열리지 않았는지 서버에서 확인
ss -ltn | grep ':25585'
# 정상 예: 127.0.0.1:25585 (0.0.0.0:25585 이면 중단하고 설정 재확인)

원격 관리가 필요할 때의 경계선

이 API는 서버 저장과 종료, 운영자와 화이트리스트 변경까지 가능한 관리면입니다. 게임 접속 포트처럼 인터넷에 포트포워딩하면 안 됩니다. 원격 관리가 필요하면 SSH 터널이나 인증된 사설 VPN 안에서 localhost 포트를 전달하는 편이 단순합니다.

브라우저에서 직접 연결하는 구성은 2.0.0부터 Sec-WebSocket-Protocol 토큰 인증과 허용 Origin 설정이 추가됐지만, 토큰을 프런트엔드에 넣으면 방문자에게 노출됩니다. 공개 웹페이지가 관리 API에 직접 붙지 않게 하고, 서버 측 중계가 필요한 경우 메서드별 권한 검사를 별도로 두세요.

• 관리 포트는 127.0.0.1 또는 사설 VPN 주소에만 바인딩
• 토큰은 환경별로 분리하고 로그와 Git에서 제외
• 업데이트 후 rpc.discover 스키마를 다시 저장해 비교
• 자동화 실패가 월드 저장·종료를 반복하지 않도록 멱등성 확인

검증 범위와 공식 참고자료

Minecraft 1.21.9의 최초 도입 문서와 1.21.11의 2.0.0 변경, 26.2의 3.0.0 변경을 대조했습니다. WebSocket 클라이언트 옵션은 배포판 버전에 따라 다르므로 websocat --help로 헤더 옵션을 확인해야 합니다. 실제 운영 토큰이나 서버 주소는 예제에 사용하지 않았습니다.

• Minecraft Java 1.21.9 공식 릴리스 노트: 관리 프로토콜 최초 사양
• Minecraft Java 1.21.11 공식 릴리스 노트: 프로토콜 2.0.0
• Minecraft Java 26.2 공식 릴리스 노트: 프로토콜 3.0.0

SameOS 작성·번역·검수 원칙 보기