HyTari Studios · Oficjalny poradnik konfiguracji

Server Router

Skonfiguruj sieć, rozumiejąc działanie każdego modułu.

Praktyczny poradnik do Server Router - Network Sync. Od tożsamości serwera i tras po systemy wspólne, natywny scoreboard i opcjonalną synchronizację ekwipunku. Każda sekcja łączy kopiowalny JSON z wyjaśnieniem rzeczywistego działania.

ROZPOCZNIJ PORADNIK STRONA MODA

ZANIM ZACZNIESZ

Pierwsze kroki

KROK 01

Zainstaluj na każdym serwerze

Używaj tej samej kompilacji ServerRouter na każdym węźle sieci.

KROK 02

Konfiguruj po jednym węźle

Nadaj każdemu serwerowi unikalny serverId, własny host/port i właściwą rolę.

KROK 03

Przetestuj przed otwarciem dostępu

Sprawdź trasy i ochronę backendu kontami staffu przed ruchem publicznym.

ServerRouter to infrastruktura sieciowa: uważnie konfiguruj dane dostępowe, hosts, uprawnienia i zasady direct access. Zachowaj kopię konfiguracji produkcyjnej przed zmianą wielu modułów.

ROZDZIAŁ 01 · 1 PRZYKŁADY

Instalacja i rola

Zidentyfikuj serwer w sieci i wybierz router, backend albo oba.

01KONFIGURACJA

Tożsamość i rola serwera

Każdy węzeł potrzebuje unikalnego serverId i adresu dostępnego dla pozostałych serwerów.

KONFIGURACJA

{
  "enabled": true,
  "role": "both",
  "serverId": "hub",
  "host": "hub.example.com",
  "port": 5520,
  "maxPlayers": 100,
  "acceptingPlayers": true
}

mods/ServerRouter/config.json

CO TO ROBI

Każdy węzeł potrzebuje unikalnego serverId i adresu dostępnego dla pozostałych serwerów.

WAŻNE DZIAŁANIE

role: main włącza routing, backend przyjmuje transfers, a both łączy obie role.
serverId musi pozostać stały i zgadzać się z wartością używaną w routes i modułach sieci.
acceptingPlayers może tymczasowo usunąć serwer z dostępnych celów bez wyłączania go.

ROZDZIAŁ 02 · 1 PRZYKŁADY

Baza danych i heartbeat

Skonfiguruj MariaDB i częstotliwość publikacji stanu każdego serwera.

01KONFIGURACJA

MariaDB, heartbeat i status online

ServerRouter używa MariaDB do współdzielenia statusu, presence, transfers i modułów sieciowych.

KONFIGURACJA

{
  "databaseHost": "127.0.0.1",
  "databasePort": 3306,
  "databaseName": "hytale_network",
  "databaseUser": "serverrouter",
  "databasePassword": "CHANGE_ME",
  "tablePrefix": "server_router_",
  "heartbeatIntervalSeconds": 5,
  "offlineTimeoutSeconds": 15
}

mods/ServerRouter/config.json

CO TO ROBI

ServerRouter używa MariaDB do współdzielenia statusu, presence, transfers i modułów sieciowych.

WAŻNE DZIAŁANIE

Wszystkie serwery tej samej sieci muszą korzystać z tej samej bazy.
heartbeatIntervalSeconds określa częstotliwość aktualizacji stanu węzła.
offlineTimeoutSeconds określa, kiedy węzeł bez heartbeat uznaje się za niedostępny.

ROZDZIAŁ 03 · 1 PRZYKŁADY

Trasy i komendy

Zdefiniuj cele, komendy, aliases, uprawnienia i wiadomości tras.

01KONFIGURACJA

Trasy, komendy, aliases i uprawnienia

Każda route łączy komendę z serwerem docelowym i jest sprawdzana przed transfer.

KONFIGURACJA

{
  "routes": [
    {
      "name": "Survival",
      "command": "survival",
      "aliases": [
        "sopravvivenza"
      ],
      "serverId": "survival",
      "host": "survival.example.com",
      "port": 5522,
      "permission": "serverrouter.command.survival"
    }
  ]
}

mods/ServerRouter/config.json → routes[]

CO TO ROBI

Każda route łączy komendę z serwerem docelowym i jest sprawdzana przed transfer.

WAŻNE DZIAŁANIE

Komenda jest zapisana w JSON bez slash i używana w grze jako /survival.
aliases dodaje alternatywne nazwy tego samego transfer.
Przed referral ServerRouter sprawdza stan, pojemność i dostępność celu.

ROZDZIAŁ 04 · 1 PRZYKŁADY

Bezpieczeństwo transferów

Chroń backendy i zarządzaj tymczasowymi autoryzacjami, rejoin oraz cooldown.

01KONFIGURACJA

Ochrona backendu i tokeny transfer

Backendy mogą odrzucać bezpośredni dostęp i przyjmować wyłącznie graczy z autoryzowanego transfer.

KONFIGURACJA

{
  "allowDirectAccess": false,
  "allowSameServerRejoin": true,
  "sameServerRejoinSeconds": 300,
  "accessTokenTtlSeconds": 60,
  "accessTokenSecret": "",
  "portalArrivalCooldownEnabled": true,
  "portalArrivalCooldownSeconds": 20,
  "loginPortalSafetySeconds": 20
}

mods/ServerRouter/config.json

CO TO ROBI

Backendy mogą odrzucać bezpośredni dostęp i przyjmować wyłącznie graczy z autoryzowanego transfer.

WAŻNE DZIAŁANIE

Przy allowDirectAccess=false backend używa tymczasowej autoryzacji wygenerowanej przez serwer źródłowy.
Natywna whitelist Hytale pozostaje ostateczną kontrolą dostępu.
Arrival cooldown zapobiega przypadkowemu odbiciu przez portal tuż po login lub transfer.

ROZDZIAŁ 05 · 1 PRZYKŁADY

Portale

Używaj tych samych tras do portali z tymi samymi kontrolami sieci.

01KONFIGURACJA

Portale połączone z trasami

Portale używają celów skonfigurowanych w routerze i tych samych kontroli dostępności oraz bezpieczeństwa.

KONFIGURACJA

{
  "routes": [
    {
      "name": "Dungeon",
      "command": "dungeon",
      "aliases": [],
      "serverId": "dungeon",
      "host": "dungeon.example.com",
      "port": 5521,
      "permission": "serverrouter.command.dungeon"
    }
  ],
  "portalArrivalCooldownEnabled": true,
  "portalArrivalCooldownSeconds": 20
}

mods/ServerRouter/config.json → routes[]

CO TO ROBI

Portale używają celów skonfigurowanych w routerze i tych samych kontroli dostępności oraz bezpieczeństwa.

WAŻNE DZIAŁANIE

Nie potrzeba drugiego celu: route jest wspólnym źródłem.
Portal assets są generowane przez plugin i ładowane jako runtime asset pack.
Jeśli cel jest offline, pełny lub niedostępny, transfer jest blokowany.

ROZDZIAŁ 06 · 1 PRZYKŁADY

Systemy wspólne

Chat, events, player list i Presence API dzielą informacje pomiędzy wszystkimi serwerami.

01KONFIGURACJA

Globalny chat i events

Serwery mogą współdzielić chat i kluczowe zdarzenia, aby Hub, Survival, Dungeon, Creative i inne węzły działały jak jedna sieć.

KONFIGURACJA

{
  "networkChat": {
    "enabled": true,
    "pollSeconds": 1,
    "messageTtlSeconds": 300,
    "maxMessageLength": 300,
    "captureMode": "eliteessentials",
    "serverDisplayNames": {
      "hub": "Hub",
      "survival": "Survival",
      "creative": "Creative"
    },
    "remoteFormat": "&8[&b%server%&8] &r%chat_format%",
    "fallbackFormat": "&8[&b%server%&8] &7%player%&r: &f%message%"
  },
  "networkEvents": {
    "enabled": true,
    "pollSeconds": 1,
    "eventTtlSeconds": 300,
    "joinEnabled": true,
    "quitEnabled": true,
    "switchEnabled": true,
    "suppressServerSwitchJoinQuit": true,
    "quitDelaySeconds": 3,
    "respectVanish": true
  }
}

mods/ServerRouter/config.json

CO TO ROBI

Serwery mogą współdzielić chat i kluczowe zdarzenia, aby Hub, Survival, Dungeon, Creative i inne węzły działały jak jedna sieć.

WAŻNE DZIAŁANIE

Network Chat przekazuje wiadomości między serwerami, zachowując nazwę serwera źródłowego i wspólny konfigurowalny format.
captureMode określa źródło lokalnego chatu; remoteFormat używa istniejącego formatowania, a fallbackFormat daje bezpieczną alternatywę.
serverDisplayNames nadaje czytelne nazwy Hub, Survival lub Creative zamiast technicznego serverId.
Network Events może ogłaszać join, quit i zmianę serwera w całej sieci; każdy typ jest sterowany osobno.
suppressServerSwitchJoinQuit zapobiega pokazywaniu zmiany serwera jako fałszywego quit i nowego join.
quitDelaySeconds pomaga odróżnić prawdziwy disconnect od transfer w toku; respectVanish chroni ukrytych graczy, jeśli integracja to obsługuje.
Network Player List i Presence API współdzielą presence z kompatybilnymi serwerami i mods bez osobnych zapytań bazy dla każdej integracji.

ROZDZIAŁ 07 · 2 PRZYKŁADY

Natywny scoreboard

Konfiguruj zawartość, pozycję, kolory, logo i overrides dla światów lub dynamicznych instances.

01KONFIGURACJA

Globalny scoreboard

Natywny scoreboard jest niezależny i może być ustawiony w jednym z czterech rogów z pixel-offset.

KONFIGURACJA

{
  "refreshSeconds": 10,
  "horizontal": "right:0",
  "vertical": "top:0",
  "boardWidth": 180,
  "backgroundColor": "default",
  "backgroundAlpha": 0.2,
  "logo": "hytari_logo.png",
  "logoWidth": 256,
  "logoHeight": 64,
  "maxLines": 12,
  "lines": [
    "&fOnline: &b{serverrouter_total_online} &7| &fTPS: &b{tps}",
    "&fPlayer: &b{player}",
    "&fWorld: &b{world}"
  ]
}

mods/ServerRouter/scoreboard.json

CO TO ROBI

Natywny scoreboard jest niezależny i może być ustawiony w jednym z czterech rogów z pixel-offset.

WAŻNE DZIAŁANIE

Natywny scoreboard jest opcjonalny i można go wyłączyć bez wyłączania ServerRouter ani systemów sieci.
horizontal przyjmuje left:<px> lub right:<px>; vertical top:<px> lub bottom:<px>.
backgroundColor przyjmuje default, none lub HEX #RRGGBB.
logo: none ukrywa logo. Linie obsługują formatowanie i dynamiczne placeholders.
Zewnętrzny scoreboard może używać placeholders ServerRouter bez wyświetlania natywnego.

02KONFIGURACJA

Overrides dla światów i dynamicznych instances

Świat może dziedziczyć globalną konfigurację i zmieniać wyłącznie potrzebne pola.

KONFIGURACJA

{
  "worlds": {
    "instance-Forgotten_Temple-*": {
      "enabled": true,
      "horizontal": "left:18",
      "vertical": "bottom:120",
      "backgroundColor": "#0E4E0D",
      "backgroundAlpha": 0.25
    },
    "creative_world": {
      "enabled": false
    }
  }
}

mods/ServerRouter/scoreboard.json → worlds

CO TO ROBI

Świat może dziedziczyć globalną konfigurację i zmieniać wyłącznie potrzebne pola.

WAŻNE DZIAŁANIE

Matching nie rozróżnia wielkości liter i obsługuje * dla instance-worldów z dynamicznym sufiksem.
Priorytet: dokładna nazwa świata > najbardziej szczegółowy wildcard > konfiguracja globalna.
Override może zmienić pozycję, linie, szerokość, tło lub logo bez duplikowania całego bloku.

ROZDZIAŁ 08 · 2 PRZYKŁADY

Inventory Sync i ItemQuality

Synchronizuj ekwipunki bezpiecznie i zachowuj ItemQuality między różnymi registries.

01KONFIGURACJA

Inventory Sync

Synchronizacja ekwipunku jest opcjonalna i używa tymczasowych locks do ochrony load, save i równoległych transfers.

KONFIGURACJA

{
  "inventorySync": {
    "enabled": false,
    "lockTtlSeconds": 120,
    "lockRefreshSeconds": 30,
    "autoSaveEnabled": true,
    "autoSaveIntervalSeconds": 600,
    "profileSaveDelayMillis": 1500,
    "loadingInventoryMessageEnabled": true,
    "loadingInventoryMessage": "server.serverrouter.inventory.loading",
    "lockedInventoryMessage": "server.serverrouter.inventory.locked",
    "debugQualityMapping": false,
    "qualityMappingLogRetentionDays": 3
  }
}

mods/ServerRouter/config.json → inventorySync

CO TO ROBI

Synchronizacja ekwipunku jest opcjonalna i używa tymczasowych locks do ochrony load, save i równoległych transfers.

WAŻNE DZIAŁANIE

Włączaj tylko na serwerach, które mają dzielić ten sam inventory-profil.
Locks zapobiegają równoległemu dostępowi mogącemu powodować duplikację lub nadpisanie.
Pozostaw debugQualityMapping wyłączone w normalnej pracy.

02KONFIGURACJA

ItemQuality między różnymi registries

ServerRouter zachowuje semantyczną tożsamość jakości zamiast polegać tylko na runtime index.

KONFIGURACJA

{
  "itemQualityMapping": {
    "enabled": false,
    "log-to-file": true,
    "log-to-console": false
  }
}

mods/ServerRouter/config.json

CO TO ROBI

ServerRouter zachowuje semantyczną tożsamość jakości zamiast polegać tylko na runtime index.

WAŻNE DZIAŁANIE

Diagnostyka ItemQuality jest najbardziej przydatna przy różnych registries lub mods.
Jeśli jakości brakuje na celu, system używa bezpiecznego fallback i zachowuje oryginalną tożsamość, gdy to możliwe.
Mapping logs są diagnostyczne i nie są wymagane w stabilnej sieci.

ROZDZIAŁ 09 · 1 PRZYKŁADY

Placeholders, API i diagnostyka

Integruj companion mods, przeładowuj scoreboard i używaj diagnostyki w razie potrzeby.

01KONFIGURACJA

Placeholders i API dla companion mods

Scoreboard zawiera wbudowane placeholders, a publiczne API pozwala innym mods rejestrować nowe bez patchowania ServerRouter.

KONFIGURACJA

{
  "integrations": {
    "api": {
      "enabled": true,
      "cacheSeconds": 10
    },
    "betterScoreBoard": {
      "enabled": false,
      "registerPlaceholders": true
    }
  },
  "scoreboardExample": [
    "{player}",
    "{world}",
    "{tps}",
    "{serverrouter_total_online}",
    "{myplugin_rank}"
  ]
}

Java API + scoreboard.json

CO TO ROBI

Scoreboard zawiera wbudowane placeholders, a publiczne API pozwala innym mods rejestrować nowe bez patchowania ServerRouter.

WAŻNE DZIAŁANIE

Custom placeholders nie rozróżniają wielkości liter i nie mogą przejąć już rozwiązanych wbudowanych placeholders.
Natywny scoreboard może pozostać wyłączony; placeholders ServerRouter mogą działać w kompatybilnych zewnętrznych scoreboards i mods.
BetterScoreBoard jest obsługiwany przez dedykowaną integrację. Dla innego scoreboard można rozważyć osobną kompatybilność.
Read-only Presence/Network API eliminuje osobne zapytania bazy przez każdy mod.
Dla natywnego scoreboard użyj /scoreboard reload po zmianach konfiguracji, logo lub layout.

Przed użyciem przykładu

Przykłady celowo dotyczą jednego modułu naraz. Dodawaj pokazane właściwości do odpowiedniego pliku zamiast zastępować pełną konfigurację produkcyjną częściowym przykładem.

Dane bazy i hosts są przykładami. Nigdy nie publikuj prawdziwych haseł ani secrets i używaj wspólnej bazy wyłącznie w jednej zaufanej sieci.

Publiczna wersja używa horizontal/vertical do pozycjonowania scoreboard. Stare pola offsetRight/offsetTop z buildów deweloperskich nie należą do dokumentowanej konfiguracji.

DO GÓRY