Come installare ESX o QBCore su un server FiveM
Scegli tra ESX Legacy e QBCore, prepara il database MariaDB, distribuisci il framework con txAdmin sul tuo server Linux, verifica il risultato e torna indietro se necessario.
In questa pagina
I tuoi valori
Inseriscili una volta: i comandi della guida si aggiornano.
ESX Legacy e QBCore sono framework di roleplay: aggiungono a FiveM personaggi, lavori, denaro e inventario. Questa guida ti aiuta a scegliere tra i due, poi a distribuirne uno con txAdmin, senza perdere la tua configurazione attuale.
Prerequisiti
- Un server installato con la guida Creare un server FiveM: utente
fivem, serviziofivem.service, script/usr/local/sbin/backup-fivem.sh - MariaDB installata, con il database
fiveme l'utentefivemcreati nella sezione MariaDB di quella guida - La password di questo utente MariaDB
- La tua chiave di licenza
cfxk_e un account amministratore principale di txAdmin
Scegliere tra ESX e QBCore
I due framework rispondono alla stessa esigenza. Il criterio decisivo è l'elenco delle risorse che intendi usare: una risorsa scritta per uno dei due non funziona così com'è sull'altro.
| Criterio | ESX Legacy | QBCore |
|---|---|---|
| Deployment in txAdmin | Popular Recipes, recipe ESX Legacy | Remote URL Template, con l'indirizzo della recipe |
| Risorsa principale | es_extended |
qb-core |
| Dipendenze principali | oxmysql, esx_lib |
oxmysql |
| Tabella dei giocatori | users |
players |
| Permessi dei giocatori | Gruppi salvati nel database, modificati con setgroup |
Livelli god, admin e mod, gestiti da permessi ACE |
| OneSync | Attivato dalla recipe | Attivato dalla recipe |
| Documentazione | docs.esx-framework.org | qbcore.org/docs |
Per decidere:
- Scegli ESX Legacy se vuoi seguire il percorso proposto direttamente da txAdmin, o se le risorse che ti interessano sono scritte per ESX.
- Scegli QBCore se le risorse che ti interessano sono scritte per QBCore, o se il tuo team lo conosce già.
- Dai un'occhiata anche a Qbox se hai dubbi sul lato QBCore: txAdmin propone la sua recipe in Popular Recipes e la presenta come compatibile con le risorse QBCore. Questa guida non ne descrive l'installazione.
Cambiare framework in seguito equivale a ripartire da zero: tabelle, funzioni e risorse sono diverse. Non installare mai entrambi sullo stesso server.
Passo 1: fare il backup del server
Lancia lo script di backup e verifica che gli archivi siano stati creati:
sudo /usr/local/sbin/backup-fivem.sh
sudo ls -lh /home/fivem/backupsAnnota la data degli ultimi due file, fivem_DATE.tar.gz e fivem_db_DATE.sql.gz. Serviranno per il ripristino.
Passo 2: preparare il database
Verifica che MariaDB funzioni e conta le tabelle del database fivem:
sudo systemctl is-active mariadb
sudo mariadb -N -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='fivem';"- Il risultato è
0: il database è vuoto, usafiveme passa al passo 3. - Il risultato è maggiore di
0: il database contiene già dei dati. Creane un altro per il framework, come qui sotto.
sudo mariadbCREATE DATABASE fivem_rp CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON fivem_rp.* TO 'fivem'@'localhost';
FLUSH PRIVILEGES;
EXIT;Indica poi questo database allo script di backup, altrimenti non verrà salvato:
sudo sed -i 's/^DB_NAME="fivem"$/DB_NAME="fivem_rp"/' /usr/local/sbin/backup-fivem.sh
sudo grep '^DB_NAME' /usr/local/sbin/backup-fivem.shNel seguito, sostituisci fivem con fivem_rp quando si tratta del nome del database.
Se hai perso la password, generane una con openssl rand -hex 16, poi applicala in sudo mariadb:
ALTER USER 'fivem'@'localhost' IDENTIFIED BY 'PASSWORD_GENERATA';Se un server esistente usa già questo account, aggiorna anche la sua riga mysql_connection_string.
Passo 3: tornare alla procedura guidata di txAdmin
Salta questo passo se non è stato ancora distribuito alcun server: txAdmin mostra già la procedura guidata.
Altrimenti, apri txAdmin tramite il tunnel SSH, poi:
- Vai in Settings, scheda FXServer.
- Copia il valore di Server Data Folder e conservalo: è il percorso del tuo server attuale.
- Clicca su Reset, poi conferma.
Questa azione arresta il server e riporta txAdmin alla procedura guidata. Non elimina né i file delle risorse né il database.
Passo 4: avviare il deployment
Nella procedura guidata, dai un nome al server, poi scegli la recipe:
- ESX Legacy: seleziona Popular Recipes, poi ESX Legacy.
- QBCore: seleziona Remote URL Template, poi incolla questo indirizzo:
https://raw.githubusercontent.com/qbcore-fivem/txAdminRecipe/main/qbcore.yamlMantieni la cartella di destinazione proposta e passa al Recipe Deployer. Incolla la tua chiave cfxk_, poi clicca su Show/Hide Database options (advanced) e compila:
| Campo | Valore |
|---|---|
| Database Host | 127.0.0.1 |
| Database Port | 3306 |
| Database Username | fivem |
| Database Password | La password dell'utente fivem |
| Database Name | fivem (o fivem_rp) |
| Delete Database | Disattivato |
Clicca su Run Recipe. Il deployment scarica molte risorse e può durare diversi minuti. Al termine, clicca su Save & Run Server.
Passo 5: verificare l'installazione
Attendi circa un minuto, poi cerca nella console la connessione al database e l'avvio del framework:
sudo grep -a -E 'Database server connection established|Started resource (es_extended|qb-core)' /home/fivem/fxserver.logDevi vedere la riga di connessione al database e quella di es_extended o di qb-core. Verifica poi che il server dichiari queste risorse:
curl -fsS http://127.0.0.1:30120/info.json | grep -oE '"(oxmysql|es_extended|qb-core)"'Controlla infine che la recipe abbia creato la tabella dei giocatori:
# ESX Legacy
sudo mariadb fivem -e "SHOW TABLES LIKE 'users';"
# QBCore
sudo mariadb fivem -e "SHOW TABLES LIKE 'players';"Connettiti poi al gioco con connect IP_DEL_SERVER:30120 e crea un personaggio. Una riga deve comparire in questa tabella.
Passo 6: darti i permessi di amministrazione
- ESX Legacy: connettiti al server, individua il tuo numero di giocatore nell'elenco dei giocatori connessi di txAdmin, poi digita in Live Console
setgroup 1 admin, sostituendo1con questo numero. Il gruppo viene salvato nella tabellausers. - QBCore: aggiungi il tuo identificatore al gruppo
qbcore.god, come spiegato in Gestire i permessi ACE su FiveM.
Esegui anche un nuovo backup: è ormai il tuo punto di ripristino di riferimento.
sudo /usr/local/sbin/backup-fivem.shTornare indietro
Questa procedura ripristina il server e il database com'erano al passo 1. Sostituisci DATE con la data annotata.
sudo systemctl stop fivem.service
sudo mv /home/fivem/txData /home/fivem/txData.framework
sudo -u fivem tar -xzf /home/fivem/backups/fivem_DATE.tar.gz -C /home/fivem
sudo mariadb -e "DROP DATABASE fivem; CREATE DATABASE fivem CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
zcat /home/fivem/backups/fivem_db_DATE.sql.gz | sudo mariadb fivem
sudo systemctl start fivem.serviceSe avevi creato fivem_rp, l'archivio del passo 1 contiene il database fivem originale, che non è stato modificato: non eseguire le righe DROP DATABASE e zcat. Elimina invece fivem_rp con sudo mariadb -e "DROP DATABASE fivem_rp;", poi rimetti DB_NAME="fivem" nello script di backup.
La cartella /home/fivem/txData.framework conserva la prova. Eliminala quando non ti serve più.
In caso di problemi
Database connection failed
Questo messaggio compare nel Recipe Deployer, seguito dalla causa:
connect ECONNREFUSED 127.0.0.1:3306: MariaDB non è in esecuzione. Verifica consudo systemctl status mariadb.Access denied for user 'fivem'@'localhost': la password non è corretta.Access denied for user 'fivem'@'127.0.0.1': aggiungi questo account seguendo Installare e configurare oxmysql su FiveM.
Access denied for user 'fivem'@'localhost' to database
Il campo Database Name contiene un nome diverso da fivem. Per impostazione predefinita, txAdmin vi inserisce l'identificatore del deployment, e l'utente fivem non ha alcun permesso su questo database. Correggi il campo.
Table 'addon_account' already exists
La recipe ESX è già stata eseguita su questo database, ad esempio durante un deployment interrotto. Se il database non contiene nulla di utile, svuotalo, poi rilancia la recipe:
sudo mariadb -e "DROP DATABASE fivem; CREATE DATABASE fivem CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"Il deployment si ferma durante un download
Le recipe scaricano molti file da GitHub, che può limitare temporaneamente le richieste. Attendi qualche minuto, poi rilancia il deployment. Verifica anche lo spazio su disco con df -h /home.
La recipe non compare o txAdmin la ritiene incompatibile
QBCore non è in Popular Recipes: usa Remote URL Template. Se txAdmin indica Some recipes are not compatible with your txAdmin version, segui Aggiornare gli artifact di FXServer, perché FXServer include txAdmin.
Could not find dependency oxmysql for resource es_extended
La risorsa oxmysql è assente o posizionata male. Lo stesso messaggio esiste per qb-core e per esx_lib. Verifica la sua presenza con la guida Installare e configurare oxmysql su FiveM.
Resource 'oxmysql' can't run
Se la riga successiva indica server needs to be 12913 or higher, la tua versione di FXServer è troppo vecchia per questa versione di oxmysql. Segui Aggiornare gli artifact di FXServer.
Table 'fivem.users' doesn't exist
La stringa di connessione punta a un database diverso da quello del deployment, oppure l'importazione SQL non è andata a buon fine. Confronta mysql_connection_string in CFG Editor con il risultato di sudo mariadb -e "SHOW DATABASES;".
Il server si avvia ma resta instabile
Consulta Diagnosticare crash e rallentamenti di un server FiveM per trovare la risorsa responsabile.