OpenSimulator · FR

FSAssets : migration, import et déplacement

Basculer depuis MySQL, déplacer le magasin vers un autre volume et préserver la cohérence SQL/fichiers.

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.

Avant toute migration : inventaire et retour arrière

Répertoriez la version exacte, les fichiers INI réellement chargés, le service d’assets actif, la base SQL d’origine, le nombre d’assets et la capacité disque/inodes. Faites un dump cohérent de la base, une copie fiable des fichiers et un test sur une instance hors production. Ne migrez pas en improvisant sur la seule grille disponible.

Migration depuis la table d’assets historique

Le module expose les commandes import et force import dans sa console ; la migration peut aussi utiliser FallbackService pour récupérer un asset absent à la demande. Ces mécanismes ne sont pas interchangeables et une migration en production doit être testée. Import accepte un paramètre de connexion et une table, avec options start/count : une erreur de source/table peut importer les mauvaises données.

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

# Syntaxe de référence du connecteur FSAssets (ne pas exécuter en aveugle)
import <connection-string> <legacy-table> [<start> <count>]
# DANGEREUX : force import peut écraser le contenu existant
force import <connection-string> <legacy-table> [<start> <count>]

Attention aux identifiants SQL dans les commandes

Un mot de passe inclus dans une commande console peut apparaître dans l’historique, les logs ou les captures d’écran. Utilisez un compte de migration à droits minimaux et des mesures de confidentialité adaptées. Ne publiez jamais la chaîne de connexion dans un ticket public.

FallbackService et migration paresseuse

Lorsque les métadonnées ou le fichier FSAssets manquent, le code peut interroger FallbackService ; si le contenu existe, il est ajouté localement. Cette migration à la demande ne prouve pas que tous les anciens assets ont été convertis : les assets jamais demandés peuvent rester uniquement dans l’ancien service. Ne retirez pas l’ancien backend sans vérification exhaustive.

Déplacer le stockage vers un autre disque

Procédure recommandée : sauvegarde complète, préparation du nouveau système de fichiers, contrôle des inodes, premier transfert de pré-copie, arrêt contrôlé du service d’écriture, copie finale y compris spool, validation des droits et montages, modification du fichier INI actif, puis redémarrage et tests. Ne modifiez pas seulement BaseDirectory en laissant SpoolDirectory sur l’ancien volume.

Pré-copie avec rsync

Copiez les deux arbres vers un nouveau répertoire en conservant permissions, dates et liens. Le premier rsync peut s’exécuter en ligne mais n’est pas une sauvegarde cohérente ; les fichiers peuvent changer pendant la copie. N’ajoutez pas --delete tant que source, destination et plan de reprise n’ont pas été validés.

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

# EXEMPLES : chemins fictifs, sans --delete
sudo rsync -aHAX --numeric-ids --info=progress2 /ancien/fsassets/data/ /nouveau/fsassets/data/
sudo rsync -aHAX --numeric-ids --info=progress2 /ancien/fsassets/tmp/ /nouveau/fsassets/tmp/
# Répéter après arrêt contrôlé de ROBUST pour finaliser

Pré-copie progressive, simulation et bascule finale

Pendant la copie initiale, une priorité faible peut réduire les effets sur les performances : nice -n 19 ionice -c2 -n7. Utilisez screen pour maintenir la copie après une déconnexion SSH et rsync --dry-run pour prévisualiser les différences. Après arrêt de tous les écrivains FSAssets, une dernière synchronisation réconcilie les fichiers. Le temps d’arrêt dépend des écarts restants et n’est pas garanti ; ne basculez jamais sans vérification du montage, du spool et des métadonnées SQL.

Exemples de chemins fictifs : adapter les deux répertoires et la stratégie SQL/spool.

nice -n 19 ionice -c2 -n7 rsync -a --info=progress2 /srv/opensim/fsassets/ /mnt/newdisk/fsassets/
rsync -a --dry-run --itemize-changes /srv/opensim/fsassets/ /mnt/newdisk/fsassets/
# Après arrêt contrôlé de tous les écrivains :
rsync -a --info=progress2 /srv/opensim/fsassets/ /mnt/newdisk/fsassets/

N’utilisez --delete sur une destination qu’après avoir validé les chemins et vérifié une simulation avec --dry-run ; il n’est pas requis pour toutes les migrations et ne remplace pas une sauvegarde distincte. Conservez l’ancien dossier pendant la vérification et ne le supprimez pas immédiatement.

Guide complet : rsync à chaud, screen et dry-run

Montage permanent et symlinks

Préférez un montage stable par UUID dans /etc/fstab et vérifiez findmnt avant démarrage. Un lien symbolique peut maintenir l’ancien chemin, mais ne protège pas contre un disque non monté : sans contrôle du montage, le processus risque d’écrire dans le répertoire vide du disque système. Une unité systemd peut utiliser RequiresMountsFor pour prévenir ce scénario.

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

lsblk -f
findmnt -T /nouveau/fsassets/data
readlink -f /nouveau/fsassets/data
# Vérifier les permissions sous l'identité réelle du service

Contrôles après bascule

Vérifiez l’absence d’erreurs [FSASSETS] dans Robust.log, le montage attendu, l’usage en inodes, show assets et show digest d’un UUID connu, puis la lecture de textures et objets depuis un viewer. Testez aussi la création d’un asset neuf et son accès après redémarrage. Conservez le stockage d’origine en lecture seule le temps de valider.

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

findmnt -T /nouveau/fsassets/data
df -h /nouveau/fsassets/data
df -i /nouveau/fsassets/data
grep -nEi '\[FSASSETS\]|IOException|No space left' /chemin/vers/Robust.log | tail -n 100

Pourquoi ne pas changer UseOsgridFormat durant la copie

Le format des chemins dérive du hash. Déplacer les fichiers sans changer cette option permet de conserver la même arborescence. Passer de false à true (ou l’inverse) sur des fichiers existants sans renommer les chemins les rendra introuvables. Traitez ce changement comme une migration distincte qui nécessite un utilitaire vérifié et une sauvegarde.

Éviter les bascules partielles

Une base FSAssets restaurée sans les fichiers correspondants crée des références cassées ; des fichiers restaurés sans leurs métadonnées ne seront pas retrouvés par UUID. Sauvegardez et restaurez un ensemble cohérent : SQL + data + spool + configurations + version applicative.

Continuer la lecture

Code source et documentation