gplay-signing-setup

Android 应用签名设置

需要为 Google Play 设置或管理应用签名时，请使用此技能。

了解 Android 应用签名

Android 应用在上传前必须使用证书签名。有两种签名方式：

1. Google Play 应用签名（推荐）——由 Google 管理您的签名密钥
2. 手动签名（旧版）——由您管理签名密钥

创建新的密钥库

生成密钥库

keytool -genkey -v \
  -keystore release.keystore \
  -alias my-app-key \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000

系统会提示您输入：

• 密钥库密码（请安全保存！）
• 密钥密码（可以与密钥库密码相同）
• 您的姓名／组织信息

密钥库文件位置

• 开发环境：保存在本地，切勿提交到 git
• 生产环境：保存在安全位置（密码管理器、机密库）
• CI/CD：使用加密机密

配置 Gradle 签名

gradle.properties（已加入 gitignore）

KEYSTORE_FILE=/path/to/release.keystore
KEYSTORE_PASSWORD=your_keystore_password
KEY_ALIAS=my-app-key
KEY_PASSWORD=your_key_password

app/build.gradle

android {
    signingConfigs {
        release {
            storeFile file(project.property('KEYSTORE_FILE'))
            storePassword project.property('KEYSTORE_PASSWORD')
            keyAlias project.property('KEY_ALIAS')
            keyPassword project.property('KEY_PASSWORD')
        }
    }

    buildTypes {
        release {
            signingConfig signingConfigs.release
        }
    }
}

使用环境变量（CI/CD）

android {
    signingConfigs {
        release {
            storeFile file(System.getenv("KEYSTORE_FILE") ?: "release.keystore")
            storePassword System.getenv("KEYSTORE_PASSWORD")
            keyAlias System.getenv("KEY_ALIAS")
            keyPassword System.getenv("KEY_PASSWORD")
        }
    }
}

设置 Play 应用签名

启用 Play 应用签名（新应用）

1. 使用上传密钥构建并签名 AAB：

   ./gradlew bundleRelease
   

2. 将 AAB 上传到 Play Console：

   gplay release \
     --package com.example.app \
     --track internal \
     --bundle app-release.aab
   

3. Google Play 会自动生成应用签名密钥

4. 下载上传证书：

   • 前往 Play Console → 应用 → 设置 → 应用签名
   • 下载“上传证书”（用于今后上传）

将现有应用迁移到 Play 应用签名

如果您的应用使用手动签名：

1. 导出上传密钥：

   keytool -export -rfc \
     -keystore release.keystore \
     -alias my-app-key \
     -file upload_cert.pem
   

2. 加密私钥（Google 要求）：

   # Generate password for encryption
   openssl rand -base64 32 > encryption_password.txt
   
   # Export and encrypt private key
   keytool -importkeystore \
     -srckeystore release.keystore \
     -destkeystore encrypted.p12 \
     -deststoretype PKCS12 \
     -srcalias my-app-key \
     -deststorepass $(cat encryption_password.txt)
   

3. 上传到 Play Console：

   • 前往 Play Console → 应用 → 设置 → 应用签名
   • 选择“导出并上传密钥”
   • 上传 encrypted.p12 和 encryption_password.txt

4. 下载新的上传密钥：

   • 迁移后，下载新的上传证书
   • 今后上传时均使用此证书

验证密钥库

列出密钥库中的密钥

keytool -list -v -keystore release.keystore

检查证书有效性

keytool -list -v \
  -keystore release.keystore \
  -alias my-app-key \
  | grep Valid

提取证书指纹

# SHA-256 (for Firebase, etc.)
keytool -list -v \
  -keystore release.keystore \
  -alias my-app-key \
  | grep SHA256

验证 APK/AAB 签名

检查 AAB 签名

jarsigner -verify -verbose -certs app-release.aab

检查 APK 签名

jarsigner -verify -verbose -certs app-release.apk

CI/CD 签名

GitHub Actions 示例

- name: Decode keystore
  run: |
    echo "${{ secrets.KEYSTORE_BASE64 }}" | base64 -d > release.keystore

- name: Build signed AAB
  env:
    KEYSTORE_FILE: release.keystore
    KEYSTORE_PASSWORD: ${{ secrets.KEYSTORE_PASSWORD }}
    KEY_ALIAS: ${{ secrets.KEY_ALIAS }}
    KEY_PASSWORD: ${{ secrets.KEY_PASSWORD }}
  run: |
    ./gradlew bundleRelease

- name: Clean up keystore
  if: always()
  run: rm -f release.keystore

将密钥库存储为 base64

# Encode keystore to base64
base64 -i release.keystore -o keystore_base64.txt

# Add to GitHub Secrets as KEYSTORE_BASE64

上传证书管理

为现有应用注册上传证书

如果您丢失了上传密钥：

1. 生成新的密钥库（如上所示）

2. 导出证书：

   keytool -export -rfc \
     -keystore new-upload.keystore \
     -alias my-app-key \
     -file new_upload_cert.pem
   

3. 联系 Google Play 支持以重置上传密钥：

   • 前往 Play Console → 帮助
   • 请求重置上传证书
   • 提供 new_upload_cert.pem

安全最佳实践

应该：

• ✅ 使用强密码（16 个字符以上）
• ✅ 将密钥库存储在多个安全位置
• ✅ 为不同应用使用不同的密钥
• ✅ 启用 Play 应用签名
• ✅ 将上传密钥与生产环境分开
• ✅ 安全记录密钥详情（不要记录密码！）
• ✅ 设置日历提醒，留意密钥到期时间（10–25 年）

不应该：

• ❌ 将密钥库提交到 git
• ❌ 通过电子邮件／聊天分享密钥库
• ❌ 使用弱密码或容易猜到的密码
• ❌ 将密码存储在代码中
• ❌ 忘记备份密钥库
• ❌ 对调试版和发布版使用同一密钥

密钥库备份策略

需要备份的内容：

1. 密钥库文件（release.keystore）
2. 密钥别名
3. 密钥库密码（存放在密码管理器中）
4. 密钥密码（存放在密码管理器中）

备份位置：

• 密码管理器（1Password、LastPass 等）
• 加密云存储
• 公司机密库
• 实体安全存储位置（企业适用）

测试恢复流程：

# Verify you can use the backup
keytool -list -v -keystore backup/release.keystore

故障排除

“jarsigner: unable to sign jar”

• 检查密钥库密码是否正确
• 验证密钥库文件路径
• 确认密钥库别名存在

“Failed to read key from keystore”

• 密钥别名可能有误
• 密钥密码可能有误
• 密钥库可能已损坏

“Upload certificate doesn't match”

• 您使用了错误的密钥库
• 密钥库曾被重新生成（请联系支持）
• 使用了应用签名密钥，而非上传密钥

密钥库丢失？

• 如果使用 Play App Signing：联系 Google 重置上传密钥
• 如果未使用 Play App Signing：无法恢复，必须发布新应用

多个应用，多个密钥

整理多个密钥库

~/keystores/
├── app1-release.keystore
├── app2-release.keystore
└── app3-release.keystore

为每个应用使用不同的 gradle.properties

# app1/gradle.properties
KEYSTORE_FILE=~/keystores/app1-release.keystore
KEY_ALIAS=app1-key

# app2/gradle.properties
KEYSTORE_FILE=~/keystores/app2-release.keystore
KEY_ALIAS=app2-key

密钥轮换

Android 应用通常使用长期有效的密钥（10-25 年）签名，但如果需要轮换：

1. 仅在启用 Play App Signing 时可行
2. 联系 Google Play 支持轮换应用签名密钥
3. 收到提示时上传新的上传证书
4. 所有后续构建都必须使用新的上传密钥

文档模板

将此信息保存在密码管理器中：

App Name: My Awesome App
Package: com.example.app
Keystore File: release.keystore (backed up in Dropbox)
Keystore Password: [IN PASSWORD MANAGER]
Key Alias: my-app-key
Key Password: [IN PASSWORD MANAGER]
Certificate Validity: Valid until 2035-02-05
SHA-256 Fingerprint: AB:CD:EF:12:...
Play App Signing: Enabled
Notes: Upload key only, Google manages app signing key