docs Registros de auditoría
Registros de auditoría
Un registro a nivel de instancia de quién hizo qué, conservado durante un número configurable de días.
Qué se registra
Se registran las acciones que los usuarios realizan en el panel o a través de la API (los despliegues lanzados automáticamente por webhooks de Git no), agrupadas por área:
| Área | Acciones |
|---|---|
| Autenticación | inicio de sesión, cierre de sesión, registro, cambio de contraseña, actualización de perfil |
| Proyectos y miembros | crear, actualizar, actualizar la página de estado, eliminar; añadir miembro, cambiar rol, eliminar miembro |
| Aplicaciones | crear, actualizar, eliminar, desplegar (incluidos los rollbacks), iniciar, detener, cambios de variables de entorno, añadir/quitar dominio, mantenimiento activado/desactivado |
| Bases de datos | crear, eliminar, iniciar, detener, backup, restauración, cambios en la configuración de backups |
| Stacks de Compose | crear, actualizar, eliminar, desplegar, iniciar, detener, reiniciar, cambios de variables de entorno, añadir/quitar dominio |
| Tareas programadas | crear, actualizar, eliminar, ejecutar ahora, comando puntual |
| Servidores de juegos | crear, actualizar, iniciar, detener, reiniciar, eliminar, comandos de consola, escribir/subir/eliminar/renombrar archivos y crear carpetas, backups y restauraciones, cambios de mods |
| Instancia | usuarios, servidores, claves SSH, canales de notificación, GitHub App (crear, eliminar, sincronizar), exportación/importación de configuración, ajustes de la instancia |
Los valores secretos nunca se escriben en el registro: al cambiar un ajuste de la instancia se guarda el nombre de la clave, no su valor, y una exportación de configuración registra el alcance y si se incluyeron los secretos.
Detalles del registro
Cada entrada incluye:
- Usuario: el ID y el email del usuario en el momento de la acción
- Acción: p. ej. application.deploy o database.restore
- Recurso: tipo, ID y nombre de lo que se vio afectado
- Metadatos: contexto adicional en JSON (p. ej. el dominio añadido, el archivo de backup restaurado)
- Dirección IP de la petición
- Marca de tiempo
Las entradas no están vinculadas a registros activos, por lo que sobreviven a la eliminación del usuario o del recurso al que se refieren: el email y el nombre del recurso almacenados siguen siendo legibles.
Consulta y filtrado
La página Audit Log solo está disponible para los Admins globales, ya que abarca todos los proyectos. Muestra el recuento de eventos de las últimas 24 horas y los últimos 7 días, y los despliegues de los últimos 7 días, y permite buscar por usuario, recurso o acción, filtrar por tipo de recurso y acción, y expandir una entrada para ver sus metadatos. Los resultados están paginados, con 50 por página.
IPs de cliente: la IP se obtiene de X-Forwarded-For solo cuando TRUST_PROXY=true; en caso contrario se registra la dirección del peer directo, que detrás de Traefik es el propio proxy. Actívalo únicamente detrás de un proxy de confianza, o los clientes podrían escribir en el registro la IP que quisieran. El docker-compose.prod.yml por defecto no pasa esta variable al contenedor de la API: añádela al bloque environment del servicio api.
Retención y limpieza
Una vez al día, alrededor de las 04:00 hora del servidor, se eliminan las entradas con más antigüedad que AUDIT_RETENTION_DAYS (por defecto: 90). El valor se lee al iniciar la API. Con el docker-compose.prod.yml por defecto, definirlo solo en .env no tiene efecto: añade AUDIT_RETENTION_DAYS: ${AUDIT_RETENTION_DAYS:-90} al entorno del servicio api y recrea el contenedor.