Docker 部署（通用）

本章面向 NAS/家庭服务器场景：用 Docker Compose 一次性启动 TrailSnap 的前端、后端、数据库与 AI 服务，并把你的照片目录挂载进来。

一键安装脚本

Windows PowerShell：

irm https://trailsnap.cn/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1

Linux / macOS / WSL2：

curl -fsSL https://trailsnap.cn/install.sh | bash

脚本会收集照片目录、一个 TrailSnap 访问端口、时区和 CPU/GPU 模式，生成 .env 与 docker-compose.yml，拉取镜像并完成健康检查。默认访问地址为 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 down

升级和卸载：

./install.sh --upgrade
./install.sh --uninstall          # 保留数据
./install.sh --uninstall --purge  # 删除数据，谨慎使用

PowerShell 脚本使用对应的 -Upgrade、-Uninstall 参数；运行 Get-Help .\install.ps1 -Detailed 可查看完整参数。

手动部署

1. 目录规划

在 NAS 上先准备一个共享文件夹作为 TrailSnap 的“项目目录”，建议包含两类数据：

• 应用数据：数据库与应用运行数据（需要长期持久化）
• 照片目录：你自己的照片库（建议只读挂载）

示例结构（仅示意）：

trailsnap/
  docker-compose.yml
  data/
  pg_data/

2. Docker Compose（推荐模板）

下面的 compose 与安装指南保持一致，你只需要修改两处：

• server.volumes 里照片目录的宿主机路径
• 如有端口冲突，修改 frontend.ports 中唯一的访问端口

version: '3.8'

services:
  postgres:
    image: crpi-d7wuvvdylhqugyu2.cn-hangzhou.personal.cr.aliyuncs.com/siyuan044/pgvector:pg18-trixie
    container_name: postgres_container
    restart: always
    environment:
      POSTGRES_DB: trailsnap
      POSTGRES_USER: trailsnap
      POSTGRES_PASSWORD: trailsnap
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --lc-collate=C --lc-ctype=C"
      PGDATA: /var/lib/postgresql/data/pgdata
    networks: [ app-network ]
    volumes:
      - ./pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U trailsnap -d trailsnap -p 5432"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 10s

  server:
    image: crpi-d7wuvvdylhqugyu2.cn-hangzhou.personal.cr.aliyuncs.com/siyuan044/trailsnap-server:latest
    restart: always
    expose: [ "8000" ]
    networks: [ app-network ]
    volumes:
      - ./data:/app/data
      - /path/to/your/photos:/app/Photos
    environment:
      - TZ=Asia/Shanghai
      - DB_URL=postgresql://trailsnap:trailsnap@postgres:5432/trailsnap
      - RAILWAY_DB_URL=postgresql://trailsnap:trailsnap@postgres:5432/railway
      - AI_API_URL=http://ai:8001
      - TRAILSNAP_ROOT_PATH=/api
      # 请替换为这台主机的局域网 IP，供 App 自动发现
      - TRAILSNAP_PUBLIC_URL=http://192.168.1.10:3180
    depends_on:
      postgres:
        condition: service_healthy

  ai:
    image: crpi-d7wuvvdylhqugyu2.cn-hangzhou.personal.cr.aliyuncs.com/siyuan044/trailsnap-ai:latest
    restart: always
    stop_grace_period: 15s
    expose: [ "8001" ]
    networks: [ app-network ]
    volumes:
      - ./data:/app/data
    environment:
      - TZ=Asia/Shanghai
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8001/health-check', timeout=3)"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s

  frontend:
    image: crpi-d7wuvvdylhqugyu2.cn-hangzhou.personal.cr.aliyuncs.com/siyuan044/trailsnap-frontend:latest
    restart: always
    ports: [ "3180:80" ]
    depends_on: [ server ]
    networks: [ app-network ]

networks:
  app-network:
    driver: bridge

3. 启动与验证

在 docker-compose.yml 所在目录执行：

docker-compose up -d

启动后只有一个用户入口：

• TrailSnap：http://<NAS_IP>:3180
• API 文档：http://<NAS_IP>:3180/api/docs

移动 App 可填写同一地址，也可以扫描连接二维码或使用“自动查找 TrailSnap”。Android App 会在 mDNS 无结果时探测默认 3180 入口，因此普通 Docker bridge 部署不需要额外开放组播端口。Server、AI 和 PostgreSQL 只在 Compose 内部网络通信。

GPU 加速支持 (可选)

如果您拥有 NVIDIA 显卡，可以启用 GPU 加速来提升 AI 处理速度。

前置条件

1. 宿主机已安装 NVIDIA 显卡驱动。
2. 已安装 NVIDIA Container Toolkit。

【Windows 安装步骤】（其他系统请自行搜索教程）：

步骤 1：打开 WSL 2 的 Linux 终端
在 Windows 开始菜单中找到你安装的 Linux 发行版（比如 Ubuntu），打开其终端（不是 Windows 的 PowerShell）。

步骤 2：在 WSL 2 中安装 nvidia-docker2
以 Ubuntu 为例，执行以下命令：

sudo apt update
sudo apt install -y lsb-release curl gpg
# 1. 设置NVIDIA软件源
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

# 2. 更新软件源并安装nvidia-docker2
sudo apt-get update
sudo apt-get install -y nvidia-docker2

# 3. 重启Docker服务
sudo systemctl restart docker

修改 docker-compose.yml

请对 ai 服务进行如下修改：

1. 将镜像标签修改为 -gpu 后缀（例如 latest-gpu）。
2. 添加 deploy 节点以请求 GPU 资源。

  ai:
    image: crpi-d7wuvvdylhqugyu2.cn-hangzhou.personal.cr.aliyuncs.com/siyuan044/trailsnap-ai:latest-gpu
    restart: always
    stop_grace_period: 15s
    expose: [ "8001" ]
    networks: [ app-network ]
    volumes:
      - ./data:/app/data
    environment:
      - TZ=Asia/Shanghai
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8001/health-check', timeout=3)"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

NAS 场景常见问题

路径怎么写才正确？

在 NAS 上请以“文件夹的真实路径”为准。不同系统的路径显示方式不同，但原则只有一个：确保容器内的 /app/Photos/ 能看到你的照片文件。

如果有多个文件夹需要挂载，推荐使用下面的格式，/app/Photos子目录下会简化后续的一些操作：

volumes:
  - ./data:/app/data
  - /你的照片文件夹真实路径1:/app/Photos/旅行
  - /你的照片文件夹真实路径2:/app/Photos/航拍
  - /你的照片文件夹真实路径3:/app/Photos/家庭

权限不足导致扫描不到照片

如果照片目录是只读共享或权限隔离，容器可能无法读取。建议：

• 给容器运行账号授予该共享文件夹的读取权限
• 或把照片目录挂载为只读并确保宿主机侧权限允许读取

端口冲突

NAS 上常见 80/443/8080 等端口容易被占用。TrailSnap 默认只开放 3180；如冲突可修改唯一的映射，例如：

ports: [ "13180:80" ]

NAS 具体教程

• 绿联 NAS 部署
• 极空间部署
• 飞牛OS 部署