安装 TrailSnap
TrailSnap 同时提供桌面安装包和 Docker 自托管部署。先根据使用场景选择版本：
| 方式 | 适合场景 | 支持平台 | AI 能力 |
|---|---|---|---|
| 桌面版 | 单台个人电脑、希望快速开始 | Windows、macOS、Linux | 安装基础客户端后，按需安装 AI 扩展 |
| Docker | NAS、家庭服务器、多设备访问 | 支持 Docker Compose 的设备 | AI 服务随 Compose 部署，可选 CPU/GPU/OpenVINO |
不确定怎么选？
只在当前电脑使用，选择桌面版；需要手机、平板和多台电脑通过局域网访问同一图库，选择 Docker。
桌面版
前往下载页面，官网会优先标出当前系统的安装包：
- Windows 10/11（x64）：下载
.exe并按向导安装。 - macOS（Apple Silicon）：下载
.dmg，将 TrailSnap 拖入“应用程序”。首次打开若被系统拦截，请在“隐私与安全性”中确认允许。 - Linux（x64）：Debian/Ubuntu 建议下载
.deb；其他发行版可使用.AppImage，并为文件添加执行权限。
桌面基础包包含相册管理和本地服务，不会强制下载体积较大的 AI 运行环境。需要人脸识别、OCR、图片分类、语义检索或本地大模型时，请继续阅读 AI 扩展使用说明。
安装完成后：
- 启动 TrailSnap。
- 在设置中添加照片目录。
- 先用少量照片完成一次扫描，确认目录权限与运行状态。
- 按需安装 AI 扩展并创建对应分析任务。
数据安全
桌面版不会替代你的照片备份。首次使用批量整理、重命名或清理功能前，请先备份图库。
Docker 部署
Docker 适合 NAS 和常驻服务器，会同时运行前端、后端、PostgreSQL 与 AI 服务。开始前请先完成部署前检查。
一键安装脚本
Windows PowerShell：
irm https://trailsnap.cn/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1Linux / macOS / WSL2：
curl -fsSL https://trailsnap.cn/install.sh | bash脚本会收集照片目录、一个 TrailSnap 访问端口、时区和 AI 模式，生成 .env 与 docker-compose.yml，拉取镜像并完成健康检查。AI 模式支持通用 CPU、NVIDIA GPU（CUDA）和适合 Intel CPU/核显/NPU 的 OpenVINO。默认地址为 http://<服务器 IP>:3180，网页、App 和 CLI 都使用这个地址。
常用管理命令（在安装目录执行）：
docker compose --env-file .env ps
docker compose --env-file .env logs -f
docker compose --env-file .env restart
docker compose --env-file .env downAndroid App 的“自动查找 TrailSnap”会直接探测宿主机发布的默认 3180 入口，普通 Docker bridge 部署无需额外配置。Linux 服务器还可以选择启用宿主机 mDNS 广播：
docker compose --env-file .env --profile lan-discovery up -d该 profile 仅增强 mDNS，不影响网页和 App 正常连接。Docker Desktop、手机热点、访客 Wi-Fi 或启用了 AP 隔离的网络仍建议使用“设置 → 连接手机 App”中的二维码。
升级和卸载：
./install.sh --upgrade
./install.sh --uninstall # 保留数据
./install.sh --uninstall --purge # 删除数据，谨慎使用PowerShell 脚本使用对应的 -Upgrade、-Uninstall 参数；运行 Get-Help .\install.ps1 -Detailed 可查看完整参数。
切换 AI 加速模式
再次运行安装脚本时，已有安装菜单会显示当前模式。选择“切换 AI 模式”后，可以在 CPU、GPU 和 OpenVINO 之间切换；数据库、模型缓存和照片目录不会被删除。
也可以直接通过命令切换并升级 AI 镜像：
# NVIDIA GPU / CUDA
.\install.ps1 -Upgrade -AiMode gpu
# 通用 CPU
.\install.ps1 -Upgrade -AiMode cpu
# Intel OpenVINO
.\install.ps1 -Upgrade -AiMode openvino# NVIDIA GPU / CUDA
./install.sh --upgrade --ai-mode gpu
# 通用 CPU
./install.sh --upgrade --ai-mode cpu
# Intel OpenVINO
./install.sh --upgrade --ai-mode openvinoGPU 模式要求 NVIDIA 驱动和 NVIDIA Container Toolkit 可用，安装器会在切换前检查环境。服务启动后，安装器还会自动进入 AI 容器验收推理后端：GPU 模式必须检测到 CUDAExecutionProvider，OpenVINO 模式必须检测到 OpenVINOExecutionProvider。验收失败不会删除数据或中止其他服务，脚本会显示诊断命令和本教程地址。
也可以手动验证 ONNX Runtime：
docker compose --env-file .env exec ai python -c "import onnxruntime as ort; print(ort.get_device()); print(ort.get_available_providers())"GPU 模式的输出应包含 GPU 和 CUDAExecutionProvider；只有 AzureExecutionProvider 与 CPUExecutionProvider 表示当前仍是 CPU 运行时。OpenVINO 模式应包含 OpenVINOExecutionProvider。