앱을 위한 스테이징 환경 구축 방법

스테이징 환경을 구축하려면 앱의 두 번째 복사본을 자체 비공개 URL에 배포하고, 자체 데이터베이스와 테스트용 API 키를 부여한 다음, 운영 환경의 설정과 최대한 똑같이 맞추세요. 그리고 중요한 변경 사항은 모두 먼저 스테이징에 배포하고, 주요 흐름을 점검한 뒤, 스테이징이 정상적으로 보일 때만 운영 환경에 배포하세요.

이 개념이 처음이라면 스테이징 환경이란 무엇인가에서 개념을 설명합니다. 이 가이드는 DevOps 팀을 운영하지 않고 AI 도구로 만드는 사람을 위한 실제 구축 방법입니다.

개발, 스테이징, 운영

대부분의 작은 앱에는 세 가지 환경이 필요합니다. 첫 번째 환경이 빌더의 미리보기일 뿐이더라도 말이죠.

스테이징의 목적은 운영 환경처럼 동작하는 것입니다. 같은 코드, 같은 스택, 같은 종류의 설정을 갖추되, 그곳에서 실수해도 아무도 피해를 입지 않아야 합니다.

1단계: 스테이징이 무엇과 맞아야 하는지 정하기

문제가 운영 환경에 나타나기 전에 스테이징에서 드러나야 스테이징이 쓸모 있습니다. 다음을 맞추세요.

• 같은 코드를 같은 방식으로 배포.
• 같은 스택과 버전: 프레임워크, 런타임, 데이터베이스 종류.
• 같은 종류의 설정: 같은 환경 변수 이름을 쓰되 값은 테스트용으로.
• 같은 서비스: 운영 환경에 웹 앱과 API가 있다면 스테이징에도 둘 다 있어야 합니다.

규모(더 작은 머신도 괜찮습니다)와 데이터는 다를 수 있습니다.

2단계: 복사본 만들기

가장 간단한 방법은 같은 프로젝트를 staging.yourapp.com이나 yourapp-staging.example.com처럼 다른 URL에 한 번 더 배포하는 것입니다.

방법은 호스트에 따라 다릅니다.

• 내장된 미리보기나 스테이징 배포를 제공하는 호스트는 Git 브랜치마다 자동으로 만들 수 있습니다.
• 그런 기능이 없는 호스트: 같은 코드로 두 번째 앱이나 프로젝트를 만들고 따로 배포하세요.
• Git에 있는 코드: staging 또는 main 브랜치를 스테이징에 배포되도록 유지하고, 운영 환경은 릴리스에서 배포하세요. AI로 만든 앱에서 Git을 쓰는 방법을 참고하세요.

3단계: 스테이징에 자체 데이터베이스 주기

이 단계가 여러분을 지켜 줍니다. 스테이징과 운영이 데이터베이스를 공유하면, 레코드를 지우는 테스트가 실제 레코드를 지워 버립니다.

• 스테이징 전용 데이터베이스를 만드세요.
• 시드 데이터로 채우세요. AI가 만들어 줄 수 있는 현실적인 가짜 레코드입니다.
• 운영 데이터의 복사본이 필요하다면, 먼저 이름, 이메일 등 개인정보를 제거하거나 뒤섞으세요.

빈 데이터베이스를 현실적인 테스트 데이터로 채우는 시드 스크립트를 작성해 주세요. 고객 20명, 여러 상태의 주문 50건, 관리자 사용자 2명을 만들어 주세요. 명백하게 가짜인 이름과 example.com 이메일 주소를 사용하세요.

설정을 신뢰하기 전에, 각 복사본이 어떤 데이터베이스에 연결되는지 확인하세요. 직접 물어보세요.

이 앱은 어떤 데이터베이스에 연결되나요? 그 설정은 어디에서 오나요? 비밀번호가 아니라 변수 이름을 보여 주세요.

4단계: 테스트 키와 분리된 설정 사용하기

외부 서비스와 통신하는 모든 것은 스테이징에서 테스트 자격 증명을 써야 합니다.

• 결제는 테스트 모드(예: Stripe 테스트 키)로 설정해서 실제 카드에 요금이 청구되지 않게 하세요.
• 이메일은 샌드박스로 보내거나 내 주소로만 보내서, 고객이 테스트 메시지를 받지 않도록 하세요.
• AI와 기타 유료 API는 별도의 키와 낮은 지출 한도를 사용하세요.
• 웹훅은 운영이 아니라 스테이징 URL을 가리키게 하세요.

두 환경에서 변수 이름은 같게 두고 값만 바꾸세요. 그러면 코드가 자신이 어디에서 실행되는지 알 필요가 없습니다. 이에 대한 자세한 내용은 API 키를 안전하게 보관하는 방법을 참고하세요.

5단계: 스테이징을 비공개로 유지하기

스테이징은 공개되어 있으면 안 됩니다.

• 로그인, 비밀번호, 또는 팀 이메일 허용 목록 뒤에 두세요.
• noindex 메타 태그나 X-Robots-Tag 헤더로 검색 엔진이 색인하지 않게 하세요.
• 공개 사이트에서 스테이징으로 링크하지 마세요.
• 다르게 보이게 하세요. 색이 들어간 "STAGING" 배너를 두면 잘못된 탭에서 테스트하는 일을 막을 수 있습니다.

APP_ENV 환경 변수가 "staging"일 때는 모든 페이지 상단에 밝은 노란색 배너를 추가해 주세요. 배너에는 "STAGING — 테스트 데이터만 사용"이라고 적어 주세요. 이 경우 noindex 메타 태그도 추가해 주세요.

6단계: 출시 루틴 만들기

스테이징은 매번 사용할 때만 도움이 됩니다. 간단한 루틴은 다음과 같습니다.

1. 개발 환경에서 변경하고 미리보기에서 확인합니다.
2. 스테이징에 배포합니다.
3. 핵심 흐름을 점검합니다. 가입, 로그인, 주요 기능, 결제, 그리고 이번 변경이 건드린 모든 부분.
4. 무언가 깨지면 고치고 다시 스테이징에 배포합니다.
5. 같은 버전을 운영 환경에 배포합니다.
6. 운영 환경을 빠르게 확인합니다. 같은 흐름을 간단히 한 번 더 봅니다.

핵심 흐름은 짧은 테스트 스크립트로 적어 두세요. 무엇을 포함할지는 출시 전에 앱을 테스트하는 방법을 참고하세요.

7단계: 데이터베이스 변경을 신중하게 다루기

데이터베이스 구조 변경(열 추가, 테이블 이름 변경)은 스테이징이 진가를 발휘하는 지점입니다.

• 모든 구조 변경은 먼저 스테이징에서 실행하세요.
• 새 기능이 작동하는지뿐 아니라 기존 데이터가 무사한지 확인하세요.
• 운영에서 같은 변경을 실행하기 전에 운영 데이터베이스를 백업하세요. 앱 데이터베이스를 백업하는 방법을 참고하세요.
• 이름을 바꾸거나 삭제하기보다 추가하는 변경을 선호하세요. 그래야 롤백했을 때 이전 버전도 계속 작동합니다.

예시 프롬프트

이 데이터베이스 변경을 운영 환경에서 실행하면 기존 데이터에 어떤 일이 일어나는지 설명해 주세요. 삭제되거나 이름이 바뀌는 것이 있나요?

API URL, 키, 이메일 발신자, 사이트 자체의 URL 등 환경별 설정을 모두 환경 변수에서 가져오도록 해 주세요. 스테이징과 운영에서 변수 이름은 같아야 합니다. 목록도 만들어 주세요.

이 앱이 하는 일을 바탕으로, 출시할 때마다 스테이징에서 테스트해야 할 흐름의 짧은 체크리스트를 작성해 주세요.

흔한 실수

• 데이터베이스 공유. 가장 큰 피해를 주는 실수입니다. 스테이징은 항상 자체 데이터베이스를 가져야 합니다.
• 스테이징에 실서비스 키 사용. 실제 결제, 실제 고객에게 가는 실제 이메일이 발생합니다.
• 스테이징이 운영과 어긋남. 버전이나 설정이 다르면 스테이징은 문제를 잡지 못하게 됩니다.
• 공개되어 색인되는 스테이징 사이트. 실제 사이트 옆에 검색 결과로 뜨게 됩니다.
• "작은" 변경이라며 스테이징을 건너뜀. 작은 변경도 무언가를 망가뜨립니다.
• 잘못된 탭에서 테스트. 눈에 띄는 배너가 이를 해결합니다.

체크리스트

• 스테이징이 운영과 같은 코드, 스택, 서비스를 실행합니다.
• 스테이징은 테스트 데이터 또는 정제된 데이터를 담은 자체 데이터베이스를 가집니다.
• 결제, 이메일, 유료 API는 스테이징에서 테스트 키를 씁니다.
• 환경마다 변수 이름이 같고, 값만 다릅니다.
• 스테이징은 로그인이나 비밀번호 뒤에 있고 색인되지 않습니다.
• 스테이징에 있을 때 배너가 표시됩니다.
• 모든 출시는 먼저 스테이징에 배포되고, 확인할 흐름 목록이 문서로 있습니다.
• 데이터베이스 변경은 먼저 스테이징에서 실행되고, 출시 전에 운영 백업을 받습니다.

Mythex의 스테이징

Mythex의 Publish는 앱마다 라이브 URL 하나를 제공하며, 별도의 스테이징 전환 기능은 없습니다. 실제로는 두 가지 선택지가 있습니다.

• 출시 전 점검으로 미리보기 사용. 모든 프로젝트는 비공개 클라우드 작업 공간에서 라이브 미리보기로 실행됩니다. /test를 입력하면 에이전트가 사용자처럼 화면을 클릭하며 테스트하고, 공유 링크로 게시하지 않고도 고객이나 팀원이 미리보기를 검토할 수 있습니다. 미리보기와 코드를 참고하세요. 혼자 하는 많은 프로젝트에는 이것으로 충분합니다.
• 스테이징으로 쓸 두 번째 프로젝트. Pro 플랜에서는 프로젝트를 내보낸 뒤 새 프로젝트로 가져오고, 그 프로젝트에 자체 데이터베이스와 테스트 키 비밀 값을 주고, 자체 슬러그로 게시할 수 있습니다. 운영 프로젝트를 게시하기 전에 이곳에 먼저 배포하세요.

어느 쪽이든, 파괴적인 작업을 테스트하기 전에 미리보기와 게시된 앱이 어떤 데이터베이스를 쓰는지 에이전트에게 물어보고, 잘못된 변경은 체크포인트로 되돌리세요. 앱을 더 넓게 라이브로 전환하는 방법은 AI 프로토타입을 운영 환경으로 옮기는 방법을 참고하세요.

자주 묻는 질문