tkrmagid/mc_domain_proxy

Fork 0

Files

tkrmagid b45e884633 docs: add MC Domain Filter Proxy spec

2026-05-20 16:25:37 +09:00

5.9 KiB

Raw Blame History

MC Domain Filter Proxy

마인크래프트 서버 접속 시 특정 도메인(mc.tkrmagid.kr)으로만 접속 가능하게 필터링하는 프록시 + 웹 관리 대시보드

프로젝트 개요

목적

외부 IP 직접입력, 다른 도메인으로 접속 시 차단
mc.tkrmagid.kr 도메인으로만 마인크래프트 서버 접속 허용
Fabric, Paper, Spigot, NeoForge 등 어떤 서버 종류든 무관하게 동작

동작 원리

마인크래프트 클라이언트는 접속 시 첫 핸드셰이크 패킷에 사용자가 입력한 주소(서버 주소창의 문자열)를 담아 전송한다.
이 프록시는 해당 패킷을 읽어 허용된 도메인이 아니면 연결을 즉시 차단한다.

네트워크 구조

외부 인터넷
    ↓
공유기 (포트포워딩 25565 → Proxmox IP)
    ↓
Proxmox Docker 컨테이너 (MC Domain Filter)
    ↓
게임PC 내부IP:25565 (실제 마인크래프트 서버)

기술 스택

구성 요소	기술
프록시 코어	Python (asyncio)
웹 대시보드	React + Vite (또는 Next.js)
백엔드 API	FastAPI
설정 저장	JSON 파일 (sqlite도 가능)
컨테이너	Docker + docker-compose
리버스 프록시	nginx (대시보드용)

기능 요구사항

핵심 기능 (프록시)

Minecraft 핸드셰이크 패킷 파싱 (varint 포함)
허용 도메인 리스트와 비교 후 차단/통과 결정
통과된 패킷을 백엔드 서버로 투명하게 중계
첫 패킷 이후 양방향 TCP 터널링

웹 대시보드 (NPM 스타일 UI)

허용 도메인 관리 - 추가 / 삭제 / 활성화 토글
백엔드 서버 설정 - 게임PC IP, 포트 변경
실시간 접속 로그 - 허용/차단 내역, 접속 IP, 사용 도메인, 시각
대시보드 홈 - 현재 상태, 총 접속 수, 차단 수 통계 카드
프록시 on/off 토글
설정 변경 후 프록시 재시작 없이 즉시 반영 (hot reload)

UI 디자인 레퍼런스

Nginx Proxy Manager Plus 스타일
다크/라이트 모드
사이드바 네비게이션
카드 기반 레이아웃
토글 스위치, 모달 폼

프로젝트 구조

mc-domain-filter/
├── docker-compose.yml
├── proxy/
│   ├── Dockerfile
│   ├── main.py              # asyncio TCP 프록시
│   ├── config.py            # 설정 로드/저장
│   ├── handshake.py         # MC 핸드셰이크 파서
│   └── requirements.txt
├── api/
│   ├── Dockerfile
│   ├── main.py              # FastAPI 백엔드
│   ├── routes/
│   │   ├── config.py        # 설정 CRUD
│   │   └── logs.py          # 로그 조회
│   └── requirements.txt
├── frontend/
│   ├── Dockerfile
│   ├── src/
│   │   ├── pages/
│   │   │   ├── Dashboard.jsx
│   │   │   ├── Domains.jsx
│   │   │   └── Logs.jsx
│   │   └── components/
│   └── package.json
├── nginx/
│   └── nginx.conf
└── data/
    ├── config.json          # 설정 파일 (볼륨 마운트)
    └── logs.db              # 접속 로그

설정 파일 구조 (config.json)

{
  "proxy": {
    "listen_port": 25565,
    "enabled": true
  },
  "backend": {
    "host": "192.168.0.xx",
    "port": 25565
  },
  "allowed_domains": [
    {
      "domain": "mc.tkrmagid.kr",
      "enabled": true,
      "note": "메인 도메인"
    }
  ]
}

Minecraft 핸드셰이크 파싱

패킷 구조:
[varint] Packet Length
[varint] Packet ID (0x00)
[varint] Protocol Version
[varint] Server Address Length
[string] Server Address  ← 이게 클라이언트가 입력한 주소
[ushort] Server Port
[varint] Next State (1=status, 2=login)

서버 주소 끝에 \x00 널 문자가 붙는 경우 있음 → strip 처리 필요

docker-compose.yml 예시

version: '3.8'
services:
  proxy:
    build: ./proxy
    ports:
      - "25565:25565"
    volumes:
      - ./data:/data
    restart: unless-stopped
    network_mode: bridge

  api:
    build: ./api
    expose:
      - "8000"
    volumes:
      - ./data:/data
    restart: unless-stopped

  frontend:
    build: ./frontend
    expose:
      - "3000"
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "8080:80"   # 대시보드 접근 포트
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - api
      - frontend
    restart: unless-stopped

API 엔드포인트

메서드	경로	설명
GET	`/api/config`	전체 설정 조회
PUT	`/api/config`	설정 저장
GET	`/api/domains`	도메인 목록
POST	`/api/domains`	도메인 추가
DELETE	`/api/domains/{domain}`	도메인 삭제
PATCH	`/api/domains/{domain}`	도메인 활성화/비활성화
GET	`/api/logs`	접속 로그 (페이지네이션)
GET	`/api/status`	프록시 상태, 통계
POST	`/api/proxy/restart`	프록시 재시작

환경 정보

Proxmox 서버 스펙 (프록시 실행 환경)

CPU: Intel Core i3-10100 (4코어 8스레드, 3.6GHz, 최대 4.3GHz)
RAM: DDR4 32GB (Samsung 16GB × 2, 3200 MT/s, 듀얼채널)
가상화: VT-x 지원

게임PC (실제 MC 서버)

같은 공유기 내 LAN 환경
내부 IP로 통신

주의사항

프록시와 FastAPI는 data/config.json을 공유 볼륨으로 사용
설정 변경 시 프록시 프로세스에 SIGHUP 또는 내부 이벤트로 hot reload
게임PC의 MC 서버는 포트 변경 불필요 (프록시가 25565→25565 그대로 중계)
대시보드는 Proxmox 내부 IP:8080 으로 접근
대시보드 포트(8080)는 외부에 포트포워딩 하지 않을 것 권장

5.9 KiB Raw Blame History Unescape Escape