Manual Técnico de Operación - Odisa Tools

? Índice

Información General
Acceso al Servidor
Scripts de Control
Inicio de la Aplicación
Detención de la Aplicación
Monitoreo y Logs
Solución de Problemas
Mantenimiento

1. Información General

Arquitectura del Sistema

Aplicación: Flask (Python)
Servidor Web: Gunicorn (producción) / Flask dev server (desarrollo)
Puerto: 8001
Proxy: Nginx (opcional)
Ubicación: /volume1/web/odisa-tools/
IP del Servidor: 192.168.2.22

Componentes Principales

app.py: Aplicación principal Flask
wsgi.py: Punto de entrada para Gunicorn
logs/: Directorio de logs
uploads/: Archivos temporales
data/: Datos de usuarios y configuración

2. Acceso al Servidor

Conexión SSH

Para acceder al servidor, es NECESARIO usar un usuario con privilegios de administrador.

# Conexión SSH con usuario administrador ssh admin@192.168.2.22 
# O si tienes otro usuario administrador ssh [usuario_admin]@192.168.2.22

⚠️ IMPORTANTE:

La dirección IP del servidor es 192.168.2.22
DEBE usar un usuario con permisos de administrador
No funcionará con usuarios regulares sin privilegios

Primer Acceso

# 1. Conectarse al servidor ssh admin@192.168.2.22 
# 2. Navegar al directorio de la aplicación cd /volume1/web/odisa-tools 
# 3. Verificar que estás en el directorio correcto pwd # Debe mostrar: /volume1/web/odisa-tools

3. Scripts de Control

3.1 Script de Inicio (`start.sh`)

Crear el archivo start.sh en /volume1/web/odisa-tools/:

#!/bin/bash # start.sh - Script de inicio para Odisa Tools 
# Colores para output RED='\033[0;31m' GREEN='\033[0;32m' YELLOW='\033[1;33m' NC='\033[0m' # No Color 
# Configuración APP_DIR="/volume1/web/odisa-tools" PORT=8001 PID_FILE="$APP_DIR/odisa_tools.pid" LOG_FILE="$APP_DIR/logs/startup.log" 
echo -e "${GREEN}========================================${NC}" echo -e "${GREEN}   Iniciando Odisa Tools${NC}" echo -e "${GREEN}========================================${NC}" 
# Verificar si ya está corriendo if [ -f "$PID_FILE" ]; then    PID=$(cat $PID_FILE)    if ps -p $PID > /dev/null 2>&1; then        echo -e "${YELLOW}⚠️  La aplicación ya está corriendo (PID: $PID)${NC}"        exit 1    else        echo -e "${YELLOW}Removiendo archivo PID obsoleto...${NC}"        rm $PID_FILE    fi fi 
# Cambiar al directorio de la aplicación cd $APP_DIR || exit 1 
# Verificar entorno virtual if [ ! -d "venv" ]; then    echo -e "${RED}❌ Error: No se encuentra el entorno virtual${NC}"    echo "Ejecute: python3 -m venv venv"    exit 1 fi 
# Activar entorno virtual echo "? Activando entorno virtual..." source venv/bin/activate 
# Verificar dependencias echo "? Verificando dependencias..." pip list | grep Flask > /dev/null 2>&1 if [ $? -ne 0 ]; then    echo -e "${YELLOW}? Instalando dependencias...${NC}"    pip install -r requirements.txt fi 
# Crear directorios necesarios echo "? Verificando directorios..." mkdir -p logs uploads data/users 
# Limpiar logs antiguos si son muy grandes (>100MB) if [ -f "logs/odisa_tools.log" ]; then    LOG_SIZE=$(du -m "logs/odisa_tools.log" | cut -f1)    if [ $LOG_SIZE -gt 100 ]; then        echo "? Rotando logs antiguos..."        mv logs/odisa_tools.log logs/odisa_tools.log.$(date +%Y%m%d)    fi fi 
# Seleccionar modo de inicio echo "" echo "Seleccione el modo de inicio:" echo "1) Desarrollo (Flask debug)" echo "2) Producción (Gunicorn)" echo -n "Opción [1-2]: " read -r MODO 
case $MODO in    1)        echo -e "${GREEN}? Iniciando en modo DESARROLLO...${NC}"        echo "Logs en: $LOG_FILE"        nohup python app.py > "$LOG_FILE" 2>&1 &        PID=$!        ;;    2)        echo -e "${GREEN}? Iniciando en modo PRODUCCIÓN...${NC}"        echo "Logs en: $LOG_FILE"        nohup gunicorn --bind 127.0.0.1:$PORT \                       --workers 2 \                       --threads 2 \                       --timeout 120 \                       --access-logfile logs/access.log \                       --error-logfile logs/error.log \                       wsgi:app > "$LOG_FILE" 2>&1 &        PID=$!        ;;    *)        echo -e "${RED}❌ Opción inválida${NC}"        exit 1        ;; esac 
# Guardar PID echo $PID > $PID_FILE 
# Esperar a que inicie echo -n "⏳ Esperando que la aplicación inicie" for i in {1..10}; do    sleep 1    echo -n "."    curl -s http://localhost:$PORT > /dev/null 2>&1    if [ $? -eq 0 ]; then        echo ""        echo -e "${GREEN}✅ Aplicación iniciada exitosamente${NC}"        echo ""        echo "? Información del servicio:"        echo "   - PID: $PID"        echo "   - Puerto: $PORT"        echo "   - URL Local: http://localhost:$PORT"        echo "   - URL Red: http://192.168.2.22:$PORT"        echo "   - Logs: $APP_DIR/logs/odisa_tools.log"        echo ""        echo -e "${GREEN}========================================${NC}"        exit 0    fi done 
echo "" echo -e "${RED}❌ Error: La aplicación no respondió después de 10 segundos${NC}" echo "Revise los logs en: $LOG_FILE" kill $PID 2>/dev/null rm $PID_FILE exit 1

3.2 Script de Detención (`stop_odisa_tools.sh`)

Crear el archivo stop_odisa_tools.sh en /volume1/web/odisa-tools/:

#!/bin/bash # stop_odisa_tools.sh - Script de detención para Odisa Tools 
# Colores RED='\033[0;31m' GREEN='\033[0;32m' YELLOW='\033[1;33m' NC='\033[0m' 
# Configuración APP_DIR="/volume1/web/odisa-tools" PORT=8001 PID_FILE="$APP_DIR/odisa_tools.pid" 
echo -e "${YELLOW}========================================${NC}" echo -e "${YELLOW}   Deteniendo Odisa Tools${NC}" echo -e "${YELLOW}========================================${NC}" 
# Método 1: Usar PID file if [ -f "$PID_FILE" ]; then    PID=$(cat $PID_FILE)    echo "? PID encontrado en archivo: $PID"        if ps -p $PID > /dev/null 2>&1; then        echo "? Deteniendo proceso $PID..."        kill $PID        sleep 2                # Verificar si se detuvo        if ps -p $PID > /dev/null 2>&1; then            echo -e "${YELLOW}⚠️  El proceso no respondió, forzando detención...${NC}"            kill -9 $PID        fi                rm $PID_FILE        echo -e "${GREEN}✅ Proceso detenido exitosamente${NC}"    else        echo -e "${YELLOW}⚠️  El proceso $PID no está corriendo${NC}"        rm $PID_FILE    fi else    echo "? No se encontró archivo PID, buscando procesos..." fi 
# Método 2: Buscar procesos por puerto echo "" echo "? Buscando procesos en puerto $PORT..." PIDS=$(lsof -ti:$PORT) 
if [ ! -z "$PIDS" ]; then    echo "Procesos encontrados: $PIDS"    for PID in $PIDS; do        echo "? Deteniendo proceso $PID..."        kill $PID 2>/dev/null    done    sleep 2        # Verificar si quedan procesos    REMAINING=$(lsof -ti:$PORT)    if [ ! -z "$REMAINING" ]; then        echo -e "${YELLOW}⚠️  Forzando detención de procesos restantes...${NC}"        for PID in $REMAINING; do            kill -9 $PID 2>/dev/null        done    fi    echo -e "${GREEN}✅ Procesos detenidos${NC}" else    echo "No se encontraron procesos en el puerto $PORT" fi 
# Método 3: Buscar procesos Python/Gunicorn relacionados echo "" echo "? Buscando procesos de la aplicación..." PYTHON_PIDS=$(ps aux | grep -E "(python.*app\.py|gunicorn.*wsgi:app)" | grep -v grep | awk '{print $2}') 
if [ ! -z "$PYTHON_PIDS" ]; then    echo "Procesos Python/Gunicorn encontrados:"    for PID in $PYTHON_PIDS; do        ps -p $PID -o pid,cmd --no-headers        echo -n "¿Detener proceso $PID? [s/N]: "        read -r CONFIRM        if [ "$CONFIRM" = "s" ] || [ "$CONFIRM" = "S" ]; then            kill $PID 2>/dev/null            echo "Proceso $PID detenido"        fi    done fi 
# Limpiar archivos temporales echo "" echo "? Limpiando archivos temporales..." rm -f $APP_DIR/*.pid rm -f $APP_DIR/*.sock 
echo "" echo -e "${GREEN}========================================${NC}" echo -e "${GREEN}   Odisa Tools detenido${NC}" echo -e "${GREEN}========================================${NC}"

3.3 Script de Reinicio (`restart.sh`)

#!/bin/bash # restart.sh - Reinicia Odisa Tools 
echo "? Reiniciando Odisa Tools..." echo "" 
# Detener ./stop_odisa_tools.sh 
echo "" echo "⏳ Esperando 3 segundos..." sleep 3 echo "" 
# Iniciar ./start.sh

3.4 Script de Estado (`status.sh`)

#!/bin/bash # status.sh - Verifica el estado de Odisa Tools 
# Colores GREEN='\033[0;32m' RED='\033[0;31m' YELLOW='\033[1;33m' NC='\033[0m' 
APP_DIR="/volume1/web/odisa-tools" PORT=8001 PID_FILE="$APP_DIR/odisa_tools.pid" 
echo "=========================================" echo "   Estado de Odisa Tools" echo "=========================================" echo "" echo "? Servidor: 192.168.2.22" echo "? Directorio: $APP_DIR" echo "? Puerto: $PORT" echo "" 
# Verificar PID file if [ -f "$PID_FILE" ]; then    PID=$(cat $PID_FILE)    if ps -p $PID > /dev/null 2>&1; then        echo -e "Estado: ${GREEN}● ACTIVO${NC}"        echo "PID: $PID"        echo "Proceso:"        ps -p $PID -o pid,vsz,rss,pcpu,pmem,cmd --no-headers    else        echo -e "Estado: ${RED}● INACTIVO${NC} (PID file obsoleto)"    fi else    echo -e "Estado: ${YELLOW}● DESCONOCIDO${NC} (sin PID file)" fi 
# Verificar puerto echo "" echo "Puerto $PORT:" lsof -i:$PORT 2>/dev/null if [ $? -ne 0 ]; then    echo "  No hay procesos escuchando" fi 
# Verificar conectividad echo "" echo "Prueba de conectividad:" curl -s -o /dev/null -w "  HTTP Code: %{http_code}\n  Tiempo: %{time_total}s\n" http://localhost:$PORT 
# URLs de acceso echo "" echo "URLs de acceso:" echo "  - Local: http://localhost:$PORT" echo "  - Red: http://192.168.2.22:$PORT" 
# Espacio en disco echo "" echo "Espacio en disco:" df -h $APP_DIR | tail -1 
# Logs recientes echo "" echo "Últimas líneas del log:" tail -5 $APP_DIR/logs/odisa_tools.log 2>/dev/null || echo "  No se puede leer el log" 
echo "========================================="

4. Inicio de la Aplicación

Procedimiento de Inicio Completo

Conectarse al servidor con usuario administrador:

ssh admin@192.168.2.22 # Ingresar contraseña del usuario administrador

Navegar al directorio de la aplicación:

cd /volume1/web/odisa-tools

Verificar ubicación actual:

pwd # Debe mostrar: /volume1/web/odisa-tools

Dar permisos de ejecución a los scripts (solo la primera vez):

chmod +x start.sh stop_odisa_tools.sh restart.sh status.sh

Iniciar la aplicación:

./start.sh # Seleccionar opción 1 para desarrollo o 2 para producción

Verificar que la aplicación esté funcionando:

./status.sh

Acceder a la aplicación desde el navegador:
- Abrir navegador web
- Ingresar: http://192.168.2.22:8001

Inicio Rápido (después de la configuración inicial)

# Conectarse ssh admin@192.168.2.22 
# Ir al directorio cd /volume1/web/odisa-tools 
# Iniciar ./start.sh

Inicio Automático al Arranque del Sistema

Crear servicio systemd (si está disponible):

sudo nano /etc/systemd/system/odisa-tools.service

Contenido del archivo:

[Unit] Description=Odisa Tools Application After=network.target 
[Service] Type=forking User=admin WorkingDirectory=/volume1/web/odisa-tools Environment="PATH=/volume1/web/odisa-tools/venv/bin" ExecStart=/volume1/web/odisa-tools/start.sh ExecStop=/volume1/web/odisa-tools/stop_odisa_tools.sh PIDFile=/volume1/web/odisa-tools/odisa_tools.pid Restart=on-failure 
[Install] WantedBy=multi-user.target

Habilitar el servicio:

sudo systemctl daemon-reload sudo systemctl enable odisa-tools sudo systemctl start odisa-tools

5. Detención de la Aplicación

Detención Normal

# Conectarse al servidor ssh admin@192.168.2.22 
# Ir al directorio cd /volume1/web/odisa-tools 
# Detener la aplicación ./stop_odisa_tools.sh

Detención de Emergencia

Si el script de detención no funciona:

# Matar todos los procesos en el puerto sudo kill -9 $(lsof -ti:8001) 
# O buscar y matar procesos Python específicos ps aux | grep "python.*app.py" | grep -v grep | awk '{print $2}' | xargs kill -9

6. Monitoreo y Logs

Ubicación de Logs

Principal: /volume1/web/odisa-tools/logs/odisa_tools.log
Acceso HTTP: /volume1/web/odisa-tools/logs/access.log
Errores: /volume1/web/odisa-tools/logs/error.log
Inicio: /volume1/web/odisa-tools/logs/startup.log

Monitoreo en Tiempo Real

# Conectarse primero ssh admin@192.168.2.22 cd /volume1/web/odisa-tools 
# Ver logs en tiempo real tail -f logs/odisa_tools.log 
# Filtrar por errores tail -f logs/odisa_tools.log | grep ERROR 
# Ver logs de eliminación de productos tail -f logs/odisa_tools.log | grep -i "elimina" 
# Monitorear estado cada 2 segundos watch -n 2 './status.sh'

Análisis de Logs

# Contar errores del día grep "$(date '+%Y-%m-%d')" logs/odisa_tools.log | grep -c ERROR 
# Ver operaciones por usuario grep "Usuario: admin" logs/odisa_tools.log | tail -20 
# Buscar problemas de API grep -i "error.*bitrix\|error.*sap" logs/odisa_tools.log 
# Ver últimas eliminaciones grep "eliminación" logs/odisa_tools.log | tail -10

7. Solución de Problemas

Problema: No puedo conectarme por SSH

Verificar:

Usar usuario administrador: ssh admin@192.168.2.22
Verificar conectividad: ping 192.168.2.22
Verificar que SSH esté habilitado en el servidor

Problema: La aplicación no inicia

Diagnóstico:

# Verificar puerto ocupado lsof -i:8001 
# Ver logs de inicio cat logs/startup.log 
# Verificar permisos ls -la logs/ uploads/ 
# Verificar Python python3 --version

Soluciones:

Puerto ocupado: Ejecutar ./stop_odisa_tools.sh primero
Permisos incorrectos: chmod -R 755 logs uploads
Falta entorno virtual: python3 -m venv venv
Faltan dependencias: source venv/bin/activate && pip install -r requirements.txt

Problema: Error 502 Bad Gateway

Diagnóstico:

# Verificar si la app responde curl http://localhost:8001 
# Ver estado ./status.sh 
# Revisar logs tail -50 logs/odisa_tools.log

Solución:

# Reiniciar la aplicación ./restart.sh

Problema: No puedo acceder desde el navegador

Verificar:

La aplicación está corriendo: ./status.sh
Firewall permite puerto 8001
URL correcta: http://192.168.2.22:8001
No usar HTTPS (es HTTP)

Problema: Logs muy grandes

Solución manual:

# Rotar logs cd /volume1/web/odisa-tools mv logs/odisa_tools.log logs/odisa_tools.log.$(date +%Y%m%d) touch logs/odisa_tools.log 
# Limpiar logs antiguos (más de 30 días) find logs/ -name "*.log.*" -mtime +30 -delete

Solución automática con crontab:

# Editar crontab como admin crontab -e 
# Agregar rotación semanal 0 0 * * 0 cd /volume1/web/odisa-tools && mv logs/odisa_tools.log logs/odisa_tools.log.$(date +\%Y\%m\%d) && touch logs/odisa_tools.log

8. Mantenimiento

Backup de Datos

Crear script backup.sh en /volume1/web/odisa-tools/:

#!/bin/bash BACKUP_DIR="/volume1/backups/odisa_tools" APP_DIR="/volume1/web/odisa-tools" DATE=$(date +%Y%m%d_%H%M%S) 
echo "? Creando backup de Odisa Tools..." 
# Crear directorio de backups si no existe mkdir -p $BACKUP_DIR 
# Crear backup tar -czf "$BACKUP_DIR/odisa_backup_$DATE.tar.gz" \    -C "$APP_DIR" \    data/ \    tools/bitrix_products/config.json \    tools/sap_promotions/sap_config.json \    tools/sap_promotions/google_sheets_config.json \    2>/dev/null 
echo "✅ Backup creado: $BACKUP_DIR/odisa_backup_$DATE.tar.gz" 
# Eliminar backups antiguos (más de 30 días) find $BACKUP_DIR -name "odisa_backup_*.tar.gz" -mtime +30 -delete echo "? Backups antiguos eliminados"

Actualización de la Aplicación

Crear script update.sh:

#!/bin/bash # update.sh - Actualizar Odisa Tools 
cd /volume1/web/odisa-tools 
echo "? Actualizando Odisa Tools..." 
# 1. Hacer backup primero ./backup.sh 
# 2. Detener aplicación ./stop_odisa_tools.sh 
# 3. Actualizar código (si usas Git) if [ -d ".git" ]; then    git pull origin main fi 
# 4. Actualizar dependencias source venv/bin/activate pip install -r requirements.txt --upgrade 
# 5. Reiniciar ./start.sh 
echo "✅ Actualización completada"

Monitoreo de Salud Automático

Crear script check_health.sh:

#!/bin/bash APP_DIR="/volume1/web/odisa-tools" PORT=8001 LOG_FILE="$APP_DIR/logs/health.log" 
# Verificar si responde curl -f http://localhost:$PORT > /dev/null 2>&1 
if [ $? -ne 0 ]; then    echo "$(date): Aplicación no responde, reiniciando..." >> $LOG_FILE    cd $APP_DIR    ./restart.sh        # Notificar por email o sistema de alertas    # mail -s "Odisa Tools reiniciado" admin@empresa.com < $LOG_FILE fi

Agregar a crontab para verificación cada 5 minutos:

*/5 * * * * /volume1/web/odisa-tools/check_health.sh

? Información de Contacto Rápido

Accesos Principales

Servidor SSH: admin@192.168.2.22
Aplicación Web: http://192.168.2.22:8001
Directorio: /volume1/web/odisa-tools/
Puerto: 8001

Rutas Importantes

Logs: /volume1/web/odisa-tools/logs/
Configuración Bitrix: /volume1/web/odisa-tools/tools/bitrix_products/config.json
Configuración SAP: /volume1/web/odisa-tools/tools/sap_promotions/sap_config.json
Usuarios: /volume1/web/odisa-tools/data/users.json

Comandos Esenciales

# Acceso al servidor (USAR USUARIO ADMIN) ssh admin@192.168.2.22 
# Navegar a la aplicación cd /volume1/web/odisa-tools 
# Estado ./status.sh 
# Iniciar ./start.sh 
# Detener ./stop_odisa_tools.sh 
# Reiniciar ./restart.sh 
# Ver logs en tiempo real tail -f logs/odisa_tools.log 
# Backup ./backup.sh

Credenciales por Defecto

Usuario administrador web: admin / admin123
Cambiar inmediatamente después del primer acceso

⚠️ RECORDATORIOS IMPORTANTES:

SIEMPRE conectarse con usuario administrador por SSH
La ruta correcta es /volume1/web/odisa-tools/
El servidor está en 192.168.2.22
Puerto de la aplicación: 8001
Hacer backups regulares de la carpeta data/

Versión del manual: 1.1 Última actualización: Agosto 2025 Ubicación del sistema: 192.168.2.22:/volume1/web/odisa-tools/

Manual técnico de Odisa-Tools Imprimir