# iOS 移动客户端

> ServerBee 原生 iOS 配套应用，支持二维码配对、推送通知和实时监控。

URL: https://docs.serverbee.app/zh/docs/mobile

ServerBee 提供原生 iOS 配套应用，把服务器监控带到你的手机：实时指标、告警推送通知，以及随时随地管理服务器。

## 获取方式 [#获取方式]

本仓库目前没有发布可直接安装的 iOS 构建，也没有提供 App Store/TestFlight 获取链接。下方流程适用于你从 ServerBee 运维方取得的构建，或自行从源码构建的应用。自行构建时先安装 Xcode 与 XcodeGen，然后执行：

```bash
cd apps/ios
xcodegen generate
open ServerBee.xcodeproj
```

在 Xcode 中选择自己的 Apple Development Team，再运行到 iPhone。推送通知还需要下文所述、与签名一致的 Apple Developer APNs 配置；仅完成本地构建并不等于具备生产 APNs 推送。

## 功能特性 [#功能特性]

* **二维码配对** -- 扫描 Web 应用中的二维码即可即时认证，无需手动输入 Token
* **推送通知** -- 当服务器离线或触发阈值时，直接在 iPhone 上接收 APNs（Apple 推送通知服务）告警
* **实时指标** -- 通过 WebSocket 传输的实时服务器状态、CPU、内存、磁盘和网络指标
* **告警历史** -- 查看近期告警及其状态（触发/已解决）和详细信息
* **安全认证** -- 基于 Bearer Token 的认证，支持自动刷新（15 分钟访问令牌，30 天刷新令牌）

## 系统要求 [#系统要求]

* iOS 17.0 或更高版本
* 启用移动认证的 ServerBee 服务器实例（v0.8.0+）
* 推送通知需要：在服务器上配置 APNs 认证密钥

## 设备配对 [#设备配对]

### 1. 启用移动认证（服务端） [#1-启用移动认证服务端]

在 v0.8.0+ 中，移动认证默认启用。除非需要调整令牌有效期，否则无需额外配置。

可选配置（`server.toml`）：

```toml
[mobile]
access_ttl = 900      # 访问令牌有效期（秒），默认 15 分钟
refresh_ttl = 2592000 # 刷新令牌有效期（秒），默认 30 天
```

### 2. 从 Web 应用开始配对 [#2-从-web-应用开始配对]

1. 登录你的 ServerBee Web 应用
2. 进入 **设置** → **移动设备**
3. 点击 **配对新设备**
4. 显示一个 5 分钟有效期的二维码

### 3. 使用 iOS 应用扫描 [#3-使用-ios-应用扫描]

1. 打开 ServerBee iOS 应用
2. 在欢迎屏幕点击 **扫描二维码**
3. 将相机对准 Web 应用中显示的二维码
4. 应用将自动认证并显示你的服务器列表

## 管理已配对设备 [#管理已配对设备]

### 查看已配对设备 [#查看已配对设备]

在 Web 应用中，进入 **设置** → **移动设备** 查看所有已配对的 iOS 设备：

* 设备名称（如 "iPhone 15 Pro"）
* 配对日期和时间
* 最后活跃时间戳

### 撤销访问权限 [#撤销访问权限]

要移除设备的访问权限：

1. 在 **移动设备** 列表中找到要移除的设备
2. 点击 **撤销** 按钮
3. 确认操作

该设备将立即登出，其所有令牌将被作废。

## 推送通知（APNs） [#推送通知apns]

### 服务器配置 [#服务器配置]

要启用推送通知，请在 Web 应用中配置 APNs 凭证：

1. 进入 **设置** → **通知**
2. 添加类型为 **APNs** 的新通知渠道
3. 上传你的 APNs 认证密钥（来自 Apple Developer Portal 的 .p8 文件）
4. 输入你的 Team ID、Key ID 和 Bundle ID
5. 使用 **测试** 按钮测试配置

### APNs 必填字段 [#apns-必填字段]

| 字段          | 说明                                              |
| ----------- | ----------------------------------------------- |
| Team ID     | 你的 Apple Developer Team 标识符（10 位字符）             |
| Key ID      | Apple Developer Portal 中 APNs 认证密钥的 Key ID      |
| Bundle ID   | 你的 iOS 应用 Bundle 标识符（如 `com.example.serverbee`） |
| Private Key | Apple Developer Portal 中 .p8 文件的内容              |

### 创建 APNs 密钥 [#创建-apns-密钥]

1. 访问 [Apple Developer Portal](https://developer.apple.com)
2. 进入 **Certificates, Identifiers & Profiles** → **Keys**
3. 创建启用 **Apple Push Notifications service (APNs)** 的新密钥
4. 下载 .p8 文件（只能下载一次）
5. 记录 Portal 上显示的 Key ID

## 安全考量 [#安全考量]

* **令牌轮换**：每次使用时轮换刷新令牌（一次性使用），旧刷新令牌不能重用
* **固定过期**：访问令牌固定 15 分钟过期（无滑动续期），以限制被盗后的暴露时间
* **安全存储**：令牌使用适当的可访问性级别存储在 iOS Keychain 中
* **会话过期**：过期的访问令牌会话每小时清理一次。该任务不会删除配对设备的刷新会话：设备列表会在刷新会话过期后将其隐藏；刷新令牌轮换会替换对应记录，登出或撤销会将其删除。

## 故障排除 [#故障排除]

### 二维码无法扫描 [#二维码无法扫描]

* 确保二维码在屏幕上清晰显示
* 检查二维码是否已过期（5 分钟超时）
* 尝试从 Web 应用生成新的二维码

### 未收到推送通知 [#未收到推送通知]

* 验证通知渠道中的 APNs 凭证是否正确
* 确保 iOS 应用已授予通知权限
* 确认设备仍在移动设备列表中，且未被撤销
* 查看服务器日志中的 APNs 投递错误

### 认证失败 [#认证失败]

* 如果应用显示"会话已过期"，将自动刷新令牌
* 如果刷新失败，需要使用新的二维码重新配对
* 检查服务器时间是否正确同步（NTP）

## 技术细节 [#技术细节]

### 认证流程 [#认证流程]

1. **登录/二维码配对**：POST `/api/mobile/auth/login` 或二维码配对端点 → 返回 access\_token + refresh\_token
2. **API 请求**：在请求头中包含 `Authorization: Bearer {access_token}`
3. **令牌刷新**：收到 401 时，POST `/api/mobile/auth/refresh` 携带 refresh\_token → 新的令牌对
4. **登出**：POST `/api/mobile/auth/logout` 作废该设备的所有令牌

### WebSocket 连接 [#websocket-连接]

iOS 应用维护 WebSocket 连接以获取实时更新：

* 连接 URL：`wss://your-server/api/ws/servers`
* 握手期间通过 `Authorization: Bearer` 头进行认证
* 自动重连，使用指数退避策略
* 访问令牌过期时连接自动关闭（重连触发刷新）