远程唤醒（Wake-on-LAN）

远程唤醒 用 Magic Packet 启动已关机或休眠的局域网设备。fn-knock 可以直接向本机所在局域网广播，也可以通过另一台 fn-knock 的内置 Relay 跨网络广播；配置 SSH 后，还能关闭在线设备。已登录用户可以从网关传送门打开精简电源控制页。

Wake-on-LAN 本身只能发出唤醒信号；远程关机使用独立的 SSH 连接和固定系统命令。目标主板、网卡、固件和操作系统必须已经启用 WOL，并且设备断电后仍需保留网卡供电。

开启功能

在 系统设置 → 功能 → 远程唤醒 开启功能。保存后会显示 远程唤醒 侧边栏入口，并启动设备在线检测、内置 Relay 和已配置的第三方平台连接。关闭开关会停止这些运行任务并隐藏入口，但不会删除设备、Relay 或第三方平台配置。

建议先在同一局域网完成一台设备的直接唤醒，再配置跨网段或第三方平台。这样可以先排除目标设备自身未启用 WOL 的问题。

添加本地设备

进入 远程唤醒 → 设备，可手工添加，也可以使用 一键发现：

1. 默认扫描 fn-knock 自动识别到的直连 IPv4 网段；需要指定范围时展开扫描设置，填写一个或多个 CIDR。
2. 扫描只显示实际响应并能从邻居表解析出 MAC 地址的在线设备。休眠、禁止 ICMP 或已被交换机老化出邻居表的设备可能不会出现。
3. 选择设备并确认名称后批量添加。发现流程会同时填写设备 IP 和对应网段的定向广播地址。

手工添加时主要字段如下：

字段	作用
名称	管理页、传送门和事件记录中显示的设备名称
MAC 地址	Magic Packet 的目标；保存后统一为大写冒号格式
设备 IP 地址	用于在线检测，不是发送 Magic Packet 的唯一依据
唤醒路径	本机设备选择直接广播；其他网络的设备选择已配对 Relay
广播地址	本机直接唤醒时使用；留空则尝试向检测到的本机网卡广播
启用	停用后保留配置，但不能从管理页、传送门或第三方平台触发唤醒

点击 唤醒 只表示广播已经提交，不代表设备一定成功开机。对同一设备的唤醒请求有短暂冷却时间，连续点击不会持续发送数据包。

在线状态如何判断

启用的设备大约每分钟检测一次。新建或编辑设备后会立即触发检测；发出唤醒后还会在短暂等待后复查两次，所以状态不会在点击按钮的瞬间变成在线。

• 在线：探测得到响应，并且响应地址与目标 MAC 一致；
• 离线：探测流程完成，但没有发现目标设备；
• 待检测：尚未检查，或探测超时、Relay 不可用、地址无法确认。

设备 IP 发生 DHCP 变化时，fn-knock 可以根据邻居表更新观察到的地址。不要把 待检测 直接解释为设备一定关机；容器网络、ICMP 策略、跨 VLAN 路由和系统权限都可能让探测结果不确定。

从网关传送门唤醒

开启 WOL 后，系统设置 → 网关 → 传送门 会出现 显示远程唤醒快捷入口，默认开启。也可以从 远程唤醒 页右上角的设置中修改。已登录用户点击入口后会打开内置 /__wol__ 页面，只能看到已启用设备的名称和简化在线状态，不会得到 MAC、设备 IP、广播地址、Relay 或内部错误详情。

这个入口同时要求：

1. WOL 功能已开启；
2. 传送门允许显示 WOL；
3. 浏览器持有仍有效的登录会话；
4. 登录凭据具有内置 WOL 页面的服务范围。

使用 全部范围 的凭据自动包含该入口；使用 自定义范围 时，需要在 认证配置 → 权限 中勾选 内置远程唤醒页面。具备该范围的用户可以唤醒设备，也可以关闭已启用 SSH 远程关机且当前显示在线的设备。隐藏传送门快捷入口不会删除设备，也不会影响管理员、Relay 或第三方平台触发，但会禁止通过公共认证 API 打开和操作该内置页面。

SSH 远程关机

先添加并保存目标设备，再编辑该设备并开启 SSH 远程关机。当前 fn-knock 会直接连接所填 SSH 主机，因此该地址必须从 fn-knock 运行环境可达，且不能指向 fn-knock 自己的本机地址。可选择 Linux、macOS 或 Windows，以及密码或 OpenSSH 私钥认证；建议为关机创建独立账号和专用私钥，不要使用日常管理员凭据。

配置顺序如下：

1. 在目标设备启用 SSH 服务，填写主机、端口、用户名和目标系统。
2. 选择认证方式并填写密码，或粘贴 OpenSSH 私钥及可选口令。
3. 给账号授予无交互执行固定关机命令的最小权限：Linux 使用 sudo -n /usr/bin/systemctl poweroff --no-block，macOS 使用 sudo -n /sbin/shutdown -h now，Windows 使用 shutdown.exe /s /t 0。
4. 点击 测试 SSH。测试会先读取并固定目标主机密钥指纹，再验证认证和关机权限，但不会执行关机。
5. 核对测试识别的主机后保存。以后主机地址、端口、用户名、系统或凭据变化时，应重新测试；主机密钥不一致会拒绝连接，而不是静默接管新设备。

设备显示在线且 SSH 配置完整时，管理页和具备 WOL 服务范围的内置页面会显示 关机。确认倒计时结束后才会发送命令；命令被 SSH 服务接受不等于操作系统已经关机，fn-knock 会继续复查在线状态。结果未知时不要立刻重复操作，同一设备的关机请求有短暂冷却时间。

密码、私钥和私钥口令保存在当前安装绑定的加密凭据目录中，不会通过设备读取接口返回。专用账号只应获准执行上述固定命令；不要授予交互式 root shell、任意 sudo 或不必要的网络登录范围。

跨网络 Relay

当目标设备与当前 fn-knock 不在同一广播域时，在目标网络也部署一台 fn-knock，并按以下顺序配对：

1. 在控制端进入 远程唤醒 → 跨网段，选择 添加远程网络，填写目标网络 fn-knock 的可达 IP。默认 UDP 端口为 40009。
2. 保存后立即复制以 FNW1. 开头的一次性配对码。
3. 在目标网络的 fn-knock 打开 远程唤醒 → 跨网段接收，粘贴配对码并启用。
4. 回到控制端执行 测试连接，再添加目标设备并把 唤醒路径 指向这个 Relay。

两台 fn-knock 之间必须存在可路由的 UDP 链路，可通过站点 VPN、受控端口映射或其他可信网络实现。路由器和主机防火墙需放行 Relay 的 UDP 端口；Docker 还要显式发布 UDP 端口，并确保容器能够向目标 LAN 发送广播。

配对码包含预共享密钥，只应通过可信通道传递。Relay 请求与 ACK 会进行签名、时间窗和重放检查；允许的来源 CIDR 可进一步限制控制端地址，但不能替代 PSK。重新生成配对码后旧密钥立即失效，目标端必须重新粘贴新码。两端系统时钟偏差过大时，Relay 会拒绝请求。

高级设置中的监听地址、广播目标和来源 CIDR 只适用于自动检测不符合 VLAN、容器或多网卡拓扑时。广播目标至少保留一项，通常使用目标网段的定向广播地址与 UDP 9 端口。

点灯科技与巴法云

编辑设备，在 第三方平台对接 中选择一个提供商。每台设备只能启用一个平台，连接状态会显示为连接中、已连接、重连中、凭据缺失或异常。

点灯科技（Blinker）

在点灯 App 创建独立网络设备，把设备密钥填入 fn-knock。启用 绑定 switch 组件 后：

• on 会触发唤醒；
• off 只回复当前在线状态，不会远程关机；
• 状态查询会返回 fn-knock 最近一次检测到的在线状态。

巴法云（Bemfa）

填写巴法云私钥和订阅主题。主题只允许字母、数字和下划线；需要被语音平台识别时，按巴法云约定使用以 001 或 006 结尾的主题。

• 收到 on 会触发唤醒；
• 收到 off 不会关机，只会向 {主题}/up 发布当前状态；
• 在线检测状态变化后也会向上行主题同步 on 或 off。

接入米家与小爱同学

完成点灯科技或巴法云配置，并确认设备已经连接后：

1. 打开米家 App，进入 我的 → 连接第三方平台。
2. 搜索 巴法 或 点灯，选择与 fn-knock 当前设备配置相同的平台并按提示添加。
3. 完成账号授权并同步设备，即可在米家 App 中触发唤醒，或通过小爱同学使用“打开”“开机”等指令唤醒设备。

米家和小爱同学发送的是第三方平台控制指令，其中“打开”会映射为 on 并触发 WOL；“关闭”不会远程关闭目标设备，只会按前述平台规则返回或同步当前状态。

两种集成都需要 fn-knock 主动访问提供商的 HTTPS 与 MQTT TLS 服务。不要公开设备密钥、私钥、主题或包含它们的截图。平台命令会绕过网关传送门页面，因此只应把平台账号和设备授权交给可信使用者。

事件、备份与迁移

每次唤醒完成都会写入 远程唤醒完成 事件，SSH 关机请求会写入 SSH 远程关机完成 事件；两者都记录目标、结果和延迟，可在事件中心创建通知规则。事件表示命令或广播流程的结果，不等同于设备已经完成开机或关机；应结合后续在线状态判断。

设备、Relay、SSH 非敏感字段和第三方集成设置属于应用配置。Relay PSK、SSH 密码或私钥、点灯设备密钥和巴法云私钥保存在当前安装绑定的加密凭据目录中，不包含在 .knock 应用备份里。迁移或恢复后应重新配对 Relay、重新填写并测试 SSH 与第三方凭据，并验证广播地址、设备 IP、端口和防火墙是否仍适用于新环境。

排错顺序

1. 在目标设备 BIOS/UEFI、网卡驱动和操作系统中确认 WOL 已开启，并先用同一 LAN 的其他工具测试。
2. 检查 MAC 是否正确；设备完全断电后确认网口仍亮灯。
3. 本机直连时检查定向广播地址。Docker 优先确认网络模式、UDP 广播可达性和宿主机防火墙。
4. 跨网络时先测试 Relay；检查 UDP 40009（或自定义端口）、路由、来源 CIDR、两端时钟和重新配对状态。
5. 广播成功但设备不启动时，问题通常在目标设备、交换机或广播路径，不要只反复点击唤醒。
6. 状态一直待检测时，确认设备 IP、ICMP、邻居表、跨 VLAN 路由或 Relay 状态检测是否可用。
7. 传送门没有入口时，检查功能开关、显示远程唤醒快捷入口 和凭据服务范围。
8. SSH 测试失败时，检查 fn-knock 到目标地址的路由和防火墙、SSH 服务、用户名与凭据、主机密钥变化，以及固定关机命令的无交互权限。
9. 第三方平台无响应时，查看连接状态和最近错误，确认出站 HTTPS / MQTT TLS、凭据和主题，再重新保存设备。

• 网关传送门
• 认证、会话与服务范围
• 事件中心与通知
• 备份、恢复与数据清理