수평 확장
프런트엔드는 자체 상태가 없고 요청 사이에 아무것도 유지하지 않으므로 자유롭게 확장할 수 있습니다. 배포에서 설명하는 대로 리버스 프록시가 /api/*를 백엔드로 바로 라우팅하면 채팅 스트림은 프런트엔드를 아예 거치지 않습니다. 아래 내용은 모두 백엔드에 관한 것입니다.
레플리카를 둘 이상 실행하기 위한 요건
| 요건 | 이유 |
|---|---|
| PostgreSQL | SQLite는 단일 작성자, 단일 프로세스입니다. 모든 레플리카가 하나의 데이터베이스를 공유하며, 레플리카를 조율하는 것도 이 데이터베이스입니다 |
공유 SKILLS_DIR | 모든 레플리카가 같은 에이전트 스킬 스토어를 마운트해야 합니다(ReadWriteMany). 실행은 시작 시의 스킬 리비전에 고정되며, 그 실행의 다음 요청은 어느 레플리카든 처리할 수 있습니다 |
| 트랜잭션 풀링 프록시 사용 금지 | 아래의 연결 풀링을 참조하세요 |
공유 MCP_PROXY_TLS_DIR | 각 레플리카는 MCP 프록시에 자신을 식별하는 자료를 그곳에 쓰고 읽으며, 프록시도 같은 디렉터리를 읽습니다. 레플리카마다 따로 두면 프록시가 본 적 없는 자료를 발급하게 됩니다 |
| 스티키 세션 | 필요하지 않습니다. 라우팅 어피니티로 해결하려 할 일을 아래의 권고 잠금이 맡습니다 |
MCP 프록시 자체는 별도의 기준으로 확장합니다. 호출 사이에 다운로드 캐시 외에는 아무것도 유지하지 않으므로 레플리카 간 조율이 전혀 필요 없으며, MCP_SANDBOX_DIR를 공유해도 되고 각자 따로 두어도 됩니다. 백엔드 레플리카 수가 아니라 동시에 실행되는 도구 호출 수에 맞춰 규모를 정하세요.
대화당 드라이버 하나
대화 하나에 대한 쓰기는 이미 레플리카 간에 안전합니다. 세션 서비스가 전체 트랜잭션 동안 추가 대상 행에 SELECT ... FOR UPDATE를 걸기 때문에 추가가 직렬화되고, 대화 상태도 이벤트 행도 유실되지 않습니다.
문제는 읽기입니다. 에이전트 런타임은 호출이 이어지는 동안 메모리에 세션 하나를 보유하므로, 그동안 다른 레플리카가 추가한 이벤트는 전달되지 않고, 실행의 나머지는 그 이벤트가 빠진 대화를 바탕으로 추론합니다. 쓰기를 직렬화해도 이 문제는 해결되지 않습니다. 세션을 한 번에 드라이버 하나로 유지하는 것만이 해결책입니다.
그래서 각 에이전트 실행(POST /api/v1/workflow-executions/{id}/agent, POST /api/v1/workflows/{id}/agent)은 PostgreSQL 세션 수준 권고 잠금을 획득해 SSE 스트림 전체에 걸쳐 유지합니다.
같은 세션의 두 번째 동시 실행은 조용히 어긋나도록 두지 않고 SSE 헤더를 보내기 전에 거부됩니다. 서로 다른 세션은 경합하지 않으며, 잠금은 포기하기 전에 잠시 기다리므로, 스트림을 중단하고 바로 다시 시도한 클라이언트가 버려진 실행이 정리되는 동안 거부되지 않습니다.
사람이 개입하는 흐름(human-in-the-loop)에는 영향이 없습니다. 프런트엔드 도구 호출은 실행을 끝내고 스트림을 닫아 잠금을 해제하며, 승인은 어느 레플리카에서든 실행될 수 있는 새 턴으로 재개됩니다.
모든 레플리카는 세션 러너도 실행합니다. 세션 러너는 브라우저가 구동하지 않는 턴, 즉 실행의 시작 턴과 승인 후 재개를 수행합니다. 같은 잠금을 기다리지 않고 획득하므로, 이미 다른 곳에서 실행 중인 세션은 그 레플리카에 맡기고, 중단된 레플리카가 끝내지 못한 턴을 이어받습니다. 레플리카 하나가 동시에 실행하는 턴의 수는 SESSION_RUNNER_CONCURRENCY로 설정합니다(구성 참조 페이지 참조).
롤아웃 중 스키마 마이그레이션
모든 레플리카는 시작할 때 아직 적용되지 않은 스키마 마이그레이션을 적용하고, 새 데이터베이스라면 초기 계정과 설정도 만듭니다. 여러 레플리카가 함께 롤아웃되면 모두 동시에 이 작업을 시도하므로 순서를 정해 처리합니다. 먼저 시작한 레플리카가 작업을 수행하고, 나머지는 최대 10분까지 완료를 기다린 뒤 할 일 없이 시작을 이어 갑니다. 그 후에도 여전히 기다리는 레플리카는 중단되고, 오케스트레이터가 이를 다시 시작합니다.
연결 풀링
이 잠금은 트랜잭션 수준이 아니라 세션 수준이므로, 배포에서 앱과 PostgreSQL 사이에 트랜잭션 풀링 프록시(transaction 모드의 PgBouncer와 대부분의 서버리스 PostgreSQL 풀러)를 두어서는 안 됩니다. 잠금이 SQL 문 사이에 유지되지 않습니다. 채팅 실시간 업데이트도 마찬가지입니다. 각 백엔드 프로세스는 다른 레플리카에서 기록된 턴을 듣기 위해 연결 하나를 열어 두며, 덕분에 한 레플리카에서 열린 채팅이 다른 레플리카에서 실행 중인 턴을 실시간으로 보여 줍니다. 세션 수준 풀링이나 직접 연결이 필요합니다.
연결 예산
각 백엔드 프로세스는 다음 용도로 데이터베이스 연결을 엽니다.
| 용도 | 연결 수 |
|---|---|
| API 요청을 처리하는 풀 | 최대 DB_POOL_SIZE + DB_MAX_OVERFLOW |
| 대화 기록용 풀 | 최대 DB_POOL_SIZE + DB_MAX_OVERFLOW |
진행 중인 각 에이전트 실행: 브라우저에서 열린 채팅 또는 서버가 자체적으로 실행하는 턴(동시에 최대 SESSION_RUNNER_CONCURRENCY개) | 실행이 지속되는 동안 1개 |
| 알림 이메일 발신자 및 스킬 풀이나 지식 베이스 수집 같은 백그라운드 작업 | 실행되는 동안 각 1개 |
| 다른 레플리카의 채팅 실시간 업데이트 | 1개, 항상 열려 있음 |
기본값이면 프로세스당 풀 연결이 최대 30개이고, 여기에 실시간 업데이트용 1개와 진행 중인 실행당 1개가 더해집니다. PostgreSQL 자체의 max_connections 기본값은 100이므로, 바쁜 레플리카 4~5개면 이 한도에 도달할 수 있습니다. 레플리카를 늘리기 전에 서버의 max_connections를 높이거나 DB_POOL_SIZE와 DB_MAX_OVERFLOW를 낮추세요(구성 참조 페이지 참조). 그래도 부족하면 PostgreSQL 앞에 session 모드의 PgBouncer를 두세요.
알림 이메일
발신 이메일 워커는 별도로 조율할 필요가 없습니다. API 프로세스 안에서 실행되든 전용 프로세스로 실행되든 email-queue 권고 잠금이 배포 전체에서 정확히 하나의 발신자를 선출하므로, 레플리카가 중복 발송하는 일이 없고 구성된 속도 제한도 정확히 유지됩니다. 워커 레플리카를 늘려도 얻는 것은 처리량이 아니라 장애 조치입니다. 프로세스 구성을 참조하세요.