移动 App 使用指南

TrailSnap App 是 Web 版的移动端原生容器，使用 Capacitor 构建。它不会提供公共云端服务，
而是连接你自己部署的 TrailSnap。因此，在安装 App 前需要先完成
TrailSnap 服务部署。

预览版本

移动 App 目前优先适配登录、相册浏览、搜索、设置等基础功能。部分原生能力仍在开发中，
建议保留浏览器访问方式作为备用。

Android 安装

如果已经部署并打开 TrailSnap，也可以在电脑网页进入 设置 → 连接手机 App。页面会显示当前版本的 APK 直接下载地址和下载二维码，用手机相机扫码即可下载；安装完成后，再用 App 扫描同一页面中的服务器连接二维码。

1. 打开项目的 GitHub Releases。
2. 找到所需的正式版本（标签格式为 v*.*.*，例如 v0.9.1）。
3. 在 Assets 中下载 APK。早期测试包的文件名可能带有 debug。
4. 在手机上打开 APK，并按系统提示允许浏览器或文件管理器“安装未知应用”。
5. 安装完成后打开 TrailSnap。

请只从 TrailSnap 官方 GitHub 仓库下载；如果 Release 页面提供了 SHA-256 校验值，请在安装前进行核对。
如果 Android 显示 Play Protect 提示，请先确认下载来源和校验值，不要从第三方网盘安装来源不明的包。

首次连接服务器

App 首次启动会打开“连接 TrailSnap”页面。这里填写的地址与浏览器访问地址完全相同，不需要添加 /api：

http://192.168.1.10:3180

其中：

• 192.168.1.10 替换为部署 TrailSnap 的电脑或 NAS 的局域网 IP；
• 3180 是一键安装脚本默认的 TrailSnap 访问端口；
• 不要填写 localhost 或 127.0.0.1，它们在手机上指向手机自身；
• 不要在地址末尾添加 /api。

点击“测试并保存”。连接成功后，App 会保存该地址并跳转到登录页面。账号、照片和相册数据仍保存在你的 TrailSnap 服务器上。

还可以使用以下免输入方式：

• 在电脑浏览器中打开 TrailSnap，进入“设置 → 连接手机 App”，然后用 App 的“扫描二维码”扫描电脑网页上的二维码；
• 点击“自动查找 TrailSnap”。App 会先使用 DNS-SD/mDNS，再自动探测当前局域网中使用默认访问地址的 Docker 部署；
• 在手机上打开 trailsnap://connect?url=... 连接深链。

二维码应显示在电脑网页上，再由手机 App 扫描；手机连接页不会为自己生成二维码。如果电脑网页使用的是 localhost 或 127.0.0.1，请在“连接手机 App”页面改成电脑的局域网 IP。

自动查找不再只依赖组播：mDNS 没有结果时，Android App 会通过 TCP 查找当前私有网段中使用默认 3180 入口的 TrailSnap，因此普通 Docker bridge 部署也可以被找到。自定义了访问端口、使用 iPhone/iPad，或者热点、访客 Wi-Fi、AP 隔离禁止设备互访时，请改用二维码或手动输入。

连接前检查

让手机与服务器连接到同一局域网，然后用手机浏览器访问：

http://192.168.1.10:3180/api/health-check

如果无法打开，请检查：

• TrailSnap 的 frontend 与 server 容器是否正常运行；
• Docker 是否将统一访问端口映射为 3180:80；
• 服务器防火墙是否允许手机访问 TCP 3180；
• Wi-Fi 是否启用了 AP 隔离或访客网络隔离；
• 地址中的 IP 和端口是否正确。

局域网内可以使用 HTTP。通过公网访问时，请配置域名和有效的 HTTPS 证书，避免账号、令牌和照片请求通过明文网络传输。

更换服务器

进入：

设置 → 关于 → 更改服务器

输入新地址并点击“测试并保存”。切换服务器后，App 会清除当前登录状态，需要使用新服务器上的账号重新登录；服务器端的照片和配置不会因此被删除。

Android 返回操作

Android 的实体返回键或返回手势遵循以下顺序：

1. 当前有弹窗时关闭弹窗；
2. 当前有上一页时返回上一页；
3. 已在首页或没有可返回页面时，将 App 切换到后台，而不是直接结束 App。

更新 App

Android App 会自行检查更新：启动数秒后向所连接的 TrailSnap 服务器查询最新版本，发现新版时弹出更新提示，展示更新内容并提供“立即更新”。点击后 App 会直接下载官方安装包，显示下载进度，完成后自动打开系统安装界面，确认即可覆盖安装。

• 首次更新时 Android 会要求允许 TrailSnap“安装未知应用”。App 会引导跳转到该授权页，授权后回到 App 再点一次“安装”。
• 下载过程中可以点击“取消下载”；也可以点击“跳过此版本”，该版本不再自动提醒（仍可手动检查）。
• 自动检查每天最多提醒一次。需要立即检查时，进入 设置 → 关于 → 检查更新。
• 安装包会先下载到 App 缓存目录，安装完成或下次更新时自动清理。
• 更新检查依赖服务器能访问外网版本清单。服务器处于纯内网时，App 无法获取新版本信息，请按下面的手动方式更新。

也可以手动更新：从 GitHub Releases 下载新版本 APK，并直接安装覆盖旧版本。覆盖更新要求：

• 应用 ID 相同；
• 新旧 APK 使用同一发布密钥签名；
• 新版本号高于已安装版本。

正常覆盖安装会保留服务器地址和登录信息。如果系统提示“签名不一致”，不要直接卸载：先确认 APK 是否来自官方 Release。卸载 App 会清除手机端保存的服务器地址和登录令牌，但不会删除服务器上的照片和数据库。

iPhone 和 iPad

iOS 原生工程已经接入，但公开 IPA 仍需要 Apple 开发者签名。目前推荐使用 PWA：

1. 用 Safari 打开 TrailSnap Web 地址，例如 http://192.168.1.10:3180；
2. 点击 Safari 的“分享”按钮；
3. 选择“添加到主屏幕”；
4. 从主屏幕打开 TrailSnap。

PWA、Android App、iOS App 和浏览器都使用同一个 TrailSnap 地址。

隐私和安全

• App 连接的是用户指定的服务器，项目维护者不会因为使用 App 而自动获得你的照片或账号数据；
• 服务器运营者仍需自行保护数据库、照片目录、备份和访问凭证；
• 公网访问务必优先使用 HTTPS，并设置强密码；
• 只对外开放 TrailSnap 统一访问端口，不要暴露 Server、AI 或数据库内部端口；
• 安装包、服务器和 Web 前端应尽量使用同一版本，以避免接口不兼容。