Bridge

신뢰할 수 있는 웹 백엔드에서 허용된 Minecraft 서버 작업을 호출하고 이벤트를 받는 Paper 플러그인. 호출자마다 인증 정보와 권한 범위를 설정합니다.

주요 기능

필요한 서버 작업 호출: 인증된 REST API로 플레이어 상태를 조회하고, 설정에서 허용한 순간이동 등의 작업을 호출합니다.
백엔드마다 다른 권한: 클라이언트별 인증 정보, 작업·이벤트 허용 목록, 요청 빈도와 동시 실행 수를 설정합니다.
서버 이벤트 수신: 선택적 WebSocket으로 플레이어 접속·퇴장 이벤트를 받습니다. 기본 이벤트에는 플레이어 UUID만 포함됩니다.
다른 플러그인으로 확장: 개발자용 bridge-api 모듈로 타입이 정해진 작업과 이벤트를 등록할 수 있습니다. 서버에 별도 플러그인으로 설치하는 파일은 아닙니다.
선택적 JWT·relay: 중앙 발급자가 있는 환경에서는 JWT/JWKS, 인바운드 연결이 어려운 환경에서는 아웃바운드 relay를 설정할 수 있습니다. 웹 측 구현은 별도로 필요합니다.
재시도 처리와 관측: 호출자별 요청 ID로 같은 요청의 동시 재시도를 합치고, 선택적 Prometheus 메트릭을 제공합니다.
선택적 Notice 연동: Notice 플러그인이 있으면 공지 동기화·즉시 방송 작업을 켤 수 있습니다. Bridge 자체의 필수 의존성은 아닙니다.

Modrinth에서 Paper 26.2용 Bridge JAR을 다운로드합니다.
서버를 정상 종료하고 JAR을 plugins 폴더에 넣습니다. 한 번 시작·종료하여 plugins/Bridge/config.yml을 생성합니다.
웹 백엔드별 토큰 파일과 http.clients를 설정합니다. 처음에는 loopback에서 읽기 전용 minecraft.player_status만 허용합니다.
서버를 정상 재시작하고 /bridge status로 확인합니다. 전체 설정 안내의 인증된 상태 조회를 시험하세요.

plugins/Bridge/config.yml

먼저 상태 조회: http.host 기본값은 127.0.0.1, port는 25585입니다. 처음에는 읽기 전용 minecraft.player_status만 허용해 연결을 확인하세요.
백엔드별 인증: 최소 32 UTF-8 바이트의 무작위 토큰을 파일로 준비하고 http.clients의 tokenFile에 경로를 지정합니다. 토큰 파일은 서버 계정만 읽을 수 있게 관리하세요.
허용 범위: allowedActions, allowedEvents와 요청 빈도·동시 실행 수를 클라이언트별로 설정합니다. 사용자 권한 판단은 호출하는 웹 백엔드에서 수행합니다.
선택 기능: WebSocket, JWT, relay, metrics와 변경 작업은 새 설치에서 꺼져 있습니다. 필요한 기능만 명시적으로 켜세요.
적용: 처음 설정하거나 JAR을 교체한 뒤에는 서버를 정상 재시작하고 /bridge status를 확인합니다. 설정 재적용에는 /bridge reload를 사용합니다.

전체 설정 안내

현재 배포 버전은 베타 릴리스 후보입니다. 운영 적용 전 서버 사본에서 확인하세요.
Paper 26.2와 Java 25가 대상입니다. Folia는 지원하지 않으며 Spigot, Bukkit 전용 서버와 Purpur 호환을 보장하지 않습니다.
일반 원격 콘솔·임의 명령 실행, 브라우저 로그인·계정 연동과 웹 관리 화면은 제공하지 않습니다.
TLS 종단 기능이 없습니다. 원격 접근에는 HTTPS 리버스 프록시, VPN 또는 사설망을 사용하고 인증 정보는 웹 백엔드에서만 관리하세요.
WebSocket 재전송 기록은 메모리에 보관하며 서버 재시작 후에는 유지되지 않습니다.