Infraestructura

Rikoo consta de dos servicios de aplicación, la api y el worker, que se apoyan en tres almacenes de datos: PostgreSQL, Redis y un almacenamiento de objetos compatible con S3. Dos servicios opcionales añaden el análisis de documentos y las herramientas integradas.

Servicios de aplicación

Servicio	Función	Obligatorio	Estado
api	API REST, Studio, script del widget, autenticación, encolado. Aplica las migraciones de la base de datos al arrancar.	Sí	Sin estado
worker	Ejecuta los agentes: llamadas a modelos, búsqueda documental, llamadas a herramientas, correos electrónicos y webhooks.	Sí	Sin estado
sidecar-parsing	Extrae el texto de documentos PDF y de Office. Sin él, el worker recurre a sus propios analizadores.	No	Sin estado
mcp-sandbox	Las herramientas integradas: un espacio de trabajo por conversación y un navegador. Sin él, esas herramientas devuelven un error y las ejecuciones continúan.	No	Con estado: un espacio de trabajo por conversación
playwright-mcp	El navegador que controla el entorno aislado.	Con el entorno aislado	Sin estado
mcp-egress	La única salida del navegador del entorno aislado, detrás de la misma protección anti-SSRF que el worker.	Con el entorno aislado	Sin estado

La api y el worker escalan horizontalmente: no guardan ningún estado fuera de los almacenes de datos.

PostgreSQL

• Versión: PostgreSQL 16 es la versión probada (las pilas de referencia usan pgvector/pgvector:pg16).
• Extensiones: vector (pgvector) y citext. Los índices vectoriales usan el tipo halfvec, disponible a partir de pgvector 0.7.0.
• Roles: las migraciones crean las extensiones y un rol rikoo_app, así que el rol que las ejecuta necesita permiso para crear extensiones y roles. Dar una contraseña a rikoo_app y hacer que APP_DATABASE_URL apunte a él permite que la seguridad a nivel de fila filtre cada consulta sobre los datos de una organización.
• Variables: DATABASE_URL (obligatoria), APP_DATABASE_URL (recomendada).
• Los servicios de PostgreSQL gestionados sirven, siempre que ofrezcan pgvector y permitan al rol de migración crear roles.

Todo salvo los archivos vive aquí, vectores incluidos. Haga copias de seguridad de esta base.

Redis

• Versión: Redis 7.
• Se usa para: las colas de trabajos, las sesiones y los contadores de inicio de sesión, y los eventos que transmiten una ejecución en directo al navegador.
• Configuración: persistencia activada (appendonly yes en las pilas de referencia) y sin desalojo (maxmemory-policy noeviction): una clave desalojada es un trabajo o una sesión perdidos.
• Variable: REDIS_URL (obligatoria), redis:// o rediss://.
• Rikoo se conecta a un único endpoint de Redis, sin modo Cluster ni Sentinel.

Almacenamiento de objetos

• Cualquier servicio compatible con S3: MinIO, incluido en las dos pilas de referencia, o el almacenamiento de objetos de su proveedor de nube.
• Un único bucket guarda los archivos de fuentes ingeridos, los adjuntos, las salidas de herramientas voluminosas y las exportaciones de auditoría, cada uno bajo un prefijo propio de la organización.
• Variables: S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID y S3_SECRET_ACCESS_KEY (obligatorias); S3_REGION (us-east-1 por defecto, el mismo valor en la api y en el worker); S3_FORCE_PATH_STYLE (true por defecto); S3_BROWSER_ENDPOINT.
• Acceso desde el navegador: los navegadores intercambian archivos directamente con el bucket, mediante URL firmadas, así que sus usuarios deben poder alcanzar S3_BROWSER_ENDPOINT. MinIO acepta todos los orígenes por defecto, mientras que un bucket en la nube no tiene ninguna regla CORS hasta que usted la añade. Permita PUT desde PUBLIC_URL, desde donde el Studio sube los documentos, y GET desde los sitios donde se ejecuta el widget, que descarga archivos para «descargar todo» y «copiar la imagen».

Red

Desde	Hacia	Por qué
Usuarios	api	Studio, widget, API pública
Usuarios	almacenamiento de objetos	Subida de adjuntos, en S3_BROWSER_ENDPOINT
api	PostgreSQL, Redis, su colector de trazas	Ningún otro acceso saliente
worker	PostgreSQL, Redis, almacenamiento de objetos	Datos
worker	Proveedores de modelos, servidores MCP, destinos de webhooks, servidor SMTP, su colector de trazas	Todo lo que sale de la plataforma

Cada petición saliente del worker pasa por una protección anti-SSRF, que rechaza las direcciones privadas y de enlace local. Para alcanzar un servidor de modelos de su propia red, por ejemplo vLLM u Ollama, autorice su rango de direcciones con RIKOO_EGRESS_ALLOW_CIDRS, con el mismo valor en la api, el worker y mcp-egress. Mantenga el rango lo más estrecho posible: cada entrada abre un hueco en la protección.

Las credenciales de los proveedores de modelos no son variables de entorno. Se introducen en el Studio, se sellan en la bóveda de secretos y solo el worker puede abrirlas.

Observabilidad

Endpoint	Servicio	Uso
GET /healthz	api	Liveness: responde mientras el proceso se ejecuta, sin tocar ninguna dependencia
GET /readyz	api	Readiness: 503 hasta que PostgreSQL y Redis responden
GET /api/v1/health	api	Estado y versión
GET /health en el puerto 3100	worker	Salud del worker, interno
GET /metrics en el puerto 3100	worker	Métricas de Prometheus
GET /metrics en el puerto 9464	api	Métricas de Prometheus, cuando OTEL_METRICS_EXPORTER_API=prometheus

Las trazas se exportan por OTLP (HTTP) a su propio colector. Defina OTEL_EXPORTER_OTLP_ENDPOINT para el worker y OTEL_EXPORTER_OTLP_ENDPOINT_API para la api. Sin colector no se exporta nada, y nada falla.