환경 변수와 시크릿이란? 쉽게 정리한 가이드

환경 변수는 DATABASE_URL이나 STRIPE_SECRET_KEY처럼 이름이 붙은 설정 값으로, 코드에 직접 적는 대신 앱이 실행될 때 전달됩니다. 시크릿은 값이 비공개로 유지되어야 하는 환경 변수입니다. API 키, 비밀번호, 서명 키가 여기에 해당하죠. 이런 값을 코드 밖에 두면 앱을 수정하지 않고도 값을 바꿀 수 있고, 테스트용과 실제 고객용으로 다른 값을 쓸 수 있으며, 코드를 공유하거나 공개할 때 값이 새어 나가는 것도 막을 수 있습니다.

AI로 만들 때 왜 중요할까요

앱이 다른 서비스와 연결되는 순간, 예를 들어 결제를 받거나 이메일을 보내거나 AI 모델을 호출하는 순간 키가 필요해집니다. AI 앱 빌더도 이런 키를 자주 요청하는데, 키가 어디에 저장되느냐에 따라 앱의 안전성이 달라집니다.

AI로 만든 앱에서는 보통 두 가지 실수가 생깁니다.

• 키를 채팅이나 코드에 그대로 붙여 넣는 경우. 키가 채팅 기록, 프로젝트 파일, 내보내기 파일, 저장소에 남습니다. 이 키를 보는 누구든 내 계정을 쓸 수 있어요.
• 키를 브라우저에서 사용하는 경우. Stripe나 OpenAI를 호출하는 코드가 페이지에서 실행되면 방문자 모두에게 키가 전달됩니다. 자동화된 스캐너가 노출된 키를 계속 찾고 있다는 점도 기억해 두세요.

환경 변수를 이해하면 두 문제를 알아채고 해결을 요청할 수 있습니다.

일상 속 비유: 호텔 금고

앱의 코드는 호텔 객실과 같습니다. 손님, 청소하는 직원, 카드키를 준 사람 모두가 그 방을 드나들죠. 여권을 책상 위에 두는 사람은 없을 거예요.

환경 변수는 객실의 금고와 같습니다. 방은 금고가 있다는 사실과 필요할 때 여는 방법을 알고 있지만, 여권은 금고 안에 들어 있습니다. 그리고 테스트 환경에서 실서비스로 옮길 때는 방을 새로 꾸미지 않고, 그 방의 금고에 다른 여권을 넣기만 하면 됩니다.

작동 원리

코드는 값이 아니라 이름을 참조합니다. 서버에서 실행되는 JavaScript라면 process.env.STRIPE_SECRET_KEY처럼 씁니다. 앱이 시작되면 실행 플랫폼이 그 이름에 맞는 값을 채워 넣습니다. 플랫폼 설정에서 값을 바꾸고 재시작하거나 다시 배포하면, 코드를 고치지 않아도 앱이 새 값을 사용합니다.

값이 저장되는 위치는 앱이 실행되는 곳에 따라 다릅니다.

공개 설정과 시크릿

모든 환경 변수가 비밀인 것은 아닙니다. 두 그룹으로 나눠 보면 이해하기 쉽습니다.

웹 프레임워크는 이 구분을 이름 규칙으로 드러냅니다. Vite에서는 이름이 VITE_로 시작하는 변수만 브라우저 코드에 포함되고, Next.js에서는 접두사가 NEXT_PUBLIC_입니다. 이 규칙은 일종의 안전장치입니다. 이 접두사가 붙은 값은 방문자가 내려받는 파일에 들어가므로, 시크릿에는 절대 이런 접두사를 붙이면 안 됩니다.

실제 예시: AI 요약 버튼

AI 모델을 호출하는 “이 메모 요약하기” 버튼을 만든다고 해 봅시다.

안전하지 않은 방식: 버튼 코드가 브라우저에서 실행되면서 API 키를 코드에 직접 적어 AI 제공업체를 호출합니다. 미리보기에서는 잘 동작하지만, 누구든 개발자 도구를 열어 키를 복사한 뒤 내 계정으로 비용을 쓸 수 있습니다.

안전한 방식:

1. AI 제공업체에서 키를 만들고, 프로젝트 설정에 OPENAI_API_KEY(또는 비슷한 이름)라는 시크릿으로 저장합니다.
2. 백엔드에 POST /api/summarise 경로를 두고, 이 경로가 process.env.OPENAI_API_KEY를 읽은 뒤 사용자가 로그인했는지 확인하고 제공업체를 호출하게 합니다.
3. 버튼은 제공업체가 아니라 내 경로를 호출합니다. 브라우저는 키를 전혀 보지 못합니다.
4. 같은 시크릿을 배포된 앱의 설정에도 추가하고 다시 배포하면, 실서비스 사이트에서도 동작합니다.

이 패턴, 즉 브라우저는 내 서버를 호출하고 서버가 키를 보관하며 외부 서비스를 호출하는 방식은 결제, 이메일, 지도 등 모든 유료 API에 적용됩니다. AI의 경우는 LLM API 사용 가이드에서 더 깊이 다룹니다.

핵심 용어

• .env 파일: 로컬 개발에서 쓰는 NAME=value 형식의 텍스트 파일입니다. 커밋되지 않도록 .gitignore에 넣어 두세요.
• .env.example: 실제 값 없이 변수 이름만 적은 복사본입니다. 다른 사람이 어떤 변수를 설정해야 하는지 알 수 있도록 커밋해 둡니다.
• 교체(Rotate): 시크릿을 새 값으로 바꾸고 기존 값은 폐기하는 것입니다.
• 범위 / 권한: 많은 제공업체가 특정 작업만 할 수 있는 키를 만들게 해 줍니다. 이메일 발송만 가능한 키는 모든 작업이 가능한 키보다 위험이 적습니다.
• 테스트 키 vs 실서비스 키: Stripe 같은 서비스는 테스트용과 실제 결제용 키를 따로 제공합니다. 출시 전까지는 테스트 키를 사용하세요.
• 서명 시크릿: 웹훅 같은 메시지가 실제로 발신자에게서 왔는지 확인하는 데 쓰는 시크릿입니다.

흔한 실수와 오해

• “저장소가 비공개니까 키를 넣어도 괜찮아요.” 비공개 저장소도 공유되고, 포크되고, 내보내지고, 노트북에 복제됩니다. 키는 여전히 거기 있으면 안 됩니다. GitHub에 프로젝트를 연결했다면 .env 파일이 포함되지 않았는지 확인하세요.
• “지웠으니 이제 없는 거죠.” Git은 기록을 남기고, 채팅 로그에도 메시지가 남아 있습니다. 키가 한 번이라도 노출됐다면 교체하세요.
• 시크릿에 공개용 접두사를 붙이는 것. VITE_OPENAI_KEY로 이름을 지으면 키가 브라우저 번들에 들어갑니다.
• 다시 배포하는 것을 잊는 것. 설정에서 변수를 바꿔도 보통 앱을 재시작하거나 다시 게시해야 반영됩니다.
• 모든 용도에 키 하나만 쓰는 것. 테스트와 실서비스, 앱별로 키를 나눠 두면 하나만 폐기해도 나머지는 영향을 받지 않습니다.
• 사용 한도가 없는 것. 유료 API라면 키가 유출되는 경우에 대비해 제공업체 대시보드에서 예산이나 한도를 설정하세요.

AI 빌더에 요청할 내용

• “Stripe 시크릿 키를 STRIPE_SECRET_KEY 환경 변수에서 읽어 주세요. 서버에서만 사용해 주세요.”
• “시크릿이 클라이언트 코드에서 쓰이지 않도록 하고, VITE_ 또는 NEXT_PUBLIC_ 접두사를 붙이지 않도록 해 주세요.”
• “앱에 필요한 모든 변수를 값 없이 나열한 .env.example을 만들고, .env가 git 무시 대상인지 확인해 주세요.”
• “빌드된 프런트엔드 파일에서 API 키처럼 보이는 문자열이 없는지 확인해 주세요.”

출시 전에 확인할 다른 항목과 함께 시크릿을 다루는 내용은 AI로 만든 앱의 보안 체크리스트에서 볼 수 있습니다.

Mythex의 시크릿

Mythex에서 시크릿은 미리보기 샌드박스와 게시된 앱 모두에 주입되는 프로젝트 환경 변수입니다. 프로젝트 설정 → Secrets에서 추가하거나, 채팅에서 /secrets를 입력하면 됩니다. 에이전트가 키가 필요하면 채팅에 시크릿 카드를 보여 주므로, 값은 채팅 기록이 아니라 입력 필드에 들어갑니다. 실서비스 중인 앱의 시크릿을 바꿨다면 다시 게시해야 배포에 반영됩니다. 프로젝트 내보내기에는 시크릿이 포함되지 않으며, 가져온 .env 파일은 시크릿이 제거되므로 설정에서 다시 추가해야 합니다. 자세한 내용은 문서의 환경 변수와 시크릿과 채팅에서 시크릿 사용하기를 참고하세요.

자주 묻는 질문