tzzr/system-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1a94cd87e77ff38d2ac2beeb848d0cba5d478b57
system-docs/MANUAL_USUARIO_DECK-OBSOLETO.md

1451 lines
35 KiB
Markdown
Raw Blame History

# MANUAL USUARIO DECK - DOCUMENTO OBSOLETO
> ⚠️ **OBSOLETO desde 2026-01-22**
>
> Este documento ha sido reemplazado por:
> - [MANUAL_USUARIO_PABLO.md](MANUAL_USUARIO_PABLO.md) - Instancia de producción
> - [MANUAL_USUARIO_MODELO_CERO.md](MANUAL_USUARIO_MODELO_CERO.md) - Plantilla base
>
> Mantienido solo para referencia histórica.
---
# MANUAL DE USUARIO - DECK
## Sistema TZZR - Skynet v8
**Servidor:** 72.62.1.113
**Fecha:** 2025-12-30
---
# Manual de Usuario - DECK (72.62.1.113)
## PARTE 1: Introducción y Servicios
---
## 1. Introducción a DECK
### ¿Qué es DECK?
DECK es uno de los cuatro servidores principales del sistema TZZR (The Zero-Trust Resilient Resource Network), ubicado en la dirección IP **72.62.1.113**.
DECK actúa como **servidor de servicios** y aloja:
- **Agentes especializados** (Clara, Alfred, Mason, Feldman) que procesan datos e interactúan con otros sistemas
- **Servicios empresariales** (Correo, almacenamiento en la nube, contraseñas, etc.)
- **Infraestructura de datos** (PostgreSQL con pgvector, Redis)
- **Aplicaciones integradas** (ERP, CMS, notificaciones, gestor de archivos)
### Rol en la Infraestructura TZZR
El sistema TZZR consta de 4 servidores distribuidos:
| Servidor | IP | Función Principal |
|----------|----|--------------------|
| **Central** | 69.62.126.110 | Coordinación (Gitea, PostgreSQL central) |
| **DECK** | 72.62.1.113 | Servicios, Agentes, Mail (Este servidor) |
| **CORP** | 92.112.181.188 | Agentes especializados (Margaret, Jared) |
| **HST** | 72.62.2.84 | Directus, gestión de imágenes |
### Acceso SSH a DECK
Para conectarse a DECK desde la máquina central o cualquier servidor autorizado:
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113
```
**Requisitos:**
- Tener la clave privada SSH en `~/.ssh/tzzr`
- Permisos de acceso configurados
- Conectividad de red al servidor
**Verificar conexión:**
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113 "echo 'Conexión exitosa'"
```
---
## 2. Servicios en DECK
DECK aloja tres categorías principales de servicios:
### 2.1 Microservicios TZZR (Puertos 505x)
Estos son servicios especializados del ecosistema TZZR que se comunican entre sí:
#### Clara (Puerto 5051)
- **Descripción:** Log inmutable y auditoría
- **Propósito:** Registra todas las transacciones y eventos del sistema de forma imposible de modificar
- **Uso:** Auditoría, trazabilidad, compliance
- **Estado:** Verificar con `service clara`
#### Alfred (Puerto 5052)
- **Descripción:** Automatización de flujos de trabajo
- **Propósito:** Ejecuta flujos de trabajo definidos, orquesta tareas entre servicios
- **Uso:** Automatización de procesos empresariales
- **Estado:** Verificar con `service alfred`
#### Mason (Puerto 5053)
- **Descripción:** Espacio de enriquecimiento de datos
- **Propósito:** Enriquece datos con información contextual, aplica transformaciones
- **Uso:** Procesamiento y normalización de datos
- **Estado:** Verificar con `service mason`
#### Feldman (Puerto 5054)
- **Descripción:** Validador Merkle
- **Propósito:** Verifica integridad de datos mediante árboles de Merkle
- **Uso:** Validación criptográfica, verificación de integridad
- **Estado:** Verificar con `service feldman`
### 2.2 Aplicaciones Empresariales
Servicios de aplicación usuario-final para uso cotidiano:
#### Nextcloud (Puerto 8084)
- **Descripción:** Almacenamiento en la nube y colaboración
- **URL:** https://cloud.tzzrdeck.me
- **Uso:** Compartir archivos, calendario, contactos
- **Capacidades:** Sincronización, compartir enlaces, versiones
#### Odoo (Puerto 8069)
- **Descripción:** Sistema ERP completo
- **URL:** https://odoo.tzzrdeck.me
- **Uso:** Facturación, inventario, CRM, recursos humanos
- **Usuarios:** Acceso basado en roles
#### Vaultwarden (Puerto 8085)
- **Descripción:** Gestor de contraseñas empresarial
- **URL:** https://vault.ttzrdeck.me
- **Uso:** Almacenar y gestionar contraseñas de forma segura
- **Integración:** Compatible con Bitwarden
#### Directus (Puerto 8055)
- **Descripción:** CMS y gestor de contenido headless
- **URL:** https://directus.tzzrdeck.me
- **Uso:** Crear y gestionar contenido, APIs automáticas
- **Flexible:** Base de datos agnóstica
#### Shlink (Puerto 8083)
- **Descripción:** Acortador de URLs
- **URL:** https://shlink.tzzrdeck.me
- **Uso:** Crear URLs cortas, rastreo de clics
- **Analytics:** Estadísticas de uso
#### Ntfy (Puerto 8080)
- **Descripción:** Sistema de notificaciones
- **URL:** https://ntfy.tzzrdeck.me
- **Uso:** Enviar notificaciones a través de HTTP
- **Integración:** Webhooks y push notifications
#### FileBrowser (Puerto 8082)
- **Descripción:** Gestor de archivos web
- **URL:** https://files.tzzrdeck.me
- **Uso:** Explorar, descargar, subir archivos
- **Seguridad:** Control de permisos por usuario
### 2.3 Infraestructura de Datos
#### PostgreSQL (Puerto 5432)
- **Descripción:** Base de datos principal del sistema
- **Características:** pgvector activado (búsqueda vectorial para IA)
- **Datos:** Contiene todas las bases de datos del sistema TZZR
- **Backup:** Se realiza automatizado
#### Redis (Puerto 6379)
- **Descripción:** Cache en memoria de alta velocidad
- **Uso:** Cache de sesiones, cache de consultas, pub/sub
- **Rendimiento:** Milisegundos de latencia
### 2.4 Servicios de Correo
#### Mailcow (Puerto 8180)
- **Descripción:** Servidor de correo empresarial completo
- **URL:** https://mail.tzzr.net
- **Servicios incluidos:**
- SMTP (envío de correos)
- IMAP/POP3 (lectura de correos)
- Webmail integrado
- Filtrado de spam
- Certificados SSL automáticos
- **Componentes:**
- Postfix: SMTP
- Dovecot: IMAP/POP3
- Nginx: Reverse proxy y webmail
- MySQL: Base de datos
- Redis: Cache
**Contenedores Mailcow:**
```
postfix-mailcow - Servidor SMTP
dovecot-mailcow - Servidor IMAP/POP3
nginx-mailcow - Webmail y reverse proxy
mysql-mailcow - Base de datos
redis-mailcow - Cache
```
---
## 3. Context-Manager (Gestor de Contexto)
### ¿Qué es Context-Manager?
Context-Manager es una herramienta central que permite a los agentes TZZR:
- Mantener contexto persistente de conversaciones
- Acceder a bloques de contexto previamente creados
- Gestionar memoria de largo plazo
- Compartir información entre agentes
### Instalación y Configuración
Context-Manager está disponible como CLI en DECK. Para verificar su disponibilidad:
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113 "context-manager --help"
```
### Comandos Principales
#### `context-manager --help`
Muestra ayuda sobre todos los comandos disponibles.
```bash
context-manager --help
```
**Ejemplo de salida:**
```
Context Manager CLI
==================
Comandos:
block list - Listar bloques de contexto
block add - Crear nuevo bloque
block view <id> - Ver contenido de bloque
block remove <id> - Eliminar bloque
memory list - Listar memorias
memory add - Agregar a memoria
memory clear - Limpiar memoria
chat - Iniciar chat interactivo
```
#### `context-manager block list`
Lista todos los bloques de contexto almacenados.
```bash
context-manager block list
```
**Ejemplo:**
```
ID | Nombre | Tipo | Fecha Creación
------|---------------------|----------|------------------
001 | Historia Clara | metadata | 2025-12-15 10:30
002 | Configuración TZZR | config | 2025-12-20 14:45
003 | Directorio RFC | reference| 2025-12-28 09:15
```
**Campos:**
- `ID`: Identificador único del bloque
- `Nombre`: Descripción del contenido
- `Tipo`: Categoría (metadata, config, reference, etc.)
- `Fecha Creación`: Cuándo se creó el bloque
#### `context-manager block view <ID>`
Ver el contenido completo de un bloque específico.
```bash
context-manager block view 002
```
**Ejemplo:**
```
Bloque: 002
Nombre: Configuración TZZR
Tipo: config
Creado: 2025-12-20 14:45
Contenido:
---------
{
"central_ip": "69.62.126.110",
"servers": {
"deck": "72.62.1.113",
"corp": "92.112.181.188",
"hst": "72.62.2.84"
},
"database": {
"host": "localhost",
"port": 5432,
"name": "tzzr_main"
}
}
```
#### `context-manager memory list`
Lista todos los elementos guardados en memoria compartida.
```bash
context-manager memory list
```
**Ejemplo:**
```
Memoria Compartida (15 items)
=============================
1. Clara - Último estado: up
2. Alfred - Procesos pendientes: 3
3. Mason - Últimas transformaciones: 2025-12-29 16:42
4. Feldman - Validaciones en caché: 127
5. PostgreSQL - Conexiones activas: 8
```
#### `context-manager memory add`
Agregar nueva información a memoria compartida.
```bash
context-manager memory add "nombre_clave" "contenido o JSON"
```
**Ejemplo:**
```bash
context-manager memory add "configuracion_temporal" '{"modo": "mantenimiento", "fecha": "2025-12-30"}'
```
#### `context-manager chat`
Inicia una sesión de chat interactivo con Context-Manager (útil para debugging).
```bash
context-manager chat
```
### Ejemplos de Uso Práctico
#### Ejemplo 1: Verificar estado del sistema
```bash
# Ver si hay configuración de mantenimiento
context-manager block view configuracion_mantenimiento
# Revisar estado en memoria
context-manager memory list
```
#### Ejemplo 2: Crear un bloque de contexto para una tarea
```bash
# Los agentes pueden crear bloques para compartir información
context-manager block add "migracion_datos_2025" \
--tipo "project" \
--contenido '{"estado": "en_progreso", "agentes": ["clara", "mason"]}'
```
#### Ejemplo 3: Consultar desde un script
```bash
#!/bin/bash
# Script que usa context-manager
CONTEXTO=$(context-manager block view configuracion)
echo "Contexto actual: $CONTEXTO"
# Actualizar estado
context-manager memory add "script_estado" "completado"
```
---
## 4. Gestión de Servicios en DECK
### Comandos Generales de Estado
#### Ver estado del sistema
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker ps -a"
```
Muestra todos los contenedores (activos e inactivos).
#### Ver estadísticas del sistema
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113 "free -h" # Memoria
ssh -i ~/.ssh/tzzr root@72.62.1.113 "df -h /" # Disco
ssh -i ~/.ssh/tzzr root@72.62.1.113 "top -bn1" # Procesos
```
### Comandos para Servicios Específicos
#### Obtener estado de un servicio
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker ps --filter name=clara"
```
#### Ver logs de un servicio
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker logs clara-service --tail 50"
```
#### Reiniciar un servicio
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker restart clara-service"
```
#### Detener un servicio
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker stop nextcloud"
```
#### Iniciar un servicio
```bash
ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker start nextcloud"
```
---
## 5. Acceso a Servicios Web
### URLs de Acceso
Todos los servicios web están disponibles bajo el dominio `tzzrdeck.me`:
| Servicio | URL | Puerto | Usuario Típico |
|----------|-----|--------|-----------------|
| Nextcloud | https://cloud.tzzrdeck.me | 8084 | Tu usuario LDAP |
| Odoo | https://odoo.tzzrdeck.me | 8069 | Tu usuario Odoo |
| Vaultwarden | https://vault.tzzrdeck.me | 8085 | Tu usuario Bitwarden |
| Directus | https://directus.tzzrdeck.me | 8055 | Tu usuario Directus |
| Shlink | https://shlink.tzzrdeck.me | 8083 | Tu usuario Shlink |
| Ntfy | https://ntfy.tzzrdeck.me | 8080 | Sin autenticación* |
| FileBrowser | https://files.tzzrdeck.me | 8082 | Tu usuario local |
| Webmail (Mailcow) | https://mail.tzzr.net | 8180 | Tu email |
*Ntfy puede usarse sin autenticación o con ella según configuración.
### Verificar Conectividad
Para verificar que un servicio está accesible:
```bash
curl -I https://cloud.tzzrdeck.me
curl -I https://mail.tzzr.net
```
Deberías recibir respuesta HTTP 200 o 302 (redirección a login).
---
## 6. Tabla de Referencia Rápida
### Puertos Principales en DECK
```
5051 - Clara (Log inmutable)
5052 - Alfred (Automatización)
5053 - Mason (Enriquecimiento)
5054 - Feldman (Validador Merkle)
5432 - PostgreSQL
6379 - Redis
8055 - Directus
8069 - Odoo
8080 - Ntfy
8082 - FileBrowser
8083 - Shlink
8084 - Nextcloud
8085 - Vaultwarden
8180 - Mailcow
22 - SSH
```
### Comandos Rápidos
```bash
# Conectar a DECK
ssh -i ~/.ssh/tzzr root@72.62.1.113
# Ver todos los servicios
docker ps -a
# Ver memoria y disco
free -h && df -h /
# Ver logs de Clara
docker logs clara-service -f
# Reiniciar Nextcloud
docker restart nextcloud
```
---
## 7. Próximas Partes del Manual
Este es el **PARTE 1** del manual. Las siguientes partes cubrirán:
- **PARTE 2:** Guía de Usuarios - Acceso a aplicaciones web
- **PARTE 3:** Gestión de Correo - Administración de Mailcow
- **PARTE 4:** Backup y Recuperación
- **PARTE 5:** Troubleshooting y Resolución de Problemas
- **PARTE 6:** Integración y APIs de Servicios TZZR
---
## 8. Soporte y Contacto
Para problemas o consultas:
1. **Verificar logs:** `docker logs <servicio>`
2. **Revisar documentación:** Contactar al equipo de ARCHITECT
3. **Escalation:** Reportar al coordinador central (CAPTAIN CLAUDE)
---
**Última actualización:** 2025-12-30
**Versión:** 1.0
**Aplicable a:** DECK (72.62.1.113)
# Manual de Usuario DECK (72.62.1.113) - PARTE 2
## PostgreSQL y Administración
**Versión:** 1.0
**Fecha:** 2025-12-30
**Sistema:** TZZR - Infraestructura Centralizada
---
## 1. PostgreSQL
### 1.1 Conexión a PostgreSQL
#### Conexión como usuario postgres
```bash
sudo -u postgres psql -d tzzr
```
#### Parámetros comunes
- **Host:** localhost (por defecto)
- **Puerto:** 5432 (por defecto)
- **Usuario:** postgres
- **Base de datos:** tzzr
#### Comandos básicos en psql
```bash
\l # Listar bases de datos
\c [nombre_db] # Conectar a una base de datos
\dt # Listar tablas
\d [nombre_tabla] # Describir estructura de tabla
\du # Listar usuarios/roles
\q # Salir
\h # Ayuda de comandos SQL
```
### 1.2 Bases de Datos
#### Base de datos: `tzzr`
Base de datos principal del sistema TZZR.
#### Base de datos: `deck`
Base de datos específica del servidor DECK.
#### Ver todas las bases de datos
```bash
sudo -u postgres psql -c "\l"
```
### 1.3 Tablas Principales del Context-Manager
El context-manager gestiona las siguientes tablas en la base de datos `tzzr`:
#### Tabla: `immutable_log`
Registro inmutable de todas las operaciones del sistema.
```bash
# Ver estructura
sudo -u postgres psql -d tzzr -c "\d immutable_log"
# Ver últimas 10 entradas
sudo -u postgres psql -d tzzr -c "SELECT * FROM immutable_log ORDER BY timestamp DESC LIMIT 10;"
```
#### Tabla: `context_state`
Estado actual del contexto del sistema.
```bash
# Ver estado actual
sudo -u postgres psql -d tzzr -c "SELECT * FROM context_state;"
```
#### Tabla: `algorithm_engine`
Configuración y estado del motor de algoritmos.
```bash
# Ver configuración
sudo -u postgres psql -d tzzr -c "SELECT * FROM algorithm_engine;"
```
#### Tabla: `agents`
Registro de agentes activos en el sistema.
```bash
# Ver agentes activos
sudo -u postgres psql -d tzzr -c "SELECT * FROM agents WHERE active = true;"
```
#### Tabla: `audit_log`
Registro de auditoría de todas las operaciones administrativas.
```bash
# Ver auditoría reciente
sudo -u postgres psql -d tzzr -c "SELECT * FROM audit_log ORDER BY timestamp DESC LIMIT 20;"
```
### 1.4 Consultas Útiles
#### Verificar integridad de la base de datos
```bash
sudo -u postgres psql -d tzzr -c "
SELECT schemaname, tablename, pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size
FROM pg_tables
WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;"
```
#### Verificar conexiones activas
```bash
sudo -u postgres psql -d tzzr -c "
SELECT pid, usename, application_name, client_addr, state
FROM pg_stat_activity
WHERE pid <> pg_backend_pid();"
```
#### Verificar índices
```bash
sudo -u postgres psql -d tzzr -c "
SELECT schemaname, tablename, indexname
FROM pg_indexes
WHERE schemaname NOT IN ('pg_catalog', 'information_schema');"
```
---
## 2. Administración
### 2.1 Comandos Docker Útiles
#### Ver estado de contenedores
```bash
docker ps # Contenedores activos
docker ps -a # Todos los contenedores
docker status # Estado general de Docker
```
#### Gestionar contenedores
```bash
docker start [container_id] # Iniciar contenedor
docker stop [container_id] # Detener contenedor
docker restart [container_id] # Reiniciar contenedor
docker logs [container_id] # Ver logs
docker logs -f [container_id] # Logs en tiempo real
docker exec -it [container_id] bash # Acceso interactivo
```
#### Gestionar imágenes
```bash
docker images # Listar imágenes
docker pull [image] # Descargar imagen
docker rmi [image_id] # Eliminar imagen
docker image prune # Limpiar imágenes no usadas
```
#### Ver recursos
```bash
docker stats # Uso de CPU/memoria en tiempo real
docker system df # Uso de disco
```
### 2.2 Logs y Diagnóstico
#### Logs de PostgreSQL
```bash
# Si PostgreSQL está en Docker
docker logs [postgres_container_id] | tail -100
# Si PostgreSQL está en el host
sudo tail -100 /var/log/postgresql/postgresql.log
```
#### Logs de Gitea
```bash
docker logs [gitea_container_id] | tail -100
```
#### Logs del sistema
```bash
sudo journalctl -xe # Últimos errores del sistema
sudo journalctl -u docker # Logs específicos de Docker
dmesg | tail -50 # Logs del kernel
```
#### Diagnóstico de red
```bash
netstat -tlnp # Puertos escuchando
ss -tlnp # Alternativa moderna de netstat
ping 69.62.126.110 # Conectividad con servidor central
```
#### Verificar espacio en disco
```bash
df -h # Espacio en particiones
du -sh /* # Uso por directorio
du -sh /var/lib/docker/* # Uso de Docker
```
### 2.3 Backups
#### Backup manual de PostgreSQL
```bash
# Backup completo de la base de datos tzzr
sudo -u postgres pg_dump tzzr > /tmp/tzzr_backup_$(date +%Y%m%d_%H%M%S).sql
# Backup de una tabla específica
sudo -u postgres pg_dump tzzr -t immutable_log > /tmp/immutable_log_backup.sql
```
#### Restaurar desde backup
```bash
# Restaurar base de datos completa
sudo -u postgres psql tzzr < /tmp/tzzr_backup.sql
# Restaurar tabla específica (cuidado: borra la tabla actual)
sudo -u postgres psql tzzr < /tmp/immutable_log_backup.sql
```
#### Backup de Gitea
```bash
# Ver documentación de Gitea para backup
docker exec [gitea_container] /app/gitea dump -c /etc/gitea/app.ini
```
#### Automático: Script de backup diario
```bash
#!/bin/bash
# Guardar como /opt/scripts/backup_daily.sh
BACKUP_DIR="/backups/postgresql"
DB_NAME="tzzr"
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR
sudo -u postgres pg_dump $DB_NAME > $BACKUP_DIR/tzzr_$DATE.sql
gzip $BACKUP_DIR/tzzr_$DATE.sql
# Eliminar backups más antiguos de 30 días
find $BACKUP_DIR -name "tzzr_*.sql.gz" -mtime +30 -delete
echo "Backup completado: $BACKUP_DIR/tzzr_$DATE.sql.gz"
```
Configurar en cron:
```bash
# Editar crontab
sudo crontab -e
# Agregar línea (backup diario a las 2:00 AM)
0 2 * * * /opt/scripts/backup_daily.sh >> /var/log/backup.log 2>&1
```
---
## 3. Troubleshooting
### 3.1 Problemas Comunes y Soluciones
#### Problema: No se puede conectar a PostgreSQL
```bash
# Verificar que PostgreSQL está corriendo
sudo systemctl status postgresql
# o si está en Docker:
docker ps | grep postgres
# Verificar puerto 5432
sudo netstat -tlnp | grep 5432
# Ver logs de PostgreSQL
sudo tail -50 /var/log/postgresql/postgresql.log
# Reiniciar PostgreSQL
sudo systemctl restart postgresql
# o si está en Docker:
docker restart [postgres_container_id]
```
#### Problema: Espacio en disco bajo
```bash
# Ver distribución de espacio
du -sh /* | sort -rh
# Limpiar logs antiguos
sudo journalctl --vacuum=30d
# Limpiar Docker
docker system prune -a --volumes
# Limpiar cache de PostgreSQL
sudo -u postgres psql -d tzzr -c "VACUUM ANALYZE;"
```
#### Problema: Conexiones agotadas a PostgreSQL
```bash
# Ver conexiones activas
sudo -u postgres psql -d tzzr -c "SELECT * FROM pg_stat_activity;"
# Terminar conexión específica
sudo -u postgres psql -d tzzr -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE pid <> pg_backend_pid();"
# Ver configuración de conexiones máximas
sudo -u postgres psql -d tzzr -c "SHOW max_connections;"
```
#### Problema: Base de datos bloqueada
```bash
# Ver transacciones abiertas
sudo -u postgres psql -d tzzr -c "SELECT * FROM pg_stat_activity WHERE state != 'idle';"
# Ver locks
sudo -u postgres psql -d tzzr -c "SELECT * FROM pg_locks;"
# Terminar transacción bloqueada
sudo -u postgres psql -d tzzr -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE pid = [PID];"
```
#### Problema: Docker fuera de espacio
```bash
# Ver uso de Docker
docker system df
# Limpiar imágenes sin usar
docker image prune -a
# Limpiar volúmenes sin usar
docker volume prune
# Limpiar redes sin usar
docker network prune
# Limpieza total (cuidado!)
docker system prune -a --volumes
```
#### Problema: Gitea no responde
```bash
# Ver estado del contenedor
docker ps | grep gitea
# Reiniciar Gitea
docker restart [gitea_container_id]
# Ver logs
docker logs [gitea_container_id] | tail -100
# Acceso a terminal de Gitea
docker exec -it [gitea_container_id] bash
```
#### Problema: Alto uso de CPU/memoria
```bash
# Ver uso en tiempo real
docker stats
# Identificar proceso problemático
ps aux | sort -k3 -rn | head -5 # Por CPU
ps aux | sort -k4 -rn | head -5 # Por memoria
# Ver procesos de PostgreSQL
ps aux | grep postgres
# Limitar recursos de contenedor (si es necesario)
docker update --memory 4g [container_id]
```
### 3.2 Contactos de Soporte
#### Contactos Técnicos
| Rol | Contacto | Disponibilidad |
|-----|----------|-----------------|
| **ARCHITECT** | architect@tzzr.local | Tiempo completo |
| **CAPTAIN CLAUDE** | captain@tzzr.local | Tiempo completo |
| **Soporte DB** | dba@tzzr.local | L-V 8AM-6PM |
| **Soporte Infraestructura** | infra@tzzr.local | 24/7 |
#### Escalation Path
1. Contactar equipo de soporte directo
2. Crear ticket en Gitea: https://69.62.126.110/gitea
3. SSH a servidor central: `ssh architect@69.62.126.110`
4. Activar modo debug si es necesario
#### Información para reportar problemas
Cuando reportes un problema, incluye:
- Fecha y hora exacta del incidente
- Mensajes de error completos
- Output de diagnósticos relevantes:
```bash
docker ps -a
docker logs [container_id]
df -h
free -h
sudo -u postgres psql -d tzzr -c "SELECT * FROM pg_stat_activity;"
```
- Pasos para reproducir el problema
### 3.3 Verificación de Salud del Sistema
Script de diagnóstico completo:
```bash
#!/bin/bash
# Guardar como /opt/scripts/health_check.sh
echo "=== SALUD DEL SISTEMA DECK ==="
echo ""
echo "1. Estado de Docker:"
docker ps -a
echo ""
echo "2. Uso de Recursos:"
free -h
df -h
echo ""
echo "3. Conectividad PostgreSQL:"
sudo -u postgres psql -d tzzr -c "SELECT version();"
echo ""
echo "4. Conexiones Activas:"
sudo -u postgres psql -d tzzr -c "SELECT COUNT(*) FROM pg_stat_activity;"
echo ""
echo "5. Conectividad con servidor central:"
ping -c 1 69.62.126.110
echo ""
echo "=== FIN DIAGNÓSTICO ==="
```
Ejecutar:
```bash
chmod +x /opt/scripts/health_check.sh
/opt/scripts/health_check.sh
```
---
## Apéndice: Atajos Útiles
### Alias recomendados para .bashrc
```bash
alias pgconnect='sudo -u postgres psql -d tzzr'
alias dockerps='docker ps -a --format "table {{.ID}}\t{{.Names}}\t{{.Status}}\t{{.Ports}}"'
alias dstats='docker stats --no-stream'
alias dblog='sudo tail -f /var/log/postgresql/postgresql.log'
alias sysdump='cd /tmp && docker ps -a > docker_status.txt && df -h > disk_status.txt && free -h > memory_status.txt && ps aux > process_status.txt'
```
Cargar alias:
```bash
source ~/.bashrc
```
---
**Fin del Manual - PARTE 2**
Para más información sobre PARTE 1 (Primeros Pasos y Servicios), consulta el manual anterior.
Fecha de última actualización: 2025-12-30
# DECK - Manual de Usuario PARTE 3: Guías Rápidas
## 1. Guía Rápida de Inicio
### Primeros Pasos
Cuando accedas a DECK por primera vez:
```bash
# 1. Conéctate al servidor
ssh root@72.62.1.113
# 2. Verifica que estés en el directorio correcto
pwd
# Deberías estar en /root
# 3. Visualiza la estructura general
ls -la
```
### Verificar Servicios con Docker
Para asegurar que todos los servicios están funcionando:
```bash
# Ver todos los contenedores activos
docker ps
# Ver todos los contenedores (incluyendo detenidos)
docker ps -a
# Ver logs de un servicio específico
docker logs -f nombre_contenedor
# Ejemplo: Ver logs de Mailcow
docker logs -f mailcow-mailserver-1
```
**Servicios esperados:**
- `mailcow-mailserver-1` - Servidor de correo
- `nextcloud-app-1` - Gestor de archivos
- `vaultwarden-app-1` - Gestor de contraseñas
- `postgres-db-1` - Base de datos
- Base de datos local de context-manager
### Verificar PostgreSQL
PostgreSQL es crítico para context-manager y otros servicios:
```bash
# Acceder a PostgreSQL
docker exec -it postgres-db-1 psql -U postgres
# Dentro de psql, ver bases de datos
\l
# Ver usuarios
\du
# Conectar a una base de datos específica
\c nombre_base_datos
# Ver tablas
\dt
# Salir
\q
# Alternativa: Verificar desde el host
sudo systemctl status postgresql
```
**Status esperado:**
- PostgreSQL debe estar `active (running)`
- Puerto 5432 debe estar escuchando
---
## 2. Casos de Uso Comunes
### Caso 1: Enviar Correo con Mailcow
#### Acceder a la interfaz web
```
URL: https://deck.local/mailcow
o
URL: https://72.62.1.113/mailcow
```
#### Crear usuario de correo
1. Accede a **Mail → Mailboxes**
2. Haz clic en **+ Add Mailbox**
3. Completa:
- **Local part**: (el nombre antes del @)
- **Domain**: (selecciona dominio)
- **Password**: (contraseña segura)
4. Haz clic en **Add**
#### Usar desde cliente de correo (Outlook, Thunderbird, Apple Mail)
```
Servidor IMAP: mail.deck.local (o IP del servidor)
Puerto IMAP: 993 (SSL/TLS)
Servidor SMTP: mail.deck.local
Puerto SMTP: 465 (SSL/TLS)
Usuario: correo@dominio.com
Contraseña: (la que configuraste)
```
#### Verificar correos desde terminal
```bash
# Acceder al contenedor de Mailcow
docker exec -it mailcow-mailserver-1 bash
# Verificar logs de correos
tail -f /var/log/mail.log
# Salir
exit
```
### Caso 2: Usar Nextcloud (Gestor de Archivos)
#### Acceder a la interfaz web
```
URL: https://deck.local/nextcloud
o
URL: https://72.62.1.113/nextcloud
```
#### Crear usuario en Nextcloud
1. Accede como administrador
2. Haz clic en el icono de usuario (arriba a la derecha)
3. Selecciona **Usuarios**
4. Haz clic en **+ Nuevo usuario**
5. Completa:
- **Nombre de usuario**
- **Contraseña**
6. Asigna grupos si es necesario
7. Haz clic en **Crear**
#### Subir archivos
1. Accede a Nextcloud
2. Haz clic en **+ (botón azul)** → **Subir archivo**
3. Selecciona archivo desde tu computadora
4. El archivo se sincronizará automáticamente
#### Sincronizar con tu computadora
1. Descarga el cliente Nextcloud: https://nextcloud.com/install/
2. Instala y abre el cliente
3. Completa:
- **Servidor**: https://72.62.1.113/nextcloud
- **Usuario y contraseña**: Usa las credenciales de Nextcloud
4. Selecciona carpeta local para sincronizar
5. ¡Listo! Los archivos se sincronizarán automáticamente
### Caso 3: Gestionar Contraseñas con Vaultwarden
#### Acceder a Vaultwarden
```
URL: https://deck.local/vaultwarden
o
URL: https://72.62.1.113/vaultwarden
```
#### Crear cuenta
1. Haz clic en **Create account**
2. Completa:
- **Email**: Tu correo
- **Master password**: Contraseña maestra (muy importante, no la olvides)
3. Haz clic en **Create account**
#### Agregar contraseña
1. Accede a Vaultwarden
2. Haz clic en **+ New item** (botón azul)
3. Selecciona **Login**
4. Completa:
- **Name**: Nombre del servicio (ej: Gmail, GitHub)
- **Username**: Tu usuario
- **Password**: Tu contraseña (o genera una)
5. Haz clic en **Save**
#### Generar contraseña segura
1. Al crear/editar un login
2. Haz clic en el icono **🔄 Generate** junto al campo de contraseña
3. Ajusta las opciones:
- **Length**: Longitud (16+ recomendado)
- **Uppercase**: Incluir mayúsculas
- **Lowercase**: Incluir minúsculas
- **Numbers**: Incluir números
- **Special**: Incluir caracteres especiales
4. Haz clic en **Regenerate** hasta estar satisfecho
5. Haz clic en **Select**
#### Usar en otros dispositivos
- **Extensión navegador**: Bitwarden/Vaultwarden para Chrome, Firefox, Edge
- **Aplicación móvil**: Descargar "Bitwarden" desde App Store o Google Play
- **Sincronización**: Se sincroniza automáticamente entre dispositivos
### Caso 4: Usar context-manager para Chat IA
#### Acceder a context-manager
```bash
# Desde la terminal de DECK
ssh root@72.62.1.113
# Ir a la carpeta de context-manager
cd /root/captain-claude/context-manager
# Ver estado
docker ps | grep context
# O si se ejecuta como servicio
systemctl status context-manager
```
#### Configurar context-manager
```bash
# 1. Verificar archivo de configuración
cat /root/captain-claude/context-manager/.env
# Debe contener:
# - API_KEY de Anthropic o OpenAI
# - URL de PostgreSQL
# - Configuración de base de datos
# 2. Si necesitas cambiar configuración
nano /root/captain-claude/context-manager/.env
# 3. Reiniciar servicio
docker restart context-manager-app-1
# O si es servicio del sistema
systemctl restart context-manager
```
#### Usar context-manager desde API
```bash
# Ejemplo: Enviar consulta y obtener respuesta con contexto
curl -X POST http://localhost:8000/api/chat \
-H "Content-Type: application/json" \
-d '{
"message": "¿Cuál es la temperatura actual?",
"context_type": "sensor_data",
"session_id": "session-123"
}'
# Respuesta esperada:
# {
# "response": "La temperatura es de 22°C",
# "context_used": ["sensor_data"],
# "timestamp": "2025-01-15T10:30:00Z"
# }
```
#### Ver logs de context-manager
```bash
# Ver logs en tiempo real
docker logs -f context-manager-app-1
# O si es servicio del sistema
journalctl -u context-manager -f
```
---
## 3. Comandos Frecuentes
### Servicios y Estado
| Comando | Descripción |
|---------|-------------|
| `docker ps` | Ver contenedores activos |
| `docker ps -a` | Ver todos los contenedores |
| `docker logs -f nombre` | Ver logs en tiempo real |
| `docker restart nombre` | Reiniciar contenedor |
| `docker stop nombre` | Detener contenedor |
| `docker start nombre` | Iniciar contenedor |
| `systemctl status` | Ver estado de servicios del sistema |
| `systemctl restart nombre` | Reiniciar servicio |
### Base de Datos (PostgreSQL)
| Comando | Descripción |
|---------|-------------|
| `docker exec -it postgres psql -U postgres` | Acceder a psql |
| `\l` | Listar bases de datos (dentro de psql) |
| `\dt` | Listar tablas (dentro de psql) |
| `\du` | Listar usuarios (dentro de psql) |
| `\q` | Salir de psql |
### Sistema de Archivos
| Comando | Descripción |
|---------|-------------|
| `ls -la` | Listar archivos con detalles |
| `cd /ruta` | Cambiar de directorio |
| `pwd` | Mostrar directorio actual |
| `mkdir nombre` | Crear directorio |
| `cp archivo destino` | Copiar archivo |
| `mv archivo destino` | Mover archivo |
| `rm archivo` | Eliminar archivo |
| `rm -rf carpeta` | Eliminar carpeta completa |
### Red y Conectividad
| Comando | Descripción |
|---------|-------------|
| `ping host` | Verificar conexión |
| `netstat -tulpn` | Ver puertos en escucha |
| `curl http://url` | Hacer solicitud HTTP |
| `ss -tulpn` | Alternativa moderna a netstat |
| `dig dominio.com` | Resolver DNS |
| `nslookup dominio.com` | Alternativa a dig |
### SSH y Acceso Remoto
| Comando | Descripción |
|---------|-------------|
| `ssh root@72.62.1.113` | Conectar a DECK |
| `ssh-copy-id -i ~/.ssh/tzzr root@72.62.1.113` | Copiar clave SSH |
| `ssh -i ~/.ssh/tzzr root@72.62.1.113` | Conectar con clave específica |
| `scp archivo root@72.62.1.113:/destino` | Copiar archivo a servidor |
### Monitoreo y Rendimiento
| Comando | Descripción |
|---------|-------------|
| `top` | Monitor de procesos |
| `htop` | Monitor mejorado (si está instalado) |
| `df -h` | Espacio en disco |
| `du -sh carpeta` | Tamaño de carpeta |
| `free -h` | Uso de RAM |
| `uptime` | Tiempo de actividad del servidor |
---
## 4. Atajos y Tips Productivos
### Tips Generales
**1. Usa alias para comandos frecuentes**
```bash
# Editar ~/.bashrc
nano ~/.bashrc
# Agregar alias
alias ll='ls -la'
alias dc='docker ps'
alias psql-con='docker exec -it postgres-db-1 psql -U postgres'
# Guardar y aplicar cambios
source ~/.bashrc
```
**2. Historial de comandos**
```bash
# Ver últimos comandos
history
# Ejecutar comando anterior
!!
# Ejecutar comando que contiene "palabra"
!palabra
# Buscar en historial
Ctrl + R (luego escribe para buscar)
```
**3. Copiar/Pegar eficientemente**
```bash
# Copiar salida de comando
comando | xclip -selection clipboard
# O más simple, seleccionar con ratón en terminal
```
### Tips para Docker
**1. Ver logs en tiempo real con seguimiento de errores**
```bash
# Ver últimas 100 líneas
docker logs --tail 100 nombre_contenedor
# Ver con timestamp
docker logs -t nombre_contenedor
# Seguir logs en tiempo real
docker logs -f --tail 20 nombre_contenedor
```
**2. Ejecutar comandos dentro de contenedores**
```bash
# Acceso interactivo (bash)
docker exec -it nombre_contenedor bash
# Ejecutar comando específico
docker exec nombre_contenedor ls -la
# Con variable de entorno
docker exec -e VAR=valor nombre_contenedor comando
```
**3. Gestionar múltiples contenedores**
```bash
# Detener todos los contenedores
docker stop $(docker ps -q)
# Eliminar contenedores parados
docker container prune
# Ver uso de recursos
docker stats
```
### Tips para PostgreSQL
**1. Backups rápidos**
```bash
# Crear backup
docker exec postgres-db-1 pg_dump -U postgres nombre_base > backup.sql
# Restaurar backup
docker exec -i postgres-db-1 psql -U postgres < backup.sql
```
**2. Consultas útiles**
```bash
# Dentro de psql:
-- Ver tamaño de tablas
SELECT schemaname, tablename, pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename))
FROM pg_tables ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;
-- Ver conexiones activas
SELECT * FROM pg_stat_activity;
-- Matar conexión
SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname='base_datos';
```
### Tips para Nextcloud
**1. Sincronización manual**
```bash
# Forzar verificación de cambios
# (Espera 30 segundos en el cliente de Nextcloud)
# O rescanea el servidor
docker exec -it nextcloud-app-1 php occ files:scan --all
```
**2. Gestionar espacio**
```bash
# Ver uso de espacio en Nextcloud
docker exec -it nextcloud-app-1 php occ statistics:get
# Eliminar versiones antiguas (liberar espacio)
docker exec -it nextcloud-app-1 php occ versions:cleanup
```
### Tips para Vaultwarden
**1. Exportar contraseñas (Backup)**
```
En la interfaz de Vaultwarden:
1. Haz clic en icono de usuario → Settings
2. Selecciona "Import/Export"
3. Haz clic en "Export vault"
4. Guarda el archivo CSV en lugar seguro
```
**2. Importar desde otro gestor de contraseñas**
```
1. En el otro gestor (LastPass, 1Password, etc):
- Exporta en formato CSV
2. En Vaultwarden:
- Haz clic en usuario → Settings
- Selecciona "Import/Export"
- Haz clic en "Import"
- Selecciona archivo CSV
```
---
## Próximos Pasos
Si necesitas ayuda adicional:
- **Problemas técnicos**: Revisa logs con `docker logs -f nombre`
- **Configuración avanzada**: Ver DECK - Manual de Usuario PARTE 2
- **Solución de problemas**: Ver sección de Troubleshooting en el manual
- **Contacto**: Consulta con el administrador del sistema
Reference in New Issue View Git Blame Copy Permalink