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:
| Ajuste | Valor necesario | Motivo |
|---|---|---|
| Almacenamiento en búfer de la respuesta | Desactivado en esas dos rutas | La 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ón | Nunca aplicada a text/event-stream | La aplicación nunca comprime una respuesta, así que cualquier compresión que vea el cliente procede de esta capa |
| Tiempo de espera de lectura / inactividad | Muy superior a la ejecución de agente más larga que esperes | Una 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 CSRF | Marcadas como Secure, así que el navegador solo las envía por HTTPS | Sin Secure, así que el navegador también las envía por HTTP sin cifrar |
| Orígenes autorizados a llamar a la API | Ese origen | Solo http://localhost:3000 |
| Correo de notificación e inicio de sesión único | Los correos enlazan a la aplicación y el inicio de sesión único se puede usar | Los 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_DIRtiene 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.ymlconcede al serviciomcp-proxyy solo a él:seccomp=unconfined,apparmor=unconfinedysystempaths=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ón | Cómo | Cuándo usarla |
|---|---|---|
| Solo API | El valor predeterminado: EMAIL_WORKER_IN_PROCESS es true, así que uvicorn main:app también vacía la cola de correo | Un 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 + worker | Ejecuta python -m worker junto a la API y establece EMAIL_WORKER_IN_PROCESS=false en ella | Cualquier 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.ymllo 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-queuey 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 datos | La base de datos indicada en DB_URL | Todo: ahí está cada registro. Consulta Base de datos |
| El almacén de skills de agente | SKILLS_DIR | Las 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 secretos | SECRET_ENCRYPTION_KEY, o el archivo de SECRET_KEY_FILE | Todos 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.