system-docs/MANUAL_USUARIO_HST.md

MANUAL DE USUARIO - HST (Servidor 72.62.2.84)

Introducción

HST es un servidor especializado en gestión de activos digitales y API de datos. Aloja la API principal (HST-API), tres instancias de Directus para gestión de contenidos, y un sistema de grafos con capacidades avanzadas de indexación.

Información del Servidor

Aspecto	Detalles
IP	72.62.2.84
Usuario	root
Acceso SSH	ssh root@72.62.2.84 -i ~/.ssh/tzzr
Ubicación	Servidor HST
Rol	API, gestión de contenidos, sistema de grafos

Servicios Disponibles

1. HST-API (API Principal)

Puerto: 5001 URL: http://72.62.2.84:5001 Documentación: http://72.62.2.84:5001/docs (OpenAPI/Swagger) Base de datos: PostgreSQL integrada

Características:

• API REST para gestión de activos
• Autenticación con tokens JWT
• Documentación interactiva Swagger
• Rate limiting y logging automático

Endpoints Principales:

# Listar activos
curl http://72.62.2.84:5001/api/v1/assets -H "Authorization: Bearer [token]"

# Obtener activo por ID
curl http://72.62.2.84:5001/api/v1/assets/[id] -H "Authorization: Bearer [token]"

# Crear nuevo activo
curl -X POST http://72.62.2.84:5001/api/v1/assets \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mi activo",
    "description": "Descripción",
    "tags": ["tag1", "tag2"],
    "metadata": {}
  }'

# Actualizar activo
curl -X PUT http://72.62.2.84:5001/api/v1/assets/[id] \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"name": "Nuevo nombre"}'

# Eliminar activo
curl -X DELETE http://72.62.2.84:5001/api/v1/assets/[id] \
  -H "Authorization: Bearer [token]"

Obtener Token de Autenticación:

# Login
curl -X POST http://72.62.2.84:5001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "[usuario]",
    "password": "[contraseña]"
  }'

# Respuesta incluye token JWT
# Usar en headers: Authorization: Bearer [token]

Ver Documentación:

Visita http://72.62.2.84:5001/docs en el navegador para documentación interactiva Swagger.

2. Directus CMS (3 Instancias)

Instancias: 8055, 8056, 8057 URLs:

• Instancia 1: http://72.62.2.84:8055
• Instancia 2: http://72.62.2.84:8056
• Instancia 3: http://72.62.2.84:8057

Uso: Gestión de contenidos, colecciones de datos, interfaz administrativa

Características Directus:

• Interfaz web intuitiva para CRUD
• Gestión de usuarios y permisos
• API REST para acceso programático
• Webhooks para automatización
• Auditoría de cambios

Acceder a Directus:

# Abrir en navegador
# http://72.62.2.84:8055 (u 8056/8057)

# Usar SSH forward si accedes remotamente
ssh root@72.62.2.84 -i ~/.ssh/tzzr -L 8055:localhost:8055

# Luego visitar http://localhost:8055 localmente

Operaciones en Directus:

# Obtener token de acceso
curl -X POST http://72.62.2.84:8055/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email]",
    "password": "[contraseña]"
  }'

# Listar colecciones
curl http://72.62.2.84:8055/collections \
  -H "Authorization: Bearer [token]"

# Obtener items de colección
curl http://72.62.2.84:8055/items/[colección] \
  -H "Authorization: Bearer [token]"

# Crear item
curl -X POST http://72.62.2.84:8055/items/[colección] \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "campo1": "valor1",
    "campo2": "valor2"
  }'

3. Graph System (Sistema de Grafos)

Componente: Sistema de indexación y consulta de grafos Nodos: 709 Edges: 1134 Propósito: Análisis relacional, búsqueda semántica, navegación de conectividades

Estadísticas del Grafo:

┌─────────────────────┐
│   GRAPH STATISTICS  │
├─────────────────────┤
│ Total Nodes: 709    │
│ Total Edges: 1134   │
│ Density: 0.0044     │
│ Avg Degree: 3.20    │
└─────────────────────┘

Consultas al Sistema de Grafos:

# Obtener nodo por ID
curl http://72.62.2.84:5001/api/v1/graph/nodes/[node-id] \
  -H "Authorization: Bearer [token]"

# Obtener nodos por tipo
curl "http://72.62.2.84:5001/api/v1/graph/nodes?type=[tipo]" \
  -H "Authorization: Bearer [token]"

# Obtener vecinos de un nodo
curl http://72.62.2.84:5001/api/v1/graph/nodes/[node-id]/neighbors \
  -H "Authorization: Bearer [token]"

# Obtener caminos más cortos entre dos nodos
curl "http://72.62.2.84:5001/api/v1/graph/shortest-path?from=[id1]&to=[id2]" \
  -H "Authorization: Bearer [token]"

# Búsqueda por propiedades
curl "http://72.62.2.84:5001/api/v1/graph/search?query=[término]&type=[tipo]" \
  -H "Authorization: Bearer [token]"

# Estadísticas del grafo
curl http://72.62.2.84:5001/api/v1/graph/stats \
  -H "Authorization: Bearer [token]"

Estructura de Nodos

Tipos principales de nodos:

- entity: Entidades principales
- document: Documentos y archivos
- concept: Conceptos abstractos
- organization: Organizaciones
- person: Personas
- asset: Activos digitales
- tag: Etiquetas y clasificadores

Tipos de Edges

Relaciones entre nodos:

- HAS: Relación de pertenencia
- REFERENCES: Referencia
- RELATED_TO: Relacionado con
- DEPENDS_ON: Depende de
- CREATED_BY: Creado por
- MODIFIED_BY: Modificado por
- TAGGED_WITH: Etiquetado con

Gestión de Tags

El sistema de tags permite clasificar y filtrar activos dinámicamente.

Tags Disponibles

# Listar todos los tags
curl http://72.62.2.84:5001/api/v1/tags \
  -H "Authorization: Bearer [token]"

# Obtener tag específico
curl http://72.62.2.84:5001/api/v1/tags/[tag-name] \
  -H "Authorization: Bearer [token]"

# Crear nuevo tag
curl -X POST http://72.62.2.84:5001/api/v1/tags \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nuevo-tag",
    "description": "Descripción del tag",
    "color": "#FF5733"
  }'

# Actualizar tag
curl -X PUT http://72.62.2.84:5001/api/v1/tags/[tag-name] \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"description": "Nueva descripción"}'

# Eliminar tag
curl -X DELETE http://72.62.2.84:5001/api/v1/tags/[tag-name] \
  -H "Authorization: Bearer [token]"

Aplicar Tags a Activos

# Agregar tag a activo
curl -X POST http://72.62.2.84:5001/api/v1/assets/[asset-id]/tags \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"tag": "[tag-name]"}'

# Quitar tag de activo
curl -X DELETE http://72.62.2.84:5001/api/v1/assets/[asset-id]/tags/[tag-name] \
  -H "Authorization: Bearer [token]"

# Filtrar activos por tag
curl "http://72.62.2.84:5001/api/v1/assets?tags=[tag-name]" \
  -H "Authorization: Bearer [token]"

# Filtrar activos por múltiples tags
curl "http://72.62.2.84:5001/api/v1/assets?tags=[tag1],[tag2]" \
  -H "Authorization: Bearer [token]"

Jerarquía de Tags

# Crear tag secundario
curl -X POST http://72.62.2.84:5001/api/v1/tags \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "subcategoría",
    "parent": "categoría-principal",
    "description": "Subtag"
  }'

# Obtener tags por categoría
curl "http://72.62.2.84:5001/api/v1/tags?parent=[parent-tag]" \
  -H "Authorization: Bearer [token]"

API Endpoints Principales

Activos

Método	Endpoint	Descripción
GET	/api/v1/assets	Listar activos
GET	/api/v1/assets/[id]	Obtener activo
POST	/api/v1/assets	Crear activo
PUT	/api/v1/assets/[id]	Actualizar activo
DELETE	/api/v1/assets/[id]	Eliminar activo

Tags

Método	Endpoint	Descripción
GET	/api/v1/tags	Listar tags
POST	/api/v1/tags	Crear tag
PUT	/api/v1/tags/[name]	Actualizar tag
DELETE	/api/v1/tags/[name]	Eliminar tag

Sistema de Grafos

Método	Endpoint	Descripción
GET	/api/v1/graph/nodes	Listar nodos
GET	/api/v1/graph/nodes/[id]	Obtener nodo
GET	/api/v1/graph/nodes/[id]/neighbors	Vecinos de nodo
GET	/api/v1/graph/edges	Listar edges
GET	/api/v1/graph/shortest-path	Camino más corto
GET	/api/v1/graph/search	Búsqueda
GET	/api/v1/graph/stats	Estadísticas

Directus

Método	Endpoint (instancia 8055)	Descripción
POST	/auth/login	Autenticación
GET	/collections	Listar colecciones
GET	/items/[collection]	Listar items
POST	/items/[collection]	Crear item
PATCH	/items/[collection]/[id]	Actualizar item
DELETE	/items/[collection]/[id]	Eliminar item

Ejemplos de Uso Comunes

Flujo: Crear Activo con Tags en el Grafo

# 1. Obtener token
TOKEN=$(curl -s -X POST http://72.62.2.84:5001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "usuario",
    "password": "contraseña"
  }' | jq -r '.token')

# 2. Crear activo
ASSET=$(curl -s -X POST http://72.62.2.84:5001/api/v1/assets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nuevo Activo",
    "description": "Descripción",
    "tags": []
  }' | jq -r '.id')

echo "Activo creado: $ASSET"

# 3. Crear tag si no existe
curl -s -X POST http://72.62.2.84:5001/api/v1/tags \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mi-tag",
    "description": "Mi etiqueta"
  }'

# 4. Asociar tag al activo
curl -s -X POST http://72.62.2.84:5001/api/v1/assets/$ASSET/tags \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tag": "mi-tag"}'

echo "Tag asociado al activo"

# 5. Crear nodo en el grafo
curl -s -X POST http://72.62.2.84:5001/api/v1/graph/nodes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "asset",
    "properties": {
      "asset_id": "'$ASSET'",
      "name": "Nuevo Activo"
    }
  }'

echo "Nodo del grafo creado"

Flujo: Buscar Activos por Tag y Explorar Relaciones

# 1. Buscar activos por tag
curl "http://72.62.2.84:5001/api/v1/assets?tags=importante" \
  -H "Authorization: Bearer $TOKEN" | jq '.'

# 2. Para cada activo, obtener su nodo en el grafo
ASSET_ID="[obtenido del paso anterior]"
GRAPH_NODE=$(curl -s "http://72.62.2.84:5001/api/v1/graph/nodes?asset_id=$ASSET_ID" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.nodes[0].id')

# 3. Explorar vecinos del nodo
curl "http://72.62.2.84:5001/api/v1/graph/nodes/$GRAPH_NODE/neighbors" \
  -H "Authorization: Bearer $TOKEN" | jq '.'

# 4. Encontrar caminos a otros nodos
curl "http://72.62.2.84:5001/api/v1/graph/shortest-path?from=$GRAPH_NODE&to=[otro-nodo]" \
  -H "Authorization: Bearer $TOKEN" | jq '.'

Mantenimiento y Operaciones

Verificar Estado de Servicios

# Conectar al servidor
ssh root@72.62.2.84 -i ~/.ssh/tzzr

# Verificar servicios activos
systemctl status

# Ver logs de HST-API
journalctl -u hst-api -f

# Ver logs de Directus
journalctl -u directus -f

Backup de Datos

# Descargar datos de Directus (instancia 8055)
curl "http://72.62.2.84:8055/items/[colección]?export=json" \
  -H "Authorization: Bearer $TOKEN" > backup.json

# Backup de grafo
curl "http://72.62.2.84:5001/api/v1/graph/export" \
  -H "Authorization: Bearer $TOKEN" > grafo-backup.json

# Guardar en R2
aws s3 cp backup.json "s3://architect/backups/hst-backup-$(date +%Y%m%d).json" \
  --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com

Monitoreo

# Estadísticas del grafo
curl http://72.62.2.84:5001/api/v1/graph/stats \
  -H "Authorization: Bearer $TOKEN" | jq '.'

# Contador de activos
curl "http://72.62.2.84:5001/api/v1/assets?limit=1" \
  -H "Authorization: Bearer $TOKEN" | jq '.total'

# Usar en script de monitoreo
while true; do
  echo "[$(date)] Estado del sistema HST:"
  curl -s http://72.62.2.84:5001/api/v1/graph/stats \
    -H "Authorization: Bearer $TOKEN" | jq '.node_count, .edge_count'
  sleep 300  # Cada 5 minutos
done

Troubleshooting

HST-API no responde

# Verificar si está corriendo
ps aux | grep hst-api

# Ver logs
journalctl -u hst-api -n 50

# Reiniciar servicio
systemctl restart hst-api

# Verificar puerto
netstat -tlnp | grep 5001

Error de autenticación

# Verificar credenciales válidas
curl -X POST http://72.62.2.84:5001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"usuario","password":"contraseña"}'

# Si error 401, credenciales incorrectas
# Si error 500, problema de servidor

Directus (8055/8056/8057) no accesible

# SSH forwarding si accedes remotamente
ssh root@72.62.2.84 -i ~/.ssh/tzzr -L 8055:localhost:8055

# Verificar que Directus está corriendo
ps aux | grep directus

# Ver logs de Directus
journalctl -u directus -n 50

Grafo bloqueado o lento

# Estadísticas actuales
curl http://72.62.2.84:5001/api/v1/graph/stats \
  -H "Authorization: Bearer $TOKEN" | jq '.'

# Si hay muchos nodos/edges, considerar:
# - Archiving de datos viejos
# - Índices de base de datos
# - Optimización de consultas

Configuración Importante

Variables de Entorno (en servidor HST)

# HST-API
export HST_API_PORT=5001
export HST_DATABASE_URL="postgresql://hst_user:password@localhost/hst_db"
export HST_JWT_SECRET="[tu-secret-jwt]"

# Directus (múltiples instancias)
export DIRECTUS_HOST=0.0.0.0
export DIRECTUS_PORT=8055  # Varía por instancia
export DIRECTUS_ADMIN_EMAIL="admin@example.com"
export DIRECTUS_ADMIN_PASSWORD="[contraseña]"

Puertos en Firewall

Asegúrate de que estos puertos estén abiertos:

• 5001: HST-API
• 8055, 8056, 8057: Directus (3 instancias)
• 5432: PostgreSQL (si es accesible)

# Verificar firewall
ufw status

# Si es necesario, abrir puertos
ufw allow 5001/tcp
ufw allow 8055/tcp
ufw allow 8056/tcp
ufw allow 8057/tcp

Referencias Rápidas

Puertos Importantes

• HST-API: 5001
• Directus 1: 8055
• Directus 2: 8056
• Directus 3: 8057

URLs Frecuentes

API Docs: http://72.62.2.84:5001/docs
HST-API: http://72.62.2.84:5001
Directus 1: http://72.62.2.84:8055
Directus 2: http://72.62.2.84:8056
Directus 3: http://72.62.2.84:8057

Comandos Frecuentes

# Conectar al servidor
ssh root@72.62.2.84 -i ~/.ssh/tzzr

# Forward Directus localmente
ssh root@72.62.2.84 -i ~/.ssh/tzzr -L 8055:localhost:8055

# Obtener token
curl -X POST http://72.62.2.84:5001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"usuario","password":"contraseña"}'

# Listar activos
curl http://72.62.2.84:5001/api/v1/assets \
  -H "Authorization: Bearer [token]"

# Stats del grafo
curl http://72.62.2.84:5001/api/v1/graph/stats \
  -H "Authorization: Bearer [token]"

Documentación Completa

Para documentación completa de cada servicio:

• HST-API: http://72.62.2.84:5001/docs (OpenAPI/Swagger)
• Directus: Documentación en cada instancia o https://docs.directus.io
• Sistema de Grafos: Consulta documentación interna en s3://architect/system/

---

Última actualización: Diciembre 2025 Versión: 1.0