# 사이트의 앱 시크릿 저장하기

Source: https://support.kapsulehost.com/ko-kr/site-secrets

Secrets 탭은 API 키, 서명 비밀 값, 서드파티 토큰처럼 Node.js 앱에 필요한 민감한 설정 값을 위한 암호화된 저장소로, 환경별로 구분되어 보관되므로 운영 자격 증명과 미리보기 자격 증명이 서로 섞이는 일이 없습니다.

## Secrets는 어디에 있는가

**웹사이트**를 열고 사이트를 클릭한 다음, 사이트 왼쪽 메뉴에서 **Environment** 그룹을 열고 **시크릿**를 선택하세요. 탭 이름은 **시크릿**입니다.

이 탭은 Node.js 사이트에서만 나타납니다. WordPress, PHP, 정적 사이트에서는 표시되지 않는데, 이들은 설정이 디스크의 파일에 저장되기 때문입니다: WordPress의 경우 `wp-config.php`이고, 순수 PHP 앱의 경우 해당 프레임워크가 읽는 파일입니다.

![Secrets tab for a Node.js site in KPanel](https://support.kapsulehost.com/help/screenshots/site-secrets.812e0706.webp)

## 값은 어떻게 보호되는가

모든 값은 데이터베이스에 저장되기 전에 암호화됩니다. 어떤 값도 읽을 수 있는 텍스트로 저장되지 않으며, 목록 화면에서도 전체 값은 절대 표시되지 않습니다. 마지막 네 글자만 보여주는 마스킹 형태로 표시되므로, 값을 노출하지 않고도 비슷한 키 두 개를 구분할 수 있습니다.

각 행에는 이를 상기시키는 **Encrypted** 표시가 붙어 있습니다. 값을 다시 읽는 것은 페이지를 열기만 하면 일어나는 일이 아니라, 별도의 의도적인 동작입니다.

> **Note:** Secret을 설정, 조회, 삭제하는 모든 작업에는 **sites:write** 권한이 필요합니다. 읽기 전용 팀원은 어떤 키가 존재하는지와 마스킹된 값은 볼 수 있지만, 실제 값은 볼 수 없습니다.

## 두 가지 환경

페이지 상단의 분할 버튼으로 **production**과 **preview**를 전환할 수 있습니다. 이 둘은 완전히 별개의 키 집합입니다. production에서 `STRIPE_SECRET_KEY`을 설정해도 preview에는 생성되지 않으며, preview에서 삭제해도 production에는 영향을 주지 않습니다.

이러한 분리가 바로 이 기능의 핵심입니다. 미리보기 빌드는 저장소 접근 권한이 있는 누구나 트리거할 수 있는 일회성 환경이므로, 실제 운영용 자격 증명이 아니라 테스트용 자격 증명을 담아야 합니다. 미리보기 환경이 어떻게 생성되는지는 [풀 리퀘스트를 위한 미리보기 배포](https://support.kapsulehost.com/ko-kr/site-preview)를 참고하세요.

## Secret 추가 또는 업데이트하기

1. 분할 버튼으로 환경을 선택합니다.
2. **KEY_NAME** 필드에 이름을 입력합니다. 이 필드는 입력하는 즉시 대문자로 강제 변환됩니다.
3. 두 번째 필드에 값을 입력합니다. 입력하는 동안 값은 마스킹됩니다.
4. **Set**을 클릭합니다.

이미 존재하는 키를 다시 설정하면 기존 값을 덮어씁니다. 별도의 수정 기능이나 덮어쓰기 확인 단계가 없으므로, **Set**을 클릭하기 전에 환경 탭을 반드시 확인하세요.

### 키 이름 규칙

키는 대문자로 시작해야 하며, 그 뒤에는 대문자, 숫자, 밑줄만 올 수 있고 최대 128자까지 가능합니다. `DATABASE_URL`, `API_KEY_V2`, `SENTRY_DSN`은 모두 유효합니다. 그 외의 형식은 **key는 UPPER_SNAKE_CASE 문자/숫자/밑줄이어야 합니다.** 메시지와 함께 거부됩니다.

알아 두면 좋은 두 가지 제한이 더 있습니다:

- 값은 비어 있을 수 없습니다. 빈 값을 제출하면 **값이 필요합니다.** 메시지가 반환됩니다.
- 값은 16KB를 초과할 수 없습니다. 토큰 하나를 저장하기에는 충분하지만, 예를 들어 전체 인증서 체인처럼 큰 값에는 부족합니다. 이런 것은 secret이 아니라 파일로 다루어야 합니다.

## 값 다시 읽기

행에서 **Copy**를 클릭하세요. KPanel은 서버 측에서 값을 복호화하여 바로 클립보드에 넣고, **값이 클립보드에 복사됨** 확인 메시지를 표시합니다. 값은 화면에 출력되지 않으므로, 화면 공유나 누군가 뒤에서 훔쳐보더라도 값이 노출되지 않습니다.

값을 조회할 때마다 누가, 어떤 키를, 언제 조회했는지가 사이트의 감사 기록에 남으며, [사이트 활동 로그](https://support.kapsulehost.com/ko-kr/site-activity-log)에서 확인할 수 있습니다.

> **Tip:** 값을 노출하지 않고 올바른지 확인해야 한다면, 대신 마스킹된 값을 비교하세요. 마지막 네 글자만으로도 올바른 토큰인지 확인하기에 충분하며, 이미 화면에 표시되어 있습니다.

## 앱에서 Secret 사용하기

값을 복사하여 서버에서 애플리케이션이 설정을 읽는 위치에 붙여넣으세요. Node.js 앱의 경우 보통 프로세스 매니저가 설정하는 환경 변수이거나, 앱 루트에 있고 코드가 시작 시 불러오는 `.env` 파일입니다.

> **Warning:** 이 파일을 저장소에 커밋하지 마세요. 파일을 만들기 전에 `.env`를 `.gitignore`에 추가하세요. git 원격 저장소에 push된 secret은 유출된 것으로 간주하고 제공업체 쪽에서 교체해야 합니다. 파일을 삭제하더라도 히스토리에는 계속 남아 있기 때문입니다.

Secrets 탭은 값이 무엇인지에 대한 기록이며, 암호화되고 감사 추적되는 저장소이지, 비밀번호 관리자나 메시지 기록에 남기는 메모가 아닙니다. 이를 진실의 원천으로 유지하세요. 제공업체 쪽에서 키를 교체할 때는 동시에 여기서도 업데이트하여, 다음에 배포하는 사람이 최신 값을 사용할 수 있도록 하세요.

## Secret 삭제하기

행에서 **Delete**를 클릭하세요. KPanel은 **Delete API_TOKEN?**로 확인을 요청하며, 다음 재시작 시 앱이 이 값에 대한 접근 권한을 잃는다고 경고합니다. 되돌리기 기능이 없고 복사본도 보관되지 않으므로, 값이 다시 필요할 수도 있다면 먼저 복사해 두세요.

제공업체 쪽에서 해당 자격 증명이 폐기되었거나, 이를 사용하던 코드가 제거되었을 때 secret을 삭제하세요. 오래된 키를 그대로 두면 나중에 어떤 키가 실제로 중요한지 구분하기 어려워집니다.

## 자격 증명을 안전하게 교체하기

안전한 순서는 항상 다음과 같습니다: 제공업체 쪽에서 새 자격 증명을 생성하고, 여기서 값을 업데이트한 뒤 배포하고, 앱이 정상 작동하는지 확인한 다음, 마지막으로 제공업체 쪽에서 기존 자격 증명을 폐기합니다.

순서를 반대로 해서 먼저 폐기부터 하면, 실행 중인 앱이 이미 죽은 자격 증명을 들고 있어 이를 필요로 하는 모든 요청이 실패하는 구간이 생깁니다. 변경 작업이 위험하다면 먼저 백업을 받아 두어 알려진 정상 상태로 되돌아갈 수 있도록 하세요. [백업하기](https://support.kapsulehost.com/ko-kr/taking-a-backup)를 참고하세요.

## 문제 해결

**Secrets 탭이 메뉴에 없습니다.** 해당 사이트가 Node.js 사이트가 아닙니다. 페이지 상단의 사이트 이름 옆에 있는 스택 표시를 확인하세요.

**Set 버튼을 눌러도 아무 반응이 없습니다.** 두 필드 모두 필수입니다. 둘 중 하나라도 비어 있으면 버튼이 **키 + 값 필수**를 표시합니다.

**키가 거부되었습니다.** 소문자, 하이픈, 점, 공백은 허용되지 않습니다. `api-key`와 `Api_Key`는 모두 실패하고, `API_KEY`은 통과합니다.

**Copy를 눌러도 클립보드에 아무것도 복사되지 않습니다.** 일부 브라우저는 비활성 탭에서의 클립보드 쓰기를 차단합니다. 먼저 페이지를 클릭한 다음 **Copy**를 다시 클릭하세요.

## 다음으로 볼 것

- [풀 리퀘스트를 위한 미리보기 배포](https://support.kapsulehost.com/ko-kr/site-preview), production과 preview 분리의 나머지 절반입니다.
- 이 값을 읽는 코드를 push하려면 [사이트 Git 배포](https://support.kapsulehost.com/ko-kr/site-git-deploy)를 참고하세요.
- 누가 secret을 설정, 조회, 삭제했는지 확인하려면 [사이트 활동 로그](https://support.kapsulehost.com/ko-kr/site-activity-log)를 참고하세요.