chore: release v1.0.18

移动端响应式适配（抽屉导航/列表卡片/弹窗自适应）、Android 正式签名与 APK 发布、 iOS(TestFlight) 工程与 CI、多平台构建流水线、相关文档同步。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-07 07:55:33 +08:00
parent 94f0fb2095
commit 480ce836bb
81 changed files with 3096 additions and 366 deletions
@@ -0,0 +1,51 @@
+# 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` 中忽略。