Instalacja

Dziesięć minut, z czego większość to czekanie na uruchomienie serwera. Nie ma tu żadnego pliku SQL do zaimportowania ani drugiego programu do uruchomienia — tabele tworzą się same przy pierwszym starcie zasobu.

Każdy poniższy krok kończy się informacją, jak poznać, że wszystko zadziałało, dzięki czemu nigdy nie przechodzisz dalej w niepewności.

Zanim zaczniesz

Czego potrzebujesz	Dlaczego
oxmysql, uruchomiony	Wszystko, co telefon zapamiętuje, trafia do Twojej bazy danych
ESX, QBCore, QBox lub fmLib	Wykrywane automatycznie; nie musisz nigdzie wpisywać, co masz
Serwer FiveM z ostatnich dwóch lat	Część webowa telefonu korzysta z wbudowanego w serwer Node’a

Nic więcej. Bez npm, bez budowania (build), bez serwera WWW.

1. Umieść folder na miejscu

Wrzuć mic_phone do swoich zasobów — najwygodniej wewnątrz folderu w nawiasach kwadratowych:

resources/[mic]/mic_phone/

Zostaw nazwę folderu jako mic_phone. Nic się nie zepsuje, jeśli ją zmienisz, ale adres webowy telefonu jest budowany na podstawie nazwy folderu, więc wszystko, co zostało o nim zapisane, również uległoby zmianie.

2. Uruchom go po zasobach, na których polega

W pliku server.cfg, poniżej oxmysql i poniżej Twojego frameworka:

ensure oxmysql
ensure es_extended        # or qb-core / qbx_core
ensure mic_phone

Zadziałało, gdy konsola podczas startu wyświetli:

[mic_phone] web: door B listening on http://0.0.0.0:30125  ·  door A at /mic_phone/web/ on the game port

Jeśli zamiast tego zobaczysz czerwoną linijkę dotyczącą frameworka, uruchom mic_phone po swoim frameworku — to niemal zawsze jest przyczyną.

3. Baza danych — nic do roboty

Pierwsze uruchomienie odczytuje sql/schema.sql i tworzy wszystko, czego brakuje. Zobaczysz ciąg przelatujących linijek CREATE TABLE IF NOT EXISTS mic_phone_…. To wszystko.

Zadziałało, gdy te linijki pojawią się raz i nigdy więcej przy kolejnych uruchomieniach.

4. Daj graczom coś, co mogą otworzyć

Domyślnie telefon wymaga przedmiotu w ekwipunku o nazwie phone:

-- shared/config.lua
Config.Open = {
    RequireItem = true,
    Item        = 'phone',
    ...
}

Większość konfiguracji ESX i QB ma już ten przedmiot. Użytkownicy ox_inventory: dodajcie go do swojej listy przedmiotów, jeśli jeszcze go tam nie ma. Tylko testujesz? Ustaw RequireItem = false i całkowicie pomiń ten krok.

Zadziałało, gdy wejdziesz na serwer, masz przy sobie przedmiot, a klawisz F1 otwiera telefon. Komenda /phone robi to samo, a klawisz T rozkłada otwarty telefon w tablet.

5. Ustawienia tylko po stronie serwera

Skopiuj przykładowy plik i uzupełnij to, czego potrzebujesz:

shared/server_config.example.lua  →  shared/server_config.lua

Ten plik jest ładowany wyłącznie jako skrypt serwerowy, więc nic z jego zawartości nigdy nie trafia do gracza. Znajdują się tam dwie rzeczy:

Zdjęcia, filmy i notatki głosowe. Wpisz token multimediów Fivemanage w ServerConfig.Media.Token (lub w convarze FIVEMANAGE_MEDIA_API_KEY), a telefon sam będzie przesyłał pliki, zapisując jedynie wynikowy link. Webhook Discorda działa jako rozwiązanie zapasowe.

Jeśli nie ustawisz żadnego z nich, FallbackToDataUrl zatrzyma plik wewnątrz Twojej bazy danych. To wystarcza do testów, ale jest bardzo ciężkie na produkcji — kilka sekund nagrania głosowego to dziesiątki kilobajtów w każdym powiązanym wierszu. Ustaw token lub wyłącz tę opcję i pozwól, by przesyłanie plików wyraźnie zgłaszało błąd.

Webhooki Discorda. Jeden adres URL na każdy rodzaj zdarzenia lub Default, aby przechwytywać wszystko. Ten, który warto ustawić, nawet jeśli pominiesz resztę, to Server: jako jedyny informuje Cię o serwerze, a nie o graczu — np. gdy zmienił się adres lub certyfikat nie został odnowiony.

Gotowe

Telefon działa. Wszystko poniżej jest opcjonalne.

Opcjonalnie: telefon na prawdziwym telefonie

Gracze mogą nosić telefon swojej postaci na własnym smartfonie. Funkcja jest już włączona: Ustawienia › Połączone urządzenia w telefonie w grze pokazuje kod QR — gracz go skanuje i przepisuje w grze sześć wyświetlonych cyfr. Od tej chwili urządzenie działa jako ta postać.

Przez zwykłe HTTP daje im to już wiadomości, pocztę, kontakty, garaż, nieruchomości i resztę. To, czego przeglądarka nie przekaże niezabezpieczonej stronie, to najlepsza część:

	Zwykłe HTTP	HTTPS
Wiadomości, poczta, garaż i cała reszta	tak	tak
Powiadomienia przy zamkniętej aplikacji	nie	tak
Połączenia głosowe	nie	tak
Mikrofon do notatek głosowych	nie	tak
Instalacja jako aplikacja z własną ikoną	nie	tak

Uzyskanie HTTPS bez instalowania czegokolwiek

Ten zasób potrafi sam pobrać i odnowić własny certyfikat. Skieruj domenę na swój serwer, otwórz dwa porty i wypełnij trzy linijki:

-- shared/server_config.lua  (server-only: this file is never sent to a client)
ServerConfig.Web = {
    Url = 'https://phone.yourserver.com/',
    Https = {
        Enabled = true,
        Names   = { 'phone.yourserver.com' },
        Contact = '[email protected]',
    },
}

Nazwa (domena). Na VPS to jeden rekord A wskazujący na jego adres IP. Nie masz domeny? duckdns.org da Ci darmową w minutę.
Port 80 i port 443 przepuszczone przez zaporę sieciową (firewall). Port 80 jest otwierany tylko na czas prośby o certyfikat i zamykany natychmiast po otrzymaniu odpowiedzi.

Zadziałało, gdy konsola wyświetli:

https: asking for phone.yourserver.com
https: port 80 open for the challenge
https: challenge port closed
https: certificate in hand, good until 2027-01-31
https: listening on https://phone.yourserver.com/

Jeśli port 443 jest zajęty — niektóre routery rezerwują go dla własnej strony administracyjnej — uruchom usługę na innym porcie: Port = 8443, przekieruj 8443 i wpisz Url = 'https://phone.yourserver.com:8443/'. Tylko zadanie weryfikacyjne (challenge) musi przejść przez port 80; certyfikat należy do nazwy domeny, a nie do portu, więc wszystko nadal będzie działać.

Plik docs/HTTPS.md opisuje pozostałe sytuacje: za proxy Cfx.re, za odwrotnym proxy (reverse proxy), które już posiadasz, lub na hostingu, który nie udostępnia dodatkowych portów.

Gdy coś działa nie tak

phonehttps check — pyta serwer testowy urzędu certyfikacji, czy jest w stanie połączyć się z Twoją maszyną. Uruchom to w pierwszej kolejności, gdy certyfikat nie dociera: pozwala to odróżnić problem z Twoją zaporą sieciową od problemu z tym zasobem.

phonehttps — pokazuje aktualny stan certyfikatu i datę jego odnowienia.

phoneduck — pokazuje stan domeny, jeśli ten serwer sam utrzymuje swoją nazwę DuckDNS skierowaną na siebie, oraz kiedy ostatnio to zgłosił. phoneduck now wysyła aktualnie posiadany adres i wypisuje odpowiedź DuckDNS, co pozwala od razu wykryć błędny token bez czekania na zmianę adresu IP.

Co widzisz	Co to oznacza
Telefon się nie otwiera	Brak przedmiotu `phone` lub opcja `RequireItem` jest włączona, a gracz nie ma go przy sobie
Kod QR prowadzi do nieosiągalnego adresu	Ustaw `ServerConfig.Web.Url` ręcznie; automatyczne wykrywanie nie widzi zmian portu wykonanych przez router
Brak certyfikatu, a logi wskazują na błąd challenge	Port 80 nie dociera do tej maszyny. Sprawdź przekierowanie portów oraz zaporę sieciową (w tej kolejności)
Zdjęcia są ogromne / baza danych bardzo szybko rośnie	Brak tokenu multimediów, a `FallbackToDataUrl` zapisuje pliki bezpośrednio w bazie danych
Połączenia między dwoma graczami są głuche (brak dźwięku)	System głosu ma ustawione `auto` i nie znalazł zasobu głosowego; wpisz swój w `Config.Bridge.voice`

Zanim otworzysz swoje miasto

shared/server_config.lua należy tylko do Ciebie. Nigdy go nie udostępniaj ani nie wrzucaj do publicznych repozytoriów; zawiera on Twój token multimediów oraz adresy URL webhooków.
Skieruj webhook Server w miejsce, które regularnie czytasz. To on informuje, że frontowe drzwi webowe telefonu przestały działać, i będzie to jedyne ostrzeżenie, jakie otrzymasz, zanim powie Ci o tym gracz.
Wyłącz Config.Debug, jeśli go włączyłeś: wypisuje on w konsoli każdą decyzję podejmowaną przez bridge.
Bezpieczeństwo jest warte dziesięciu minut lektury, jeśli prowadzisz publiczne miasto: dowiesz się, co ten zasób zakłada o osobach łączących się z nim i jakich zasad pilnuje, aby zmodyfikowany klient nie mógł wyjść poza własną postać.