본문으로 건너뛰기

배포

배포는 프런트엔드, 백엔드, 관계형 데이터베이스 하나로 구성됩니다. Docker Compose로 실행이 셋을 모두 갖추는 가장 빠른 방법입니다. 여기서는 스택이 프록시 뒤에 놓이고 보존할 가치가 있는 데이터를 담게 될 때 달라지는 점을 다룹니다.

브라우저는 하나의 오리진과 통신하고, 리버스 프록시가 경로에 따라 라우팅합니다. /api/*와 /openapi.json은 백엔드로, 나머지는 모두 프런트엔드로 보냅니다. 둘 다 같은 도메인에 있으므로 인증 쿠키는 퍼스트 파티로 유지되며, 열려 있는 모든 채팅의 장시간 스트림은 프런트엔드를 거치지 않고 백엔드로 바로 갑니다. compose.yml의 ingress 서비스(Envoy)가 이 라우팅의 실제 동작 예입니다.

이 라우트가 없으면 프런트엔드가 /api/*를 직접 백엔드로 전달하며, 컨테이너 없이 실행할 때가 이 방식입니다. 동작은 같지만 열려 있는 채팅마다 프런트엔드의 연결도 하나씩 점유하므로, 동시 채팅 수에 맞춰 프런트엔드도 확장해야 합니다. 여기에 나오는 모든 변수는 구성 참조에 설명되어 있습니다.

리버스 프록시와 로드 밸런서​

스티키 세션(세션 어피니티)은 필요하지 않습니다. 수평 확장을 참조하세요. 대화 하나를 한 번에 드라이버 하나에 묶어 두는 것은 라우팅 어피니티가 아니라 PostgreSQL 권고 잠금이며, 그것도 SSE 스트림 하나가 이어지는 동안뿐입니다.

SSE 에이전트 라우트(POST /api/v1/workflow-executions/{id}/agent와 POST /api/v1/workflows/{id}/agent)를 백엔드로 라우팅하는 리버스 프록시에는 다음 설정이 필요합니다.

설정필수 값이유
응답 버퍼링이 두 경로에서 끔앱이 X-Accel-Buffering: no를 보내며, nginx는 전역으로 버퍼링이 켜져 있어도 응답별로 이를 따릅니다. 다른 프록시는 모두 자체 구성에서 꺼야 합니다
압축text/event-stream에는 절대 적용하지 않음앱은 응답을 압축하지 않으므로, 클라이언트가 보는 압축은 모두 이 계층에서 비롯됩니다
읽기 / 유휴 타임아웃예상되는 가장 긴 에이전트 실행보다 충분히 길게에이전트 실행에는 서버 측 시간 제한이 없으므로 스트림을 끝낼 수 있는 것은 프록시의 읽기 타임아웃뿐이며, 너무 짧으면 정상적인 긴 응답이 조용히 잘립니다. 일반적인 요청이 아니라 가장 긴 실행을 기준으로 정하세요

롤링 배포는 컨테이너가 SIGTERM을 받고 30초가 지난 뒤에도 열려 있는 SSE 스트림을 강제로 종료합니다(백엔드 Dockerfile의 CMD에 설정된 --timeout-graceful-shutdown 30). 이는 안전합니다. 권고 잠금은 연결과 함께 해제되고 클라이언트는 새 요청으로 재개하며, 버려진 스트림이 이미 동작하는 방식과 똑같습니다.

HTTPS 뒤에서 운영하기​

HTTPS 뒤에 두는 배포에 필요한 설정은 하나입니다. APP_BASE_URL에 브라우저가 보는 오리진(예: https://a2flow.example.com)을 설정합니다. 나머지는 여기서 정해집니다.

대상APP_BASE_URL이 https://일 때APP_BASE_URL이 없을 때
세션 및 CSRF 쿠키Secure가 붙어 브라우저가 HTTPS로만 보냅니다Secure가 붙지 않아 브라우저가 평문 HTTP로도 보냅니다
API 호출을 허용하는 오리진그 오리진http://localhost:3000만
알림 이메일과 싱글 사인온이메일에 앱으로 돌아가는 링크가 붙고 싱글 사인온을 사용할 수 있습니다이메일이 링크 없이 전송되고 싱글 사인온을 사용할 수 없습니다

앞의 두 가지는 SESSION_COOKIE_SECURE와 CORS_ORIGINS로 덮어쓸 수도 있습니다. 구성 참조를 참조하세요. Docker Compose 스택에 동작하는 예가 있습니다. HTTPS로 제공하기는 ingress 서비스 앞에 TLS를 종료하는 프록시를 두고 주소를 백엔드에 전달합니다.

프로세스 구성​

배포에서는 API와 함께 MCP 프록시를 실행합니다. 테넌트가 등록한 MCP 서버를 실제로 시작하거나 연결하는 프로세스입니다. 분리하는 것이 핵심입니다. 제3자 코드가 실행되는 곳이므로 데이터베이스 접근 권한도, 시크릿 암호화 키도, LLM API 키도 갖지 않습니다. compose.yml은 이를 mcp-proxy 컨테이너로, API와만 공유하는 네트워크에서 실행하므로 데이터베이스에 아예 접근할 수 없습니다. 컨테이너를 직접 구성하는 배포도 같은 방식으로 프록시를 데이터베이스 네트워크에서 분리하고 MCP 프록시에서 구성해야 합니다.

올바르게 맞춰야 할 점이 두 가지 있습니다.

  • API가 먼저 시작되어야 합니다. 양쪽이 서로를 식별하는 데 쓰는 자료를 API가 발급하므로, 그 자료가 기록될 때까지 프록시는 아무것도 받지 않습니다. compose.yml처럼 API의 상태 확인을 통과한 뒤에 프록시를 시작하세요.
  • 공유 디렉터리가 필요합니다. MCP_PROXY_TLS_DIR는 양쪽에서 같은 저장 공간이어야 하며, API에는 쓰기 가능, 프록시에는 읽기 전용이어야 합니다. 이곳에는 영구히 보관할 데이터가 없습니다. 내용이 없거나 만료가 가까워지면 다시 기록됩니다.
  • 프록시가 샌드박스를 만들 수 있어야 합니다. 프록시는 모든 서버를 각자의 샌드박스에서 시작하며 시작 시 이것이 가능한지 확인합니다. 불가능하면 샌드박스 없이 서버를 실행하는 대신 오류와 함께 중단합니다. 컨테이너 안에서는 보안 옵션 세 가지가 필요하며, compose.yml은 이를 mcp-proxy 서비스에만 부여합니다. seccomp=unconfined, apparmor=unconfined, systempaths=unconfined입니다. Ubuntu 24.04 이상 호스트에서는 권한 없는 사용자 네임스페이스도 허용해야 합니다(sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0).

프록시를 생략할 수도 있습니다. MCP_PROXY_URL을 설정하지 않으면 API가 MCP 서버에 직접 접근하며, 로컬 개발 실행이 이 방식입니다. 등록된 서버가 배포의 자격 증명 옆에서 실행된다는 뜻이므로, 누구나 서버를 등록할 수 있는 환경에서 택할 방식이 아닙니다.

백엔드는 같은 데이터베이스를 사용하는 두 개의 진입점으로도 제공됩니다. 어느 쪽을 실행하느냐에 따라 알림 이메일을 전송하는 위치가 결정됩니다.

구성방법사용 시점
API만기본값입니다. EMAIL_WORKER_IN_PROCESS가 true이므로 uvicorn main:app이 이메일 대기열도 처리합니다단일 프로세스 배포, 또는 요청 경로에서 릴레이가 멈춰도 감수할 수 있을 만큼 작은 배포
API + 워커API와 함께 python -m worker를 실행하고 API에 EMAIL_WORKER_IN_PROCESS=false를 설정합니다릴레이가 멈춰도 요청을 처리하는 어떤 것에도 영향을 주면 안 되는 경우. compose.yml이 이 방식입니다

워커 프로세스에 대해 알아 둘 점이 두 가지 있습니다.

  • 마이그레이션과 시드를 수행하지 않습니다. 둘 다 API의 시작 과정이 맡으므로 워커는 API가 올라온 뒤에 시작해야 합니다. compose.yml은 API의 상태 확인을 통과한 뒤에 워커를 시작합니다.
  • 레플리카를 늘려도 얻는 것은 처리량이 아니라 장애 조치입니다. 레플리카들은 email-queue 권고 잠금을 두고 경쟁하고, 하나를 제외한 나머지는 설계상 유휴 상태로 있으며, 이것이 전송 속도를 정확하게 유지합니다.

상태 확인​

오케스트레이터나 로드 밸런서가 GET /api/v1/health를 확인하도록 설정하세요. 상태 확인을 참조하세요.

유지해야 하는 상태​

컨테이너보다 오래 남아야 하고, 배포가 온전하게 다시 올라오려면 내구성 있는 스토리지에 있어야 하는 것이 세 가지 있습니다.

대상위치잃으면
데이터베이스DB_URL이 가리키는 데이터베이스전부 잃습니다. 모든 레코드가 여기에 있습니다. 데이터베이스를 참조하세요
에이전트 스킬 스토어SKILLS_DIR실행이 고정된 스킬 리비전을 로드할 수 없습니다(HTTP 409 SKILL_NOT_READY). 캐시가 아니라 지속되는 상태입니다. 에이전트 스킬 스토어를 참조하세요
시크릿 암호화 키SECRET_ENCRYPTION_KEY 또는 SECRET_KEY_FILE의 파일저장된 로컬 시크릿을 모두 복호화할 수 없게 되고, 인증 기관이 모든 MCP 도구 호출에 필요한 인증서를 더 이상 발급하거나 검증할 수 없습니다. 시크릿 관리를 참조하세요

각각을 백업하고 복원하는 방법은 백업 및 복원에 있습니다.