consultoria-as/Skeen-CRM
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Skeen-CRM/docs/MANUAL_PRODUCCION.md
root be2dbbc194 docs: manual de producción completo + ajustes seed fallback 
- Add production manual (docs/MANUAL_PRODUCCION.md)
- Fix seed script to work without OpenAI API key (zero-vector fallback)
- Fix alembic env to use database_url_str
- Fix pyproject.toml hatch build config
2026-04-29 05:51:27 +00:00

15 KiB
Raw Permalink Blame History

Manual de Producción — SKEEN CRM AI Agent

Versión: 1.0
Fecha: 29 de abril de 2026
VM: 192.168.10.100 (Ubuntu 24.04 LTS)
Stack: Python 3.13, FastAPI, PostgreSQL 16 + pgvector, Redis 7, Celery, Docker

1. Resumen Ejecutivo

Este documento describe la instalación, configuración y operación del SKEEN CRM AI Agent, un agente de inteligencia artificial para WhatsApp Business API integrado con ERPNext Healthcare.

Servicios desplegados en la VM

Servicio Puerto Tecnología Estado
FastAPI (Agente) 8000 Python 3.13 + Uvicorn Systemd
Celery Worker — Python 3.13 + Celery Systemd
Celery Beat — Python 3.13 + Celery Systemd
PostgreSQL 5432 (interno) Docker (ankane/pgvector) Docker
Redis 6379 (interno) Docker (redis:7-alpine) Docker
Gitea (Git) 3000 Docker (gitea/gitea) Docker
Meta Webhook 8000/api/v1/webhooks/whatsapp FastAPI Activo

2. Arquitectura del Sistema

┌─────────────────────────────────────────────────────────────────────────┐
│                              PACIENTE                                    │
│                         (WhatsApp Móvil)                                 │
└───────────────────────────────┬─────────────────────────────────────────┘
                                │
                    ┌───────────▼───────────┐
                    │  Meta WhatsApp API    │
                    │  (WhatsApp Business)  │
                    └───────────┬───────────┘
                                │ Webhook
                                ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         SKEEN CRM AI AGENT                              │
│  ┌─────────────────┐  ┌──────────────┐  ┌──────────────────────────┐   │
│  │  FastAPI        │  │  Celery      │  │  PostgreSQL + pgvector   │   │
│  │  • Webhooks     │  │  • Workers   │  │  • Conversaciones        │   │
│  │  • API REST     │  │  • Scheduler │  │  • Mensajes              │   │
│  │  • Auth         │  │  • Colas     │  │  • Knowledge Base (RAG)  │   │
│  └────────┬────────┘  └──────┬───────┘  └────────────┬─────────────┘   │
│           │                  │                       │                 │
│  ┌────────▼────────┐  ┌──────▼───────┐  ┌────────────▼─────────────┐   │
│  │  OpenAI GPT-4o  │  │  Redis       │  │  ERPNext Healthcare      │   │
│  │  • Chat         │  │  • Cache     │  │  • Pacientes             │   │
│  │  • Embeddings   │  │  • Broker    │  │  • Citas                 │   │
│  │  • Functions    │  │  • Rate Limit│  │  • Doctores              │   │
│  └─────────────────┘  └──────────────┘  └──────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                │
                    ┌───────────▼───────────┐
                    │  Gitea (Git Server)   │
                    │  http://192.168.10.100:3000
                    └───────────────────────┘

3. Accesos y URLs

Servicio URL Interna URL Externa (si aplica)
Gitea http://192.168.10.100:3000 Pendiente de dominio
API Health http://192.168.10.100:8000/health Pendiente de dominio
API Docs http://192.168.10.100:8000/docs Solo desarrollo
Webhook Meta http://192.168.10.100:8000/api/v1/webhooks/whatsapp Configurar en Meta Developers
Prometheus http://192.168.10.100:8000/metrics Métricas raw

Credenciales Gitea

  • Usuario: skeen-admin
  • Contraseña: skeen-admin-2024
  • Email: admin@skeen.mx
  • Token API: 5ef0f75cefb665136896b63db05680d70647c894

4. Estructura de Archivos en la VM

/root/Skeen-CRM/
├── .env                          # Variables de entorno (PROTEGER)
├── .venv/                        # Entorno virtual Python
├── docker-compose.yml            # Infraestructura Docker
├── src/                          # Código fuente
│   ├── main.py                   # Entry point FastAPI
│   ├── config.py                 # Configuración Pydantic
│   ├── api/v1/                   # Endpoints REST
│   ├── use_cases/                # Lógica de negocio
│   ├── infrastructure/           # Clientes externos
│   │   ├── whatsapp/             # Meta WhatsApp API
│   │   ├── ai/                   # OpenAI + RAG
│   │   ├── erpnext/              # ERPNext Frappe API
│   │   ├── db.py                 # PostgreSQL
│   │   └── redis.py              # Redis
│   ├── domain/models/            # Entidades SQLAlchemy
│   └── workers/                  # Celery
├── alembic/                      # Migraciones DB
├── scripts/
│   ├── validate_setup.py         # Validación de servicios
│   └── seed_knowledge.py         # Seed del catálogo
├── tests/                        # Tests automatizados
└── docs/                         # Documentación

5. Guía de Instalación (Ya completada)

Los pasos 1-5 ya fueron ejecutados en la VM. Este es el registro para referencia futura o reinstalación.

Paso 1: Requisitos de la VM

# CPU: 4 cores, RAM: 15 GB, Disk: 29 GB
# OS: Ubuntu 24.04 LTS
# IP: 192.168.10.100

Paso 2: Instalar Docker

apt-get update
apt-get install -y ca-certificates curl gnupg lsb-release
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" > /etc/apt/sources.list.d/docker.list
apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
systemctl enable docker
systemctl start docker

Paso 3: Levantar PostgreSQL + Redis

cd /root/Skeen-CRM
docker compose up -d postgres redis

Paso 4: Instalar dependencias Python

pip install uv
uv venv .venv
source .venv/bin/activate
uv pip install -r pyproject.toml --extra dev

Paso 5: Ejecutar migraciones y seed

source .venv/bin/activate
alembic upgrade head
python scripts/seed_knowledge.py

Paso 6: Instalar Gitea (Git Server)

docker run -d --name gitea \
  --env GITEA__database__DB_TYPE=sqlite3 \
  --env GITEA__database__PATH=/data/gitea/gitea.db \
  --env GITEA__server__DOMAIN=192.168.10.100 \
  --env GITEA__server__HTTP_PORT=3000 \
  --env GITEA__server__ROOT_URL=http://192.168.10.100:3000/ \
  --env GITEA__server__SSH_PORT=222 \
  --env GITEA__security__INSTALL_LOCK=true \
  -p 3000:3000 -p 222:22 -v gitea_data:/data \
  gitea/gitea:latest

# Crear admin
docker exec gitea sh -c "su git -c 'gitea admin user create --username skeen-admin --password skeen-admin-2024 --email admin@skeen.mx --admin'"

# Generar token
docker exec gitea sh -c "su git -c 'gitea admin user generate-access-token --username skeen-admin --token-name setup-token --scopes write:repository,write:user'"

Paso 7: Configurar systemd services

Archivos creados:

  • /etc/systemd/system/skeen-api.service
  • /etc/systemd/system/skeen-worker.service
  • /etc/systemd/system/skeen-scheduler.service
systemctl daemon-reload
systemctl enable skeen-api skeen-worker skeen-scheduler

6. Configuración de Credenciales (PENDIENTE POR EL CLIENTE)

Editar /root/Skeen-CRM/.env con las credenciales reales:

Meta / WhatsApp Business API

Obtener de: https://developers.facebook.com/apps

META_ACCESS_TOKEN=EAAxxxxxxxxxxxxxxxxxxxxxxxxxxxx
META_PHONE_NUMBER_ID=123456789012345
META_BUSINESS_ACCOUNT_ID=987654321098765
META_WEBHOOK_VERIFY_TOKEN=tu-token-seguro-aleatorio
META_APP_SECRET=tu-app-secret-de-meta

OpenAI

Obtener de: https://platform.openai.com/api-keys

OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

ERPNext

ERPNEXT_BASE_URL=https://tu-instancia.erpnext.com
ERPNEXT_API_KEY=xxxxxxxxxxxxxxxx
ERPNEXT_API_SECRET=xxxxxxxxxxxxxxxx

IMPORTANTE: Después de configurar las credenciales:

  1. Regenerar embeddings: python scripts/seed_knowledge.py
  2. Validar conexiones: python scripts/validate_setup.py
  3. Reiniciar servicios: systemctl restart skeen-api skeen-worker

7. Operación Diaria

Comandos útiles

# Ver estado de todos los servicios
systemctl status skeen-api skeen-worker skeen-scheduler
docker ps

# Ver logs en tiempo real
journalctl -u skeen-api -f
journalctl -u skeen-worker -f

# Reiniciar servicios
systemctl restart skeen-api skeen-worker skeen-scheduler

# Validar conexiones externas
cd /root/Skeen-CRM && source .venv/bin/activate && python scripts/validate_setup.py

# Ver métricas Prometheus
curl http://localhost:8000/metrics

# Acceder a PostgreSQL
docker exec -it skeen-postgres psql -U skeen -d skeen_crm

# Acceder a Redis
docker exec -it skeen-redis redis-cli

Configuración del Webhook en Meta

  1. Ir a https://developers.facebook.com/apps/[TU_APP_ID]/whatsapp-business/waba-de-configuracion/
  2. En Webhooks, configurar:
    • Callback URL: http://192.168.10.100:8000/api/v1/webhooks/whatsapp
    • Verify Token: El valor de META_WEBHOOK_VERIFY_TOKEN en .env
    • Subscription: messages
  3. Si la VM no tiene IP pública estática, usar ngrok o Cloudflare Tunnel para exponer el puerto 8000.

Backup de la base de datos

# Backup PostgreSQL
docker exec skeen-postgres pg_dump -U skeen skeen_crm > /root/backups/skeen_crm_$(date +%Y%m%d_%H%M%S).sql

# Backup Redis
docker exec skeen-redis redis-cli BGSAVE
cp /var/lib/docker/volumes/skeen-crm_redis_data/_data/dump.rdb /root/backups/redis_$(date +%Y%m%d_%H%M%S).rdb

# Backup Gitea
docker exec gitea sh -c "su git -c 'gitea dump -c /data/gitea/conf/app.ini -f /data/gitea-dump.zip'"
cp /var/lib/docker/volumes/gitea_data/_data/gitea-dump.zip /root/backups/gitea_$(date +%Y%m%d_%H%M%S).zip

8. Integraciones

ERPNext Healthcare

El agente se conecta a ERPNext via API REST de Frappe. Doctypes utilizados:

Doctype Operación Endpoint
Patient CRUD /api/resource/Patient
Healthcare Practitioner Listar /api/resource/Healthcare Practitioner
Patient Appointment CRUD /api/resource/Patient Appointment
Clinical Procedure Template Listar /api/resource/Clinical Procedure Template
Patient Wallet Consultar /api/resource/Patient Wallet

OpenAI GPT-4o

  • Modelo: gpt-4o
  • Temperatura: 0.3
  • Max tokens: 1500
  • Embeddings: text-embedding-3-small (1536 dimensiones)
  • Function Calling: 6 tools disponibles

Meta WhatsApp Business API

  • Versión: v18.0
  • Endpoint base: https://graph.facebook.com/v18.0/
  • Phone Number ID: Configurado en .env
  • Tipos de mensaje soportados: Texto, Template, Botones interactivos, Listas interactivas
  • Verificación: HMAC-SHA256 en webhooks (producción)

9. Troubleshooting

El agente no responde mensajes de WhatsApp

  1. Verificar que el webhook está configurado correctamente en Meta
  2. Revisar logs: journalctl -u skeen-api -n 100
  3. Validar token de Meta: python scripts/validate_setup.py
  4. Verificar que Celery worker está corriendo: systemctl status skeen-worker

Error de conexión a ERPNext

  1. Verificar URL y credenciales en .env
  2. Probar conexión: curl -u "api_key:api_secret" https://tu-erpnext.com/api/method/frappe.auth.get_logged_user
  3. Revisar firewall entre VM y ERPNext

RAG no encuentra resultados

  1. Verificar que OPENAI_API_KEY está configurado
  2. Regenerar embeddings: python scripts/seed_knowledge.py
  3. Verificar tabla knowledge_chunks en PostgreSQL

PostgreSQL no responde

docker compose ps
docker compose logs postgres
docker compose restart postgres

Out of Memory

La VM tiene 15 GB RAM. Si hay problemas:

  • Reducir CELERY_WORKER_CONCURRENCY a 2
  • Reducir workers de Uvicorn a 1
  • Verificar con free -h y htop

10. Seguridad

  • .env contiene secretos. Nunca commitear.
  • El archivo ya está en .gitignore.
  • Webhooks validan firma HMAC-SHA256 en producción (APP_ENV=production).
  • Logs no exponen datos PHI (solo últimos 4 dígitos de teléfono).
  • Gitea está configurado con acceso privado.
  • Se recomienda configurar firewall ufw:
ufw default deny incoming
ufw allow 22/tcp      # SSH
ufw allow 8000/tcp    # API (o restringir a IPs de Meta)
ufw allow 3000/tcp    # Gitea
ufw enable

11. Próximos pasos recomendados

  1. Configurar credenciales reales en .env
  2. Configurar webhook en Meta Developers
  3. Configurar dominio y HTTPS (Caddy o Nginx + Let's Encrypt)
  4. Configurar backups automatizados (cron diario)
  5. Configurar monitoreo (Grafana + Prometheus)
  6. Integrar pasarela de pagos (Stripe/MercadoPago webhooks)
  7. Entrenar al equipo de SKEEN en el uso del agente

12. Contacto y soporte

Documento generado automáticamente por SKEEN Development Team.

Reference in New Issue View Git Blame Copy Permalink