# Android 正式签名 — 一次性配置

CI 用正式 release keystore 给 APK 签名。keystore **不入库**，通过 Forgejo Secrets 注入。
本文档是一次性操作，配置完成后每次打 tag 自动签名打包。

> 本地构建无需做这些：缺少 `key.properties` 时 `flutter build apk` 自动回退 debug 签名。

## 1. 生成 keystore（本地执行一次）

```bash
keytool -genkeypair -v \
  -keystore jiu-release.jks \
  -alias jiu \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -storepass '<你的store密码>' \
  -keypass '<你的key密码>' \
  -dname "CN=Yanmei, OU=Jiu, O=Yanmei, L=, ST=, C=CN"
```

**务必妥善保管 `jiu-release.jks` 与两个密码**：一旦丢失，已安装用户将无法收到覆盖升级（签名不匹配）。
建议把 `jiu-release.jks` 备份到 `~/.env` 同级的安全位置（勿提交到仓库）。

## 2. 生成 base64（供 CI 注入）

```bash
base64 -i jiu-release.jks | pbcopy   # macOS：已复制到剪贴板
```

## 3. 在 Forgejo 仓库配置 Secrets

仓库 → Settings → Actions → Secrets，新增 4 项：

| Secret 名 | 值 |
|-----------|-----|
| `ANDROID_KEYSTORE_BASE64` | 第 2 步的 base64 字符串 |
| `ANDROID_KEYSTORE_PASSWORD` | store 密码 |
| `ANDROID_KEY_ALIAS` | `jiu` |
| `ANDROID_KEY_PASSWORD` | key 密码 |

## 4. 验证

打一个 tag 触发流水线，确认：
- `build-android` job 绿，产出 `jiu-android.apk`；
- 日志出现 `configuring release signing`（而非 `falling back to debug signing`）；
- 下载安装后，下次升级能覆盖安装（签名一致）。

## 工作原理

- `client/android/app/build.gradle.kts`：存在 `key.properties` 则用正式签名，否则回退 debug。
- `scripts/ci/compile-android.sh`：从 `ANDROID_KEYSTORE_BASE64` 还原 keystore，写出 `key.properties`，构建后清理。
- `key.properties`、`*.jks`、`*.keystore` 已在 `client/android/.gitignore` 中忽略。