# 설정, 계정, 자격 증명과 데이터 보관

> 기준일: 2026-09-19
> 대상: 셀비 회원, AI 상담 답변 작성자, 웹 도움말 편집자

이 문서는 현재 구현을 읽어 정리한 안내다. 실제 회원의 사용 기간, 공급자 잔액, API 권한, 장애 여부를 조회한 결과가 아니다. 화면의 상태와 오류 문구를 먼저 확인하고 해당되는 절차만 안내한다.

## KB-SET-001 · 설정 화면의 목적과 메뉴

왼쪽 **설정**에서 다음 항목을 선택한다.

- **화면과 저장**: 계정 정보, 다크·라이트 모드, 저장 폴더, 기존 파일 정리, 복구 보관함 관리.
- **API 키**: Gemini API Key, Google Vertex Key, Fish Audio, YouTube, 쿠팡 파트너스 등록·교체·삭제. UUP 토큰 상태도 요약하고 관리 화면으로 연결한다.
- **대본과 음성**: TTS 기본값, Gemini TTS 목소리, Fish Audio 모델·목소리·미리듣기.
- **UUP 전달**: UUP 연결과 전달 설정. 자세한 절차는 [게시 준비와 UUP](06-publishing-and-uup.md)를 따른다.
- **환경 검사**: FFmpeg·ffprobe, 미리보기 서버, WebView2, 저장 폴더의 현재 상태를 검사한다.
- **앱 정보**: 현재 버전, 업데이트 상태, 오류 자동 보고, 글꼴 라이선스.

화면에 표시하는 날짜와 시각은 한국 시간(KST) 기준이다. 다크 모드가 첫 실행 기본값이며 선택한 화면 모드는 다음 실행에도 유지된다.

## KB-SET-002 · Google 로그인과 사용 기간

### 목적과 전제

셀비는 Google 로그인과 유효한 사용 기간이 있어야 제작 기능을 사용할 수 있다. 데스크톱 앱과 selvi.kr에서 같은 Google 계정을 사용해야 한다. Google 로그인 성공과 셀비 이용 권한 활성화는 별개다.

### 이용 순서

1. 앱 로그인 화면에서 **Google로 계속**을 누른다.
2. 열린 브라우저에서 selvi.kr의 안내를 따라 로그인한다. 기기 확인 화면이 나타나면 자신이 시작한 앱 로그인인지 확인한다.
3. 앱으로 돌아와 로그인 결과와 사용 기간 안내를 확인한다.
4. 권한 변경 직후라면 화면의 **다시 확인**을 누른다. **selvi.kr 마이페이지 열기**에서도 사용 기간을 확인한다.
5. 로그아웃하려면 **설정 → 상단 로그아웃**을 누른다. 진행 중인 작업도 취소되므로 저장 상태를 먼저 확인한다.

### 기기 교체와 만료

- 같은 계정으로 새 데스크톱 세션을 만들면 이전 데스크톱 세션이 교체된다. 동시에 여러 컴퓨터에서 계속 사용하는 방식이 아니다.
- 기존 앱이 교체 사실을 확인하면 로그인 화면으로 돌아간다. 사용할 컴퓨터에서 다시 로그인한다.
- 사용 기간 만료·권한 회수·차단을 확인하면 앱은 세션을 지우고 제작 화면을 잠그며 실행 중인 작업을 취소한다.
- **기간이 없거나 만료된 문제는 재로그인만으로 연장되지 않는다.** 계정의 실제 이용 상태를 확인해야 한다. AI 상담이 권한을 부여하거나 차단을 해제할 수 있다고 안내하지 않는다.
- 인터넷 연결이 필요하다. 현재 구현은 마지막 서버 확인 뒤 60초의 짧은 연결 유예를 두며, 장기 오프라인 제작 권한을 제공하지 않는다. 연결 끊김과 계정 차단은 같은 원인으로 단정하지 않는다.
- 로그아웃이 저장된 프로젝트를 삭제하는 것은 아니다. 다만 미저장 편집 내용의 복구를 항상 보장할 수 없으므로, 복구 안내가 나오면 먼저 확인한다.

## KB-SET-003 · API 키는 필요한 기능별로 등록

Google 로그인만으로 모든 외부 AI 서비스 이용 권한이 생기지는 않는다. 모든 키를 채워야 프로그램을 쓸 수 있는 것도 아니다. 이용하려는 기능에 필요한 자격 증명을 준비한다.

### Gemini API Key

- **메뉴**: 설정 → API 키 → Gemini API Key.
- **용도**: 영상 분석, 대본 작성, 번역, Gemini TTS 등 Gemini 계열 기능.
- **등록**: Google AI Studio에서 발급한 API 키를 입력하고 보관 여부를 선택한 뒤 **키 저장 → 연결 테스트**를 누른다.
- **결과**: 저장만 하면 `등록됨 · 연결 미확인`, 연결 테스트가 성공하면 `연결됨`과 확인 시각을 보여 준다.
- **제한**: 연결 테스트 성공이 모든 이미지·영상·음성 모델의 권한과 잔여 할당량까지 보장하지는 않는다. 실제 선택한 모델의 요청은 별도로 실패할 수 있다.

### Google Vertex Key

- **메뉴**: 설정 → API 키 → Google Vertex Key.
- **용도**: Google Cloud 서비스 계정으로 Gemini 계열 기능을 사용한다. 앱 화면에서는 Google Vertex Key라는 이름을 쓴다.
- **등록**: **JSON 파일 선택**으로 서비스 계정 키 파일을 선택하고, **이 기기의 키 파일로 보관** 여부를 정한 뒤 **키 저장**을 누른다. 리전은 같은 카드에서 **리전 저장**으로 저장하고 **연결 테스트**로 확인한다.
- **결과**: JSON 구조와 키를 검증한 뒤 프로젝트 정보를 표시한다. 키 원문은 다시 보여 주지 않는다.
- **제한**: 일반 Gemini API 키 문자열을 JSON 파일 칸에 넣는 방식이 아니다. 결제, API 사용 설정, 권한, 모델·리전 지원은 연결된 Google Cloud 프로젝트를 따른다. 상담 답변에서 프로젝트가 활성화되어 있다고 추정하지 않는다.
- **보관 차이**: 영구 보관을 선택한 Vertex JSON은 앱 설정 영역의 별도 키 파일로 저장된다. macOS 키체인이나 Windows 자격 증명 관리자에 넣는 일반 API 키와 다르다. 파일 권한을 제한하지만, 이를 “OS 보안 저장소에 암호화 보관”이라고 설명하지 않는다.

### Gemini와 Vertex 중 무엇을 선택하나

둘 중 하나만 등록하면 앱이 사용할 자격 증명을 정하므로 **메인 자격 증명** 선택 카드가 나타나지 않는다. 둘 다 등록하면 **설정 → API 키 → 메인 자격 증명**에서 다음을 고른다.

- **Gemini API Key**: AI Studio 키를 기본으로 사용.
- **Google Vertex Key**: 서비스 계정 JSON을 기본으로 사용.
- **공용 (작업마다 선택)**: 대본 생성 등 AI 작업에서 사용할 자격 증명을 그때 선택.

여기서 **공용은 셀비가 무료 API 키나 무료 AI 이용량을 나누어 주는 뜻이 아니다.** 등록된 두 자격 증명 가운데 작업별로 선택하는 모드다. 비용·할당량은 실제 사용한 공급자 계정과 프로젝트를 따른다.

**설정 → API 키 → Gemini 모델**에서 영상 분석·대본·번역 모델을 선택한다. 기본 `자동 · 최신 Flash` 대신 특정 모델을 고른 경우 **모델 저장**을 눌러 고정한다. 모델 목록 조회 실패와 키 미등록은 서로 다른 상태다.

### Fish Audio

- **메뉴**: 설정 → API 키 → Fish Audio.
- **용도**: Fish 음성 합성, 계정 목소리·공개 목소리 조회.
- **등록**: API 키 입력 → 보관 여부 선택 → **키 저장 → 연결 테스트**.
- **음성 선택**: 설정 → 대본과 음성 → Fish Audio 목소리·모델에서 **목소리 찾기**, **목소리 저장**, **미리듣기**를 사용한다.
- **분기**: 목소리 미선택 상태의 연결 테스트는 키 확인을 수행한다. 목소리를 저장한 상태에서는 짧은 합성으로 연결을 확인할 수 있다. 연결 테스트나 미리듣기를 항상 무료라고 단정하지 않는다.
- **제한**: 카탈로그에서 보이는 목소리라고 모든 이용 목적에 대한 권리가 자동 부여되지는 않는다. 사용 권한과 공급자 정책을 직접 확인한다.

### YouTube

- **메뉴**: 설정 → API 키 → YouTube.
- **용도**: 쇼핑쇼츠 검색, 성과·댓글 조회용 YouTube Data API 키.
- **등록**: 데이터 조회 키 입력 → **키 저장**.
- **결과와 제한**: 키가 저장되면 `등록됨`을 표시한다. 별도 **연결 테스트 버튼은 없다**. 실제 조회 성공 여부는 찾기 화면에서 확인한다. 이 키로 유튜브 게시 계정을 연결하거나 영상 파일을 다운로드하는 기능은 아니다.

### 쿠팡 파트너스

- **메뉴**: 설정 → API 키 → 쿠팡 파트너스.
- **용도**: 상품 검색, 제휴 수익 링크 생성.
- **등록**: **Access Key**와 **Secret Key**를 모두 입력 → 보관 여부 선택 → **키 저장**.
- **보관**: 현재 앱은 쿠팡 키도 다른 일반 API 키처럼 기기 보안 저장소 보관 또는 이번 실행만 사용을 선택할 수 있다. “쿠팡 키는 무조건 앱 종료 시 삭제된다”는 과거 설명을 사용하지 않는다.
- **결과와 제한**: `등록됨`은 저장 확인이다. 별도 연결 테스트 버튼은 없다. 키 없이도 이미 발급받은 `link.coupang.com` 수익 링크를 직접 붙여 넣는 경로를 사용할 수 있다.

## KB-SET-004 · 키 저장, 교체, 삭제의 의미

일반 키 카드의 **이 기기의 보안 저장소에 암호화 보관**은 새 등록 시 기본 선택되어 있다.

- 선택한 일반 API 키는 macOS 키체인 또는 Windows 자격 증명 관리자에 보관한다.
- 선택을 해제하고 저장하면 기존 보관 값을 제거하고 이번 앱 실행의 메모리에서만 사용한다. 다음 실행에는 다시 등록해야 한다.
- 새 값을 입력하고 **새 키로 교체**를 누르면 기존 자격 증명을 바꾸며 연결 확인 상태도 다시 확인이 필요한 상태가 된다.
- **삭제**는 앱이 보관한 해당 자격 증명을 제거하는 동작이다. 공급자 사이트의 키 자체를 폐기하는 동작과는 다르다. 키가 노출되었다면 공급자에서 폐기·재발급한 뒤 앱 값을 교체한다.
- 저장 후 화면에 키 원문을 다시 표시하지 않는다. 빈 입력칸만 보고 키가 사라졌다고 판단하지 말고 카드의 `등록됨`, `연결됨`, `이번 실행만`, `보안 저장소` 표시를 확인한다.
- Vertex JSON은 위의 별도 키 파일 보관 방식을 따른다. 모든 자격 증명을 동일한 방식으로 암호화한다고 묶어 설명하지 않는다.

상담에서는 API 키, Secret Key, 서비스 계정 JSON 원문, UUP 토큰을 보내 달라고 요청하지 않는다. 확인에는 공급자 이름, 선택한 모델, 상태 문구, 비밀을 가린 오류 문구만 사용한다.

## KB-SET-005 · 저장소와 프로젝트 제거·복구

### 저장 폴더

**설정 → 화면과 저장 → 저장소 → 저장 폴더 선택**에서 기본 폴더를 정한다. 앱이 쓰기 권한과 여유 공간을 검사한다.

선택한 저장 폴더 아래에 다음처럼 정리한다.

- `셀비/프로젝트`: 영상 프로젝트별 폴더.
- `셀비/캐러셀`: 캐러셀 프로젝트.
- `셀비/복구 보관함`: 제거한 프로젝트 보관.

저장 폴더를 바꾸는 것과 기존 프로젝트 파일을 자동으로 모두 옮기는 것은 같은 뜻이 아니다. 목록이 비어 보이면 이전에 선택했던 저장 폴더인지 먼저 확인한다. **기존 파일 정리**는 앱이 찾은 예전 배치의 파일을 정리하는 기능이며, 백업이나 삭제 복구를 대신하지 않는다.

외장 드라이브가 분리되거나 저장 폴더가 사라지면 연결 상태와 폴더 위치를 먼저 확인한다. 데이터가 없어진 것으로 단정하거나 빈 폴더를 덮어쓰게 하지 않는다.

### 프로젝트 제거

**제작실 → 프로젝트 카드의 제거 아이콘**을 누르면 별도 확인 문구 입력 없이 프로젝트 폴더가 **셀비/복구 보관함**으로 이동한다. 실행 중인 작업이 있으면 완료하거나 취소해야 한다. 제거는 즉시 영구 삭제가 아니다.

되돌릴 때는 작업을 멈추고 저장 폴더의 `셀비/복구 보관함`에서 해당 프로젝트 폴더가 남아 있는지 확인한다. 원래 프로젝트 위치로 폴더를 되돌린 후 제작실 목록을 다시 확인하는 방식이다. 앱이 안내하는 것은 폴더를 통한 복구이며, 존재하지 않는 전용 “복원” 버튼을 안내하지 않는다. 같은 이름이나 같은 프로젝트의 사본이 이미 있으면 덮어쓰지 말고 지원에 문의한다.

### 복구 보관함 비우기

**설정 → 화면과 저장 → 복구 보관함 비우기**는 확인 대화상자를 거쳐 복구 프로젝트를 **영구 삭제**한다. 자동으로 비우지 않는다. 복구할 프로젝트가 없는지 확인하고 실행한다. 비운 뒤에는 앱 복구 보관함을 통한 복원을 약속할 수 없다.

## KB-SET-006 · 로컬 보관과 외부 전송은 구분

“로컬에서 제작한다”는 “모든 기능이 인터넷 없이 동작하며 아무 데이터도 외부로 나가지 않는다”는 뜻이 아니다.

- **로컬 제작**: 프로젝트 파일, 소스, 생성 음성, 편집 상태와 완성본을 컴퓨터에서 관리하며 FFmpeg로 영상 처리를 수행한다.
- **Google 로그인**: 계정 인증과 사용 기간 확인을 위해 서버와 통신한다.
- **AI 분석·생성**: 사용자가 요청한 기능에 필요한 프롬프트, 대본, 상품 설명, 대표 이미지·영상 프레임, 선택한 기능에 따른 원본 음성 등이 AI 공급자에 전송될 수 있다. 영상 원본 전체가 언제나 전송된다고 하거나, 영상 정보가 전혀 전송되지 않는다고 단정하지 않는다.
- **음성 합성**: 합성할 문장과 목소리·모델 설정이 선택한 TTS 공급자로 전달된다.
- **검색·다운로드**: 검색어나 대상 URL 등 요청에 필요한 정보가 해당 서비스와 통신한다.
- **UUP 전달**: 사용자가 전달한 게시 자산과 게시 준비 정보가 UUP로 넘어간다. 세부 범위는 [게시 준비와 UUP](06-publishing-and-uup.md)를 확인한다.
- **업데이트·도구 설치**: 버전 확인과 필요한 파일 다운로드를 위해 인터넷을 사용한다.
- **오류 자동 보고**: 아래의 별도 진단 항목을 전송한다. AI 요청과 오류 보고는 서로 다른 데이터 흐름이다.

AI 공급자가 요청 데이터를 얼마나 보관하거나 학습에 사용하는지는 해당 공급자·계정·계약의 현재 정책으로 확인해야 한다. 셀비 상담 자료만으로 “학습에 절대 쓰이지 않는다”, “국내에만 저장된다” 등을 보장하지 않는다.

## KB-SET-007 · 오류 자동 보고

### 목적과 켜기·끄기

**설정 → 앱 정보 → 오류 자동 보고**는 개발자가 문제를 분석할 수 있도록 정제한 진단 정보를 비공개 오류 목록으로 보내는 기능이다. **오류 자동 보고 끄기/켜기**로 변경한다. 끄기는 즉시 적용되고 선택이 저장된다. `이 빌드는 미설정`이면 보고 주소가 없어 전송하지 않는 빌드다.

### 보내는 항목

- 앱 버전, 운영체제 종류·버전, CPU 아키텍처, 무작위 설치 식별자.
- 오류 위치·메시지, 정제한 스택·로그 일부, FFmpeg 버전.
- 메모리·여유 디스크 용량, 프록시 사용 여부.
- 로그인 중이면 **계정 이메일과 Google 계정 식별자**.
- 재생 문제에서는 화면·작업 단계, 최근 버튼 동작, 브라우저·온라인 상태, 재생 위치·길이·크기·로딩 상태 등 진단 정보.
- 업데이트 문제에서는 버전·실패 단계·운영체제 오류 코드. Windows 보안 차단이면 권한이 허용하는 범위에서 보안 제품명과 해당 업데이트 파일의 최근 탐지·처리 결과.

API 키, 파일 경로, 로컬 사용자명 등은 전송 전에 정제하며 프로젝트 내용·영상 파일·대본 자체를 오류 보고 첨부로 보내지 않는다. 다만 계정 이메일 등이 포함되므로 **완전한 익명 보고**라고 표현하지 않는다.

Cloudflare의 개발자 전용 오류 목록에 보관하며 30일 지난 보고는 매일 정리한다. 자동 보고 켜짐이 원격 접수 성공을 항상 보장하지는 않는다. 오프라인·서버 제한·앱 종료 등으로 접수가 누락될 수 있다. 상담 AI가 실제 접수 기록을 조회하지 않았다면 “이미 접수되었습니다”나 “완료 처리되었습니다”라고 답하지 않는다.

## KB-SET-008 · 자동 업데이트와 환경 검사

**설정 → 앱 정보 → 앱 업데이트**에서 현재·대상 버전과 진행 상태를 확인하고 **업데이트 확인**, 준비 완료 시 **저장 후 재시작**을 사용한다. 앱은 새 버전을 자동 확인하고 파일 준비 뒤 진행 중인 작업과 저장을 기다려 재시작한다. 미저장 설정이나 실행 중인 작업이 있으면 대기 이유를 표시한다. 공개 파일은 서명된 체크섬 정보와 파일 무결성을 검증하는 절차를 거친다.

**설정 → 환경 검사 → 다시 검사**는 영상 처리 도구와 저장 환경을 확인한다. Windows x64와 macOS Apple Silicon은 사용할 수 있는 FFmpeg·ffprobe가 없거나 부적합하면 자동 설치를 지원한다. 진행 중에는 기다리고, 실패 후 버튼이 표시되면 **FFmpeg 다시 받기**를 사용한다. 네트워크나 조직 보안 정책으로 실행이 막힌 경우에는 다운로드 반복만으로 해결되지 않을 수 있다.

상세 오류 대응은 [문제 해결](08-troubleshooting.md)을 따른다.

## 구현 근거

다음은 유지보수용 저장소 상대 경로와 심볼이다. 이 문서는 소스와 화면 문구를 대조했으며 별도의 실기 조작 결과를 뜻하지 않는다.

- `frontend/src/main.ts` — `renderSettings`, `CREDENTIALS`, `credentialCard`, `vertexCredentialCard`, `credentialStatus`, `geminiMainCard`, `geminiModelCard`, `fishVoiceCard`, `errorReportingCard`, `renderEnvironmentPane`, `renderAppUpdate`; `delete-project`·`empty-trash` 액션.
- `app.go` — `SaveCredential`, `saveCredentialLocked`, `setRememberFlagLocked`, `credential`, `saveVertexKeyLocked`, `TestProvider`, `DeleteProject`.
- `internal/secrets/credential_darwin.go` — `darwinStore`, `NewStore`; `internal/secrets/credential_windows.go` — `windowsStore`, `writeWindowsCredential`.
- `app_auth.go` — `StartGoogleLogin`, `GetAuthSession`, `SignOut`, `startAccountRecheck`, `requireAccount`.
- `internal/auth/service.go` — `Refresh`, `snapshotLocked`, `acceptSessionLocked`, `clearSessionLocked`; `internal/auth/session.go` — `offlineGrace`, `persistSession`; `internal/auth/watch.go` — `Watch`.
- `selvi.web` 저장소의 `api/internal/auth/session.go` — `replaceDesktopSessions`.
- `internal/project/layout.go` — `ProjectsDir`, `CarouselDir`, `TrashDir`; `internal/project/store.go` — `Delete`, `EmptyTrash`.
- `internal/provider/gemini.go` — `GeminiRequest`, `GenerateScript`; `internal/provider/geminitext.go` — `GenerateUploadCopy`.
- `app_errreport.go` — `newErrorReporting`, `errorReportAccount`, `errorReportResources`; `internal/errreport/errreport.go` — `Payload`, `Report`.
- `app_mediatools.go` — `mediaAutoInstallSupported`, `InstallMediaTools`, `mediaFixHint`; `app_update.go` — 업데이트 상태·재시작 처리; `internal/updater/updater.go` — `downloadVerifiedAsset`.