Cliente: Centrica Soluciones
Proyecto: Nebula ERP — Componente Nebula Vault (DataVault)
Version: 1.0
Fecha: 20 de Abril, 2026
Autor: Carlos Alberto Torres Camargo — Arquitecto de Software
Clasificacion: Uso Interno — Equipo de Desarrollo y Operaciones
Guia de procedimientos para monitoreo, revision y diagnostico del servidor OAIS desplegado en nodo-01 (10.120.0.2). Documenta los comandos, scripts y rutas que el equipo utiliza para verificar el estado del sistema, revisar logs, inspeccionar carpetas del repositorio y ejecutar tareas de mantenimiento.
# Desde equipo con VPN activa (configuracion en ~/.ssh/config)
ssh nodo-01
# Equivalente manual
ssh -p 2202 sysadmin@nebula.centricasoluciones.com -i ~/.ssh/id_ed25519
| Parametro | Valor |
|---|---|
| Host | nebula.centricasoluciones.com |
| Puerto SSH | 2202 |
| Usuario | sysadmin |
| Clave | ~/.ssh/id_ed25519 |
| IP interna | 10.120.0.2 |
| Red Docker | dev-network |
| Ruta en host | Descripcion |
|---|---|
/home/sysadmin/docker/compose/datavault/ |
Docker Compose y configuracion |
/home/sysadmin/docker/compose/datavault/oais/ |
Codigo fuente OAIS, scripts, .env |
/home/sysadmin/docker/compose/datavault/oais/datavault/ |
Aplicacion Python (bind mount en contenedores) |
/home/sysadmin/docker/compose/datavault/oais/watcher.log |
Log del watcher en host |
Ruta en contenedores (volumen oais-repositorio) |
Descripcion |
|---|---|
/home/egs/datavault/Repositorio/ |
Raiz del repositorio OAIS |
/home/egs/datavault/Repositorio/ingest_sip/ |
Staging — archivos pendientes de procesamiento |
/home/egs/datavault/Repositorio/_procesados/ |
SIPs procesados exitosamente |
/home/egs/datavault/Repositorio/_errores/ |
SIPs que fallaron en procesamiento |
/home/egs/datavault/Repositorio/{PROYECTO}/SIP/ |
Paquetes de envio por proyecto |
/home/egs/datavault/Repositorio/{PROYECTO}/AIP/ |
Paquetes archivisticos por proyecto |
/home/egs/datavault/Repositorio/{PROYECTO}/DIP/ |
Paquetes de distribucion por proyecto |
| Contenedor | Imagen | Funcion | Estado Esperado |
|---|---|---|---|
datavault-backend |
registry.centricasoluciones.com/datavault/datavault-backend:latest |
API REST FastAPI (puerto 8547) | Up (healthy) |
oais-watcher |
python:3.11-slim |
Daemon que monitorea ingest_sip/ cada 10s |
Up |
| Contenedor | Profile | Funcion | Estado Normal |
|---|---|---|---|
oais-cloud-sync-sip |
cloud |
Sincroniza SIPs a Azure | No activo (sin Azure) |
oais-cloud-sync-aip |
cloud |
Sincroniza AIPs a Azure | No activo (sin Azure) |
oais-preservation-verifier |
preservation |
Verificacion de integridad | Ejecucion bajo demanda |
# Ver todos los contenedores del stack
docker ps -a --filter "name=datavault" --filter "name=oais" \
--format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
# Resultado esperado:
# NAMES STATUS PORTS
# datavault-backend Up X days (healthy) 0.0.0.0:8547->8000/tcp
# oais-watcher Up X days
El watcher escribe un log en el host via bind mount. Este es el metodo principal de revision:
# Ver las ultimas 50 lineas
tail -50 /home/sysadmin/docker/compose/datavault/oais/watcher.log
# Seguir en tiempo real
tail -f /home/sysadmin/docker/compose/datavault/oais/watcher.log
# Buscar errores
grep -i "error\|ERROR\|❌" /home/sysadmin/docker/compose/datavault/oais/watcher.log
# Buscar procesamiento exitoso
grep "✅ SIP creado\|AIP creado\|\[OK\] Proceso terminado" /home/sysadmin/docker/compose/datavault/oais/watcher.log
# Ver actividad de un dia especifico
grep "^2026-04-20" /home/sysadmin/docker/compose/datavault/oais/watcher.log
# Watcher — ultimas 100 lineas
docker logs oais-watcher --tail 100
# Watcher — seguir en tiempo real
docker logs oais-watcher -f
# Backend — ultimas 50 lineas
docker logs datavault-backend --tail 50
# Logs desde una fecha/hora especifica
docker logs oais-watcher --since "2026-04-20T10:00:00"
| Mensaje | Significado |
|---|---|
Carpetas detectadas en .../ingest_sip: [...] |
El watcher encontro elementos nuevos en staging |
Carpeta detectada para procesar: X |
Inicia procesamiento de un SIP |
Ya procesada o con error: X |
El archivo ya existe en _procesados/ o _errores/ |
Proyecto encontrado en BD desde metadatos: X |
Se asocio el SIP a un proyecto registrado |
SIP creado exitosamente |
Fase 1 completada: paquete SIP creado |
AIP creado exitosamente |
Fase 2 completada: paquete archivistico (ZIP) |
DIP creado exitosamente |
Fase 3 completada: paquete de distribucion |
[OK] Proceso terminado |
Pipeline OAIS completo — incluye IDs y rutas |
[PRESERVATION] Verificacion automatica completada |
Checksum verificado post-creacion |
Movido exitosamente: ... -> _procesados/ |
SIP movido a procesados |
Error obteniendo proyectos activos |
Problema de BD (ver seccion 7.1) |
# Ver estructura de primer nivel del repositorio
docker exec oais-watcher ls /home/egs/datavault/Repositorio/
# Resultado esperado:
# ARCHIVO_CENTRAL CONTRALORIA_DOCUMENTOS HOJAS_DE_VIDA PRUEBA_INGESTA_FRONT
# _errores _procesados ingest_sip
# Ver que hay pendiente de procesar
docker exec oais-watcher ls -la /home/egs/datavault/Repositorio/ingest_sip/
# Si hay carpetas aqui, el watcher deberia estar procesandolas
# Si una carpeta persiste, revisar logs para ver si hay error
# Ver procesados exitosos
docker exec oais-watcher ls -la /home/egs/datavault/Repositorio/_procesados/
# Ver errores
docker exec oais-watcher ls -la /home/egs/datavault/Repositorio/_errores/
# Ejemplo: inspeccionar proyecto ARCHIVO_CENTRAL
docker exec oais-watcher find /home/egs/datavault/Repositorio/ARCHIVO_CENTRAL -maxdepth 3 -type f
# Ver AIPs (archivos preservados)
docker exec oais-watcher ls -la /home/egs/datavault/Repositorio/ARCHIVO_CENTRAL/AIP/
# Ver SIPs (paquetes de envio)
docker exec oais-watcher ls -la /home/egs/datavault/Repositorio/ARCHIVO_CENTRAL/SIP/
# Ver DIPs (paquetes de distribucion)
docker exec oais-watcher ls -la /home/egs/datavault/Repositorio/ARCHIVO_CENTRAL/DIP/
Ubicados en /home/sysadmin/docker/compose/datavault/oais/. Se ejecutan dentro del contenedor del watcher:
Lee oais_status.json y muestra resumen de archivos, proyectos y actividad reciente.
docker exec oais-watcher python /home/egs/datavault/check_oais_status.py
# Con opciones:
docker exec oais-watcher python /home/egs/datavault/check_oais_status.py --summary
docker exec oais-watcher python /home/egs/datavault/check_oais_status.py --projects
docker exec oais-watcher python /home/egs/datavault/check_oais_status.py --activity --limit 20
Verifica consistencia entre proyectos registrados en PostgreSQL y carpetas en el repositorio.
docker exec oais-watcher python /home/egs/datavault/check_projects.py
Muestra:
Verificacion exhaustiva de todos los componentes:
docker exec oais-watcher sh -c "cd /home/egs/datavault/datavault && python app/check_server_status.py"
Verifica:
# Ver estado OAIS en formato legible
docker exec oais-watcher python -m json.tool /home/egs/datavault/oais_status.json | head -50
# O desde el host
python3 -m json.tool /home/sysadmin/docker/compose/datavault/oais/oais_status.json | head -50
column projects.auto_process does not existCausa: El modelo Python tiene columnas (auto_process, retention_days, folder_structure, custom_subfolders) que no existen en la tabla PostgreSQL. Falta ejecutar migracion Alembic.
Sintoma en logs:
ERROR Error obteniendo proyectos activos: (psycopg2.errors.UndefinedColumn)
column projects.auto_process does not exist
Efecto: El watcher no puede obtener proyectos activos. Procesa archivos pero no los asocia correctamente a proyectos.
Solucion:
# Conectar a postgres-dev y agregar columnas faltantes
docker exec -it postgres-dev psql -U datavault_user -d datavault -c "
ALTER TABLE projects ADD COLUMN IF NOT EXISTS auto_process BOOLEAN DEFAULT true;
ALTER TABLE projects ADD COLUMN IF NOT EXISTS retention_days INTEGER DEFAULT 0;
ALTER TABLE projects ADD COLUMN IF NOT EXISTS folder_structure VARCHAR(50) DEFAULT 'flat';
ALTER TABLE projects ADD COLUMN IF NOT EXISTS custom_subfolders TEXT;
"
# O ejecutar migracion Alembic desde el backend
docker exec datavault-backend alembic upgrade head
Causa: El watcher detecta la carpeta pero ya existe en _procesados/ o _errores/.
Diagnostico:
# Verificar si ya fue procesado
docker exec oais-watcher ls /home/egs/datavault/Repositorio/_procesados/ | grep "nombre_carpeta"
docker exec oais-watcher ls /home/egs/datavault/Repositorio/_errores/ | grep "nombre_carpeta"
Solucion: Si se desea reprocesar, eliminar la entrada en _procesados/ o _errores/:
docker exec oais-watcher rm -rf /home/egs/datavault/Repositorio/_procesados/NOMBRE_CARPETA
# El watcher lo reprocesara en el siguiente ciclo (10s)
# Verificar estado
docker ps --filter "name=oais-watcher"
# Reiniciar
cd /home/sysadmin/docker/compose/datavault
docker compose restart oais-watcher
# Ver logs de arranque
docker logs oais-watcher --tail 30
El sistema a veces crea carpetas aip/, dip/, processed_sip/ en la raiz del proyecto. Scripts de limpieza:
# Ejecucion manual
bash /home/sysadmin/docker/compose/datavault/oais/cleanup_datavault.sh
# El script monitor_cleanup.sh corre en loop eliminandolas cada minuto
bash /home/sysadmin/docker/compose/datavault/oais/monitor_cleanup.sh &
Alternativa a la revision por SSH: el backend expone endpoints para gestionar los daemons OAIS via API REST.
Base URL: https://api-datavault-legacy-dev.centricasoluciones.com
curl -s -H "Authorization: Bearer $TOKEN" \
"https://api-datavault-legacy-dev.centricasoluciones.com/api/cloud/daemon/status/all" | python3 -m json.tool
curl -s -H "Authorization: Bearer $TOKEN" \
"https://api-datavault-legacy-dev.centricasoluciones.com/api/cloud/daemon/logs?daemon_name=oais_watcher&lines=50"
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
"https://api-datavault-legacy-dev.centricasoluciones.com/api/cloud/daemon/restart?daemon_name=oais_watcher"
Nota: Estos endpoints requieren autenticacion JWT con rol superadmin.
Procedimiento recomendado para verificacion rutinaria:
# 1. Conectar al servidor
ssh nodo-01
# 2. Verificar que los contenedores esten corriendo
docker ps --filter "name=datavault" --filter "name=oais" --format "table {{.Names}}\t{{.Status}}"
# 3. Revisar errores recientes en el log del watcher
grep -i "error\|ERROR" /home/sysadmin/docker/compose/datavault/oais/watcher.log | tail -20
# 4. Verificar cola de ingesta (deberia estar vacia o procesandose)
docker exec oais-watcher ls /home/egs/datavault/Repositorio/ingest_sip/
# 5. Ver procesados del dia
grep "$(date +%Y-%m-%d)" /home/sysadmin/docker/compose/datavault/oais/watcher.log | grep "\[OK\]"
# 6. Verificar errores del dia
grep "$(date +%Y-%m-%d)" /home/sysadmin/docker/compose/datavault/oais/watcher.log | grep -i "error"
# 7. Estado general OAIS
docker exec oais-watcher python /home/egs/datavault/check_oais_status.py --summary
# 8. Healthcheck del backend
curl -s http://localhost:8547/health
El volumen oais-repositorio es donde reside toda la preservacion digital del sistema. Contiene los paquetes SIP, AIP y DIP de todos los proyectos.
| Aspecto | Valor |
|---|---|
| Nombre Docker | oais-repositorio |
| Driver | local |
| Mountpoint en host | /var/lib/docker/volumes/oais-repositorio/_data |
| Ruta dentro de contenedores | /home/egs/datavault/Repositorio |
| Creado por | Docker Compose (datavault project) |
| Contenedores que lo montan | datavault-backend (rw), oais-watcher (rw), oais-cloud-sync-* (rw), oais-preservation-verifier (rw) |
/var/lib/docker/volumes/oais-repositorio/_data/ ← HOST (nodo-01)
│
├── ingest_sip/ ← Cola de entrada (staging)
│ └── {PROYECTO}_{archivo} ← Archivos pendientes de procesamiento
│
├── _procesados/ ← SIPs procesados exitosamente
│ └── {PROYECTO}_{archivo} ← Movidos aqui tras exito
│
├── _errores/ ← SIPs con error
│ └── {PROYECTO}_{archivo} ← Movidos aqui tras fallo
│
├── ARCHIVO_CENTRAL/ ← Proyecto: Archivo Central
│ ├── SIP/ ← Submission Information Packages
│ │ └── {unique_id}/
│ │ ├── data/ ← Archivos originales
│ │ ├── metadata/ ← Metadatos OAIS (descriptive, technical, preservation)
│ │ └── manifest.xml ← Manifiesto del paquete
│ ├── AIP/ ← Archival Information Packages
│ │ ├── {doc_id}.zip ← Paquete archivistico comprimido
│ │ ├── {doc_id}.legal_hold_*.lock ← Lock files (legal hold)
│ │ └── {doc_id}.retention.json ← Metadata de retencion
│ └── DIP/ ← Dissemination Information Packages
│ └── {doc_id}.zip ← Paquete para distribucion/consulta
│
├── CONTRALORIA_DOCUMENTOS/ ← Proyecto: Contraloria
│ └── (misma estructura SIP/AIP/DIP)
│
├── HOJAS_DE_VIDA/ ← Proyecto: Hojas de Vida
│ └── (misma estructura SIP/AIP/DIP)
│
└── PRUEBA_INGESTA_FRONT/ ← Proyecto: Pruebas Frontend
└── (misma estructura SIP/AIP/DIP)
| Aspecto | Detalle |
|---|---|
| Persistencia | El volumen sobrevive reinicios de contenedores y docker compose down. Solo se elimina con docker volume rm oais-repositorio |
| Respaldo | NO tiene backup automatico. Reside en /var/lib/docker/volumes/ dentro del disco del servidor (49GB total, 35GB libres) |
| Integridad | El preservation_verifier calcula checksums SHA-256 post-creacion de AIPs |
| Legal Hold | Archivos con .lock no deben eliminarse — representan retenciones legales activas |
| Retencion | Archivos .retention.json contienen politicas de retencion con fechas de expiracion |
# Acceso directo al volumen (requiere root o permisos docker)
sudo ls -la /var/lib/docker/volumes/oais-repositorio/_data/
# Tamano total del repositorio
docker exec oais-watcher du -sh /home/egs/datavault/Repositorio
# Tamano por proyecto
docker exec oais-watcher find /home/egs/datavault/Repositorio -maxdepth 1 -type d -exec du -sh {} \;
# Contar AIPs por proyecto
docker exec oais-watcher find /home/egs/datavault/Repositorio -path "*/AIP/*.zip" | wc -l
# Verificar locks activos (legal holds)
docker exec oais-watcher find /home/egs/datavault/Repositorio -name "*.lock" -type f
# Verificar retenciones activas
docker exec oais-watcher find /home/egs/datavault/Repositorio -name "*.retention.json" -type f
| Riesgo | Probabilidad | Impacto | Mitigacion |
|---|---|---|---|
Perdida del volumen por docker volume rm accidental |
Baja | CRITICO — Perdida total de documentos preservados | Implementar backup periodico a MinIO o almacenamiento externo |
| Disco lleno en nodo-01 | Media | Alto — Detiene ingesta | Monitorear uso de disco; mover a almacenamiento externo cuando supere 70% |
| Corrupcion por escritura concurrente | Baja | Alto | Solo el watcher y backend escriben; no hay conflicto porque operan en rutas distintas |
| Eliminacion accidental de AIPs | Baja | CRITICO | Legal holds previenen eliminacion; backups regulares recomendados |
# Backup completo a MinIO (nodo-01 → minio-dev en mismo nodo)
docker run --rm \
-v oais-repositorio:/source:ro \
--network dev-network \
minio/mc \
sh -c "mc alias set local http://minio-dev:9000 sysadmin centrica2026 && \
mc mirror /source local/datavault-backups/$(date +%Y%m%d)/"
# O backup a archivo tar en /tmp
docker run --rm \
-v oais-repositorio:/data:ro \
-v /tmp:/backup \
alpine tar czf /backup/oais-repo-$(date +%Y%m%d).tar.gz -C /data .
cd /home/sysadmin/docker/compose/datavault
docker compose down
docker compose up -d
cd /home/sysadmin/docker/compose/datavault
docker compose pull datavault-backend
docker compose up -d datavault-backend
Los contenedores ya tienen configurado log rotation via Docker (max-size: 10m, max-file: 3). El archivo watcher.log en el host no tiene rotacion automatica:
# Tamano actual del log
ls -lh /home/sysadmin/docker/compose/datavault/oais/watcher.log
# Rotacion manual si es necesario
mv /home/sysadmin/docker/compose/datavault/oais/watcher.log \
/home/sysadmin/docker/compose/datavault/oais/watcher.log.$(date +%Y%m%d)
docker compose restart oais-watcher
# El volumen oais-repositorio contiene todos los documentos preservados
docker run --rm -v oais-repositorio:/data -v /tmp:/backup \
alpine tar czf /backup/oais-repositorio-$(date +%Y%m%d).tar.gz /data
Departamento de Arquitectura — Centrica Soluciones