9f3a4214d3
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>
413 lines
11 KiB
Markdown
413 lines
11 KiB
Markdown
# MANUAL DE USUARIO - ARCHITECT (Servidor Central TZZR)
|
|
|
|
## Introducción
|
|
|
|
ARCHITECT es el coordinador central del sistema TZZR alojado en el servidor 69.62.126.110. Este manual describe los servicios, herramientas y procedimientos para trabajar en el servidor central.
|
|
|
|
## Información del Servidor
|
|
|
|
| Aspecto | Detalles |
|
|
|--------|----------|
|
|
| **IP** | 69.62.126.110 |
|
|
| **Usuario** | architect |
|
|
| **Ubicación** | Servidor Central TZZR |
|
|
| **Rol** | Coordinador multiagente, gestión de servicios |
|
|
|
|
## Servicios Disponibles
|
|
|
|
### 1. Gitea (Control de Versiones)
|
|
|
|
**Puerto**: 3000
|
|
**URL**: http://69.62.126.110:3000
|
|
**Uso**: Repositorio central de código para todos los proyectos
|
|
|
|
#### Características:
|
|
- Hospedaje de repositorios Git
|
|
- Interfaz web para gestión de código
|
|
- Integración con pipelines de CI/CD
|
|
- Backup automático en R2
|
|
|
|
#### Acceso:
|
|
```bash
|
|
# Clonar repositorio
|
|
git clone http://69.62.126.110:3000/architect/[repo-name].git
|
|
|
|
# Ver estado de repositorio
|
|
cd /home/architect/[repo-name]
|
|
git status
|
|
git log --oneline
|
|
```
|
|
|
|
### 2. PostgreSQL (Base de Datos)
|
|
|
|
**Puerto**: 5432
|
|
**Usuario**: architect
|
|
**Base de datos**: TTZR (por defecto)
|
|
**Uso**: Almacenamiento central de datos persistentes
|
|
|
|
#### Características:
|
|
- Base de datos relacional centralizada
|
|
- Backups automáticos en R2
|
|
- Esquemas versionados
|
|
- Logs de auditoría
|
|
|
|
#### Conexión:
|
|
```bash
|
|
# Conectar a PostgreSQL
|
|
psql -h localhost -U architect -d TTZR
|
|
|
|
# Comandos básicos en psql:
|
|
\dt # Listar tablas
|
|
\d [tabla] # Ver estructura de tabla
|
|
SELECT * FROM [tabla] LIMIT 10; # Consultar datos
|
|
```
|
|
|
|
## Acceso a Servidores Remotos
|
|
|
|
Tienes acceso SSH a tres servidores remotos via la clave `~/.ssh/tzzr`:
|
|
|
|
### Servidores Disponibles
|
|
|
|
| Servidor | IP | Acceso | Rol |
|
|
|----------|-----|--------|-----|
|
|
| **deck** | 72.62.1.113 | root@72.62.1.113 | GPU/Computación |
|
|
| **corp** | 92.112.181.188 | root@92.112.181.188 | Servicios corporativos |
|
|
| **hst** | 72.62.2.84 | root@72.62.2.84 | HST-API + Directus |
|
|
|
|
#### Conectar a servidor remoto:
|
|
```bash
|
|
# Conexión general
|
|
ssh root@[IP] -i ~/.ssh/tzzr
|
|
|
|
# Ejemplos:
|
|
ssh root@72.62.1.113 -i ~/.ssh/tzzr # Conectar a deck
|
|
ssh root@92.112.181.188 -i ~/.ssh/tzzr # Conectar a corp
|
|
ssh root@72.62.2.84 -i ~/.ssh/tzzr # Conectar a hst
|
|
```
|
|
|
|
## Almacenamiento R2 (Cloudflare)
|
|
|
|
### Configuración
|
|
|
|
**Endpoint**: https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
|
**Bucket**: architect
|
|
**Acceso**: via AWS CLI
|
|
|
|
### Estructura de Carpetas R2
|
|
|
|
```
|
|
s3://architect/
|
|
├── documentos adjuntos/ # Documentos para compartir con usuario
|
|
├── documentos adjuntos/architect/ # Reportes y documentación generada
|
|
├── system/ # Configs, backups internos, manuales
|
|
├── gpu-services/ # Servicios GRACE/PENNY/FACTORY
|
|
├── backups/ # Backups automáticos de Gitea/PostgreSQL
|
|
└── auditorias/ # Logs de auditoría y eventos
|
|
```
|
|
|
|
### Comandos R2 Básicos
|
|
|
|
#### Listar contenido:
|
|
```bash
|
|
# Listar raíz de bucket
|
|
aws s3 ls s3://architect/ --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
|
|
|
# Listar carpeta específica
|
|
aws s3 ls s3://architect/system/ --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
|
|
|
# Listar recursivamente
|
|
aws s3 ls s3://architect/system/ --recursive --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
|
```
|
|
|
|
#### Subir archivos:
|
|
```bash
|
|
# Subir documento para usuario
|
|
aws s3 cp archivo.md "s3://architect/documentos adjuntos/archivo.md" \
|
|
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
|
|
|
# Subir a system (configs, manuales, backups internos)
|
|
aws s3 cp archivo "s3://architect/system/archivo" \
|
|
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
|
|
|
# Subir carpeta completa
|
|
aws s3 cp carpeta/ "s3://architect/system/carpeta/" --recursive \
|
|
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
|
```
|
|
|
|
#### Descargar archivos:
|
|
```bash
|
|
# Descargar archivo individual
|
|
aws s3 cp "s3://architect/system/archivo" ./archivo \
|
|
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
|
|
|
# Descargar carpeta recursivamente
|
|
aws s3 cp "s3://architect/system/carpeta/" ./ --recursive \
|
|
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
|
```
|
|
|
|
## Gestión de Backups
|
|
|
|
### Backups Automáticos
|
|
|
|
El sistema realiza backups automáticos de:
|
|
- **Gitea**: Repositorios y base de datos Gitea
|
|
- **PostgreSQL**: Base de datos TTZR
|
|
- Almacenados en: `s3://architect/backups/`
|
|
|
|
### Restaurar desde Backup
|
|
|
|
```bash
|
|
# Listar backups disponibles
|
|
aws s3 ls s3://architect/backups/ --recursive \
|
|
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
|
|
|
# Descargar backup
|
|
aws s3 cp "s3://architect/backups/[backup-name]" ./ \
|
|
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
|
|
|
# Restaurar PostgreSQL desde dump
|
|
psql -h localhost -U architect -d TTZR < backup.sql
|
|
```
|
|
|
|
## Uso de context-manager Local
|
|
|
|
context-manager es una herramienta local para gestionar contexto de aplicaciones y bases de datos.
|
|
|
|
### Ubicación
|
|
```
|
|
/home/architect/captain-claude/context-manager/
|
|
```
|
|
|
|
### Estructura
|
|
|
|
```
|
|
context-manager/
|
|
├── schemas/ # Esquemas SQL versionados
|
|
│ ├── 00_base.sql
|
|
│ ├── 01_immutable_log.sql
|
|
│ ├── 02_context_manager.sql
|
|
│ └── 03_algorithm_engine.sql
|
|
├── src/ # Código Python
|
|
│ ├── database.py # Conexión y operaciones BD
|
|
│ ├── models.py # Modelos de datos
|
|
│ ├── context_selector.py
|
|
│ └── providers/ # Proveedores de IA
|
|
│ ├── base.py
|
|
│ ├── anthropic.py
|
|
│ └── openai.py
|
|
└── tests/ # Tests
|
|
```
|
|
|
|
### Uso Básico
|
|
|
|
#### 1. Inicializar base de datos
|
|
```bash
|
|
cd /home/architect/captain-claude/context-manager
|
|
python -m src.database init
|
|
|
|
# Ver estado de BD
|
|
python -m src.database status
|
|
```
|
|
|
|
#### 2. Guardar contexto
|
|
```python
|
|
from src.database import ContextManager
|
|
|
|
cm = ContextManager()
|
|
|
|
# Guardar contexto
|
|
cm.save_context(
|
|
context_id="task-123",
|
|
content="Descripción de la tarea",
|
|
metadata={"project": "skynet", "version": 8}
|
|
)
|
|
```
|
|
|
|
#### 3. Recuperar contexto
|
|
```python
|
|
# Recuperar contexto
|
|
context = cm.get_context("task-123")
|
|
print(context.content)
|
|
print(context.metadata)
|
|
|
|
# Listar contextos
|
|
contexts = cm.list_contexts(project="skynet")
|
|
```
|
|
|
|
#### 4. Seleccionar contexto (IA)
|
|
```python
|
|
# Seleccionar contexto óptimo con IA
|
|
selected = cm.select_context_ai(
|
|
query="Necesito información sobre arquitectura",
|
|
provider="anthropic" # o "openai"
|
|
)
|
|
```
|
|
|
|
### Variables de Entorno Requeridas
|
|
|
|
```bash
|
|
# En ~/.bashrc o ~/.env
|
|
export ANTHROPIC_API_KEY="sk-ant-..."
|
|
export OPENAI_API_KEY="sk-..."
|
|
export DATABASE_URL="postgresql://architect@localhost/TTZR"
|
|
```
|
|
|
|
## Flujo de Trabajo Diario
|
|
|
|
### 1. Verificar Estado del Sistema
|
|
```bash
|
|
# Ver servicios activos
|
|
systemctl status
|
|
|
|
# Ver logs de Gitea
|
|
tail -f /var/log/gitea/gitea.log
|
|
|
|
# Ver conexión a PostgreSQL
|
|
psql -h localhost -U architect -d TTZR -c "SELECT version();"
|
|
```
|
|
|
|
### 2. Gestionar Repositorios
|
|
```bash
|
|
# Clonar nuevo repo desde Gitea
|
|
git clone http://69.62.126.110:3000/architect/[proyecto].git
|
|
|
|
# Trabajar localmente
|
|
cd [proyecto]
|
|
git checkout -b feature/[nombre]
|
|
# ... realizar cambios ...
|
|
git add .
|
|
git commit -m "Descripción de cambios"
|
|
git push origin feature/[nombre]
|
|
|
|
# En Gitea: crear Pull Request y revisar
|
|
```
|
|
|
|
### 3. Manejar Datos
|
|
```bash
|
|
# Backup de BD antes de cambios importantes
|
|
pg_dump -h localhost -U architect TTZR > backup-$(date +%Y%m%d).sql
|
|
|
|
# Exportar desde R2
|
|
aws s3 cp "s3://architect/backups/" ./backups/ --recursive \
|
|
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
|
```
|
|
|
|
### 4. Documentar y Archivar
|
|
```bash
|
|
# Generar documentación
|
|
# ... crear archivos .md ...
|
|
|
|
# Subir a R2
|
|
aws s3 cp reporte.md "s3://architect/documentos adjuntos/architect/reporte.md" \
|
|
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
|
|
|
# Verificar subida
|
|
aws s3 ls "s3://architect/documentos adjuntos/architect/" \
|
|
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
|
|
|
# Limpiar local
|
|
rm reporte.md
|
|
```
|
|
|
|
## Seguridad y Mejores Prácticas
|
|
|
|
### SSH
|
|
- Usa siempre la clave `~/.ssh/tzzr` para conectar a servidores remotos
|
|
- Nunca compartas las claves SSH
|
|
- Mantén permisos restrictivos: `chmod 600 ~/.ssh/tzzr`
|
|
|
|
### Credenciales
|
|
- Nunca commits credenciales en Gitea
|
|
- Usa variables de entorno para API keys
|
|
- Rota credenciales regularmente
|
|
|
|
### R2
|
|
- Verifica siempre que archivos se suban correctamente
|
|
- No guardes documentos en el filesystem local
|
|
- Limpia archivos locales después de subirlos a R2
|
|
|
|
### Base de Datos
|
|
- Realiza backups antes de cambios estructurales
|
|
- Usa transacciones para operaciones críticas
|
|
- Revisa logs de auditoría regularmente
|
|
|
|
## Troubleshooting
|
|
|
|
### No puedo conectar a PostgreSQL
|
|
```bash
|
|
# Verificar que PostgreSQL está activo
|
|
systemctl status postgresql
|
|
|
|
# Verificar permisos
|
|
sudo -u postgres psql -c "SELECT * FROM pg_user WHERE usename = 'architect';"
|
|
|
|
# Reiniciar si es necesario
|
|
sudo systemctl restart postgresql
|
|
```
|
|
|
|
### Error al subir a R2
|
|
```bash
|
|
# Verificar credenciales AWS configuradas
|
|
aws configure
|
|
|
|
# Verificar conectividad
|
|
aws s3 ls s3://architect/ --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
|
|
|
# Reintentar con --no-progress para más info
|
|
aws s3 cp archivo s3://architect/system/archivo --no-progress \
|
|
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
|
```
|
|
|
|
### Gitea no responde
|
|
```bash
|
|
# Ver logs
|
|
tail -f /var/log/gitea/gitea.log
|
|
|
|
# Reiniciar servicio
|
|
sudo systemctl restart gitea
|
|
|
|
# Verificar puerto
|
|
netstat -tlnp | grep 3000
|
|
```
|
|
|
|
## Contacto y Soporte
|
|
|
|
Para problemas con los servicios o el servidor:
|
|
1. Revisa los logs relevantes
|
|
2. Verifica el estado del servicio
|
|
3. Consulta la documentación en `s3://architect/system/`
|
|
4. Contacta al administrador del sistema
|
|
|
|
## Referencias Rápidas
|
|
|
|
### Puertos Importantes
|
|
- **Gitea**: 3000
|
|
- **PostgreSQL**: 5432
|
|
- **SSH**: 22
|
|
|
|
### Directorios Importantes
|
|
- Proyectos: `/home/architect/captain-claude/`
|
|
- Backups locales: `/home/architect/backups/`
|
|
- Logs: `/var/log/`
|
|
|
|
### Comandos Frecuentes
|
|
```bash
|
|
# Actualizar repositorio
|
|
cd /home/architect/[proyecto] && git pull
|
|
|
|
# Ver últimos cambios
|
|
git log --oneline -10
|
|
|
|
# Conectar a BD
|
|
psql -h localhost -U architect -d TTZR
|
|
|
|
# Listar en R2
|
|
aws s3 ls s3://architect/system/ --recursive \
|
|
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
|
```
|
|
|
|
---
|
|
|
|
**Última actualización**: Diciembre 2025
|
|
**Versión**: 1.0
|