server-icon.png: 정확한 요구 사항, 그리고 아무도 쓰지 않는 관리 API
64x64, PNG, 서버 루트 — 세 가지 중 하나라도 틀리면 아이콘은 아무 말 없이 나타나지 않습니다. 콘솔 화면 긁어오기를 대체한 JSON-RPC 관리 API는 기본적으로 localhost에만 열립니다.
서버 아이콘은 Minecraft에서 가장 봐주지 않는 작은 기능입니다. 모든 실패 양상이 똑같이 보이기 때문입니다. 아이콘 없음, 오류 없음.
세 가지 요구 사항, 전부 필수
- 정확히 64×64 픽셀. 63도, 128도 안 됩니다. 서버는 크기를 조정하지 않습니다.
- PNG 형식. 이름만 바꾼 JPG가 아니라 진짜 PNG여야 합니다.
- 이름은
server-icon.png, 위치는 서버 루트 — 월드 폴더 안이 아니라server.properties옆입니다.
하나라도 틀리면 서버는 정상적으로 시작하고 기본 아이콘을 표시합니다. 크기가 잘못됐거나 진짜 PNG가 아닌 파일은 시작할 때 한 줄을 기록하기는 합니다 — Couldn't load server icon — 하지만 이름이나 위치가 잘못된 파일은 아무것도 기록하지 않습니다. (server-icon.png가 아예 없으면 서버는 월드 자체의 icon.png가 있을 경우 그것으로 대체합니다.)
역시나 망가뜨리는 것들
- 인터레이스 PNG. 일부 편집기는 기본값으로 인터레이스로 저장하는데, Minecraft의 판독기는 이를 거부합니다. 비인터레이스로 다시 내보내세요.
- 16비트 색상 심도. 채널당 8비트로 저장하세요.
- 색상 프로필. 내장된 ICC 프로필이 간혹 파서를 걸리게 합니다. 내보낼 때 메타데이터를 제거하세요.
- 투명도는 괜찮습니다 그리고 서버 목록에서 올바르게 렌더링됩니다.
서버는 한 번만 읽습니다
서버는 시작할 때 server-icon.png를 로드하고 다시는 읽지 않습니다. 실행 중인 서버에서 파일을 교체해도 재시작 전까지는 아무것도 바뀌지 않습니다 — 그래서 재시작 없이 아이콘 변경을 테스트하면 안 된다고 확신하게 됩니다. 재시작 후 클라이언트는 다음 서버 목록 새로 고침 때 새 아이콘을 가져옵니다.
관리 API
최근 서버 버전은 JSON-RPC 관리 인터페이스를 노출하는데, 이는 콘솔 출력을 파싱하거나 플러그인을 덧대는 것에 대한 공인된 대체 수단입니다.
server.properties에서 활성화하세요:
management-server-enabled=true
management-server-host=localhost
management-server-port=25585
management-server-tls-enabled=falseTLS는 기본적으로 켜져 있으며 키스토어(management-server-tls-keystore)가 필요하므로, 키스토어를 지정하거나 — localhost에서만 — 위처럼 끄세요. TLS가 켜져 있고 키스토어가 없으면 관리 서버는 시작되지 않습니다. 포트에도 기본값이 없습니다 (25585는 그저 예시일 뿐입니다).
그런 다음 해당 포트로 WebSocket을 열고, server.properties의 management-server-secret를 Authorization: Bearer <secret>로 보내고, JSON-RPC로 대화하세요:
{ "jsonrpc": "2.0", "id": 1, "method": "minecraft:players" }메서드는 플레이어 목록, 서버 상태, 허용 목록과 차단 목록, 게임 규칙, 설정, 그리고 저장/중지 쌍을 포괄합니다. 각각은 정규식으로 파싱해야 하는 텍스트 한 줄 대신 구조화된 JSON을 반환합니다.
localhost에 바인딩하세요
기본값은 localhost이며 그대로 두어야 합니다. 이 인터페이스는 인터넷에 노출되도록 만들어진 것이 아닙니다 — 비밀을 알고 접근하는 사람은 누구나 서버를 중지시킬 수 있고, 비밀은 server.properties만큼만 안전합니다. 원격 접근이 필요하면 SSH 터널이나 인증이 있는 리버스 프록시를 통해 노출하세요, 호스트를 0.0.0.0로 바꾸는 방식으로는 절대 안 됩니다.
왜 중요한가
대시보드, Discord 봇, 가동 시간 모니터는 역사적으로 콘솔 로그를 읽거나 RCON을 사용해 작동해 왔는데, 둘 다 취약합니다. 타입이 지정된 API가 있으면 로그 한 줄의 형식이 바뀌어도 플레이어 수 위젯이 깨지지 않습니다.
아무 이미지나 규격에 맞는 server-icon.png로 변환하고 Server Icon & API Tools에서 JSON-RPC 메서드를 살펴보세요.