部署前检查
在运行安装脚本前，用这一页确认环境和预期。这样可以避免“容器启动了，但照片无法扫描或手机无法访问”的常见问题。
你需要准备什么
| 项目 | 最低要求 | 建议 |
|---|---|---|
| 系统 | Windows、macOS、Linux 或支持 Docker 的 NAS | 64 位 x86 或 ARM 系统，保持系统与 Docker 为受支持版本 |
| Docker | Docker Engine / Desktop 与 Docker Compose | 先运行 docker compose version 确认可用 |
| 存储 | 能容纳原始照片、缩略图和数据库 | 预留额外空间，并为备份准备独立位置 |
| 网络 | 服务器可被浏览器访问 | 手机使用时，手机与服务器处于同一局域网或配置 HTTPS 公网访问 |
| AI | CPU 可运行基础流程 | 大图库或本地模型建议使用更充足的内存和 GPU；GPU 不是安装前提 |
照片目录检查
- 使用一个真实存在的绝对路径，不要填写临时盘、网络断开的映射盘或容器内路径。
- 确认 Docker 有读取该目录的权限；如果需要上传、整理或重命名，也需要相应写入权限。
- 第一次导入前先备份照片。批量整理、重命名和清理功能会影响文件，建议先在小目录试用。
- 首次扫描时间取决于照片数量、文件大小、硬盘速度和是否启用 AI；扫描可在后台进行，不代表网页不可用。
网络与端口检查
- 一键安装只对外开放一个 TrailSnap 访问端口；网页、App 和 CLI 使用相同地址，以安装完成后的终端输出为准。
- Android/iOS App 可以扫描连接二维码、发现同一局域网中的服务，或手动填写该地址；不要填写
localhost。 - 如果局域网访问失败，先检查 Docker 端口映射、防火墙和 Wi-Fi 的 AP / 访客网络隔离。
开始前的选择
- 只想试用：先选择一个少量照片的测试目录，使用 CPU 模式部署。
- 导入家庭图库：先完成照片和数据库备份，再在空闲时间开始首次扫描。
- 使用公网或移动端：先规划域名与 HTTPS，只开放 TrailSnap 统一入口，不要把 Server、AI 或数据库内部端口暴露到公网。
- 使用外部 AI 服务或 Agent：先阅读数据、隐私与备份，为 Token 设定最小权限。
确认无误后，继续阅读安装指南。