Panel en ligne, agent et licence

#Comment tout est relié

Avec le panel en ligne, tu n'installes pas de site web sur ta machine : le panel tourne chez nous, et un petit programme, l'agent, tourne à côté de ton serveur FiveM.

ton navigateur ──HTTPS──▶ panel en ligne ◀──WSS (sortant)── agent ──▶ ta base MariaDB
                                                              ├──▶ le dossier du serveur
                                                              └──▶ FXServer (démarrer, arrêter, RCON)

• L'agent ouvre une connexion sortante chiffrée vers le panel : aucun port à ouvrir chez toi.
• Il n'exécute qu'une liste fermée d'opérations : requêtes sur la base du serveur, fichiers du dossier du serveur uniquement, démarrage / arrêt / état de FXServer, RCON et pont local du jeu.
• Les secrets de server.cfg (mot de passe RCON, panel_token) sont lus par l'agent sur ta machine et ne partent jamais au panel.

Dans cette page, l'adresse du panel est notée panel.exemple.fr : remplace-la par celle que tu as reçue.

#La clé de licence

Ta clé de licence Socle a la forme SOCLE-XXXX-XXXX-XXXX. Elle sert à deux endroits : dans server.cfg (le jeu vérifie la licence) et dans le panel (pour ajouter ton serveur).

#Dans server.cfg

# Clé de licence Socle : « set », JAMAIS « setr » (elle ne doit pas partir aux joueurs)
set socle_license_key "SOCLE-XXXX-XXXX-XXXX"

Le serveur vérifie la clé au démarrage, puis toutes les 6 heures. La console affiche le résultat sous la catégorie LICENCE (par exemple statut active (offre …)).

Coupure réseau : si le site de vérification est injoignable, le serveur garde le dernier résultat valide (mémorisé sur la machine) pendant 72 heures, puis passe en mode limité. Une simple maintenance de notre côté ne coupe donc jamais ton serveur.

#Le mode limité

En mode limité, le serveur tourne mais refuse les connexions, avec le message « Ce serveur est temporairement fermé : sa licence Socle n'est plus active ». Un rappel est écrit dans la console toutes les 10 minutes.

Restent autorisés à se connecter les joueurs qui ont l'ace socle.license.bypass (ou l'ace command), pour que ton staff puisse vérifier le serveur :

# exemple : autoriser le groupe admin à entrer même en mode limité
add_ace group.admin socle.license.bypass allow
add_principal identifier.license:0123456789abcdef0123456789abcdef01234567 group.admin

#OmniShield inclus

Selon ton offre, l'anticheat partenaire OmniShield est inclus ; il le reste à vie après 12 mois d'abonnement continu. Côté code, exports.socle:licenseShield() renvoie true quand c'est le cas (et false en mode limité).

#Dans le panel

• Une clé = un serveur : la même clé ne peut pas servir à deux serveurs du panel.
• Ajouter un serveur ou changer sa clé exige une licence active ou grace.
• Le panel revérifie la licence au plus toutes les 15 minutes quand tu ouvres ton serveur.
• Licence expired ou unknown : toutes les pages du serveur affichent Licence inactive avec un lien de renouvellement ; seule la liste des serveurs reste utilisable. Tes données ne sont pas supprimées.

#Ajouter ton serveur

1. Connecte-toi sur https://panel.exemple.fr avec ton compte Discord.
2. Serveurs › Ajouter un serveur : donne un nom (2 à 64 caractères) et ta clé de licence.
3. Le panel affiche une seule fois la configuration de l'agent, avec son jeton. Copie-la tout de suite : elle ne sera plus jamais affichée (au pire, tu pourras régénérer le jeton).

Tu peux créer 5 serveurs par heure au plus.

#Installer l'agent

#Prérequis

• Node.js 20 ou plus récent (version LTS) sur la machine du serveur FiveM.
• Dans server.cfg :

set mysql_connection_string "mysql://utilisateur:motdepasse@127.0.0.1:3306/ma_base?charset=utf8mb4"
# arrêt propre du serveur par le panel (sauvegarde des inventaires puis « quit »)
set rcon_password "un-mot-de-passe-long-et-aleatoire"
# pont entre le panel et le jeu : une longue valeur aléatoire, « set » seulement
set panel_token "une-longue-valeur-aleatoire-de-64-caracteres"
# signature des events du Socle : un entier, « setr » (le client doit le lire)
setr network_token 123456789

#Étapes

1. Copie le dossier agent/ sur la machine du serveur, par exemple C:\SocleAgent. 2. Dans ce dossier, installe ses dépendances :

cd C:\SocleAgent
npm ci

3. Crée config.json à partir de config.example.json et colle la configuration donnée par le panel :

{
  "hubUrl": "wss://panel.exemple.fr/agent",
  "serverId": "00000000-0000-0000-0000-000000000000",
  "token": "<le jeton affiché par le panel>",
  "serverDir": "C:\\FXServer\\server-data",
  "databaseUrl": "mysql://utilisateur:motdepasse@127.0.0.1:3306/ma_base",
  "fxserver": {
    "exe": "C:\\FXServer\\artifact\\FXServer.exe",
    "args": ["+exec", "server.cfg"],
    "cwd": "",
    "statusUrl": "http://127.0.0.1:30120"
  }
}

4. Lance l'agent :

node index.mjs

Le journal affiche « connecté au panel » et la page Serveurs passe ton agent en ligne. Si la connexion tombe, l'agent se reconnecte seul (après 1 s, 2 s, 4 s… jusqu'à 30 s entre deux essais).

#Lancer l'agent au démarrage de Windows

Avec NSSM (nssm.cc), l'agent devient un service Windows qui démarre avec la machine et redémarre s'il s'arrête. Dans une invite de commandes administrateur :

nssm install SocleAgent "C:\Program Files\nodejs\node.exe" "C:\SocleAgent\index.mjs"
nssm set SocleAgent AppDirectory C:\SocleAgent
nssm set SocleAgent AppStdout C:\SocleAgent\agent.log
nssm set SocleAgent AppStderr C:\SocleAgent\agent.log
nssm set SocleAgent AppRotateFiles 1
nssm set SocleAgent AppRotateBytes 5000000
nssm start SocleAgent

Le service tourne par défaut sous le compte SYSTÈME. Pour que FXServer, démarré par l'agent, ait les mêmes droits que d'habitude, fais tourner le service sous le compte Windows qui lance normalement le serveur :

nssm set SocleAgent ObjectName .\Utilisateur MotDePasse

Arrêt et suppression : nssm stop SocleAgent, puis nssm remove SocleAgent confirm.

Sans NSSM, le Planificateur de tâches fait l'affaire : tâche « Au démarrage », exécutée même si l'utilisateur n'est pas connecté, programme C:\Program Files\nodejs\node.exe, argument index.mjs, dossier de départ C:\SocleAgent, redémarrage toutes les minutes en cas d'échec, sans limite de durée.

#Le jeton de l'agent

Le jeton prouve au panel que l'agent est bien celui de ton serveur. Seule son empreinte est gardée par le panel.

• Jeton perdu ou compromis : sur la fiche de ton serveur, un propriétaire peut régénérer le jeton. L'agent connecté est aussitôt déconnecté et l'ancien jeton refusé. Colle la nouvelle configuration dans config.json, puis relance l'agent (nssm restart SocleAgent).
• Supprimer le serveur du panel (propriétaire, en recopiant son nom exact) : membres, invitations et dossier CDN du serveur sont supprimés, la licence est libérée, l'agent est déconnecté. Ta base de données et tes fichiers de jeu ne sont pas touchés.

Chaque action importante (création, clé, invitation, rôle, jeton, suppression) est inscrite dans le journal du serveur ; les 20 dernières lignes sont visibles sur sa fiche.

#Équipe et invitations

• Seul un propriétaire invite, change un rôle ou retire un membre. Un serveur garde toujours au moins un propriétaire.
• Une invitation est un lien valable 7 jours, utilisable une seule fois, pour un rôle donné. La personne invitée se connecte avec Discord en ouvrant le lien.
• Le détail de ce que chaque rôle voit dans le panel est dans Équipe et accès.

#Le CDN de ton serveur

Les fichiers envoyés dans la médiathèque du panel (logos, bannières, sons, vidéos) reçoivent une adresse publique propre à ton serveur :

https://panel.exemple.fr/cdn/s/<identifiant-du-serveur>/<fichier>

• Chaque serveur a son propre dossier : un autre client ne voit pas tes fichiers.
• Le nom du fichier est son empreinte : un même fichier envoyé deux fois n'est stocké qu'une fois. Les liens sont mis en cache longtemps par les navigateurs.
• Quota : 1 Go par serveur par défaut. L'occupation compte tes fichiers CDN et le dossier assets/ de socle sur ta machine. L'achat d'espace supplémentaire en crédits n'est pas disponible avec le panel en ligne.
• Les fichiers du jeu (nui://socle/assets/…) restent sur ta machine ; le panel les gère à travers l'agent.

Le fonctionnement de la médiathèque est décrit dans Fichiers et stockage.

#Mises à jour depuis le panel

Une mise à jour de Socle est un dossier (pas une archive à envoyer au panel) nommé par exemple socle-1.3.0, qui contient un fichier socle-update.json (version, ressources concernées, empreinte de chaque fichier) et un dossier resources/.

#Appliquer une mise à jour

1. Fais une sauvegarde de ta configuration (Serveur › Sauvegardes).
2. Sur la machine du serveur, décompresse la mise à jour dans un dossier updates à côté de `server.cfg` : updates/socle-1.3.0/socle-update.json doit exister.
3. Serveur › Mises à jour › 1. Choisir la mise à jour : indique le chemin relatif updates/socle-1.3.0.
4. Le panel analyse le paquet (les empreintes sont calculées sur ta machine par l'agent : rien ne transite par Internet, même pour plusieurs centaines de Mo). Un fichier manquant ou différent de son empreinte, et la mise à jour est refusée sans rien appliquer : retélécharge-la. Sinon, le plan liste les nouveaux fichiers, les fichiers remplacés, les fichiers supprimés (retirés du Socle), les fichiers protégés, laissés tels quels, et les conflits.
5. 2. Appliquer : tape la version pour confirmer. Si le serveur de jeu tourne, choisis Arrêter puis appliquer (les fichiers ne peuvent pas être remplacés pendant qu'il tourne).
6. Redémarre le serveur. Les tables de la base se mettent à jour toutes seules au démarrage.

Avant toute copie, chaque fichier remplacé ou supprimé est sauvegardé dans backups/update-… dans le dossier du serveur. Si l'application échoue, elle est annulée automatiquement.

#Les conflits

Après chaque installation, le panel enregistre l'empreinte de chaque fichier livré (resources/.socle-installed.json). À la mise à jour suivante, un fichier livré que tu as modifié apparaît en conflit : il est remplacé quand même (ou supprimé, s'il est retiré du Socle), et ta version est gardée dans la sauvegarde backups/update-….

C'est pour ça que ton code doit vivre dans tes propres fichiers (voir Créer ton module) et jamais dans les fichiers du Socle.

#Ce qui n'est jamais écrasé

• tout ce qui n'est pas listé dans le paquet : tes propres ressources, tes dossiers de module (socle/modules/<ton_module>/), tes fichiers ajoutés, server.cfg, server_resources.cfg ;
• les dossiers de resources/ que la mise à jour ne concerne pas (le plan les liste) ;
• les fichiers protégés par le paquet (motifs preserve, par exemple socle/configs/**) s'ils existent déjà ;
• tes réglages, textes et apparence : ils sont en base de données, pas dans les fichiers ;
• les sources de l'interface ui/src (seul ui/dist, compilé, est livré : voir L'interface NUI).

#Revenir en arrière

Restaurer la version précédente remet les fichiers de la dernière mise à jour appliquée par le panel, tant qu'elle n'a pas déjà été annulée. Les fichiers remplacés ou supprimés sont remis depuis backups/update-…, et ceux que la mise à jour avait ajoutés sont retirés (sauf si tu les as modifiés depuis).

#Maintenance planifiée

La page Maintenance du panel planifie des opérations lourdes sur la base, exécutées par le serveur de jeu à son prochain démarrage complet, juste après les migrations.

• Une planification se confirme en tapant CONFIRMER. Tant qu'elle est en attente, tu peux l'annuler.
• Avant d'exécuter, le serveur sauvegarde chaque table touchée dans une table bak_<table>_<date> et vérifie la copie. Si la sauvegarde échoue, l'action passe en échec et rien n'est modifié.
• Seules les 5 dernières sauvegardes bak_ de chaque table sont gardées (réglable avec set maintenance_backup_keep 10 dans server.cfg).
• Le résultat (fait, échec, nombre de lignes, sauvegarde) s'affiche ensuite sur la page.

#Limites du panel en ligne

• Un fichier du serveur de plus de 20 Mo ne peut être ni lu ni écrit par le panel (une vidéo de 80 Mo dans les fichiers du jeu, par exemple). Empreintes, copies et renommages n'ont pas de limite.
• Journaux : la page Santé lit les 4 derniers Mo du journal du serveur, la console les 96 derniers Ko.
• La corbeille des fichiers du jeu est le dossier .panel-trash/ du dossier du serveur.
• L'assistant d'installation du panel local n'existe pas en ligne : les lignes de server.cfg ci-dessus sont à écrire toi-même.

#En cas de problème