시크릿 및 환경 변수
Convex 백엔드의 API 키와 환경 변수를 관리하세요.
Builder 툴바의 Settings 버튼을 클릭하면 Settings 시트가 열립니다. 시트는 세 개의 섹션으로 구성되어 있습니다.
| 섹션 | 용도 |
|---|---|
| General | 프로젝트 이름 및 지식 베이스 |
| SEO & sharing | 사이트 제목, 설명, 파비콘 설정 |
| Secrets | Convex 백엔드의 환경 변수 |
시크릿을 추가하려면 어떻게 하나요?
섹션 제목: “시크릿을 추가하려면 어떻게 하나요?”- Builder 툴바의 Settings 버튼을 클릭합니다
- Secrets 탭을 엽니다
- 이름(예:
STRIPE_SECRET_KEY)과 값을 입력합니다 - Add를 클릭합니다
앱에서 시크릿을 사용하려면 어떻게 하나요?
섹션 제목: “앱에서 시크릿을 사용하려면 어떻게 하나요?”시크릿은 앱의 Convex 백엔드와 동기화됩니다. Convex action/mutation/query 코드에서 process.env.SECRET_NAME 형식으로 참조할 수 있습니다. 시크릿은 frontend 코드나 pod 수준의 환경 변수로는 사용할 수 없습니다. 이는 시크릿이 브라우저 번들에 노출되는 것을 방지하기 위해서입니다.
AI는 기능을 구현할 때 시크릿을 자동으로 활용합니다.
"Accept payments with Stripe"→STRIPE_SECRET_KEY사용"Send emails with Resend"→RESEND_API_KEY사용"Add Google OAuth"→GOOGLE_CLIENT_ID및GOOGLE_CLIENT_SECRET사용
시크릿은 Convex 백엔드 함수(action 및 mutation)에서만 접근 가능하며, frontend React 코드에서는 사용할 수 없습니다. AI는 process.env를 통해 시크릿을 읽는 Convex 함수를 생성합니다.
시크릿을 생성한 후 확인하거나 수정할 수 있나요?
섹션 제목: “시크릿을 생성한 후 확인하거나 수정할 수 있나요?”시크릿 값은 기본적으로 마스킹 처리됩니다. 가시성을 토글하여 값을 확인하거나, 수정하거나, 삭제 후 다시 생성할 수 있습니다.
AI가 내 시크릿을 볼 수 있나요?
섹션 제목: “AI가 내 시크릿을 볼 수 있나요?”AI는 시크릿 이름은 볼 수 있지만 값은 볼 수 없습니다. 이를 통해 AI는 민감한 데이터를 노출하지 않으면서도 기능 구현 시 올바른 환경 변수를 참조할 수 있습니다.
민감한 키 감지
섹션 제목: “민감한 키 감지”Proyecta는 일반적인 민감한 키 패턴(API 키, 토큰, 비밀번호)을 자동으로 감지하여 UI에서 값을 마스킹 처리합니다.
사이트 메타데이터
섹션 제목: “사이트 메타데이터”SEO & sharing 섹션에서 다음 항목을 설정할 수 있습니다.
- Site title — 브라우저 탭과 검색 결과에 표시됩니다
- Site description — SEO 메타 설명으로 사용됩니다
- Favicon — 브라우저 탭에 표시되는 아이콘입니다
이 설정들은 프로젝트에 저장되며 publish 시 적용됩니다.
지식 베이스
섹션 제목: “지식 베이스”Knowledge Base 섹션에서는 AI가 앱을 구현할 때 활용할 참고 자료와 컨텍스트를 추가할 수 있습니다. 브랜드 가이드라인, 기술 사양, 또는 AI가 더 나은 결정을 내리는 데 도움이 되는 모든 문서를 추가해 보세요.
자주 묻는 질문
섹션 제목: “자주 묻는 질문”시크릿은 암호화되어 저장되나요?
시크릿은 프로젝트에 저장되어 Convex deployment와 동기화됩니다. commit된 코드에는 절대 노출되지 않습니다.
개발 환경과 프로덕션 환경에 각각 다른 시크릿을 설정할 수 있나요?
현재는 시크릿이 개발 런타임과 published(프로덕션) Convex deployment 모두에 동일하게 적용됩니다. 환경별 시크릿 관리 기능은 향후 릴리스에서 제공될 예정입니다.
실수로 시크릿을 노출했다면 어떻게 해야 하나요?
즉시 기존 시크릿을 삭제하고, 해당 서드파티 제공업체에서 키를 폐기한 후, 새로운 키를 생성하세요.
시크릿과 커넥터의 차이점은 무엇인가요?
시크릿은 사용자가 직접 관리하는 원시 환경 변수입니다. 커넥터는 Proyecta가 자격 증명 저장, 인증, 토큰 갱신, 감사 로그를 대신 처리해 주는 관리형 통합입니다. 커넥터가 제공되는 경우(Stripe, Slack, Resend, ElevenLabs)에는 커넥터를 사용하고, 아직 커넥터가 없는 서비스에는 시크릿을 사용하세요.