trading-platform/docs/95-guias-desarrollo/PUERTOS-SERVICIOS.md

---
id: "PUERTOS-SERVICIOS"
title: "PUERTOS DE SERVICIOS - ORBIQUANT IA TRADING PLATFORM"
type: "Documentation"
project: "trading-platform"
version: "1.0.0"
updated_date: "2026-01-04"
---

# PUERTOS DE SERVICIOS - ORBIQUANT IA TRADING PLATFORM

**Documento:** Asignación de Puertos para Desarrollo y Producción
**Proyecto:** OrbiQuant IA Trading Platform
**Fecha:** 2025-12-05
**Estado:** Activo

---

## ÍNDICE

1. [Resumen Ejecutivo](#resumen-ejecutivo)
2. [Tabla de Puertos](#tabla-de-puertos)
3. [Servicios Detallados](#servicios-detallados)
4. [Configuración por Entorno](#configuración-por-entorno)
5. [Verificación de Puertos](#verificación-de-puertos)
6. [Troubleshooting](#troubleshooting)

---

## RESUMEN EJECUTIVO

Este documento centraliza la asignación de puertos para todos los servicios del proyecto OrbiQuant IA Trading Platform. Los puertos están organizados por bloques funcionales para facilitar la gestión de firewall y evitar conflictos.

### Principios de Asignación

- **Rango 3100-3199**: Servicios de Frontend (React/Vite)
- **Rango 4000-4099**: Servicios Backend (Node.js/Express)
- **Rango 5000-5099**: Servicios Python (FastAPI/AsyncIO)
- **Rango 5432-5433**: PostgreSQL (principal y testing)
- **Puerto 6379**: Redis (estándar)
- **Rango 8000-8099**: CI/CD y herramientas externas
- **Rango 9000-9099**: Monitoreo (Prometheus, Grafana)

### Archivo de Configuración Central

Todos los puertos están definidos en:
```
/home/isem/workspace/projects/trading-platform/.env.ports
```

---

## TABLA DE PUERTOS

### Servicios de Aplicación

| Servicio | Puerto | Protocolo | Estado | Descripción |
|----------|--------|-----------|--------|-------------|
| **Frontend Web** | 3100 | HTTP | Activo | Aplicación React principal (Vite dev server) |
| **Frontend Admin** | 3101 | HTTP | Reservado | Panel de administración (futuro) |
| **Frontend Preview** | 4173 | HTTP | Dev | Preview de build de Vite |
| **Backend API** | 4000 | HTTP | Activo | API REST principal (Express) |
| **Backend WebSocket** | 4001 | WS | Activo | WebSocket para real-time updates |
| **Backend Webhooks** | 4002 | HTTP | Reservado | Endpoint para webhooks externos |
| **ML Engine** | 5000 | HTTP | Activo | API de predicciones (FastAPI) |
| **Data Service** | 5001 | TCP | Activo | Sincronización de datos de mercado |
| **LLM Agent** | 5002 | HTTP | Planeado | Asistente inteligente (FastAPI) |
| **Portfolio Manager** | 5003 | HTTP | Planeado | Gestión de portafolios (FastAPI) |

### Infraestructura

| Servicio | Puerto | Protocolo | Estado | Descripción |
|----------|--------|-----------|--------|-------------|
| **PostgreSQL** | 5432 | TCP | Activo | Base de datos principal |
| **PostgreSQL Test** | 5433 | TCP | Dev | Instancia para testing |
| **Redis** | 6379 | TCP | Activo | Cache y message queues |
| **MySQL (Legacy)** | 3306 | TCP | Temporal | Solo para migración |

### CI/CD y Monitoreo

| Servicio | Puerto | Protocolo | Estado | Descripción |
|----------|--------|-----------|--------|-------------|
| **Jenkins** | 8080 | HTTP | Planeado | CI/CD pipeline |
| **Jenkins Agent** | 50000 | TCP | Planeado | Comunicación con agentes |
| **Prometheus** | 9090 | HTTP | Opcional | Métricas del sistema |
| **Grafana** | 3200 | HTTP | Opcional | Dashboards de monitoreo |

### Herramientas de Desarrollo

| Servicio | Puerto | Protocolo | Estado | Descripción |
|----------|--------|-----------|--------|-------------|
| **PgAdmin** | 5050 | HTTP | Opcional | Administración de PostgreSQL |
| **Mailhog SMTP** | 1025 | SMTP | Opcional | Testing de emails (SMTP) |
| **Mailhog Web** | 8025 | HTTP | Opcional | Testing de emails (Web UI) |

---

## SERVICIOS DETALLADOS

### Frontend Services

#### 1. Frontend Web (React + Vite)
- **Puerto**: `3100`
- **Comando Dev**: `npm run dev -- --port 3100`
- **URL**: `http://localhost:3100`
- **Variables de Entorno**:
  ```bash
  VITE_API_URL=http://localhost:4000/api/v1
  VITE_WS_URL=ws://localhost:4001
  ```

#### 2. Frontend Admin Panel (Futuro)
- **Puerto**: `3101`
- **Estado**: Reservado para separación de panel admin
- **URL**: `http://localhost:3101`

### Backend Services

#### 1. Backend API (Express)
- **Puerto**: `4000`
- **Archivo**: `/apps/backend/src/index.ts`
- **Comando**: `npm run dev`
- **Endpoints**:
  - API REST: `http://localhost:4000/api/v1`
  - Health: `http://localhost:4000/health`
  - Docs: `http://localhost:4000/api/v1/docs`
- **Variables de Entorno**:
  ```bash
  PORT=4000
  DB_PORT=5432
  REDIS_PORT=6379
  ML_ENGINE_URL=http://localhost:5000
  ```

#### 2. WebSocket Server
- **Puerto**: `4001`
- **Protocolo**: WebSocket (WS/WSS)
- **Uso**: Real-time charts, notifications, live prices
- **Conexión**: `ws://localhost:4001`

### Python Services

#### 1. ML Engine (FastAPI)
- **Puerto**: `5000`
- **Archivo**: `/apps/ml-engine/src/api/main.py`
- **Comando**: `uvicorn src.api.main:app --host 0.0.0.0 --port 5000 --reload`
- **Endpoints**:
  - API Docs: `http://localhost:5000/docs`
  - Health: `http://localhost:5000/health`
  - Predictions: `http://localhost:5000/predict/range`
- **Modelos Servidos**:
  - Range Predictor (ΔHigh/ΔLow)
  - TP/SL Classifier
  - Signal Generator

#### 2. Data Service (Python AsyncIO)
- **Puerto**: `5001`
- **Archivo**: `/apps/data-service/src/main.py`
- **Comando**: `python -m src.main`
- **Funciones**:
  - Sync de datos de Polygon.io cada 5min
  - Tracking de spreads desde MT4/MetaAPI
  - Entrenamiento de modelos de ajuste de precios
- **Variables de Entorno**:
  ```bash
  POLYGON_API_KEY=your_key
  METAAPI_TOKEN=your_token
  SYNC_INTERVAL_MINUTES=5
  ```

#### 3. LLM Agent API (Futuro)
- **Puerto**: `5002`
- **Estado**: Planeado (Módulo OQI-007)
- **Función**: Asistente inteligente con Claude/GPT

#### 4. Portfolio Manager (Futuro)
- **Puerto**: `5003`
- **Estado**: Planeado (Módulo OQI-008)
- **Función**: Gestión de portafolios de inversión

### Infrastructure Services

#### 1. PostgreSQL
- **Puerto**: `5432`
- **Estado**: ACTIVO (No cambiar)
- **Conexión**: `postgresql://orbiquant_user:password@localhost:5432/orbiquant_trading`
- **Schemas**:
  - `users` - Usuarios y autenticación
  - `market_data` - Datos de mercado
  - `trading` - Señales y operaciones
  - `education` - Contenido educativo
  - `investment` - Cuentas de inversión
  - `payments` - Suscripciones y pagos
  - `broker_integration` - Integración con brokers

#### 2. Redis
- **Puerto**: `6379`
- **Estado**: ACTIVO (No cambiar)
- **Conexión**: `redis://localhost:6379`
- **Uso**:
  - Session storage
  - Cache de queries
  - Message queues para jobs
  - Rate limiting

---

## CONFIGURACIÓN POR ENTORNO

### Desarrollo Local

Crear archivo `.env` en la raíz del proyecto:

```bash
# Copiar plantilla de puertos
cp .env.ports .env.local

# Variables de entorno específicas
NODE_ENV=development
POSTGRES_PASSWORD=orbiquant_dev_2025
JWT_ACCESS_SECRET=your-secret-min-32-chars
JWT_REFRESH_SECRET=your-secret-min-32-chars
STRIPE_SECRET_KEY=sk_test_...
POLYGON_API_KEY=your_polygon_key
```

### Docker Compose

El archivo `docker-compose.yml` usa los mismos puertos:

```bash
# Iniciar todos los servicios
docker-compose up -d

# Iniciar con herramientas de desarrollo
docker-compose --profile dev-tools up -d

# Ver logs
docker-compose logs -f backend

# Detener
docker-compose down
```

### Producción (Jenkins)

Jenkins usará los mismos puertos. Configurar en `.env.production`:

```bash
NODE_ENV=production
FRONTEND_WEB_PORT=3100
BACKEND_API_PORT=4000
ML_ENGINE_PORT=5000
POSTGRES_PORT=5432
REDIS_PORT=6379
```

---

## VERIFICACIÓN DE PUERTOS

### Comandos Útiles

#### Listar puertos en uso
```bash
# Todos los puertos TCP/UDP en escucha
ss -tuln | grep LISTEN

# Específico de un puerto
ss -tuln | grep :4000

# Usando netstat (si está instalado)
netstat -tuln | grep LISTEN
```

#### Verificar servicio en puerto
```bash
# Verificar con curl
curl http://localhost:4000/health

# Verificar con telnet
telnet localhost 4000

# Verificar proceso usando puerto
lsof -i :4000
```

#### Matar proceso en puerto
```bash
# Encontrar PID
lsof -t -i :4000

# Matar proceso
kill -9 $(lsof -t -i :4000)
```

### Script de Verificación

Crear `/scripts/check-ports.sh`:

```bash
#!/bin/bash

echo "=== OrbiQuant Port Status ==="
echo ""

declare -A services=(
  ["Frontend Web"]="3100"
  ["Backend API"]="4000"
  ["Backend WS"]="4001"
  ["ML Engine"]="5000"
  ["Data Service"]="5001"
  ["PostgreSQL"]="5432"
  ["Redis"]="6379"
)

for service in "${!services[@]}"; do
  port=${services[$service]}
  if ss -tuln | grep -q ":$port "; then
    echo "✓ $service (port $port) - RUNNING"
  else
    echo "✗ $service (port $port) - NOT RUNNING"
  fi
done
```

Ejecutar:
```bash
chmod +x scripts/check-ports.sh
./scripts/check-ports.sh
```

---

## TROUBLESHOOTING

### Problema: Puerto ya en uso

**Síntoma**: Error `EADDRINUSE` o `Address already in use`

**Solución**:
```bash
# 1. Identificar proceso
lsof -i :3100

# 2. Matar proceso
kill -9 <PID>

# 3. Usar puerto alternativo temporalmente
PORT=3200 npm run dev
```

### Problema: No se puede conectar al servicio

**Verificar**:
1. Servicio está corriendo: `ss -tuln | grep :4000`
2. Firewall permite conexión: `sudo ufw status`
3. Variables de entorno correctas: `echo $BACKEND_API_PORT`
4. Logs del servicio: `docker-compose logs backend`

### Problema: CORS en desarrollo

**Causa**: Frontend en puerto diferente al configurado

**Solución**: Actualizar `CORS_ORIGINS` en backend `.env`:
```bash
CORS_ORIGINS=http://localhost:3100,http://localhost:4173
```

### Problema: WebSocket no conecta

**Verificar**:
1. Backend WS está corriendo en puerto 4001
2. Frontend usa `ws://` (no `wss://`) en desarrollo
3. No hay proxy inverso bloqueando WS

---

## ACTUALIZACIÓN DE PUERTOS

Si necesitas cambiar un puerto:

1. **Actualizar** `/home/isem/workspace/projects/trading-platform/.env.ports`
2. **Actualizar** este documento
3. **Actualizar** `docker-compose.yml`
4. **Actualizar** archivos `.env` de cada servicio:
   - `/apps/backend/.env`
   - `/apps/frontend/.env`
   - `/apps/ml-engine/.env`
   - `/apps/data-service/.env`
5. **Reiniciar** servicios afectados
6. **Notificar** al equipo del cambio

---

## REFERENCIAS

- **Archivo de puertos**: `/home/isem/workspace/projects/trading-platform/.env.ports`
- **Docker Compose**: `/home/isem/workspace/projects/trading-platform/docker-compose.yml`
- **Config Backend**: `/home/isem/workspace/projects/trading-platform/apps/backend/.env.example`
- **Config Frontend**: `/home/isem/workspace/projects/trading-platform/apps/frontend/vite.config.ts`
- **Config ML Engine**: `/home/isem/workspace/projects/trading-platform/apps/ml-engine/src/api/main.py`
- **Config Data Service**: `/home/isem/workspace/projects/trading-platform/apps/data-service/src/main.py`

---

**Última Actualización**: 2025-12-05
**Mantenedor**: DevEnv Agent
**Contacto**: Equipo de Desarrollo OrbiQuant