FiveM Whitelist — Kompletny przewodnik (txAdmin, Scripts, DB)

Biała lista w FiveM to mechanizm kontroli dostępu, który ogranicza wejście na serwer do wcześniej zatwierdzonych graczy, dopasowanych na podstawie ich unikalnych identyfikatorów (licencja Rockstar, Steam ID, Discord ID itp.). Poniżej znajduje się gotowy do produkcji przewodnik obejmujący wbudowaną białą listę txAdmin, wzorce skryptów, przechowywanie w bazie danych i uwagi dotyczące niezawodności.

TL;DR Macierz opcji

Tryb	Gdzie ustawić	Co sprawdza	Najlepsze dla	Uwagi
Zatwierdzona licencja	txAdmin → Ustawienia → Menedżer graczy → Tryb białej listy	`license:` (Rockstar)	Większość serwerów	Proste, niezawodne; obsługiwane ręczne zatwierdzenia lub wstępne zatwierdzenia
Członek Discord	txAdmin (połączone z Discord)	`discord:` jest członkiem gildii	Społeczności skupione na Discord	Użytkownicy spoza Discord zablokowani
Rola Discord	txAdmin (połączone z Discord)	`discord:` ma określoną rolę	Dostęp ograniczony rolą (darczyńca, personel)	Połącz z automatyzacją ról
Tylko administratorzy	txAdmin	Tylko admini	Noce konserwacji/deweloperskie	Skutecznie blokuje serwer, niezalecane
Niestandardowy skrypt	Zasób Lua/JS	Dowolne identyfikatory, które chcesz	Szczegółowe zasady & UX	Wymaga kodu i utrzymania

Zalecenie: Używać Zatwierdzona licencja dla podstawowej wersji (każdy ma licencję Rockstar), a następnie dodaj Rola Discord jako dodatkowa brama dla specjalnych poziomów.

Jak utworzyć whitelistę

Utwórz whitelistę za pomocą Discorda

Jak włączyć & obsługiwać whitelistę w txAdmin

Wymagania wstępne

txAdmin uruchomiony (dostarczany z FXServer).
Dla trybów Discord: skonfigurowana integracja Discorda (bot zaproszony, wybrana gildia/rola).

Włącz whitelistę

Otwórz txAdmin → Ustawienia → Player Manager.
Ustaw Tryb whitelisty do jednego z: Zatwierdzona licencja, Członek Discord, Rola Discord, lub Tylko administratorzy.
Ustaw Wiadomość odrzucenia, np.:
Not whitelisted. Apply at discord.gg/yourinvite
Zapisz.

Zatwierdzanie graczy (dwa przepływy)

Pasywny (kolejka): Gdy niezatwierdzony gracz próbuje dołączyć, pod Biała lista. pojawia się prośba. Zatwierdź/odrzuć jednym kliknięciem.
Aktywny (wstępne zatwierdzenie): Przejdź do Lista dozwolonych → Dodaj zatwierdzenie i wklej identyfikator w formularzu type:value, np.
- license:110000112345678
- steam:11000010abcdef0
- discord:123456789012345678

Cofnij

Otwórz Gracze Lub Biała lista i kliknij Cofnij obok zatwierdzenia.

Wskazówki

Woleć license identyfikatory dla podstawowego dostępu (powszechnie obecne).
Utrzymuj swoją wiadomość odrzucenia praktyczną (link Discord + podstawowe zasady + wezwanie do działania przez zgłoszenie).
Dla personelu/deweloperów, wymagania stosowe: np. musi być license + discord role.

Szczegóły implementacji technicznej

Listy dozwolonych uruchamiane są podczas opóźnienia połączenia etapu. Serwer sprawdza zestaw identyfikatorów gracza i akceptuje lub odrzuca przed załadowaniem zasobów. Utrzymuje to niskie obciążenie i blokuje niezatwierdzonych graczy na wczesnym etapie.

Typy identyfikatorów (niezawodność)

license: (Rockstar) — stabilny, powiązany z zakupem gry; zalecany klucz główny.
steam: — obecny tylko jeśli Steam jest uruchomiony; może go brakować, jeśli gracze nie korzystają ze Steama.
discord: — obecny tylko jeśli Discord jest uruchomiony i twój serwer go odczytuje.
ip: — dynamiczny; używaj do telemetrii/ograniczania prędkości, nie do identyfikacji.

Minimalny skrypt listy dozwolonych (UX opóźnień + wiele identyfikatorów)

-- resource: simple-whitelist
-- fxmanifest.lua should include '@oxmysql/lib/MySQL.lua' if you use DB code below.

local STATIC_WHITELIST = {
 ["license:110000112345678"] = true,
 ["steam:11000010abcdef0"] = true,
 ["discord:123456789012345678"] = true,
}

local function collectIdentifiers(src)
 local ids = {}
 for _, id in ipairs(GetPlayerIdentifiers(src)) do ids[id] = true end
 return ids
end

AddEventHandler("playerConnecting", function(name, setKickReason, deferrals)
 local src = source
 deferrals.defer()
 deferrals.update(("Checking whitelist for %s..."):format(name))

 local ids = collectIdentifiers(src)

 -- Require at least a Rockstar license in all cases
 local hasLicense = false
 for id, _ in pairs(ids) do
 if id:sub(1, 8) == "license:" then hasLicense = true break end
 end
 if not hasLicense then
 return deferrals.done("You must start the game normally (Rockstar license missing). Restart and try again.")
 end

 -- Static allowlist quick‑path
 for id, _ in pairs(ids) do
 if STATIC_WHITELIST[id] then
 return deferrals.done()
 end
 end

 -- Fallback: not approved
 return deferrals.done("Not whitelisted. Apply at discord.gg/yourinvite")
end)

Używać deferrals.update aby wyświetlać komunikaty postępu podczas sprawdzania identyfikatorów i/lub bazy danych. Zmniejsza to fałszywe raporty o “przekroczeniu czasu”.

Lista dozwolonych oparta na bazie danych (oxmysql, gotowa do produkcji)

Schemat

CREATE TABLE IF NOT EXISTS whitelist (
 id INT UNSIGNED NOT NULL AUTO_INCREMENT,
 identifier VARCHAR(64) NOT NULL,
 note VARCHAR(120) NULL,
 added_by VARCHAR(64) NULL,
 added_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
 PRIMARY KEY (id),
 UNIQUE KEY u_identifier (identifier)
);

Sprawdzanie po stronie serwera (oxmysql)

-- Requires oxmysql. Add to fxmanifest: '@oxmysql/lib/MySQL.lua'
AddEventHandler('playerConnecting', function(name, setKickReason, deferrals)
 local src = source
 deferrals.defer()
 deferrals.update('Verifying whitelist...')

 local ids = {}
 for _, id in ipairs(GetPlayerIdentifiers(src)) do table.insert(ids, id) end

 -- Single scalar: any identifier approved?
 local rowCount = MySQL.scalar.await(
 'SELECT COUNT(*) FROM whitelist WHERE identifier IN (?)',
 { ids }
 )

 if rowCount and rowCount > 0 then
 return deferrals.done()
 else
 return deferrals.done('Access denied. Apply at discord.gg/yourinvite')
 end
end)

Polecenia QoL dla administratora (przykład)

RegisterCommand('wladd', function(src, args)
 if src ~= 0 then return end -- console only for simplicity
 local identifier = args[1]
 if not identifier or not identifier:find(':') then
 print('Usage: wladd identifierType:identifierValue')
 return
 end
 local ok = MySQL.prepare.await('INSERT IGNORE INTO whitelist (identifier,note,added_by) VALUES (?, ?, ?)', {
 identifier, 'manual add', 'console'
 })
 print(ok and ('Whitelisted: %s'):format(identifier) or 'Failed to add')
end, true)

RegisterCommand('wlrm', function(src, args)
 if src ~= 0 then return end
 local identifier = args[1]
 local ok = MySQL.prepare.await('DELETE FROM whitelist WHERE identifier = ?', { identifier })
 print(ok and ('Removed: %s'):format(identifier) or 'Failed to remove')
end, true)

Dla mysql-async, zamień MySQL.scalar.await z MySQL.Async.fetchScalar oraz styl parametrów na @param/?. Preferuj oxmysql dla wydajności i obsługi await.

Wydajność

Zachowaj indeks UNIQUE przy identifier (zobacz schemat).
Opcjonalnie rozgrzej pamięć podręczną przy uruchomieniu i przy zmianie; odwołuj się do bazy tylko przy braku w pamięci podręcznej.
Ograniczaj częstotliwość powtarzających się nieudanych prób połączenia według license\/IP.

Zasady wielu identyfikatorów

Niektóre serwery wymagają wielu identyfikatorów (np. zarówno Steam, jak i Discord) dla poziomów personelu. Przykładowy wzór:

local function hasType(ids, typ)
 for id, _ in pairs(ids) do if id:sub(1, #typ+1) == (typ..':') then return true end end
 return false
end

-- Require license, and if staff, also discord
if not hasType(ids, 'license') then
 return deferrals.done('Start the game normally (license missing).')
end
if staffModeEnabled and not hasType(ids, 'discord') then
 return deferrals.done('Join our Discord and link your account to enter.')
end

Używanie Discord jako listy dozwolonych (bez własnego kodu)

Jeśli twoja społeczność działa na Discord, użyj txAdmin’s Członek Discord Lub Rola Discord tryby:

Połącz txAdmin ze swoją gildią Discord.
Wybierz Członek Discord aby zezwolić dowolnemu członkowi gildii, lub Rola Discord aby ograniczyć do konkretnej roli (np., @Whitelisted).
Trzymać Zatwierdzona licencja jako drugie ograniczenie, jeśli chcesz obu warunków.

Najlepsza praktyka: utrzymuj #whitelist-requests kanał + lekki formularz. Zautomatyzuj przypisywanie roli po zatwierdzeniu za pomocą bota lub przepływu moderacji.

FAXES: System listy dozwolonych Discord dla FiveM

Pomysły na integrację

Boty Discord: automatyczne zatwierdzanie, gdy użytkownik ukończy aplikację, boostuje lub subskrybuje.
Panel internetowy: personel dodaje/usuwa identyfikatory, z dziennikiem audytu.
Płatne poziomy: przyznaj discord role za pośrednictwem twojego sklepu (Tebex/Patreon) i pozwól trybowi roli txAdmin egzekwować dostęp.

Rozwiązywanie problemów i pułapki

Gracz nie pojawia się w żądaniach txAdmin: Upewnij się, że lista dozwolonych jest włączona w odpowiednim profilu; sprawdź, czy gracz faktycznie dotarł do etapu odroczenia (obserwuj konsolę na żywo txAdmin).
Brakuje Steam ID: Steam musi być uruchomiony; nie opieraj swojej listy dozwolonych wyłącznie na steam:. Preferuj license:.
Brakuje ID Discord: Użytkownik musi mieć uruchomiony Discord, a twój serwer musi być skonfigurowany do odczytu discord:; zweryfikuj integrację Discord.
license vs license2: Niektóre frameworki rejestrują dwa pola licencji; upewnij się, że twoje zapytania migracji/bazy danych uwzględniają oba podczas przenoszenia danych.
Przekroczenia czasu odroczenia: Zawsze wywołuj deferrals.update(...) gdy czekasz na bazę danych; odpowiedz w ciągu ~10–15 sekund.
Niezgodny format identyfikatora: Upewnij się, że wklejasz type:value dokładnie (małe litery typ, separator dwukropek).
Wysokie skoki ruchu: Buforuj listę dozwolonych w pamięci, podgrzewaj przy starcie i ograniczaj wywołania bazy danych.

FAQ SEO (treść gotowa do schematu)

Jaki jest najlepszy identyfikator dla listy dozwolonych FiveM?
The Rockstar license: jest najbardziej uniwersalny i niezawodny; używaj go jako klucza głównego.

Czy mogę dodać do listy dozwolonych za pomocą Discord bez kodowania?
Tak. txAdmin obsługuje Członek Discord I Rola Discord tryby listy dozwolonych po połączeniu Discord.

Czy potrzebuję Steam do listy dozwolonych?
Nie. Wielu graczy nie używa Steam; unikaj czynienia steam: obowiązkowym dla podstawowego dostępu.

Czy mogę łączyć wiele kontroli (np. licencja + rola Discord)?
Tak. Użyj trybu roli txAdmin I zachowując kontrolę licencji w swoim niestandardowym skrypcie lub procesie przyjmowania.

Jak wstępnie zatwierdzić graczy?
txAdmin → Lista dozwolonych → Dodaj zatwierdzenie, wklej identifierType:identifier (np., license:...).

Kopiuj-Wklej komunikaty odrzucenia (użyj swojej marki)

Oparte na kolejce: You’re not whitelisted yet. Apply in #whitelist-requests → discord.gg/yourinvite
Oparte na roli: Your Discord account doesn’t have @Whitelisted. Join discord.gg/yourinvite and request access.
Konserwacja: Server is in Admin‑only mode for maintenance. Please try again later.

Podsumowanie

Lista dozwolonych FiveM weryfikuje identyfikatory graczy podczas fazy opóźnienia połączenia i blokuje niezatwierdzonych użytkowników przed załadowaniem zasobów. Dla większości serwerów włącz Zatwierdzona licencja w txAdmin, opcjonalnie dodaj warstwę Rola Discord do bramkowania społeczności i użyj listy opartej na DB z buforowaniem dla skalowalności.

Dodatek: Oryginalny minimalny przykład (dla odniesienia)

-- server.lua
local whitelist = {
 ["steam:110000132456789"] = true,
 ["license:abc123def456789"] = true,
 ["discord:123456789012345678"] = true
}

AddEventHandler("playerConnecting", function(name, setKickReason, deferrals)
 local player = source
 local identifiers = GetPlayerIdentifiers(player)
 local whitelisted = false
 
 deferrals.defer()
 
 for _, id in pairs(identifiers) do
 if whitelist[id] then
 whitelisted = true
 break
 end
 end
 
 if not whitelisted then
 deferrals.done("Not whitelisted. Apply at: your-discord.gg/invite")
 else
 deferrals.done()
 end
end)