안드로이드 앱 출시 시 keystore 생성 및 적용 가이드

안드로이드 앱이나 게임을 구글 플레이 스토어에 정식으로 배포하기 위해 반드시 거쳐야 하는 핵심 단계, 바로 Keystore(키스토어) 설정입니다.

이 글에서는 키스토어의 개념부터 생성, Godot 엔진 적용, 그리고 가장 중요한 업데이트 시 관리 방법까지 내용 생략 없이 상세하게 총정리해 드립니다.

---

1. Keystore(키스토어)란?

키스토어는 개발자가 만든 앱이 원본임을 증명하는 디지털 서명 파일(.keystore 또는 .jks)입니다. 구글 플레이 스토어는 이 서명을 통해 "이 앱은 A라는 개발자가 만든 공식 앱이 맞다"고 인증합니다. 악의적인 해커가 동일한 이름의 앱을 스토어에 덮어씌우는 것을 방지하는 핵심 보안 장치입니다.

2. Keystore 생성 방법

Godot를 포함한 대부분의 안드로이드 빌드 환경에서는 Java 개발 키트(JDK)에 포함된 keytool 명령어를 사용하여 키스토어를 생성하는 것이 가장 확실하고 빠릅니다.

1. 터미널(또는 명령 프롬프트) 실행
2. 명령어 입력: 원하는 폴더로 이동한 뒤 아래 명령어를 입력합니다. (mygame 부분은 본인의 프로젝트 이름에 맞게 수정합니다.)

keytool -v -genkeypair -v -keystore mygame.keystore -alias mygame -keyalg RSA -keysize 2048 -validity 10000

• -keystore mygame.keystore: 생성될 파일의 이름입니다.
• -alias mygame: 이 키스토어 안에서 사용할 고유한 별칭(Alias)입니다.
• -keyalg RSA -keysize 2048: RSA 2048비트 암호화 알고리즘을 사용합니다. (구글 권장 규격)
• -validity 10000: 서명의 유효기간을 일(days) 단위로 설정합니다. (10000일 = 약 27년)

3. 정보 입력:
   명령어를 실행하면 비밀번호(Keystore password)를 설정하라는 프롬프트가 나옵니다. 안전한 비밀번호를 입력합니다. (입력 시 화면에 글자가 보이지 않으니 주의해서 타이핑합니다.)
   이후 이름, 조직 단위, 국가 코드(한국은 KR) 등의 정보를 묻습니다. 정확히 기입한 후 y를 눌러 완료합니다.

3. Godot 프로젝트에 Keystore 적용 (릴리즈 빌드)

생성한 키스토어를 Godot 엔진에 연결하여 스토어 배포용 AAB 또는 APK 파일을 뽑아내는 과정입니다.

1. Godot 에디터 상단 메뉴에서 프로젝트(Project) > 내보내기(Export)를 클릭합니다.
2. 좌측 목록에서 Android 프리셋을 선택합니다.
3. 우측 설정 창을 아래로 스크롤하여 Keystore 섹션을 찾습니다.
4. 배포용 서명이므로 Release 항목을 설정해야 합니다.
   • Release: 방금 생성한 mygame.keystore 파일의 경로를 찾아 지정합니다.
   • Release User: 키스토어 생성 시 사용한 별칭(-alias에 적은 이름)을 입력합니다.
   • Release Password: 키스토어 생성 시 설정한 비밀번호를 입력합니다.
5. 설정이 완료되면 내보내기 창 하단의 프로젝트 내보내기(Export Project) 버튼을 눌러 스토어 제출용 파일을 빌드합니다.

4. [매우 중요] 앱 업데이트 및 Keystore 관리 수칙

앱 출시 이후 가장 치명적인 실수가 발생하는 구간입니다. 앱의 버전을 올려 업데이트할 때는 반드시 기존에 사용했던 동일한 키스토어로 서명해야 합니다.

• 절대 새로운 키스토어를 생성하여 업데이트하지 마십시오. 구글 플레이 콘솔은 최초 앱 등록 시 사용된 키스토어의 서명 값과, 업데이트 시 올라온 앱의 서명 값이 다르면 업데이트 자체를 거부합니다. "기존 서명과 일치하지 않습니다"라는 오류를 뱉어냅니다.
• 업데이트 시 무언가 오류가 발생하거나 설정이 꼬였다면, 임의로 새 키를 만들지 말고 반드시 이전에 성공적으로 빌드했던 기존 키스토어 환경으로 롤백하여 재사용해야 합니다.

관리 핵심 포인트

1. 다중 백업: 생성한 .keystore 파일은 개발 PC뿐만 아니라 구글 드라이브, 외장 하드, USB 등 여러 곳에 안전하게 백업하십시오.
2. 정보 기록: 파일뿐만 아니라 설정한 Alias(별칭)와 비밀번호도 반드시 안전한 텍스트 파일이나 비밀번호 관리자 등에 따로 기록해 두어야 합니다. 파일을 가지고 있어도 비밀번호를 까먹으면 서명할 수 없습니다.

(최근 구글 플레이는 'Play 앱 서명(Play App Signing)' 기능을 필수로 사용하여 키 분실 시 구글 고객센터를 통해 업로드 키를 재설정할 수 있는 구제책을 제공하고 있으나, 과정이 매우 번거로우므로 원본 키스토어 관리가 최우선입니다.)