Saltar al contenido principal

Despliegue

Un despliegue consta del frontend, el backend y una base de datos relacional; Ejecutar con Docker Compose es el camino más corto hacia los tres. Lo que sigue es lo que cambia cuando la pila se coloca detrás de un proxy y contiene datos que merece la pena conservar.

El navegador se comunica con un único origen, y el proxy inverso lo dirige por ruta: /api/* y /openapi.json al backend, todo lo demás al frontend. Ambos están en el mismo dominio, así que las cookies de autenticación siguen siendo de origen propio, y los streams de larga duración de cada chat abierto van directamente al backend en lugar de pasar por el frontend. El servicio ingress de compose.yml (Envoy) es un ejemplo funcional de este enrutamiento.

Sin esa ruta, el frontend reenvía /api/* al backend por sí mismo, que es como funciona un arranque sin contenedores. El comportamiento es el mismo, pero cada chat abierto mantiene además una conexión en el frontend, así que también hay que escalar el frontend según el número de chats simultáneos. Todas las variables que se mencionan aquí se describen en Referencia de configuración.

Proxy inverso y balanceador de carga​

No se necesitan sesiones persistentes (sticky sessions) ni afinidad de sesión. Consulta Escalado horizontal: lo que mantiene una conversación asignada a un solo conductor a la vez es un bloqueo consultivo de PostgreSQL, no la afinidad de enrutamiento, y solo durante un único stream SSE.

Las rutas SSE del agente (POST /api/v1/workflow-executions/{id}/agent y POST /api/v1/workflows/{id}/agent) necesitan lo siguiente en el proxy inverso que las dirige al backend:

AjusteValor necesarioMotivo
Almacenamiento en búfer de la respuestaDesactivado en esas dos rutasLa aplicación envía X-Accel-Buffering: no, que nginx respeta por respuesta aunque el búfer esté activado globalmente. Cualquier otro proxy necesita desactivarlo en su propia configuración
CompresiónNunca aplicada a text/event-streamLa aplicación nunca comprime una respuesta, así que cualquier compresión que vea el cliente procede de esta capa
Tiempo de espera de lectura / inactividadMuy superior a la ejecución de agente más larga que esperesUna ejecución de agente no tiene límite de tiempo en el servidor, así que un tiempo de espera de lectura del proxy es lo único que puede terminar un stream, y uno bajo trunca sin avisar una respuesta larga legítima. Dimensiónalo según tu ejecución más larga, no según una solicitud típica

Un despliegue gradual termina a la fuerza cualquier stream SSE que siga abierto 30 segundos después de que el contenedor reciba SIGTERM (--timeout-graceful-shutdown 30, definido en el CMD del Dockerfile del backend). Es seguro: el bloqueo consultivo se libera con la conexión y el cliente reanuda con una solicitud nueva, igual que ya ocurre con un stream abandonado.

Detrás de HTTPS​

Un solo ajuste decide lo que necesita un despliegue detrás de HTTPS: define APP_BASE_URL con el origen que ve el navegador, como https://a2flow.example.com. El resto se deriva de él:

QuéCon un APP_BASE_URL https://Sin APP_BASE_URL
Cookies de sesión y CSRFMarcadas como Secure, así que el navegador solo las envía por HTTPSSin Secure, así que el navegador también las envía por HTTP sin cifrar
Orígenes autorizados a llamar a la APIEse origenSolo http://localhost:3000
Correo de notificación e inicio de sesión únicoLos correos enlazan a la aplicación y el inicio de sesión único se puede usarLos correos se envían sin enlaces y el inicio de sesión único no está disponible

SESSION_COOKIE_SECURE y CORS_ORIGINS aún pueden sustituir los dos primeros; consulta Referencia de configuración. La pila de Docker Compose incluye un ejemplo funcional: Servir por HTTPS coloca un proxy que termina TLS delante del servicio ingress y pasa la dirección al backend.

Disposición de procesos​

Junto a la API, un despliegue ejecuta el proxy MCP: el proceso que realmente inicia los servidores MCP que un tenant ha registrado o se conecta a ellos. Mantenerlo separado es precisamente el objetivo: es donde se ejecuta código de terceros, así que no tiene acceso a la base de datos, ni clave de cifrado de secretos, ni clave de API del LLM. compose.yml lo ejecuta como el contenedor mcp-proxy, en una red que solo comparte con la API, por lo que no puede llegar a la base de datos en absoluto; un despliegue que monte sus propios contenedores debería mantener el proxy fuera de la red de la base de datos de la misma forma, y configurarlo en Proxy MCP.

Dos cosas que hay que hacer bien:

  • La API tiene que arrancar primero. Emite el material con el que ambos extremos se identifican mutuamente, así que el proxy no aceptará nada hasta que se haya escrito. Condiciona el arranque del proxy a la comprobación de estado de la API, como hace compose.yml.
  • Necesitan un directorio compartido. MCP_PROXY_TLS_DIR tiene que ser el mismo almacenamiento en ambos lados: con escritura para la API y de solo lectura para el proxy. Allí no se guarda nada duradero: se reescribe siempre que falta o está a punto de caducar.
  • El proxy tiene que poder crear sandboxes. Inicia cada servidor en un sandbox propio y comprueba al arrancar que puede hacerlo; si no puede, se detiene con un error en lugar de ejecutar servidores sin sandbox. Dentro de un contenedor, esto requiere tres opciones de seguridad, que compose.yml concede al servicio mcp-proxy y solo a él: seccomp=unconfined, apparmor=unconfined y systempaths=unconfined. En un host con Ubuntu 24.04 o posterior, también hay que permitir los espacios de nombres de usuario sin privilegios: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0.

Se puede prescindir del proxy: deja MCP_PROXY_URL sin definir y la API accederá a los servidores MCP por sí misma, que es lo que hace un arranque de desarrollo local. Eso significa que un servidor registrado se ejecuta junto a las credenciales del despliegue, así que no es una opción para un entorno donde cualquiera puede registrar uno.

El backend también se distribuye con dos puntos de entrada contra la misma base de datos. El que ejecutes determina desde dónde se entrega el correo de notificación:

DisposiciónCómoCuándo usarla
Solo APIEl valor predeterminado: EMAIL_WORKER_IN_PROCESS es true, así que uvicorn main:app también vacía la cola de correoUn despliegue de un solo proceso, o uno lo bastante pequeño como para que un relé atascado en la ruta de las solicitudes sea aceptable
API + workerEjecuta python -m worker junto a la API y establece EMAIL_WORKER_IN_PROCESS=false en ellaCualquier caso en el que un relé colgado no deba afectar a nada que atienda solicitudes. Es lo que hace compose.yml

Dos cosas sobre el proceso del worker:

  • No migra ni carga datos iniciales. Ambas cosas corresponden al arranque de la API, así que el worker tiene que iniciarse después de que la API esté en marcha; compose.yml lo condiciona a la comprobación de estado de la API.
  • Más de una réplica aporta conmutación por error, no rendimiento. Compiten por el bloqueo consultivo email-queue y todas menos una permanecen inactivas por diseño, que es lo que mantiene exacta la velocidad de envío.

Comprobaciones de estado​

Apunta tu orquestador o balanceador de carga a GET /api/v1/health. Consulta Comprobaciones de estado.

Estado que debe persistir​

Tres cosas sobreviven a un contenedor y deben estar en almacenamiento duradero para que un despliegue vuelva a funcionar intacto:

QuéDónde estáSi se pierde
La base de datosLa base de datos indicada en DB_URLTodo: ahí está cada registro. Consulta Base de datos
El almacén de skills de agenteSKILLS_DIRLas ejecuciones no pueden cargar la revisión de la skill a la que están fijadas (HTTP 409 SKILL_NOT_READY). Es estado duradero, no una caché; consulta Almacén de skills de agente
La clave de cifrado de secretosSECRET_ENCRYPTION_KEY, o el archivo de SECRET_KEY_FILETodos los secretos locales almacenados se vuelven indescifrables, y la autoridad de certificación ya no puede emitir ni verificar los certificados que necesita cada llamada a una herramienta MCP. Consulta Gestión de secretos

Cómo copiar y restaurar cada una de ellas se explica en Copia de seguridad y restauración.