OpenSimulator · FR

FSAssets : guide technique complet

Architecture, stockage des assets, métadonnées SQL, compression, spool et configuration ROBUST.

Guide fondé sur les fichiers sources du fork OpenSimulator 0.9.3.1 / .NET 8. Vérifiez la version et sauvegardez avant toute modification en production.

Ce que FSAssets remplace — et ce qu’il ne remplace pas

FSAssets conserve les données des assets sous forme de fichiers sur un volume et les métadonnées en base de données. Il ne remplace ni les bases d’inventaire, ni les données des régions, ni les OAR/IAR. Un objet qui apparaît dans l’inventaire peut donc encore dépendre d’un fichier d’asset absent.

Comprendre la chaîne d’écriture

Le code calcule un SHA-256 du contenu. L’asset est d’abord écrit dans SpoolDirectory/spool puis déplacé vers SpoolDirectory, avant traitement par un thread écrivain vers BaseDirectory sous forme compressée .gz. Les entrées SQL relient l’UUID à ce hash. Sur une production, sauvegardez toutes les parties d’un même état, y compris le spool encore actif.

Activer le connecteur dans ROBUST

Dans [AssetService], une seule option LocalServiceModule doit être active. Remplacez le service d’assets standard par le connecteur FSAssets uniquement après sauvegarde et plan de retour arrière. Le serveur ROBUST lit le fichier INI passé au lancement ; attention à Robust.ini, Robust.HG.ini et leurs variantes .example.

Exemple à adapter : ne jamais appliquer aveuglément en production.

[AssetService]
LocalServiceModule = "OpenSim.Services.FSAssetService.dll:FSAssetConnector"
BaseDirectory = "/srv/opensim/fsassets/data"
SpoolDirectory = "/srv/opensim/fsassets/tmp"
DaysBetweenAccessTimeUpdates = 30
ShowConsoleStats = true
UseOsgridFormat = false

Préparer les répertoires

Créez data et tmp sur un volume monté et vérifiez que le compte qui lance ROBUST possède l’accès en lecture/écriture. Évitez d’exécuter ROBUST en root ; utilisez le compte de service réel. Les chemins absolus sont plus simples à diagnostiquer que les chemins relatifs.

Exemple à adapter : ne jamais appliquer aveuglément en production.

# À adapter à votre compte de service et à votre montage
sudo install -d -o opensim -g opensim -m 750 /srv/opensim/fsassets/data
sudo install -d -o opensim -g opensim -m 750 /srv/opensim/fsassets/tmp
findmnt -T /srv/opensim/fsassets/data
findmnt -T /srv/opensim/fsassets/tmp
sudo -u opensim test -w /srv/opensim/fsassets/data && echo 'data writable'
sudo -u opensim test -w /srv/opensim/fsassets/tmp && echo 'tmp writable'

SpoolDirectory et BaseDirectory : même volume

Les modèles du fork indiquent que BaseDirectory et SpoolDirectory doivent être sur le même système de fichiers physique. L’organisation en spool et la gestion des fichiers temporaires justifient de les placer sur le même montage. Ne dirigez pas le spool vers /tmp si /tmp est sur un autre volume ou supprimé au redémarrage. Vérifiez les montages réels et les liens symboliques.

Exemple à adapter : ne jamais appliquer aveuglément en production.

readlink -f /srv/opensim/fsassets/data
readlink -f /srv/opensim/fsassets/tmp
findmnt -T /srv/opensim/fsassets/data -o TARGET,SOURCE,FSTYPE,OPTIONS
findmnt -T /srv/opensim/fsassets/tmp -o TARGET,SOURCE,FSTYPE,OPTIONS

Paramètres à comprendre

FallbackService est un service source interrogé lorsqu’un asset manque : il peut permettre une transition contrôlée depuis l’ancien stockage. Realm définit la table logique des métadonnées (fsassets par défaut). StorageProvider et ConnectionString, si absents de [AssetService], proviennent de [DatabaseService]. DaysBetweenAccessTimeUpdates limite les mises à jour d’accès SQL. ShowConsoleStats gère les statistiques. SecondaryInstance est réservé à des architectures multi-instances maîtrisées.

Arborescence et UseOsgridFormat

Le format standard répartit le hash par préfixes de 2, 2, 2 et 4 caractères ; UseOsgridFormat=true emploie deux niveaux de 3 caractères. Une modification de ce réglage sur une base existante change le chemin attendu des assets et peut les rendre introuvables. Ne modifiez jamais ce paramètre sans procédure de migration vérifiée.

Hash, UUID et déduplication

Le code utilise le hash du contenu pour déterminer le fichier de destination et l’UUID pour les métadonnées en SQL. Plusieurs UUID peuvent ainsi désigner le même contenu ; le nombre de lignes SQL n’est pas forcément égal au nombre de fichiers. Le nom d’un fichier final est dérivé du hash, pas de l’UUID.

Commandes console disponibles

Le connecteur enregistre show assets, show digest <ID>, delete asset <ID>, import et force import. Les deux premières sont utilisables pour diagnostic ; delete asset et force import modifient les métadonnées ou écrasent du contenu : ne les utilisez pas comme tests. Ces commandes existent sur la console où le connecteur FSAssets est chargé.

Exemple à adapter : ne jamais appliquer aveuglément en production.

show assets
show digest 00000000-0000-0000-0000-000000000000

Relation avec Hypergrid

Le fork dispose aussi de HGFSAssetService. Ce n’est pas un remplacement automatique de FSAssetConnector : les règles de transfert, permissions et identités externes sont spécifiques à Hypergrid. Vérifiez le connecteur HG configuré dans ROBUST avant d’activer un service différent.

Vérifier le bon fonctionnement de FSAssets

La présence du message FS asset service enabled confirme le chargement du module, mais pas l’intégrité de tous les assets. Vérifiez l’écriture d’un nouvel asset, sa lecture après redémarrage, l’absence d’erreurs de spool et le résultat dans le viewer. N’utilisez jamais une seule texture comme test exhaustif.

Continuer la lecture

Code source et documentation