常见问题
按问题分类逐条排查；80% 的问题都在前 3 个。
连接类
「无法连接桌面，请检查网络或确认桌面端已启动」
按下面的顺序逐项排查：
- 桌面端「远程访问」是否在跑？状态条是不是绿灯？
- 公网 URL 在浏览器能否打开
https://你的地址/api/v1/ping？应返回{"ok":true,...} - frp 服务端口是否被防火墙封？
- ICP 备案的 80/443 走 https 没问题
- 自定义端口（如 7000、7420）可能被运营商封 — 改用 443
- 手机 WiFi 是否能访问公网 URL？切到 4G/5G 再试一次（排查 WiFi 路由器问题）
启动前可达性检测
桌面端 v3.5.0 起，启动 frpc 前会自动 ping 一次 frps 服务端，不可达直接弹错。
「证书验证失败」 / TLS 错误
- 配对时记录的证书指纹与当前不一致
- 通常发生在：换了域名 / 换了 frp tunnel / Cloudflare 代理证书变化
- 解决：手机端「设备」页删除该桌面 → 重新配对
鉴权类
「鉴权失败，可能 Token 已被吊销」
可能原因：
| 原因 | 解决 |
|---|---|
| 桌面端「已配对设备」表里手动吊销了本设备 | 删除设备记录 → 移动端重新配对 |
| 多次输错 PIN 触发 IP 锁定 5 分钟 | 等 5 分钟再试 |
| 桌面端清空所有 token（紧急下线） | 重新配对 |
| 桌面端升级后数据库迁移异常 | 桌面端「设置 → 远程访问 → 一键安全自检」检查 |
「PIN 错误或当前没有进行中的配对」
- PIN 60 秒过期，回桌面端重新生成
- 检查输入的 6 位是否全对
- 多次输错会触发 IP 锁定 5 分钟
配对类
扫码不工作
| 排查 | 操作 |
|---|---|
| 相机权限 | 系统设置 → 应用权限 → AICoder → 相机 → 允许 |
| 二维码内容 | 桌面端的"公网 URL"必须先填好，再点「配对新设备」，否则二维码不包含完整信息 |
| 二维码亮度 | 桌面屏幕调亮一点；或拉近距离让摄像头清晰对焦 |
| 摄像头被其他 App 占用 | 关掉别的相机 App 再试 |
配对成功但收不到 AI 输出
通常是 WebSocket 连不上：
- 公网 URL 是否包含
wss://支持？（浏览器测试wss://地址/api/v1/sessions/SID/ws） - frps 是否支持 WebSocket 升级？默认支持；如果用 Caddy/Nginx 反代到 frps，需要确认反代规则没拦截 Upgrade 头
- 手机 → 设备页 → 切换一次桌面（前端会强制重连）
通知类
通知开关开了但收不到
| 排查 | 操作 |
|---|---|
| 系统通知权限 | 系统设置 → 应用权限 → AICoder → 通知 → 允许 |
| App 在后台被杀 | 锁屏 / 后台被系统杀死后无法收到（Web Notification 的局限，不是 bug） |
| 「我的」页测试通知 | 点「测试通知」按钮，能弹说明系统权限正常；不能弹则去系统设置 |
| 国产 ROM 自启动限制 | 小米/华为/OPPO 等需要在"自启动管理"里允许 AICoder 后台运行 |
麦克风类
按住说话报「未授予权限」（已经允许过）
Tauri Mobile WebView 在 Android 上需要同时拥有 RECORD_AUDIO 和 MODIFY_AUDIO_SETTINGS 两项权限才能激活麦克风。v0.1.0 已在 AndroidManifest.xml 同时声明这两项；如果仍报错：
- 系统设置 → 应用权限 → AICoder → 麦克风 → 允许
- 重启 App
- 还不行：卸载重装 v0.1.0+ APK（旧的 debug 版本可能缺权限）
录音很短就报「录音太短」
按住时间需要 ≥ 0.3 秒。v0.1.0 已修复一个 React 状态闭包陷阱（之前会立即报"录音太短"）。 确认你装的是 v0.1.0+ APK。
多设备类
一台手机怎么管多个桌面
「设备」页 → 「+ 添加桌面」 → 重复配对流程。每台桌面独立 token，互不影响。
多台手机连同一桌面
桌面端可以配对多台手机，每台独立 token。同一时刻多台手机看同一桌面，所有 PTY 输出都会同时推送到所有连接的手机。
桌面端「已配对设备」表里能看到所有配对过的设备 + 单独吊销。
安全类
手机丢了，怎么紧急下线？
桌面端 → 设置 → 远程访问 → 「紧急下线」按钮：
- 立即吊销所有已配对设备的 token
- 关闭 axum 网关
- 所有连接的手机立即收到「鉴权失败」断开
- 你自己跑的 frp / cloudflared 等反向代理由你自己关停（与 App 解耦）
之后需要重新配对所有想保留的设备。
公网 URL 是不是不安全？
只要满足以下三条，被攻破概率极低：
- 强制 HTTPS / WSS（默认开启，HTTP 部署会被自检阻断）
- token 是随机 256 位，无法暴力枚举
- 熔断：失败 10 次/60s 触发 5 分钟 IP 锁定
桌面端「设置 → 远程访问 → 一键安全自检」会扫描以下风险：
- 是否暴露明文 HTTP
- 是否有过期 token
- 是否启用了熔断
- frpc 配置文件权限（避免泄露）
其它
移动端 versionName 显示是 0.1.0，桌面端是 3.5.1，是 Bug 吗？
不是 Bug。移动端与桌面端版本号完全独立，各自迭代各自发版：
- 桌面端 v3.5.1 = 桌面应用第 3 大版本第 5 小版本第 1 修订
- 移动端 v0.1.0 = 移动伴侣首发版
之后桌面端可能升到 v3.6.0，移动端可能还在 v0.1.0；移动端升到 v0.2.0 时桌面端可能依然 v3.5.1。两条版本线不再合并。
iOS 什么时候发布？
阻塞 macOS 设备 + Apple Developer 账号（$99/年）+ 审核流程。当前优先级低于桌面端核心功能迭代，暂无明确时间表。
我能在 iPad / 平板上装吗？
Android 平板可以，APK 是 universal-release，按 Android 8.0+ 系统都能装；只是 UI 是按手机设计的，平板上会有大量留白。