2

Solución de Problemas

groales edited this page 2025-12-03 17:27:29 +01:00

Table of Contents

• Solución de Problemas
• 🔍 Herramientas de Diagnóstico
• Ver Logs
• Verificar Estado
• 🗄️ Problemas de Base de Datos
• "Database connection failed" en instalación
• PostgreSQL no inicia
• Error de migración
• 🌐 Problemas de Conectividad
• No puedo acceder a https://gitea.tudominio.com
• SSL/TLS errors
• 📥 Problemas con Git Operations
• No puedo hacer push/pull
• Push rechazado por tamaño
• 🔑 Problemas de Autenticación
• Olvidé contraseña de administrador
• No puedo iniciar sesión
• 📧 Problemas de Email
• Emails no se envían
• 💾 Problemas de Espacio
• Disco lleno
• Volumen corrupto
• ⚡ Problemas de Rendimiento
• Gitea muy lento
• 🔄 Problemas de Actualización
• Contenedor no inicia después de actualizar
• 🆘 Comandos de Emergencia
• Reiniciar Completamente
• Reiniciar TODO (CUIDADO)
• Acceder al Shell
• 📞 Obtener Ayuda

Solución de Problemas

Guía para resolver los problemas más comunes con Gitea.

🔍 Herramientas de Diagnóstico

Ver Logs

# Logs de Gitea en tiempo real
docker compose logs -f gitea

# Logs de PostgreSQL
docker compose logs -f gitea-db

# Últimas 100 líneas
docker compose logs --tail=100 gitea

# Logs dentro del contenedor
docker compose exec gitea cat /data/gitea/log/gitea.log

Verificar Estado

# Estado de contenedores
docker compose ps

# Recursos usados
docker stats gitea gitea-db

# Conectividad de redes
docker network inspect gitea-internal
docker network inspect proxy

# Espacio en disco
df -h
docker system df -v | grep gitea

🗄️ Problemas de Base de Datos

"Database connection failed" en instalación

Síntomas: Error al conectar con PostgreSQL durante el asistente

Causas posibles:

• PostgreSQL aún no está listo
• Contraseña incorrecta
• Configuración de red incorrecta

Soluciones:

# 1. Verificar que gitea-db está corriendo
docker compose ps gitea-db

# 2. Ver logs de PostgreSQL
docker compose logs gitea-db | tail -20

# 3. Verificar que están en la misma red
docker network inspect gitea-internal | grep -A 10 Containers

# 4. Probar conexión manualmente
docker compose exec gitea nc -zv gitea-db 5432

# 5. Verificar contraseña
docker compose exec gitea env | grep GITEA__database__PASSWD

# 6. Reiniciar PostgreSQL
docker compose restart gitea-db
sleep 10

# 7. Reintentar instalación

PostgreSQL no inicia

Síntomas: gitea-db en estado Exited o Restarting

Soluciones:

# Ver error específico
docker compose logs gitea-db | grep -i error

# Verificar permisos
docker compose exec gitea-db ls -la /var/lib/postgresql

# Si está corrupto, restaurar desde backup
docker compose down
docker volume rm gitea_db
docker volume create gitea_db
# Restaurar BD desde backup

Error de migración

Síntomas: Gitea no inicia después de actualizar, logs muestran migration error

Solución:

# 1. Volver a versión anterior
docker compose down
docker pull gitea/gitea:1.20.0  # Versión previa
# Editar compose para usar versión anterior
docker compose up -d

# 2. Restaurar BD desde backup
# (Ver página Backup y Restauración)

# 3. Intentar actualización nuevamente

🌐 Problemas de Conectividad

No puedo acceder a https://gitea.tudominio.com

Síntomas: Timeout o conexión rechazada

Soluciones para Traefik:

# 1. Verificar que Traefik está corriendo
docker ps | grep traefik

# 2. Verificar labels de Gitea
docker inspect gitea | grep -A 20 Labels

# 3. Ver logs de Traefik
docker logs traefik | grep gitea

# 4. Verificar que está en red proxy
docker network inspect proxy | grep gitea

# 5. Probar acceso directo al puerto 3000
curl http://localhost:3000

Soluciones para NPM:

# 1. Verificar Proxy Host en NPM
# Accede a NPM y revisa la configuración

# 2. Probar acceso directo
docker compose exec gitea curl localhost:3000

# 3. Verificar DNS
nslookup gitea.tudominio.com

# 4. Verificar que Gitea y NPM están en red proxy
docker network inspect proxy | grep -E "(gitea|npm)"

SSL/TLS errors

Síntomas: Certificado inválido o ERR_CERT_AUTHORITY_INVALID

Soluciones:

# Verificar certificado
echo | openssl s_client -connect gitea.tudominio.com:443 | grep -A 5 "Certificate chain"

# Para Traefik: verificar resolver
docker exec traefik cat /etc/traefik/traefik.yml | grep -A 10 certificatesResolvers

# Para NPM: regenerar certificado
# En NPM: Edit Proxy Host → SSL → Force SSL → Request New Certificate

📥 Problemas con Git Operations

No puedo hacer push/pull

Síntomas: fatal: unable to access o autenticación fallida

Soluciones:

# 1. Verificar URL del remoto
git remote -v

# 2. Probar con verbose
GIT_CURL_VERBOSE=1 git push origin main

# 3. Verificar credenciales
git config credential.helper

# 4. Limpiar cache de credenciales
git credential-cache exit

# 5. Verificar URL base en Gitea
docker compose exec gitea cat /data/gitea/conf/app.ini | grep ROOT_URL

Push rechazado por tamaño

Síntomas: error: RPC failed; HTTP 413

Solución:

Edita app.ini:

[repository.upload]
FILE_MAX_SIZE = 100  # En MB

Reinicia:

docker compose restart gitea

🔑 Problemas de Autenticación

Olvidé contraseña de administrador

Solución:

# Cambiar contraseña desde línea de comandos
docker compose exec gitea gitea admin user change-password \
  --username admin \
  --password nueva_password_segura

No puedo iniciar sesión

Síntomas: Credenciales correctas pero login falla

Soluciones:

# 1. Verificar que el usuario existe
docker compose exec gitea gitea admin user list

# 2. Ver logs durante el intento de login
docker compose logs -f gitea

# 3. Verificar sesiones
docker compose exec gitea-db psql -U gitea -c "SELECT * FROM session LIMIT 5;"

# 4. Limpiar sesiones antiguas
docker compose exec gitea-db psql -U gitea -c "DELETE FROM session WHERE expiry < NOW();"

📧 Problemas de Email

Emails no se envían

Síntomas: No llegan notificaciones

Soluciones:

# 1. Verificar configuración SMTP en app.ini
docker compose exec gitea cat /data/gitea/conf/app.ini | grep -A 10 "\[mailer\]"

# 2. Probar envío desde Gitea
# Site Administration → Configuration → Send Testing Email

# 3. Ver logs de error
docker compose logs gitea | grep -i mail

# 4. Verificar conectividad SMTP
docker compose exec gitea nc -zv smtp.tudominio.com 587

💾 Problemas de Espacio

Disco lleno

Síntomas: Gitea lento, errores al hacer push

Soluciones:

# 1. Ver espacio usado
df -h
docker system df -v

# 2. Limpiar logs antiguos
docker compose exec gitea find /data/gitea/log -name "*.log" -mtime +30 -delete

# 3. Limpiar imágenes Docker sin usar
docker image prune -a

# 4. Limpiar volúmenes huérfanos
docker volume prune

# 5. Ver tamaño de repositorios
docker compose exec gitea du -sh /data/git/repositories/*

Volumen corrupto

Síntomas: Errores de I/O, contenedor no inicia

Solución drástica:

# 1. HACER BACKUP SI ES POSIBLE
docker compose exec gitea tar czf /tmp/backup.tar.gz /data

# 2. Copiar backup fuera del contenedor
docker cp gitea:/tmp/backup.tar.gz ./

# 3. Recrear volumen
docker compose down
docker volume rm gitea_data
docker volume create gitea_data

# 4. Restaurar desde backup
docker run --rm -v gitea_data:/data -v $(pwd):/backup alpine \
  sh -c "cd /data && tar xzf /backup/backup.tar.gz --strip-components=1"

# 5. Reiniciar
docker compose up -d

⚡ Problemas de Rendimiento

Gitea muy lento

Síntomas: Interfaz web tarda mucho, git operations lentas

Soluciones:

# 1. Verificar recursos
docker stats gitea gitea-db

# 2. Ver procesos dentro de Gitea
docker compose exec gitea top

# 3. Optimizar PostgreSQL
# Editar compose, añadir a gitea-db:
command: postgres -c shared_buffers=256MB -c max_connections=200

# 4. Ver queries lentas en PostgreSQL
docker compose exec gitea-db psql -U gitea -c "
SELECT query, calls, total_time, mean_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;"

# 5. Verificar disco
iostat -x 5

🔄 Problemas de Actualización

Contenedor no inicia después de actualizar

Soluciones:

# 1. Ver logs de error
docker compose logs gitea | grep -i error

# 2. Volver a versión anterior
docker compose down
# Editar compose: image: gitea/gitea:VERSION_ANTERIOR
docker compose up -d

# 3. Si persiste, restaurar desde backup
# (Ver página Backup y Restauración)

🆘 Comandos de Emergencia

Reiniciar Completamente

# Reinicio completo manteniendo datos
docker compose restart

# Recrear contenedores manteniendo volúmenes
docker compose down
docker compose up -d

# Forzar recreación
docker compose up -d --force-recreate

Reiniciar TODO (CUIDADO)

# ⚠️ ESTO ELIMINA TODOS LOS DATOS
docker compose down -v
docker compose up -d

# Tendrás que:
# 1. Pasar por el asistente de instalación nuevamente
# 2. Restaurar desde backup

Acceder al Shell

# Shell de Gitea
docker compose exec gitea bash

# Shell de PostgreSQL
docker compose exec gitea-db bash

# Ejecutar comando sin shell interactivo
docker compose exec gitea ls -la /data/gitea

📞 Obtener Ayuda

Si ninguna solución funciona:

1. Recopila información:

   docker compose logs > logs.txt
   docker compose ps > ps.txt
   docker inspect gitea > inspect.txt
   

2. Consulta recursos:

   • Gitea Documentation
   • Gitea Discourse
   • GitHub Issues

3. Abre un issue con:

   • Versión de Gitea (gitea --version)
   • Logs relevantes
   • Pasos para reproducir
   • Configuración (sin contraseñas)

---

Volver a: Home

📚 Wiki de Gitea

Inicio

• 🏠 Home

🚀 Despliegue

• Traefik
• Nginx Proxy Manager

⚙️ Configuración

• Configuración Inicial
• Personalización

🔧 Mantenimiento

• Backup y Restauración
• Actualización
• Solución de Problemas

---

📖 Enlaces Útiles

• 📦 Repositorio
• 📝 README
• 🌐 Gitea Docs
• 💬 Gitea Discourse

---

Última actualización: Diciembre 2025