ghcr.io/trugamr/wol:0.3.0

wol

一个用于发送局域网唤醒（Wake-On-LAN，WOL）魔术包以唤醒网络设备的CLI工具。同时支持CLI命令和Web界面。

Features

• 通过CLI或Web界面发送WOL魔术包
• 配置多台机器并命名以便快速访问
• 可配置广播地址和端口，并支持按机器覆盖
• 列出已配置的机器
• 用于便捷唤醒的Web界面
• 基于cron计划的定时唤醒
• Docker支持

Installation

预构建二进制文件

从发布页面下载适用于您平台的最新版本。

支持平台：

• Linux（x86_64、arm64、armv7）
• macOS（x86_64、arm64）
• Windows（x86_64）

使用Go安装

go install github.com/trugamr/wol@latest

使用Docker

docker run --network host -v $(pwd)/config.yaml:/etc/wol/config.yaml ghcr.io/trugamr/wol:latest

或使用docker-compose：

# 方法1：使用绑定挂载
services:
  wol:
    image: ghcr.io/trugamr/wol:latest
    command: serve # 启动Web界面
    network_mode: "host"
    volumes:
      - ./config.yaml:/etc/wol/config.yaml

# 方法2：使用环境变量
services:
  wol:
    image: ghcr.io/trugamr/wol:latest
    command: serve # 启动Web界面
    network_mode: "host"
    environment:
      WOL_CONFIG: |
        machines:
          - name: desktop
            mac: "00:11:22:33:44:55"
            ip: "192.168.1.100" # 可选，用于状态检查
          - name: server
            mac: "AA:BB:CC:DD:EE:FF"
            ip: "server.local"
        server:
          listen: ":7777" # 可选，默认为:7777
        ping:
          privileged: false # 可选，设为true以使用特权ping

查看examples/reverse-proxy.yml，了解在反向代理后运行wol并配置基本认证、HTTPS等的示例。

配置文件应挂载到容器内的/etc/wol/config.yaml。为确保局域网唤醒包在本地网络正常工作，建议使用主机网络模式。

镜像标签：

• latest和X.Y.Z跟踪命名版本（X.Y.Z固定特定版本）。
• edge跟踪main分支的最新提交，用于尝试未发布的更改。

Configuration

在以下位置之一创建config.yaml文件（按优先级排序）：

• ./config.yaml（当前目录）
• ~/.wol/config.yaml（主目录）
• /etc/wol/config.yaml（系统级）

要从任意路径加载配置文件，传递-c/--config参数：

wol serve --config /etc/wol/config.yaml

显式指定的--config文件具有权威性：它必须存在（如果不存在，wol将报错退出），并且会忽略上述默认搜索位置和WOL_CONFIG环境变量。启动时，serve会记录其加载的配置源。

或者，您可以通过WOL_CONFIG环境变量提供配置：

export WOL_CONFIG='
machines:
  - name: desktop
    mac: "00:11:22:33:44:55"
    ip: "192.168.1.100" # 可选，用于状态检查
  - name: server
    mac: "AA:BB:CC:DD:EE:FF"
    ip: "server.local"

server:
  listen: ":7777" # 可选，默认为:7777
'

配置示例：

machines:
  - name: desktop
    mac: "00:11:22:33:44:55"
    ip: "192.168.1.100" # 可选，用于状态检查
  - name: server
    mac: "AA:BB:CC:DD:EE:FF"
    ip: "server.local"
    # 可选的按机器广播覆盖，例如当机器位于不同子网/VLAN时。未设置的字段继承下面的全局广播配置。
    broadcast:
      address: "192.168.20.255"

server:
  listen: ":7777" # 可选，默认为:7777

# 可选。魔术包发送目标；默认为255.255.255.255:9。
broadcast:
  address: "255.255.255.255"
  port: 9

ping:
  privileged: false # 可选，如果需要特权ping则设为true

schedules: # 可选，由`wol serve`运行的cron定时唤醒
  - name: weekend-backup # 可选标签，显示在日志中
    machine: server # 必须与上面定义的机器名称匹配
    cron: "0 2 * * 6" # 周六02:00

广播地址和端口

默认情况下，魔术包发送到广播地址255.255.255.255的9端口。在具有多个网络接口的主机上（例如WSL2或带有Docker桥接的主机），操作系统可能会通过错误的接口发送数据包，导致设备无法接收。

如果发生这种情况，请设置设备所在子网的广播地址。对于192.168.1.100/24的设备，该地址为192.168.1.255。这样数据包将通过正确的接口路由。

您可以通过三种方式设置广播目标：

• 全局设置，在broadcast键下。
• 按机器设置，在机器自身的broadcast键下。当机器位于不同子网时非常有用。未设置的字段将回退到全局值。
• 单次发送时，使用--broadcast和--port标志。

当设置多个时，优先级顺序为：CLI标志，然后是按机器配置，接着是全局配置，最后是内置默认值255.255.255.255:9。

安装

预构建二进制文件

从https://github.com/trugamr/wol/releases%E4%B8%8B%E8%BD%BD%E9%80%82%E7%94%A8%E4%BA%8E%E6%82%A8%E5%B9%B3%E5%8F%B0%E7%9A%84%E6%9C%80%E6%96%B0%E7%89%88%E6%9C%AC%E3%80%82

支持的平台：

• Linux (x86_64, arm64, armv7)
• macOS (x86_64, arm64)
• Windows (x86_64)

使用 Go

go install github.com/trugamr/wol@latest

使用 Docker

docker run --network host -v $(pwd)/config.yaml:/etc/wol/config.yaml ghcr.io/trugamr/wol:latest

或者使用 docker-compose：

# 方法 1：使用绑定挂载
services:
  wol:
    image: ghcr.io/trugamr/wol:latest
    command: serve # 启动 Web 界面
    network_mode: "host"
    volumes:
      - ./config.yaml:/etc/wol/config.yaml

# 方法 2：使用环境变量
services:
  wol:
    image: ghcr.io/trugamr/wol:latest
    command: serve # 启动 Web 界面
    network_mode: "host"
    environment:
      WOL_CONFIG: |
        machines:
          - name: desktop
            mac: "00:11:22:33:44:55"
            ip: "192.168.1.100" # 可选，用于状态检查
          - name: server
            mac: "AA:BB:CC:DD:EE:FF"
            ip: "server.local"
        server:
          listen: ":7777" # 可选，默认为 :7777
        ping:
          privileged: false # 可选，设为 true 以使用特权 ping

查看 examples/reverse-proxy.yml 获取在反向代理后运行 wol 的示例，包括基本身份验证、HTTPS 等配置。

[!NOTE] 配置文件应挂载到容器内的 /etc/wol/config.yaml。为确保局域网内 Wake-on-LAN 数据包正常工作，建议使用主机网络模式。

镜像标签：

• latest 和 X.Y.Z 跟踪命名发布版本（X.Y.Z 固定特定版本）。
• edge 跟踪 main 分支的最新提交，用于尝试未发布的更改。

配置

在以下位置之一创建 config.yaml 文件（按优先级排序）：

• ./config.yaml（当前目录）
• ~/.wol/config.yaml（主目录）
• /etc/wol/config.yaml（系统级）

要从任意路径加载配置文件，传递 -c/--config 参数：

wol serve --config /etc/wol/config.yaml

显式指定的 --config 文件具有权威性：该文件必须存在（如果不存在，wol 将退出并报错），并且会忽略上述默认搜索位置和 WOL_CONFIG 环境变量。启动时，serve 命令会记录其加载的配置源。

或者，您可以通过 WOL_CONFIG 环境变量提供配置：

export WOL_CONFIG='
machines:
  - name: desktop
    mac: "00:11:22:33:44:55"
    ip: "192.168.1.100" # 可选，用于状态检查
  - name: server
    mac: "AA:BB:CC:DD:EE:FF"
    ip: "server.local"

server:
  listen: ":7777" # 可选，默认为 :7777
'

示例配置：

machines:
  - name: desktop
    mac: "00:11:22:33:44:55"
    ip: "192.168.1.100" # 可选，用于状态检查
  - name: server
    mac: "AA:BB:CC:DD:EE:FF"
    ip: "server.local"
    # 可选的每台机器广播覆盖，例如当机器位于不同子网/VLAN 时。未设置的字段继承全局广播配置。
    broadcast:
      address: "192.168.20.255"

server:
  listen: ":7777" # 可选，默认为 :7777

# 可选。魔术包发送目标；默认为 255.255.255.255:9。
broadcast:
  address: "255.255.255.255"
  port: 9

ping:
  privileged: false # 可选，如需使用特权 ping 请设为 true

schedules: # 可选，由 `wol serve` 运行的定时唤醒任务
  - name: weekend-backup # 可选标签，显示在日志中
    machine: server # 必须与上述机器名称匹配
    cron: "0 2 * * 6" # 周六 02:00

广播地址和端口

默认情况下，魔术包发送到广播地址 255.255.255.255 的 9 端口。在具有多个网络接口的主机上（例如 WSL2 或带有 Docker 桥接的主机），操作系统可能会通过错误的接口发送数据包，导致设备无法接收。

如果发生这种情况，请设置设备所在子网的广播地址。对于 192.168.1.100/24 的设备，该地址为 192.168.1.255。这样数据包将通过正确的接口路由。

您可以通过三种方式设置广播目标：

• 全局设置，在 broadcast 键下。
• 每台机器单独设置，在机器自身的 broadcast 键下。当机器位于不同子网时，这非常有用。未设置的字段将回退到全局值。
• 单次发送时，使用 --broadcast 和 --port 标志。

当设置多个时，优先级顺序为：CLI 标志，然后是每台机器的配置，接着是全局配置，最后是内置默认值 255.255.255.255:9。

定时唤醒

可选的 schedules 部分使 wol serve 能够按 cron 计划自动唤醒机器。省略该部分（或留空）将禁用调度功能——serve 的行为与之前完全相同。

每个调度包含：

• machine（必填）——在 machines 下定义的机器名称。
• cron（必填）——唤醒时间。支持标准的五字段 cron 表达式（分 时 日 月 周），以及 @hourly、@daily、@weekly、@monthly 和 @every 1h30m 描述符。
• name（可选）——日志输出中使用的标签；默认为机器名称。

Cron 表达式根据服务器的本地时间进行计算。在容器中运行时，设置 TZ 环境变量（例如 TZ=America/New_York）可控制时区。

调度会在 serve 启动时进行验证：引用未知机器或包含无效 cron 表达式的调度会导致 wol serve 以错误退出，因此可立即发现配置错误，而非静默失效。

使用方法

命令行命令

# 列出所有已配置的机器
wol list

# 通过名称唤醒机器
wol send --name desktop

# 通过 MAC 地址唤醒机器
wol send --mac "00:11:22:33:44:55"

# 为单次发送覆盖广播地址和端口
#（例如，以到达特定子网中的设备）
wol send --mac "00:11:22:33:44:55" --broadcast 192.168.1.255 --port 9

# 启动 Web 界面
wol serve

# 使用显式配置文件启动 Web 界面
wol serve --config /etc/wol/config.yaml

# 显示版本信息
wol version

Web 界面

在运行 serve 命令时，Web 界面可通过 http://localhost:7777 访问。它提供：

• 所有已配置机器的列表
• 一键唤醒按钮
• 实时机器状态监控（配置 IP 时可用）
• 版本信息
• 文档和支持链接

从源代码构建

# 克隆仓库
git clone https://github.com/trugamr/wol.git
cd wol

# 构建
go build

# 运行
./wol

已知问题

Docker 容器 Ping 权限

在 Docker 容器中运行时，使用 ping 的机器状态功能可能因权限问题无法工作。这是因为应用程序使用 https://github.com/prometheus-community/pro-bing 发送 ping，而这需要特定的 Linux 内核设置。

要解决此问题，需在主机系统上设置以下 sysctl 参数：

sysctl -w net.ipv4.ping_group_range="0 2147483647"

要使此更改持久化，将其添加到 /etc/sysctl.conf 文件中。

也可尝试在配置中设置 ping.privileged: true 作为替代解决方案。

更多详情，请参见 https://github.com/Trugamr/wol/issues/12%E3%80%82

发布

发布由 https://github.com/googleapis/release-please 处理。每次推送到 main 分支都会更新一个“发布”拉取请求，该请求根据历史记录中的 Conventional Commits 来更新版本号和变更日志。合并该拉取请求会标记发布，并触发 GoReleaser 发布二进制文件和容器镜像。在发布拉取请求合并前，不会发布任何内容。

许可证

本项目采用 MIT 许可证。详情请参见 LICENSE 文件。

贡献

欢迎贡献！随时提交 issue 或拉取请求。