使用帮助 - WOL 远程唤醒

快速入门 Web 控制台 C3 网关操作 PC 客户端扫码唤醒 SN 管理系统管理员功能技术架构常见问题

快速入门

WOL (Wake-on-LAN) 远程唤醒系统由 C3 网关硬件、云端平台 和 PC 客户端 三部分组成。C3 负责局域网唤醒信号转发和设备状态管理，云端负责用户认证和设备管理，PC 客户端负责心跳上报和指令接收。

1

给 C3 通电

C3 通过 USB 供电。首次使用自动开启 AP 模式，SSID 为 WOL-xxxx。用手机或电脑连接此 WiFi，浏览器打开 192.168.4.1 进入配网页。

2

配网

在 C3 配网页中选择家中/公司的 WiFi 并输入密码，C3 自动连接并重启。之后即插即用，无需再管。

3

安装 PC 客户端

电脑上安装 WOL PC 客户端。运行后自动发现局域网内的 C3 网关，同时弹出登录/注册窗口。

4

注册并绑定 SN

首次使用请切换到「注册」标签页，填写用户名、密码和 C3 机身标签上的 SN 序列号。注册成功后自动登录到云端控制台。

5

使用控制台

浏览器打开云端控制台（/dashboard.html），可管理设备、网关、查看操作记录等。PC 客户端自动最小化到系统托盘，每 10 秒发送心跳。

Web 控制台

登录后进入控制台，共 6 个标签页，覆盖设备/网关管理、SN 管理、操作审计、系统设置等。

📋 设备管理

设备列表：显示名称、IP、MAC、状态、所属网关、最近心跳时间
状态三态显示：在线（10s 内有心跳） / 软件异常（心跳超 90s 但 IP 可 Ping） / 离线（超 90s 且 Ping 不通）
操作按钮：开机（发送 WOL 魔术包）、关机（通过网关转发 UDP 指令）、删除设备
统计卡片：顶部显示总设备、在线、软件异常、离线数量
搜索筛选：按名称、IP 或 MAC 关键词搜索
15 秒自动刷新倒计时，也可手动刷新
快捷按钮：添加网关、添加设备、扫码唤醒

🌐 网关管理

网关列表：显示名称、状态（在线/离线）、本地 IP、MAC、SN、设备数、在线设备数、最后在线时间
添加网关：通过 SN 序列号或手动输入名称/地址绑定
重新生成 API Key：网关认证密钥，重置后需 C3 重启生效
删除网关：解除网关与所有关联设备的绑定
网关刚注册时显示欢迎/激活状态横幅
一台账号最多绑定 2 个网关（可联系管理员提升）

🔑 SN 管理

SN 列表：显示 SN 序列号、MAC、状态、绑定用户、网关、绑定时间
SN 状态：可用 / 已绑定 / 待审核 / 已作废
搜索 SN（按序列号关键词）
导出 SN 列表为 CSV
解绑流程：用户申请解绑 → 管理员审核（通过或驳回）
生成记录子标签页：显示本地生成历史记录，可导出或清空

📜 操作记录

审计日志：记录所有关键操作，包括登录、登出、开机、关机、添加/删除设备、注册等
每条记录显示：操作时间、操作类型、操作目标、客户端 IP
筛选：可按「全部」「开机」「关机」过滤
保存最近 200 条记录，翻页查看

👥 用户管理（管理员可见）

列出所有注册用户：ID、用户名、网关数、设备数、注册时间
删除非管理员用户（级联删除网关、设备、SN 绑定等所有关联数据）

⚙️ 系统设置（管理员可见）

动态读取和保存系统配置参数
可配置项包括：二维码默认有效期、PC 心跳超时秒数、WOL/关机命令过期时间等
保存后即时生效

👤 用户中心

点击右上角用户名弹窗
支持修改用户名、修改密码（需验证原密码）

C3 网关操作说明

首次配网

C3 出厂时无 WiFi 配置，上电后自动开启 AP 模式。手机连上后浏览器访问 192.168.4.1，设置管理密码 → 选择 WiFi → 连接。配网成功后 C3 自动重启，进入 STA 模式连接路由器。

本地 WebUI

C3 内置轻量 Web 服务器，浏览器访问 C3 的局域网 IP 即可进入。本地 WebUI 提供：

系统状态 — 运行时间、设备数、内存、WiFi 信号强度（RSSI）、SN、MAC
设备列表 — 本地管理的 PC 设备及其在线状态
事件日志 — 64 条环形缓存，记录心跳、命令执行、设备状态变化等
WiFi 扫描 — AP 配网模式下扫描附近 WiFi
OLED 控制 — 🔆 按钮切换息屏/点亮
系统操作 — 重启 C3、恢复出厂设置

OLED 显示

显示内容：SN、MAC、IP 地址、WiFi 状态（W=STA / AP 标识）、在线设备数/总数
每 2 秒刷新一次
WebUI 状态卡片右上角 🔆 按钮切换息屏/点亮

LED 状态指示灯

正常 — 1Hz 慢闪（约 1 秒亮 1 秒灭）
WiFi 断开 — 快速闪烁
空闲（无设备） — 极慢闪烁

BOOT 按键

短按：息屏/点亮切换（未启用时预留）
长按：恢复出厂设置（清空 WiFi、SN、设备列表并重启）

恢复出厂设置

访问 C3 本地 WebUI → 系统操作 → 恢复出厂设置。或在串口/API 调用 POST /api/config/reset。

看门狗

C3 内置 30 秒硬件看门狗，系统死锁时自动重启，确保长期运行不宕机。

PC 客户端说明

自动发现 C3

PC 客户端启动时自动广播 WOL-DISCOVER 到局域网 UDP 端口 8888，C3 会回复自身 IP、MAC 和 SN。无需手动填写网关地址。也支持通过命令行参数 --c3-ip 手动指定网关 IP。

登录与注册

客户端窗口有「登录」和「注册」两个标签页：

新用户：切到「注册」页，填写用户名、密码和 C3 的 SN → 注册成功自动登录
老用户：直接输入用户名密码登录
登录后自动绑定 PC 的 MAC 地址到云端，自动分配到所属网关

MAC 地址

客户端自动获取本机有线网卡 MAC 地址。也支持通过配置文件手动覆盖（mac_override）。MAC 用于云端设备识别和 WOL 唤醒包发送。

双重心跳

UDP 心跳 → C3 局域网（每 10 秒）：C3 据此管理本地设备在线状态
HTTPS 心跳 → 云端（每 10 秒）：云端据此维护设备状态

云端掉线不影响局域网唤醒，局域网掉线不影响云端记录。

云端职责

在线 — 10 秒内有 HTTPS 心跳，PC 客户端正常运行
软件异常 — 心跳超 90 秒但 IP 可 Ping 通（电脑没关机，客户端崩了），watchdog 会自动拉起
离线 — 心跳超 90 秒且 Ping 不通（电脑关机或断网）

命令拉取

客户端每 10 秒向云端拉取待处理指令（GET /api/pc/commands）。支持的命令：

shutdown — 执行系统关机（shutdown /s /t 0）
wake / wol — 发送 WOL 魔术包唤醒（客户端可唤醒局域网内其他设备）

UDP 关机监听

客户端监听 UDP 端口 8888，接收 C3 转发的关机指令。收到指令后自动执行系统关机。

HTTP 本地服务（端口 8889）

POST /shutdown — HTTP 关机接口
POST /wake — HTTP WOL 唤醒接口（需传 MAC）
GET /ping — 健康检查
GET / — 状态页面

调试模式

通过命令行参数 --debug 或托盘菜单「调试模式」开启。开启后所有开关机指令被弹窗拦截不真正执行，用于测试指令链路是否通畅。

系统托盘图标

绿色圆点 = 在线，灰色 = 离线
右键菜单：显示窗口、注销、退出

计划任务（崩溃保底）

安装时自动部署两个 Windows 计划任务：

WOL-RemoteShutdown — 远程触发安全关机
WOL-Client-Watchdog — 每 5 分钟检查客户端进程，崩溃自动拉起

配置持久化

登录 token、网关信息、调试开关等配置保存在 %APPDATA%/WOL-PC-Client/auth.json，重启后自动恢复登录状态。

📱 扫码唤醒

无需登录控制台，通过手机扫码即可远程唤醒或关闭电脑。

生成 QR 令牌

在控制台「设备」标签页点击「扫码唤醒」按钮
选择令牌有效期：30 分钟、1 小时、1 天、7 天（默认）、30 天、半年、一年
自动生成二维码图片和唤醒链接
将二维码截图分享给需要的人，或保存备用

扫码唤醒页

手机扫码后打开独立页面（/wake.html?token=xxx），无需登录即可：

查看令牌所属用户的所有设备（名称、IP、在线状态）
点击「唤醒」按钮发送 WOL 魔术包
点击「关机」按钮发送关机指令

令牌过期后页面友好提示「令牌无效或已过期」。生成的令牌仅限对应设备使用，不能操作其他用户的设备。

🔑 SN 管理系统

每台 C3 网关拥有唯一的 SN 序列号（产线烧录），新用户注册时必须输入 SN 才能完成注册。未购买硬件的用户无法注册。

SN 状态流转

状态	说明
可用	SN 未绑定，等待用户注册使用
已绑定	已被用户注册，绑定到特定 C3 网关的 MAC 地址
待审核	用户申请解绑，等待管理员审核
已作废	SN 被回收或作废，不可再使用

解绑流程

用户在控制台 SN 管理页面向管理员申请解绑（需填写原因）
管理员在 SN 管理页审核申请
通过：SN 释放回可用池；驳回：保持已绑定状态

二次烧录 SN 恢复

产线工具二次烧录同一台 C3（同 MAC 地址）时，自动查询云端恢复原来的 SN，不浪费号码。

🛡️ 管理员功能

用户管理

查看所有注册用户的 ID、用户名、网关数、设备数、注册时间
删除非管理员用户：级联删除该用户的所有网关、设备、SN 绑定、令牌、审计日志

SN 管理

查看全部 SN 统计：总数、可用、已绑定、待审核
生成 SN：设置数量和前缀，批量生成新 SN 序列号（每次最多 500 个）
审核解绑申请：通过或驳回用户的解绑请求
删除指定 SN（仅可用或已作废状态的 SN 可删除）
导出 SN 列表为 CSV
生成记录查看：本地历史记录导出/清空

系统设置

动态读写系统参数，包括：
qr_default_duration — 二维码默认有效期（默认 7d）
heartbeat_timeout_sec — PC 心跳超时秒数（默认 120）
cmd_expiry_wol_min — WOL 命令过期时间（默认 2 分钟）
cmd_expiry_shutdown_min — 关机命令过期时间（默认 5 分钟）
修改后即时生效

CLI 工具

服务器端命令行工具（php gen_sn.php）：

--batch 100 — 生成 100 个 SN
--input sn_mac.csv --api-url — 从 CSV 导入并写入数据库
--output out.csv — 导出 SN 列表
--list — 查看 SN 池状态统计

安装向导

首次部署时访问 /install.php，四步完成：环境检测 → 数据库配置 → 创建管理员 → 完成。安装后建议删除 install.php。

技术架构

整个系统分三端：PC 客户端（心跳上报 + 指令接收）、云端 API（认证 + 管理 + 命令队列）、C3 网关（局域网唤醒转发 + 本地设备管理）。

┌─ PC 客户端 ────────────────────────────────────┐
│ 登录/注册（SN 绑定） → 自动绑定 MAC             │
│ 局域网发现 C3（WOL-DISCOVER 广播）              │
│ UDP 设备心跳 → C3:8888                          │
│ HTTPS 云端心跳 → 云端 API                        │
│ 拉取云端指令（每 10s）                          │
│ UDP 关机监听（8888）                            │
│ HTTP 本地服务（:8889）                           │
│ Windows 计划任务（watchdog + 关机保底）          │
└──────┬────────────────────────────┬─────────────┘
       │ HTTPS                      │ UDP
       ▼                            ▼
┌─ 云端 API ──────────────────┐  ┌─ C3 网关 ─────────────────────┐
│ 用户注册/登录               │  │ UDP 心跳接收（:8888）         │
│ 设备 CRUD / 搜索            │  │ 设备状态机（在线/可疑/离线）  │
│ 网关管理（绑定/API Key）    │  │ WOL 魔术包发送（端口 9 & 7）  │
│ SN 分配/校验/解绑           │  │ 应答 WOL-DISCOVER 发现        │
│ PC 心跳 → 设备三态          │  │ 云命令轮询（每 10s，最长 60s）│
│ 命令队列（WOL/Shutdown）    │  │ 云端自心跳（每 120s）          │
│ QR 唤醒令牌                 │  │ 设备状态同步（每 60s）         │
│ 审计日志                    │  │ 本地 WebUI（:80）              │
│ 管理员/系统设置             │  │ OLED 显示 + 息屏控制          │
└─────────────────────────────┘  │ WiFi STA + AP 双模             │
                                 │ SN 恢复（MAC→云端查询）        │
                                 │ 看门狗 30s                     │
                                 └────────────────────────────────┘
    

通信协议

方向	协议	端口	频率	说明
PC → C3	UDP	8888	10s	设备心跳 + 在线状态上报
PC → C3	UDP	8888	启动时	WOL-DISCOVER 发现广播
C3 → PC	UDP	8888	按需	SHUTDOWN 关机指令
C3 → PC	UDP	9/7	按需	WOL 魔术包唤醒
PC → 云端	HTTPS	443	10s	心跳 + 状态上报 + MAC 绑定
PC → 云端	HTTPS	443	10s	拉取待执行指令
C3 → 云端	HTTPS	443	120s	C3 自心跳
C3 → 云端	HTTPS	443	10s	轮询待执行命令（长轮询）
C3 → 云端	HTTPS	443	60s	设备状态同步
C3 → 云端	HTTPS	443	启动时	IP 上报 + MAC 校验

认证机制

类型	方式	有效期
用户登录	Bearer Token（64 字符 hex）	72 小时
网关 API Key	gw_ 前缀 + 48 字符 hex，通过 X-API-Key 头传递	永久（可重��）
产线密钥	production_key（config.php 配置）	永久
限流	登录 5次/分钟，API 60次/分钟（按 IP 统计）	—

常见问题

C3 配网页进不去怎么办？

C3 出厂无密码保护，首次使用直接连上 AP 模式后访问 192.168.4.1 即可配网。如果已配过网，查看 C3 OLED 上显示的 IP 地址，浏览器直接访问该 IP 进入本地 WebUI。

设备显示「软件异常」是什么意思？

电脑还开着（IP 可 Ping 通），但 PC 客户端已崩溃或退出。系统每隔 90 秒自动验证一次，如果 PC 客户端被 watchdog 重启恢复，状态会自动变回在线。

PC 客户端连不上 C3？

确保 PC 和 C3 在同一个局域网。PC 客户端启动时会自动广播发现 C3。如果发现失败：①检查 C3 OLED 是否显示 IP 地址（已联网）②防火墙是否阻止了 UDP 8888 端口 ③可手动指定 --c3-ip 参数。

云端显示网关离线？

C3 每 120 秒向云端发送一次自心跳
检查 C3 是否已成功连接 WiFi（OLED 显示 IP 地址）
检查 C3 的 SN 是否已在控制台绑定到你的账号下
如刚绑定，等待 2 分钟内 C3 会自动上报
C3 看门狗 30 秒，死锁会自动重启

控制台显示「网络错误: failed to fetch」？

浏览器向服务器发��请求失败。常见原因：

SSL 证书问题：如果使用的是 Let's Encrypt Generation Y 证书，部分旧版移动浏览器可能不信任，联系管理员检查证书链或更换 CA
网络不通：检查设备网络连接，尝试刷新页面
跨域问题：前端和 API 域名不同，需服务器配置 CORS

C3 OLED 一直亮着，会不会烧屏？

不会。当前 OLED 采用常规显示，且 WebUI 提供 🔆 按钮手动息屏。后续固件将加入自动熄屏功能。

扫码唤醒的令牌安全吗？

令牌为随机生成的 64 字符 token，可设置有效期（最短 30 分钟，最长 1 年）。到期自动失效。令牌仅限操作令牌所属用户的指定设备。

产线工具二次烧录会浪费 SN 吗？

不会。二次烧录同一台 C3（同 MAC 地址），产线工具自动查询云端恢复原来的 SN。

最多可以绑定多少个设备？

每台 C3 网关可管理 200+ 台 PC（实际受路由器 ARP 表限制）。云端每账号默认最多绑定 20 台设备、2 个网关，可联系管理员调整。

PC 客户端崩溃了怎么办？

安装时自动部署了 WOL-Client-Watchdog 计划任务，每 5 分钟检查客户端进程，崩溃自动拉起。同时 WOL-RemoteShutdown 计划任务作为保底，即使客户端完全退出也能远程关机。