Sauvegarde et restauration du serveur Gitea
Sauvegarde et restauration de Gitea, la bonne manière
Les sauvegardes de Gitea touchent trois éléments en mouvement — la base de données, les dépôts git et les fichiers de l’application — et depuis 2024, la commande intégrée gitea dump gère tous ces éléments d’un coup.
Dans l’article Test de Gitea, nous avons installé le serveur gitea. Voici la suite : comment réellement le sauvegarder et, plus important encore, le restaurer lorsque quelque chose se passe mal.
Pour la collection complète des outils de développement incluant les flux de travail Git et la gestion Docker, consultez Outils de développement : Le guide complet des flux de travail de développement modernes.
Si vous installez Gitea pour la première fois, consultez Choisir un serveur git libre auto-hébergé - Gitea est le gagnant ! pour les détails d’installation, et Gitea SSL avec Apache en tant que proxy inversé pour un déploiement sécurisé.
Quand réhearser cette procédure
Maintenant, tout simplement comme précaution contre des événements désastreux, est un bon moment pour réhearser la procédure de sauvegarde et de restauration - avant d’en avoir réellement besoin, et non après qu’un disque ait défailli.
Mieux vaut être prudent que de le regretter.
Où se trouvent les données
Une instance Gitea est réellement composée de trois composants qui doivent tous rester synchronisés :
- le code (dépôts git)
- le stockage de fichiers (pièces jointes, avatars, objets LFS, indexeurs)
- la base de données (utilisateurs, problèmes, PR, paramètres)
Dans notre environnement de test, pris ensemble, ils prennent un peu plus de 700 Mo :
Étant donné que ces trois éléments se référencent mutuellement, la documentation officielle de Gitea est explicite sur la cohérence de la sauvegarde : l’instance doit être arrêtée pendant toute la durée de la sauvegarde, sinon un dépôt copié en plein milieu d’une migration peut finir désynchronisé par rapport à ce que la base de données considère comme ayant eu lieu. La restauration, pour la même raison, doit également se faire en une seule transaction.
La méthode simple - gitea dump
C’est la partie qui a changé par rapport à la version précédente de cet article : au lieu de jongler manuellement avec pg_dump, tar et des dossiers séparés, Gitea fournit une commande dump unique qui regroupe la base de données, les dépôts, les données LFS, les pièces jointes et la configuration dans une seule archive.
gitea dump -c /path/to/app.ini
Cela produit un fichier horodaté comme gitea-dump-1610949662.zip contenant :
app.ini- copie du fichier de configurationcustom/- personnalisations souscustom/data/- pièces jointes, avatars, objets LFS, indexeurs (et le fichier SQLite, si c’est votre base de données)repos/- copie complète du répertoire des dépôtsgitea-db.sql- décharge SQL de la base de donnéeslog/- journaux (non nécessaires pour la restauration)
Des options utiles à connaître :
--file name/-f name- nom du fichier de sortie (-pour la sortie standard, pratique pour rediriger directement versscpou le stockage d’objets)--type- format de sortie :zip(par défaut),tar,tar.gz,tar.xz,tar.zst, etc.--database/-d- force le dialecte SQL dansgitea-db.sql(sqlite3,mysql,mssql,postgres) - utile lors de la migration entre moteurs de base de données--skip-repository/-R,--skip-lfs-data,--skip-attachment-data,--skip-package-data,--skip-log,--skip-db- réduit la décharge à seulement ce dont vous avez besoin--tempdir/-t- l’endroit où les fichiers intermédiaires sont stockés (par défaut/tmpou$TMPDIR) - assurez-vous qu’il y a assez d’espace libre pour l’instance entière
Exécution de gitea dump sous Docker
La plupart des installations auto-hébergées exécutent Gitea via docker-compose, la commande doit donc être exécutée à l’intérieur du conteneur, en tant qu’utilisateur git, depuis le répertoire temporaire du conteneur :
cd ~/gitea-srv-local
# créer une décharge dans le conteneur en cours d'exécution
sudo docker exec -u git -it -w /tmp gitea bash -c \
'/usr/local/bin/gitea dump -c /data/gitea/conf/app.ini'
# copier le zip résultant hors du conteneur
sudo docker cp gitea:/tmp/gitea-dump-*.zip ./gitea-backups/
-w /tmp est important : dump doit écrire et archiver son répertoire de travail temporaire, et son exécution dans un emplacement sans permissions d’écriture échouera avec une erreur de permission.
Ensuite, comme précédemment, récupérez l’archive depuis la machine :
scp uname@gitea-srv-ip-addr:~/gitea-srv-local/gitea-backups/gitea-dump-*.zip ~/gitea-backups/
Si vous préférez décharger la base de données avec les outils natifs (la documentation de Gitea recommande cela pour MySQL/PostgreSQL, étant donné que la décharge SQL basée sur XORM dans gitea dump présente des cas limites connus lors de la restauration), vous pouvez toujours le faire en parallèle :
sudo docker exec -t gitea-srv-local_db_1 bash -c \
'pg_dump gitea -U gitea --file=/var/lib/postgresql/backups/gitea-db-$(date +%Y-%m-%d).sql'
Consultez l’Aide-mémoire PostgreSQL pour plus d’options pg_dump/pg_restore, et l’Aide-mémoire Docker Compose si la syntaxe docker exec/docker cp ci-dessus vous est familière.
Comment - Restaurer
Il n’y a toujours pas de commande unique de restauration - la documentation de Gitea est franche à ce sujet : il s’agit encore d’un processus manuel consistant à replacer les fichiers à leur place et à restaurer la décharge de la base de données. Mais ! Vérifiez toujours d’abord la documentation originale, car les chemins et les structures de conteneurs changent entre les versions.
# installer/démarrer un gitea neuf (même version que la sauvegarde) puis l'arrêter
sudo docker-compose down
# dézipper la décharge
unzip gitea-dump-1610949662.zip -d gitea-restore
cd gitea-restore
# restaurer les dépôts et les données dans les volumes utilisés par gitea
sudo cp -r repos/* ../gitea/git/
sudo cp -r data/* ../gitea/gitea/
sudo chown -R 1000:1000 ../gitea/git ../gitea/gitea
# redémarrer gitea
sudo docker-compose up -d
# restaurer la base de données
sudo docker exec -i gitea-srv-local_db_1 psql -U gitea gitea < gitea-db.sql
Si vous avez déchargé la base de données séparément avec pg_dump/pg_restore, restaurez cette décharge de la même manière que pour n’importe quelle autre instance Postgres - consultez l’Aide-mémoire PostgreSQL pour les commandes exactes.
Régénérer les hooks après la restauration
Si vous avez restauré vers une méthode d’installation différente (binaire vs Docker) ou un chemin différent, les git hooks intégrés dans chaque dépôt pointeront toujours vers les anciens chemins. Corrigez cela avec :
sudo docker exec -u git -it gitea bash -c '/usr/local/bin/gitea admin regenerate hooks'
Ignorer cette étape est la cause classique d’un échec de push juste après une restauration, sans erreur évidente dans l’interface.
Vérifier la restauration
Avant de considérer le travail comme terminé :
- Connectez-vous à l’interface et confirmez que les utilisateurs, les problèmes et les paramètres sont corrects.
- Clonez un dépôt et poussez un commit trivial pour confirmer que les hooks fonctionnent.
- Exécutez
gitea doctor check(ajoutez--fixsi quelque chose est signalé) pour détecter tôt les incohérences de chemin ou de permissions.
Restaurer un dépôt unique - restore-repo
L’autre élément véritablement nouveau depuis la dernière version de cet article est une paire de commandes pour la sauvegarde et la restauration au niveau des dépôts, distincte du flux de travail dump/restauration complet ci-dessus. Elles sont pratiques lorsque vous n’avez besoin de récupérer qu’un seul projet - par exemple, si quelqu’un a forcé la suppression d’un dépôt - au lieu de revenir en arrière sur tout le serveur.
dump-repo extrait un dépôt unique (plus, en option, ses problèmes, PR, wiki et autres métadonnées) vers un répertoire local :
gitea dump-repo \
--git_service gitea \
--clone_addr https://gitea.example.com/owner/repo.git \
--auth_token <token> \
--repo_dir /backup/repos/owner/repo \
--units wiki,issues,labels,releases,milestones,pull_requests,comments
restore-repo rejoue ensuite ce répertoire dans une instance, vers un propriétaire/dépôt choisi :
gitea restore-repo \
--repo_dir /backup/repos/owner/repo \
--owner_name owner \
--repo_name repo \
--units issues,labels,milestones,pull_requests,comments
Les deux listes --units sont optionnelles - omettez-les et tout ce qui est pris en charge sera migré. Cette paire est en réalité un outil de migration (il fonctionne également contre GitHub/GitLab comme source via --git_service), mais il sert également bien d’alternative légère, par dépôt, à une gitea dump complète lorsqu’une restauration complète serait exagérée.
L’automatiser
Une décharge quotidienne plus une copie hors de la machine est un travail cron de deux lignes une fois que les étapes manuelles ci-dessus fonctionnent :
# /etc/cron.d/gitea-backup
0 2 * * * root docker exec -u git -w /tmp gitea gitea dump -c /data/gitea/conf/app.ini -f - > /home/uname/gitea-backups/gitea-dump-$(date +\%F).zip 2>> /var/log/gitea-backup.log
Associez-le à un nettoyage de rétention (find ~/gitea-backups -mtime +14 -delete) et à une copie hors-site via scp/rsync pour qu’une défaillance sur un seul hôte n’emporte pas les sauvegardes avec elle.
Dépannage
permission deniedpendantdump- vous n’exécutez pas en tant qu’utilisateurgit, ou--tempdir/-wpointe vers un répertoire que l’utilisateur du conteneur ne peut pas écrire.- La restauration réussit mais
git pushéchoue - les hooks n’ont pas été régénérés ; exécutezgitea admin regenerate hooks. - Erreurs de restauration de la base de données sur une grande instance - préférez les outils natifs
pg_dump/mysqldumpau SQL intégré au zip degitea dump; il est connu pour avoir des bords rugueux lors de la restauration pour les schémas volumineux ou inhabituels. - Restauré vers une nouvelle version majeure - exécutez
gitea doctor check --all --fixet vérifiez les notes de version pour les étapes de migration de cette version avant de supposer que la restauration est complète.
Pour référence rapide sur les commandes Git, consultez Aide-mémoire GIT : Les commandes GIT les plus utiles.
