Sync from R2 skynet v8: manuales, operación, glosario v3

Añadido:
- MANUAL_USUARIO_ARCHITECT.md
- MANUAL_USUARIO_CORP.md
- MANUAL_USUARIO_DECK.md
- MANUAL_USUARIO_HST.md
- 07_OPERACION/ (monitoring, runbooks, incident_response)
- glosario_she_enterprise_v3.md

Eliminado:
- glosario_she_enterprise_v2.md (reemplazado por v3)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
ARCHITECT
2026-01-01 10:53:57 +00:00
parent 36f87ca9b7
commit 9f3a4214d3
10 changed files with 5694 additions and 400 deletions

608
MANUAL_USUARIO_HST.md Normal file
View File

@@ -0,0 +1,608 @@
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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)
```bash
# 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)
```bash
# 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
```bash
# 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