Cake20 전체 서비스 구조

한눈에 보는 배치 구조

Cake20은 중앙 서비스, 서버별 공개 트래픽과 관리 기능, 웹사이트별 실행 영역을 분리합니다. Gateway는 HTTP와 WebSocket을 처리하고 Core는 Provider와 Worker를 관리하며 Runtime은 동적 웹사이트마다 독립 실행합니다.

• 중앙 한 세트: Hub, Docs, AI 문서, CDN과 Package
• 각 서버: Cake20 Gateway, Cake20 Core와 비공개 Provider·Worker 자식 프로세스
• 사이트 트래픽: 정적 Release는 Gateway가 직접 제공하고 동적 사이트는 Runtime으로 전달
• 설치 패키지: @cake20/runtime, @cake20/provider, @cake20/worker와 @cake20/cli
• 웹사이트마다 분리: 소스, Release, PostgreSQL DB와 files; 동적 사이트만 실행 프로세스

구성 요소의 연결

Hub: 여러 Core를 연결하는 중앙 Control Plane

Hub는 웹사이트 Runtime이 아니라 계정과 여러 Cake20 Core 장비를 관리하는 중앙 서비스입니다. 사이트가 어느 Core에 있는지 찾고, 중앙 로그인과 관리 요청을 올바른 Core로 연결합니다.

• Core 등록, 상태·사양·위치·버전과 설정 불일치를 확인합니다.
• 그룹·예약 배포, 작업 잠금, 재시도, 중단과 전체 롤백을 조정합니다.
• 소스·데이터 백업, 복구 점검과 Hub 자체 백업을 관리합니다.
• 계정·구독, 감사기록, 보안 세션, 알림과 메트릭 이력을 관리합니다.
• 회원과 사이트를 다른 Core로 옮기고 완료 전후 무결성을 확인합니다.
• 실제 웹사이트 소스, DB와 프로세스의 최종 실행 책임은 각 Core에 남습니다.

Gateway: 공개 트래픽만 맡는 서버 입구

Cake20 Gateway는 각 서버의 공개 도메인 입구에서 web-* 기본 주소와 사용자 정의 도메인을 웹사이트에 연결합니다. 일반 사이트 요청은 Core를 거치지 않고 정적 Release 또는 실행 중인 Runtime으로 전달합니다.

• Gateway는 @cake20 패키지가 아니라 서버에 함께 배치하는 독립 Bun 서비스입니다.
• HTTP와 WebSocket을 같은 도메인 규칙으로 분기합니다.
• 정적 사이트는 프로세스 없이 Release 파일을 직접 제공하고 동적 사이트는 Runtime으로 프록시합니다.
• Core의 인증된 Route Snapshot을 저장하고 즉시 알림과 주기 동기화로 갱신합니다.
• 잠든 사이트 요청은 Core에 깨우기를 요청하며, 명시적으로 종료된 사이트는 실행하지 않습니다.
• 접속 사용자와 방문 수를 모아 Core에 일괄 반영합니다.
• Core가 재기동되어도 저장된 Route와 실행 중인 사이트의 공개 트래픽은 계속 처리합니다.

Core: 장비별 웹사이트 Control Plane

Cake20 Core는 브라우저 에디터, Preview, AI Chat, 검수, 배포와 웹사이트 생명주기를 한 서버에서 관리합니다. 일반 사이트 트래픽은 Gateway가 처리하므로 Core는 관리와 실행 제어에 집중합니다.

• 웹사이트 생성·삭제, 템플릿, 도메인 설정, 로그와 실행 상태를 관리합니다.
• 도메인과 실행 대상의 Route Snapshot을 만들어 인증된 Gateway에 전달합니다.
• 공용 DB·Redis·files는 유지하고 Debug와 Release 코드를 분리해 빌드·시작·복구합니다.
• Core 시작 시 Provider와 Worker를 먼저 실행하고 상태·재시작·종료를 함께 관리합니다.
• 사이트 시작은 공용 Worker를 교체하지 않으며, 장애가 확인된 Worker의 교체와 연결 사이트의 순차 재시작은 Core 관리 프로세스만 수행합니다.
• 에디터 전용 Preview와 템플릿 요청은 Core 내부 경로에서 계속 처리합니다.
• Hub가 일시적으로 없어도 장비 내부 웹사이트 관리는 Core가 담당합니다.
• Runtime 구현을 복사하지 않고 @cake20/runtime 공개 기능을 호출합니다.

Core 재기동과 장애 경계

Gateway가 공개 트래픽 경로를 분리하므로 Core를 재기동하거나 교체해도 이미 실행 중인 웹사이트의 서비스 중단 범위를 줄일 수 있습니다.

• 실행 중인 정적·동적 사이트와 기존 WebSocket 연결은 Core 재기동 중에도 유지됩니다.
• 관리 화면, 에디터, AI, 빌드·배포와 새 시작·깨우기는 Core가 돌아올 때까지 사용할 수 없습니다.
• 잠든 사이트는 Core가 없으면 깨울 수 없지만, 이미 실행 중인 Runtime에는 영향을 주지 않습니다.
• Gateway 자체는 서버의 공용 입구이므로 상태 감시와 자동 재기동이 필요합니다.

Provider: Core가 관리하는 외부 서비스 실행 프로세스

@cake20/provider는 AI, Codex, Playwright 기반 MCP 브라우저 점검, 메일, Gmail, Telegram과 결제 연동을 Core 프로세스 밖에서 실행하는 비공개 패키지입니다. Core가 생명주기와 인증을 맡으므로 사용자는 설정하지 않습니다.

• Core와 Provider는 공개 포트가 아닌 로컬 IPC로 통신합니다.
• Core는 MCP 브라우저 도구와 배포 점검을 인증하고 Provider가 실제 브라우저를 실행합니다.
• 관리자 화면에는 공용 Provider나 Provider 주소 설정이 없습니다.
• cake login은 계정에 배정된 Core를 찾아 CLI 연결정보를 자동으로 저장합니다.
• CLI Runtime은 메일·Gmail·Telegram·결제 연결을 인증된 Core API로 받습니다.
• 외부 연동 설정과 인증정보는 Core 서버에 남고 브라우저나 소스에 노출되지 않습니다.

Worker: 서버와 로컬이 공유하는 실행 엔진

@cake20/worker는 DB와 파일 변환처럼 무거운 작업을 Runtime 프로세스 밖에서 실행합니다. Core는 웹사이트 시작 여부와 관계없이 Worker를 먼저 실행하고 각 웹사이트는 필요한 DB 연결을 로컬 IPC에 등록합니다.

• 운영 Worker는 공개 도메인이나 서비스 포트 없이 로컬 IPC로만 연결됩니다.
• Prisma 호환 DB 작업, 배열형 transaction, DB 용량, ZIP과 XLSX 변환을 처리합니다.
• Runtime은 단일 시트 행 데이터와 storage 경로만 유지하고 XLSX 처리는 Worker에 위임합니다.
• 사이트 소스는 Worker를 import하지 않고 기존 db, zip과 excel API를 사용합니다.
• 로컬 CLI도 패키지 Worker를 자동 실행하거나 기존 로컬 Worker를 재사용합니다.
• CLI server는 Core 인증 게이트웨이를 거쳐 서버 내부 Worker를 사용합니다.
• Worker가 교체되면 Core가 연결된 웹사이트를 다시 연결하고 필요한 프로세스를 복구합니다.
• Interactive transaction과 Prisma raw API는 별도 마이그레이션 대상으로 남습니다.

Runtime: 독립적으로 설치하는 웹사이트 엔진

@cake20/runtime은 Core 내부 복사본이 아니라 독립적으로 버전 관리하고 Package 서버에서 설치하는 엔진입니다. Core와 CLI가 같은 검사, UI 빌드, API, PostgreSQL, storage와 서버 실행 기능을 사용합니다.

• local 모드는 data/postgres의 PGlite와 CLI 자동 Worker를 사용합니다.
• server 모드는 내부 Worker의 PostgreSQL 실행을 사용하며 웹사이트별 DB를 분리합니다.
• dev는 화면 HMR, API, DB와 seed를 함께 실행하고 design·preview는 화면만 실행합니다.
• build는 Release를 만들고 start는 만들어진 운영 Release를 실행합니다.
• 설치 패키지와 운영 Release는 dist의 JavaScript와 빌드된 UI 자산을 사용합니다.
• Runtime 버전 차이는 경고로 남기되 가능한 경우 실행을 계속합니다.
• @cake20/db와 @cake20/view는 Runtime 의존성이므로 사이트에서 중복 선언하지 않습니다.

CLI: Core 없이 사용하는 Runtime 인터페이스

@cake20/cli는 호환되는 Runtime 버전 범위를 사용하며 cake 명령을 제공합니다. 폴더나 Cake20 ZIP을 Core에 등록하지 않고도 로컬에서 생성, 검사, 개발, DB 백업, 빌드와 실행할 수 있습니다.

• cake init, prepare와 doctor로 프로젝트와 개발 도구를 준비합니다.
• cake dev, design, preview, build, start와 run으로 폴더와 ZIP을 실행합니다.
• cake db version, export와 import로 로컬·서버 PostgreSQL을 확인하고 옮깁니다.
• cake login은 소속 Core를 자동 연결하고 cake deploy는 검수 후 사이트를 배포합니다.
• Runtime만 필요한 독립 실행에는 Core나 Hub 연결을 강제하지 않습니다.

CDN: 브라우저 공용 자산 배포

https://cdn.cake20.com은 여러 웹사이트가 공유하는 브라우저 전용 ES Module, CSS, 글꼴과 정적 자산을 버전 경로로 제공합니다.

• CodeMirror와 Prisma 언어, Tiptap Rich Editor, DataTables와 Responsive 호환 모듈을 제공합니다.
• IBM Plex Sans와 Lilex 같은 WOFF2 글꼴과 CSS를 자체 호스팅합니다.
• 버전 URL은 변경하지 않고 새 버전은 새 경로로 배포합니다.
• 서버 API·task·job에서는 CDN 모듈을 import하지 않습니다.
• Secret, 인증정보와 사용자별 비공개 데이터를 공개 CDN에 넣지 않습니다.

Package: Cake20 패키지 Registry

https://package.cake20.com은 @cake20 범위 패키지를 내려받는 Registry입니다. 조회와 설치는 공개하고 게시 권한은 운영 계정으로 제한합니다.

• @cake20/runtime, @cake20/provider, @cake20/worker와 @cake20/cli를 독립적으로 배포합니다.
• @cake20/db는 PostgreSQL, Prisma adapter와 PGlite 표준 조합을 제공합니다.
• @cake20/view는 Cake20 View, Router, Cake20 UI 연동과 빌드 도구의 표준 조합을 제공합니다.
• @cake20/exceljs와 @cake20/nitropack은 장기 보존과 호환성을 위한 관리 패키지입니다.
• @cake20 범위만 Package Registry로 지정하고 일반 공개 패키지는 기본 npm Registry에서 받습니다.

프로그램 배포와 데이터 저장소의 경계

서비스 프로그램은 교체 가능한 Release로 배포하고, 사용자 소스·DB·패키지와 백업은 Release 밖의 -files 저장소에 둡니다. 프로그램을 새로 배포해도 지속 데이터가 함께 삭제되거나 덮어써지지 않습니다.

• Core 웹사이트 소스·Release·files: cake20-core-files
• Hub 배포 자산·백업: cake20-hub-files
• CDN 공개 자산: cake20-cdn-public
• Package tarball·메타데이터·인증 파일: cake20-package-files
• CLI 영구 로컬 DB와 업로드: 프로젝트의 data/postgres와 files
• CLI --memory 실행: OS 임시 폴더를 사용하고 종료 시 제거
• 웹사이트 공용 DB와 Manager DB는 분리되며 프로그램 Release가 공용 데이터를 덮어쓰지 않습니다.