Skip to content

🚀 使用 Docker Compose 部署 UpSnap

🚀 使用 Docker Compose 部署 UpSnap

UpSnap 是一款使用 SvelteKit、Go、PocketBase 和 nmap 编写的简单局域网唤醒（Wake-on-LAN, WOL）应用程序。它允许您通过简洁的 Web 界面远程唤醒局域网内的计算机设备，非常适合管理家庭实验室或多台设备的场景。

📦 项目简介

核心功能 * 🚀 一键唤醒：通过仪表板快速唤醒已添加的设备。 * ⏰ 定时任务：通过 Cron 表达式设置自动化的定时唤醒或关机事件。 * 🔌 端口检测：Ping 您选择的任何端口以监控设备服务状态。 * 🔍 网络扫描：使用 nmap 进行网络扫描以发现设备（此功能需要 nmap）。 * 📊 状态可视：清晰展示设备在线/离线状态。 * 👤 用户管理：支持多用户和安全的用户管理。

其他特性 * 主题丰富：提供 29 个主题可供选择。 * 多语言支持：支持国际化，包括中文等语言。 * 跨平台镜像：提供适用于 amd64、arm64、arm/v7、arm/v6 的 Docker 映像。

⚙️ 部署前准备

  1. 环境要求：确保你的系统已安装 Docker 和 Docker Compose。
  2. 环境检查：在终端中执行以下命令，确认 Docker 环境正常： bash docker --version docker-compose --version
  3. 创建项目目录：为部署和管理方便，建议创建一个独立目录。 bash mkdir -p /opt/docker/upsnap && cd /opt/docker/upsnap

🛠 配置 Docker Compose

基于你提供的配置并参考最佳实践，创建 docker-compose.yml 文件：

#version: '3.8'

services:
  upsnap:
    container_name: upsnap
    image: ghcr.io/seriousm4x/upsnap:4  # 也可使用 Docker Hub: seriousm4x/upsnap:4
    network_mode: host # 使用 host 网络模式简化 WOL 广播包的发送
    restart: unless-stopped
    #restart: always
    environment:
      - PUID=1000 # 设置为你的实际用户ID，0 为 root
      - PGID=1000 # 设置为你的实际组ID，0 为 root
      - TZ=Asia/Shanghai # 🕐 设置容器时区，解决定时任务不执行问题
      # - UPSNAP_INTERVAL=@every 10s # 设置设备状态检查间隔
      # - UPSNAP_SCAN_RANGE=192.168.1.0/24 # 设置网络扫描范围
    volumes:
      - ./data:/app/pb_data # 持久化存储配置和数据
    #privileged: true
    #特权:真

关键配置说明：

配置项 说明与建议
network_mode: host 强烈推荐。使用 host 网络模式可以简化 WOL 广播包的发送，避免桥接网络可能带来的问题，并有助于改善在本地网络下的设备发现。
volumes ./data:/app/pb_data 将容器内的数据目录映射到宿主机，确保配置、设备信息和用户数据在容器更新或重启后不会丢失。
environment PUID/PGID：设置容器内进程运行的用户和组ID，应与宿主机上计划用于运行容器的用户权限匹配。如果遇到权限问题，可以尝试设置为 0 (root)。
TZ：务必设置正确时区，这是保证定时任务（Cron）按预期执行的关键。
image 指定使用的镜像及其版本。使用特定版本号（如 :4）有助于避免因镜像更新导致意外问题。

注意：如果使用 network_mode: host，则不需要在配置中映射端口（ports 部分），因为容器直接使用宿主机的网络堆栈。UpSnap 服务默认会在宿主机的 8090 端口上监听。

🚀 启动与初始化

  1. 启动服务：在 docker-compose.yml 文件所在目录执行： bash docker-compose up -d 此命令会拉取镜像并在后台启动容器。

  2. 检查状态： bash docker-compose ps 如果看到容器的状态为 Up，则说明启动成功。

  3. 查看日志（可选）：如果需要排查问题，可以查看容器日志： bash docker-compose logs -f upsnap

  4. 访问并初始化 Web 界面：

    • 在浏览器中访问 http://你的服务器IP:8090。
    • 首次访问时，系统会提示你设置管理员账户和密码，请务必妥善保管。

⚙️ 基本配置与使用

  1. 添加设备

    • 手动添加：在 Web 界面的设置中，手动添加设备信息，包括设备名、MAC 地址（必填）、IP 地址等。
    • 网络扫描：UpSnap 支持网络扫描发现设备（此功能需要 nmap）。你可以在设置中找到网络扫描功能，输入扫描范围（例如 192.168.1.0/24）来发现网络中的设备，然后选择性添加。

  2. 唤醒与管理设备

    • 在主界面，你会看到已添加的设备卡片。
    • 设备状态：通常绿色代表设备已开机，红色代表设备关机。
    • 唤醒操作：点击对应设备的唤醒按钮即可发送唤醒数据包。

  3. 设置定时任务 (Cron)

    • 可以为设备设置定时唤醒或关机任务。
    • 注意时区：确保在 docker-compose.yml 中正确设置了 TZ 环境变量（例如 Asia/Shanghai），否则定时任务可能不会按预期时间执行。

🔒 维护与管理

  • 服务管理：

    • 停止服务：docker-compose down
    • 重启服务：docker-compose restart
    • 查看服务状态：docker-compose ps

  • 版本更新： bash # 进入 docker-compose.yml 所在目录 docker-compose down docker-compose pull # 拉取最新镜像 docker-compose up -d

  • 数据备份：定期备份你的 docker-compose.yml 文件以及 data 目录，这个目录包含了 UpSnap 的所有配置和设备信息。

🐛 常见问题排查 (FAQ)

问题现象 可能原因与解决方法
无法唤醒设备 1. 确认目标设备的 BIOS/固件设置中已启用 Wake-on-LAN 功能。
2. 确认设备与运行 UpSnap 的服务器在同一局域网内。
3. 检查防火墙设置，确保未阻断 WOL 使用的端口（通常是 UDP 端口 7 或 9）。
4. 尝试使用 network_mode: host，这通常能解决网络广播问题。
定时任务不执行 检查时区设置：确保在 docker-compose.yml 中正确配置了 TZ 环境变量（例如 TZ=Asia/Shanghai）。
Web 界面无法访问 1. 检查容器是否正常运行：docker-compose ps。
2. 确认服务器防火墙/安全组放行了 8090 端口。
3. 检查日志：docker-compose logs upsnap。
网络扫描找不到设备 1. 确保在 docker-compose.yml 中正确设置了 UPSNAP_SCAN_RANGE 环境变量（例如 UPSNAP_SCAN_RANGE=192.168.1.0/24）。
2. 某些设备可能不响应 nmap 的扫描请求。

希望这份教程能帮助你顺利搭建属于自己的网络唤醒工具，轻松管理局域网内的设备！