Hướng dẫn / Server & hiệu năng

server-icon.png: các yêu cầu chính xác và API quản lý mà không ai dùng

64x64, PNG, đặt tại thư mục gốc của server — sai một trong ba điều kiện là icon lặng lẽ biến mất. Kèm theo đó là API quản lý JSON-RPC đã thay thế việc đọc thô console.

2026-06-14

Icon server là tính năng nhỏ khó tính nhất trong Minecraft, bởi vì mọi kiểu lỗi đều trông giống hệt nhau: không có icon, không có thông báo lỗi.

Ba yêu cầu, tất cả đều bắt buộc

1. Đúng 64×64 pixel. Không phải 63, không phải 128. Server không tự thay đổi kích thước.
2. Định dạng PNG. Phải thực sự là PNG, không phải file JPG đổi đuôi.
3. Đặt tên server-icon.png, tại thư mục gốc của server — nằm cạnh server.properties, không phải bên trong thư mục world.

Sai bất kỳ điều nào thì server vẫn khởi động bình thường và hiển thị icon mặc định. Kích thước sai hoặc file không thực sự là PNG sẽ ghi một dòng log lúc khởi động — Couldn't load server icon — nhưng file đặt sai tên hoặc sai chỗ thì không ghi gì cả. (Nếu hoàn toàn không có server-icon.png, server sẽ dùng icon.png của chính world đó nếu có.)

Những thứ khác cũng làm hỏng icon

• PNG xen kẽ (interlaced). Một số trình chỉnh sửa mặc định lưu ở dạng xen kẽ; trình đọc của Minecraft từ chối nó. Hãy xuất lại ở dạng không xen kẽ.
• Độ sâu màu 16-bit. Hãy lưu ở 8-bit mỗi kênh.
• Hồ sơ màu (colour profile). Hồ sơ ICC nhúng đôi khi làm trình phân tích lỗi. Hãy xóa metadata khi xuất file.
• Độ trong suốt thì không sao và hiển thị đúng trong danh sách server.

Server chỉ đọc file một lần

Server nạp server-icon.png khi khởi động và không bao giờ đọc lại. Thay file trên một server đang chạy không thay đổi gì cho đến khi khởi động lại — đó là lý do khi thử đổi icon mà không khởi động lại, bạn sẽ tưởng là nó không hoạt động. Sau khi khởi động lại, client sẽ nhận icon mới ở lần làm mới danh sách server kế tiếp.

API quản lý

Các phiên bản server gần đây cung cấp giao diện quản lý JSON-RPC, đây là cách thay thế được chính thức chấp nhận cho việc phân tích output console hay gắn thêm plugin.

Bật nó trong server.properties:

management-server-enabled=true
management-server-host=localhost
management-server-port=25585
management-server-tls-enabled=false

TLS được bật mặc định và cần một keystore (management-server-tls-keystore), nên hoặc trỏ nó tới một keystore, hoặc — chỉ trên localhost — tắt đi như trên; nếu bật TLS mà không có keystore thì server quản lý sẽ không khởi động. Cổng cũng không có giá trị mặc định (25585 chỉ là ví dụ).

Sau đó mở một WebSocket tới cổng đó, gửi management-server-secret từ server.properties dưới dạng Authorization: Bearer <secret>, và nói chuyện bằng JSON-RPC:

{ "jsonrpc": "2.0", "id": 1, "method": "minecraft:players" }

Các phương thức bao gồm danh sách người chơi, trạng thái server, danh sách cho phép và danh sách cấm, gamerule, cài đặt, và một cặp lệnh lưu/dừng. Mỗi phương thức trả về JSON có cấu trúc thay vì một dòng text mà bạn phải dùng regex để xử lý.

Gắn nó vào localhost

Mặc định là localhost và nên giữ nguyên như vậy. Giao diện này không được thiết kế để đối mặt với internet — bất kỳ ai truy cập được nó cùng với secret đều có thể dừng server của bạn, và secret chỉ an toàn ngang với server.properties của bạn. Hãy để lộ nó qua một đường hầm SSH hoặc reverse proxy có xác thực nếu bạn cần truy cập từ xa, tuyệt đối không đổi host thành 0.0.0.0.

Vì sao điều này quan trọng

Các dashboard, bot Discord và công cụ giám sát uptime trước đây thường hoạt động bằng cách đọc log console hoặc dùng RCON, cả hai đều dễ hỏng. Một API có kiểu dữ liệu rõ ràng nghĩa là widget đếm người chơi sẽ không hỏng khi một dòng log đổi định dạng.

Hãy chuyển đổi bất kỳ hình ảnh nào thành server-icon.png hợp lệ và xem qua các phương thức JSON-RPC tại Công cụ Icon Server & API.

Công cụ icon server & API →