Respaldo y restauración del servidor Gitea
Copia de seguridad y restauración de Gitea: la forma correcta
Las copias de seguridad de Gitea tocan tres componentes en movimiento: la base de datos, los repositorios git y los archivos de la aplicación. Desde 2024, el comando integrado gitea dump maneja todo esto de una sola vez.
En la publicación Probando Gitea, instalamos el servidor Gitea. Este es el seguimiento: cómo hacer la copia de seguridad de manera práctica y, lo que es más importante, cómo restaurarla cuando algo sale mal.
Para la colección completa de herramientas de desarrollo, que incluye flujos de trabajo de Git y gestión de Docker, consulte Herramientas de Desarrollo: La guía completa para flujos de trabajo de desarrollo moderno.
Si está configurando Gitea por primera vez, eche un vistazo a Elegir un servidor git autoalojado gratuito: ¡Gitea es el ganador! para los detalles de instalación, y a Gitea SSL con Apache como proxy inverso para una implementación segura.
Cuándo practicar esto
Ahora, simplemente como precaución contra cosas terribles, es un buen momento para ensayar el procedimiento de copia de seguridad y restauración: antes de que realmente lo necesite, no después de que un disco falle.
Más vale prevenir que curar.
Dónde residen los datos
Una instancia de Gitea es realmente tres componentes que deben mantenerse sincronizados:
- código (repositorios git)
- almacén de archivos (adjuntos, avatares, objetos LFS, indexadores)
- base de datos (usuarios, issues, PRs, configuraciones)
En nuestro entorno de prueba, juntos ocupan un poco más de 700MB:
Dado que estas tres piezas se hacen referencia entre sí, la documentación propia de Gitea es explícita sobre la consistencia de la copia de seguridad: la instancia debe detenerse durante la duración de la copia de seguridad, de lo contrario, un repositorio copiado a mitad de una migración puede terminar desincronizado con lo que la base de datos cree que ha sucedido. La restauración, por la misma razón, también debe ocurrir como una única transacción.
La forma fácil: gitea dump
Esta es la parte que ha cambiado desde la versión anterior de este artículo: en lugar de manejar pg_dump, tar y carpetas separadas a mano, Gitea incluye un único comando dump que agrupa la base de datos, los repositorios, los datos LFS, los adjuntos y la configuración en un solo archivo.
gitea dump -c /path/to/app.ini
Esto produce un archivo con marca de tiempo como gitea-dump-1610949662.zip que contiene:
app.ini- copia del archivo de configuracióncustom/- personalizaciones bajocustom/data/- adjuntos, avatares, objetos LFS, indexadores (y el archivo SQLite, si esa es su base de datos)repos/- copia completa del directorio de repositoriosgitea-db.sql- volcado SQL de la base de datoslog/- registros (no necesarios para la restauración)
Banderas útiles que vale la pena conocer:
--file name/-f name- nombre del archivo de salida (-para stdout, práctico para enviar directamente ascpo almacenamiento de objetos)--type- formato de salida:zip(predeterminado),tar,tar.gz,tar.xz,tar.zst, etc.--database/-d- fuerza el dialecto SQL engitea-db.sql(sqlite3,mysql,mssql,postgres): útil al migrar entre motores de base de datos--skip-repository/-R,--skip-lfs-data,--skip-attachment-data,--skip-package-data,--skip-log,--skip-db- reduce el volcado a solo lo que necesita--tempdir/-t- dónde se preparan los archivos intermedios (predeterminado/tmpo$TMPDIR): asegúrese de que tenga suficiente espacio libre para toda la instancia
Ejecutar gitea dump en Docker
Dado que la mayoría de las instalaciones autoalojadas ejecutan Gitea mediante docker-compose, el comando debe ejecutarse dentro del contenedor, como el usuario git, desde el directorio temporal del contenedor:
cd ~/gitea-srv-local
# crear un volcado dentro del contenedor en ejecución
sudo docker exec -u git -it -w /tmp gitea bash -c \
'/usr/local/bin/gitea dump -c /data/gitea/conf/app.ini'
# copiar el zip resultante fuera del contenedor
sudo docker cp gitea:/tmp/gitea-dump-*.zip ./gitea-backups/
-w /tmp es importante: dump necesita escribir y comprimir su directorio de trabajo temporal, y ejecutarlo en cualquier lugar sin permisos de escritura fallará con un error de permisos.
Luego, como antes, lleve el archivo fuera de la máquina:
scp uname@gitea-srv-ip-addr:~/gitea-srv-local/gitea-backups/gitea-dump-*.zip ~/gitea-backups/
Si prefiere volcar la base de datos con herramientas nativas (la documentación de Gitea recomienda esto para MySQL/PostgreSQL, ya que el volcado SQL basado en XORM dentro de gitea dump tiene casos límite conocidos en la restauración), aún puede hacerlo en paralelo:
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'
Consulte la Hojas de referencia de PostgreSQL para más opciones de pg_dump/pg_restore, y la Hojas de referencia de Docker Compose si alguna de la sintaxis docker exec/docker cp anterior le parece unfamiliar.
Cómo - Restauración
Aún no hay una restauración con un solo comando; la documentación de Gitea es abierta en decir que esto sigue siendo un proceso manual de mover los archivos de vuelta a su lugar y restaurar el volcado de la base de datos. ¡Pero! Siempre revise la documentación original primero, ya que las rutas y los diseños de contenedores cambian entre versiones.
# instalar/iniciar un gitea nuevo (misma versión que la copia de seguridad) y luego detenerlo
sudo docker-compose down
# descomprimir el volcado
unzip gitea-dump-1610949662.zip -d gitea-restore
cd gitea-restore
# restaurar repositorios y datos en los volúmenes que usa gitea
sudo cp -r repos/* ../gitea/git/
sudo cp -r data/* ../gitea/gitea/
sudo chown -R 1000:1000 ../gitea/git ../gitea/gitea
# subir gitea de nuevo
sudo docker-compose up -d
# restaurar la base de datos
sudo docker exec -i gitea-srv-local_db_1 psql -U gitea gitea < gitea-db.sql
Si volcó la base de datos por separado con pg_dump/pg_restore, restaure ese volcado de la misma manera que haría para cualquier otra instancia de Postgres; consulte la Hojas de referencia de PostgreSQL para los comandos exactos.
Regenerar hooks después de la restauración
Si restauró a un método de instalación diferente (binario vs Docker) o a una ruta diferente, los git hooks integrados en cada repositorio aún apuntarán a las rutas antiguas. Corrija eso con:
sudo docker exec -u git -it gitea bash -c '/usr/local/bin/gitea admin regenerate hooks'
Omitir este paso es la causa clásica de que push falle justo después de una restauración sin ningún error obvio en la interfaz.
Verificar la restauración
Antes de considerar terminado:
- Inicie sesión en la interfaz y confirme que los usuarios, issues y configuraciones se vean correctos.
- Clonar un repositorio y hacer un push de un commit trivial para confirmar que los hooks funcionan.
- Ejecute
gitea doctor check(añada--fixsi marca algo) para detectar desajustes de ruta o permisos temprano.
Restaurando un solo repositorio: restore-repo
Otra pieza genuinamente nueva desde la última versión de este artículo es un par de comandos para copia de seguridad y restauración a nivel de repositorio, separados del flujo de trabajo de dump/restauración de toda la instancia anterior. Son prácticos cuando solo necesita recuperar un proyecto; por ejemplo, si alguien eliminó forzosamente un repositorio, en lugar de revertir todo el servidor.
dump-repo extrae un solo repositorio (más, opcionalmente, sus issues, PRs, wiki y otros metadatos) a un directorio 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 luego reproduce ese directorio de vuelta en una instancia, en un owner/repo elegido:
gitea restore-repo \
--repo_dir /backup/repos/owner/repo \
--owner_name owner \
--repo_name repo \
--units issues,labels,milestones,pull_requests,comments
Ambas listas --units son opcionales; omítalas y todo lo soportado será migrado. Este par es realmente una herramienta de migración en su núcleo (también funciona contra GitHub/GitLab como fuente mediante --git_service), pero funciona bien como una alternativa ligera, por repositorio, a un gitea dump completo cuando una restauración completa sería un exceso.
Automatización
Un volcado diario más una copia fuera de la máquina es una tarea de cron de dos líneas una vez que los pasos manuales anteriores funcionan:
# /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
Combínelo con una limpieza de retención (find ~/gitea-backups -mtime +14 -delete) y una copia en otro sitio vía scp/rsync para que una falla de un solo host no lleve las copias de seguridad consigo.
Solución de problemas
permission denieddurantedump- no está ejecutando como el usuariogit, o--tempdir/-wapunta a un directorio al que el usuario del contenedor no puede escribir.- La restauración tiene éxito pero
git pushfalla - los hooks no se regendaron; ejecutegitea admin regenerate hooks. - Errores de restauración de base de datos en una instancia grande - prefiera
pg_dump/mysqldumpnativos sobre el SQL incrustado en el zip degitea dump; se sabe que tiene aristas en la restauración para esquemas grandes o inusuales. - Restaurado a una nueva versión principal - ejecute
gitea doctor check --all --fixy revise las notas de lanzamiento para los pasos de migración de esa versión antes de suponer que la restauración está completa.
Para referencia rápida sobre comandos de Git, consulte Hojas de referencia de GIT: Los comandos GIT más útiles.
