自定义移动端构建（可选）

对绝大多数自托管用户而言，无需自行构建定制版 App。推荐配置方案如下：

1. 自托管服务端
2. 使用 Kaiwu 客户端，并将 Server URL 指向你的实例

本文面向进阶用户，适用于希望在手机上安装专属构建版本的场景（例如使用不同的 Bundle ID/包名、独立的 Expo 项目，或维护私有 Fork）。

本文重点介绍面向个人设备或团队内部的本地/内部安装流程。发布至应用商店不在本文讨论范围内。

通知工作原理（架构）

• 客户端注册 Expo 推送令牌并将其保存到服务端（/v1/push-tokens）。
• CLI 从服务端拉取保存的令牌，再通过 Expo 的推送 API 发送通知。
• 在当前设计中，服务端仅负责存储令牌，并不直接发送推送载荷。

自定义构建前置要求

1) iOS (APNs)

自定义构建需要在你的 Expo/EAS 项目中配置有效的 APNs 凭据。

2) Android (FCM + google-services.json)

自定义构建需要配置 FCM，且构建时必须包含有效的 Firebase Android 配置文件（google-services.json）。

在本代码库中，Expo 配置要求如下：

• apps/ui/app.config.js → android.googleServicesFile: "./google-services.json"

3) 服务端 URL

自定义构建必须指向你的自托管服务端 URL（可通过应用内设置配置，或直接打包预置为默认值）。

在手机上安装（无需应用商店）

iOS（推荐方案：hstack 辅助工具）

如果你在本地栈环境中开发，hstack 提供了辅助工具，支持通过 USB 连接在 iPhone 上构建并安装：

• 安装共享 dev-client（仅需一次）：

hstack mobile-dev-client --install

• 安装各栈独立的 App（每个栈在主屏幕生成独立的应用图标）：

hstack stack mobile:install <stack>

完整工作流及故障排查方法，请参阅 hstack → Mobile (iOS)。

Android

对于 Android，可使用 EAS 内部发布通道，或采用针对当前 Expo 项目的本地 Android 构建流程。请确保应用配置了正确的 google-services.json，并与所安装的 Android 包名保持一致。

API 密钥访问限制（Android / Firebase）

google-services.json 包含客户端 API 密钥。保障其安全靠的是访问限制，而非保密防泄露。

应用限制（推荐）

将密钥的使用范围限制为：

• Android 应用
• 对应应用的包名
• 签名证书的 SHA-1 指纹

对于 EAS 构建，只要持续沿用相同的 Android keystore，SHA-1 就会保持固定。

如果你通过 Play 商店分发，用户从 Google Play 安装的版本会改由 Play 应用签名密钥重新签名（该密钥与你的上传密钥不同）。请一并将该密钥的 SHA-1 添加进来，否则商店安装版可能会出现 Firebase/FCM 功能失效的问题。

API 限制（Cloud Messaging 推荐最小许可名单）

如果仅使用 Firebase Cloud Messaging，建议将密钥限制在以下 API 范围内：

• Firebase Management API (firebase.googleapis.com)
• Cloud Logging API (logging.googleapis.com)
• Firebase Installations API (firebaseinstallations.googleapis.com)
• FCM Registration API (fcmregistrations.googleapis.com)

若启用了其他 Firebase 产品（如 Firestore、Storage、Auth 等），请同步在许可名单中追加对应项。