검수와 시작

에디터와 운영 환경의 분리

에디터에서 새 탭으로 여는 데이터베이스와 데이터베이스 오른쪽 펼침 메뉴의 캐시 메모리·스토리지는 운영 Release와 같은 공용 데이터를 사용합니다. 소스, Debug와 Release 코드는 분리되지만 데이터 편집은 즉시 현재 웹사이트에 반영됩니다.

• 데이터베이스: 에디터, 검수와 운영은 web-{website-id} PostgreSQL DB 하나를 사용합니다.
• 캐시 메모리: 모든 실행 대상이 cake20:web-{website-id}:* Redis prefix를 공유합니다.
• 빌드 파일: 디자인 Preview cache, build/debug 검수와 build/release 운영 결과를 분리합니다. 빌드된 화면 자산은 각 결과의 app에 저장하며 build/*/ui는 사용하지 않습니다.
• 소스는 하나를 함께 사용하지만, 수정된 소스가 운영에 적용되는 시점은 사용자가 최종 배포를 실행한 뒤입니다.
• 검수 Runtime은 예약 Task를 실행하지 않지만 API와 수동 작업의 데이터 변경은 공용 DB·Redis·files에 그대로 남습니다.

Vite UI Preview

• 에디터가 열리면 웹사이트별 Vite 개발 서버를 내부 loopback 포트와 샌드박스에서 실행하고 Manager가 HTTP와 HMR WebSocket을 중계합니다.
• Cake20 View 진입 모듈과 화면 Runtime이 준비됐다는 신호를 받은 뒤 Preview를 표시하며, 그전에는 연결 오류 대신 준비 화면을 유지합니다. 웹사이트의 build/preview/vite 캐시는 다음 디자인 서버 시작에도 재사용합니다.
• Cake20 View·CSS 저장은 전체 production 빌드나 iframe 교체 없이 변경 모듈만 HMR로 갱신합니다. 구조 설정 변경 때만 디자인 서버를 다시 시작합니다.
• 디자인 서버는 에디터 재진입과 검수 화면 전환에도 재사용하며 Preview 트래픽이 10분 동안 없으면 종료합니다.
• 이미지, SVG와 ICO는 왼쪽 스크립트 영역에 표시합니다. SVG는 이미지와 스크립트를 전환해 저장 전 화면과 소스를 모두 확인할 수 있으며, PNG, JPEG, WebP, GIF, AVIF, BMP와 ICO는 이미지로 표시합니다.
• 오른쪽 WEB PREVIEW는 Cake20 View·CSS 또는 HTML을 선택할 때만 화면을 바꾸고, 그 밖의 파일을 선택하면 마지막 웹 화면을 그대로 유지합니다.
• Web Preview 오른쪽의 데스크탑·태블릿·모바일 메뉴에서 실제 viewport 해상도를 선택할 수 있습니다. 선택한 화면은 검은 기기 프레임과 함께 창 안에 비율대로 축소되며 가로·세로 전환과 마지막 선택을 유지합니다.
• package.json의 device와 orientation은 이 메뉴의 최초 선택입니다. 설정이 없으면 desktop·landscape로 시작합니다.
• 첫페이지 메뉴에서 index 또는 다른 페이지를 선택하면 소스 선택과 관계없이 그 화면을 유지합니다. 선택 안함은 현재 파일 Preview로 돌아갑니다.
• 콘솔창은 스크립트 영역 아래에 고정되며 경계선을 드래그하거나 방향키로 높이를 조절할 수 있습니다.
• 에디터 상단은 별도의 디자인 모드·런타임 모드 표시를 두지 않습니다. 시작·종료 버튼으로 검수 웹사이트를 제어하고 오른쪽 열기로 새 창에서 확인합니다.
• API와 server/tasks 파일은 에디터의 파일별 테스트 실행으로 별도 확인합니다.
• Preview에는 웹사이트 서버나 잠자기·깨우기가 없습니다. 실제 endpoint 검수에만 -test 웹사이트를 사용합니다.
• Preview는 수정 확인용입니다. 새 웹사이트와 템플릿 시작 소스는 에디터 검수 없이 웹사이트 목록에서 바로 시작할 수 있습니다.

Preview에서 요소 직접 수정

Preview는 화면과 Cake20 View 원본 위치를 연결해 정적 콘텐츠를 직접 수정합니다. 검수 실행 중 요소선택을 켜면 검수 사이트를 중지하지 않고 최신 디자인 Preview로 전환해 요소를 고른 뒤 실행 화면으로 돌아갑니다. MCP가 수정 중이어도 요소를 선택할 수 있고 저장 직전에 파일 충돌을 다시 검사합니다.

• 요소선택을 켜고 화면을 누르면 Cake20 View AST에 기록된 파일, hash와 원본 위치를 기준으로 요소편집 창을 엽니다. 다른 곳에서 파일이 먼저 바뀌었다면 덮어쓰지 않고 Preview에서 다시 선택하도록 안내합니다.
• 이지모드에서는 해상도 왼쪽의 요소선택을 사용합니다. 같은 Cake20 View AST 위치를 요소편집 창으로 보내지 않고 페이지·파일·태그·source offset·selector만 담은 짧은 AI Chat 초안으로 전달합니다.
• 정적 텍스트와 속성, public 이미지는 요소편집에서 바로 바꿉니다. 텍스트의 폰트·크기·굵기·기울기·장식·정렬은 정적 Tailwind class로 저장하며, 직접 수정할 수 없는 변수·표현식과 외부 이미지는 AI Chat 요청으로 연결합니다.
• 줄바꿈이나 하위 태그로 분리된 정적 문구는 원본 위치별 입력란으로 모두 표시합니다. 연결된 Cake20 View 파일이 여러 개면 모든 파일의 hash와 위치를 확인한 뒤 한 작업으로 저장하고 실행 취소도 함께 처리합니다.
• 요소편집 창은 제목 영역을 드래그해 Preview를 가리지 않는 화면 안쪽 위치로 옮길 수 있습니다. 마지막 위치는 현재 에디터 화면을 닫을 때까지만 메모리에 유지합니다.
• 문구와 정적 스타일은 저장하면 현재 iframe과 Cake20 View 컴포넌트 상태를 유지한 채 Vite HMR로 즉시 반영합니다.
• AI 요청은 페이지·파일·태그·source offset·selector·문구만 간단히 담고, 필요할 때 동적 표현식과 이미지 경로를 덧붙입니다.
• 요소편집은 최근 100개를 기억합니다. Ctrl+Z 또는 Cmd+Z는 최근 작업부터 한 단계씩 원본을 복구하며, 그 사이 파일이 달라졌다면 충돌을 알리고 임의로 덮어쓰지 않습니다.
• 저장 후에는 변경된 경우에만 Preview를 갱신합니다. 현재 페이지에서 실제로 이동한 window와 스크롤 태그의 위치만 기억하고, 다시 그릴 때 스크롤 애니메이션 없이 같은 위치로 복원합니다.

에디터 검수

에디터와 MCP는 web-{website-id} 소스 하나를 함께 사용합니다. 운영 결과물은 build/release, 검수 결과물은 build/debug에 분리하고 빌드된 화면 자산은 각각의 app에 저장합니다. build/*/ui는 사용하지 않습니다.

에디터의 전체 검수는 build/debug Runtime을 -test 주소에서 실행하되 web-{website-id} DB, Redis와 files를 공유합니다.

검수 Runtime을 준비한 뒤 server/**/*.test.ts를 Bun으로 실행합니다. 모두 성공하면 검수 웹사이트를 WEB PREVIEW 런타임 모드로 바꾸며 새 창 아이콘으로 별도 브라우저에서도 열 수 있습니다.

검수 버튼이나 F9로 실행하며, 실행 중 다시 누르면 테스트 웹사이트를 중지하고 준비 단계 없이 기존 편집 Preview로 돌아갑니다.

서버 API가 포함된 전체 검수는 MCP beta_service를 사용할 수 있습니다. 검수 중 예약 Task는 비활성화되지만 수동 데이터 변경은 공용 데이터에 반영됩니다.

시작과 자동 배포

Cake20은 현재 저장된 소스 트리와 운영 release에 기록된 Git 소스 트리를 비교하지만 웹사이트 페이지에는 항상 시작 버튼을 표시합니다.

시작은 release가 없거나 소스가 달라졌으면 현재 소스를 운영 release로 먼저 배포한 뒤 실행합니다. 준비된 release가 있으면 빌드 없이 바로 실행합니다.

새 웹사이트는 검수 환경을 먼저 만들지 않으며 첫 검수 때 build/debug를 준비합니다. DB 모델이 있는 웹사이트의 공용 DB는 필요한 첫 빌드에서 생성합니다.

배포 빌드는 Cake20 View UI, API, route, hook, event, shared, npm dependency와 Prisma Client를 하나의 release로 생성합니다. 새 release 적용에 실패하면 기존 release로 되돌립니다.

운영 웹사이트가 정상 시작되면 현재와 직전 Release를 보존합니다. Preview는 최신 cache를 재사용하고 Debug와 임시 산출물은 다시 만들 수 있도록 정리합니다.

빌드는 원본 소스를 직접 읽으며 build/debug와 build/release에는 소스 사본을 만들지 않습니다. 편집기와 MCP 저장은 계속 가능하지만 빌드 중 저장한 변경의 포함 여부는 보장하지 않으므로 새 검수·배포 빌드로 확인합니다.

실행 URL

시작하면 할당된 내부 포트에 하나의 웹 프로세스가 실행됩니다. API와 예약 task도 같은 프로세스에서 실행됩니다. 공개 파일은 루트 files에 저장하고 Bun 임시 파일은 내부 tmp에 분리합니다.

Bun 실행 파일과 설치·Runtime 캐시는 TEMPLATE_ROOT의 .bun을 모든 사이트가 공유하며 사이트별 tmp/bun은 만들지 않습니다.

운영·검수 Runtime을 시작할 때 저장된 포트가 다른 웹사이트 또는 프로세스와 충돌하면 빈 포트를 자동으로 다시 할당합니다. 운영 웹사이트의 변경된 포트는 관리 정보에도 함께 반영합니다.

Cake20 관리자가 다시 시작돼도 기존 웹사이트 PID와 웹 프로세스는 유지합니다. 실행이 끊긴 웹사이트만 자동 복구하며 멈춘 웹사이트는 자동으로 시작하지 않습니다.

일반 실행 준비는 시작 중, sleeping Runtime을 다시 실행할 때만 깨우는 중, 감시기가 실제 재시작을 수행하는 동안만 자동 복구 중으로 표시합니다.

HTTP, Task와 Queue job 활동이 5분간 없고 열린 SSE·WebSocket 연결도 없으면 내부 sleeping 상태로 정상 종료합니다. 사용자 화면에는 실행 중으로 표시하며 다음 요청은 기존 release를 빠르게 깨워 전달합니다.

운영에 배포되고 시작된 웹사이트는 active: true인 cron Task 실행 5초 전에 내부 HTTP 핑으로 자동 기상합니다.

에디터에서 실행한 테스트 웹사이트는 에디터 연결 중에는 잠들지 않으며, 마지막 테스트 에디터가 닫히거나 연결이 2분간 끊기면 stopped 상태로 종료합니다.

구독 중이 아닌 웹사이트는 마지막 공개 HTTP·HTTPS 접속 후 90일이 지나면 소스와 files, 공용 DB·Redis를 포함한 모든 데이터를 자동으로 영구 삭제합니다.

관리자는 웹사이트 페이지의 전체 웹사이트 재시작으로 실행 대상만 1초 간격으로 하나씩 재시작할 수 있습니다.

https://web-{website-id}.cake20.com

console 로그

• UI 출력은 브라우저 개발자 콘솔과 에디터 Preview 로그에 함께 표시하고, 선택 파일의 테스트 출력은 Console의 Test 출력에 표시합니다. 실행 모드 전환 같은 에디터 동작 안내는 Preview, 실행 중인 서버 출력은 Server 로그에 기록합니다.
• 테스트·운영 빌드는 별도 샌드박스 워커에서 실행하며 시작, 완료와 오류를 해당 웹사이트 로그에 기록합니다. 사용자 소스 빌드 오류는 Cake20 시스템 오류로 전파하지 않습니다.
• API에는 요청 파일 경로, task에는 작업 이름이 자동으로 붙습니다.
• 별도의 Cake20 로그 함수를 선택할 필요 없이 모든 코드에서 console.log를 사용합니다.

console.log("처리를 시작합니다.", data);

소스와 DB 자동 백업

• 각 웹사이트는 독립된 로컬 Git 저장소를 사용하며 배포 직전에 변경된 소스를 자동 커밋합니다.
• 기존 웹사이트도 관리자가 배포할 때 현재 소스로 Git 저장소와 첫 커밋을 자동 생성합니다.
• release.json에는 빌드에 사용한 Git 커밋 SHA를 기록해 release와 소스를 연결합니다.
• .cake, build, backup, files, logs, tmp와 캐시·생성물은 Git에서 제외합니다.
• 매일 00:00 KST에 직전 소스 백업과 Git tree가 다를 때만 일일 소스 체크포인트를 만듭니다. 변경이 없으면 새 백업을 만들지 않습니다.
• 자정 자동 백업은 검수 또는 운영 빌드를 통과한 현재 소스만 편집기에서 보이는 형태의 ZIP으로 저장합니다. 빌드 이후 소스가 바뀌었거나 이전 ZIP과 소스가 같으면 새 ZIP을 만들지 않습니다.
• 실제 DB와 빌드할 Prisma 구조가 다르거나 미적용 migration이 있으면 반영 직전에 dump를 저장합니다.
• 빌드 중 DB가 사라진 경우 빈 DB를 자동 생성하지 않고 중단하므로 백업 및 복원에서 먼저 확인할 수 있습니다.
• 매일 00:00 KST에는 서비스 폴더 밖의 cake20-core-backup에 YYYYMMDD-{웹사이트ID}.dump와 같은 이름의 DB 백업을 저장합니다. 검수된 소스가 바뀌었으면 같은 형식의 .zip도 저장합니다.
• DB 변경 적용 전의 YYYY-MM-DD-build.dump와 MCP 작업 백업은 복구용 자정 백업과 구분해 웹사이트 내부에 저장합니다.
• 웹사이트 설정의 펼침 메뉴에 있는 백업 및 복원에서 소스 체크포인트와 DB dump를 확인합니다.
• 소스 복원은 웹사이트를 중지한 뒤 실행합니다. 현재 변경분을 먼저 커밋하고 선택한 커밋의 파일을 복원한 뒤 새 복원 커밋으로 남깁니다.
• Git 복원은 DB와 files를 변경하지 않습니다. DB는 DB 백업에서 별도로 복원하며 files 자동 복원은 제공하지 않습니다.
• 외부 소스 ZIP과 DB dump는 웹사이트별로 각각 최신 2개만 남기며, 새 백업이 생성될 때 더 오래된 파일을 정리합니다.
• 보존 개수를 넘은 release와 보존 기간이 지난 로그도 자동 정리합니다.
• 매주 최신 DB 백업을 운영 DB와 다른 임시 PostgreSQL DB 또는 PGeasy에 실제로 복원해 table과 row를 확인합니다.
• 전용 Redis는 RDB 무결성을 검사한 뒤 별도 loopback 포트의 임시 Redis로 기동해 복원 가능성을 확인합니다. 운영 DB·Redis는 바꾸지 않습니다.