smart-shutdown/API.md

API Reference — Smart Network Shutdown Monitor

完整的 CLI 命令说明与参数参考文档。

注意： 服务管理相关指令（start, stop, restart, install, uninstall）均需在管理员 (Windows) / root (Linux) 权限下执行。

---

服务生命周期

start

唤起并注册后台监控守护进程，服务将随系统开机自动启动。

smart-shutdown start

stop

停止当前运行的后台网络探测服务。

smart-shutdown stop

restart

重启后台服务（配置变更后需执行此命令以应用新配置）。

smart-shutdown restart

status

输出当前服务存活状态、载入的配置参数、日志存放路径及最近 10 条日志。

smart-shutdown status

---

安装与卸载

install

将可执行文件复制至系统目录并写入全局环境变量，同时注册为开机自启服务。

smart-shutdown install

uninstall

停止并注销后台服务，清理系统目录中的程序副本与环境变量。执行时将询问是否同时清除配置文件与日志。

smart-shutdown uninstall

---

配置管理

config set <Key> <Value>

直接修改指定配置项，并执行合法性校验。改写后需执行 restart 使其生效。

# 修改目标监控 IP 地址
smart-shutdown config set TargetIP 192.168.0.1

# 修改断网容忍时长（秒）
smart-shutdown config set MonitorWindowSeconds 300

# 修改关机倒计时缓冲（秒）
smart-shutdown config set ShutdownCountdown 60

# 修改探测发包间隔（秒）
smart-shutdown config set NormalPingInterval 15

可用配置项：

参数项	含义	默认值
TargetIP	目标 IPv4 地址，程序向其发送 ICMP 包检测联通性。	192.168.3.1
MonitorWindowSeconds	网络中断超出此时长（秒）则触发关机流程。	180
ShutdownCountdown	正式关机前的倒计时缓冲时间（秒）。	60
NormalPingInterval	网络正常时的探测发包间隔（秒）。	15

配置文件路径：

• Windows: C:\ProgramData\SmartNetworkMonitor\config.json
• Linux: /etc/smart-network-monitor/config.json

---

后台休眠控制

pause

向正在运行的后台守护进程发送休眠指令，后台停止发包但不启动前台监控。必须指定 --stop-after 或 --stop-at 之一（或同时指定，以先到达的时间为准）。

# 休眠 2 小时后自动唤醒
smart-shutdown pause --stop-after 2h

# 休眠至明早 8 点自动唤醒
smart-shutdown pause --stop-at "2026-03-25 08:00:00"

# 同时指定两个时间，取较早者
smart-shutdown pause --stop-after 3h --stop-at "2026-03-25 08:00:00"

Flag	说明	格式示例
--stop-after	休眠时长，到期自动唤醒。	30m, 2h, 1h30m
--stop-at	休眠至指定绝对时间自动唤醒。	"2026-03-25 08:00:00"

resume

立即撤销休眠指令，后台将在下一轮探测周期（约 15 秒内）重新激活。

smart-shutdown resume

---

前台临时监控模式

直接执行 smart-shutdown（不带子命令）可进入前台临时监控模式，日志将写入 network_monitor_front.log 与原后台日志隔离。

• 监控参数（--target-ip 等）未指定时，使用配置文件中的值。
• 运行时长参数（--stop-after / --stop-at）均未指定时，前台监控将一直运行，直到手动按 Ctrl+C 终止。

smart-shutdown [flags]

Flag	说明	示例
--target-ip	临时覆盖目标监控 IP	--target-ip 8.8.8.8
--window-sec	临时覆盖断网容忍时长（秒）	--window-sec 60
--shutdown-cnt	临时覆盖关机倒计时（秒）	--shutdown-cnt 10
--ping-interval	临时覆盖探测发包间隔（秒）	--ping-interval 5
--override-bg	挂起后台守护进程，由前台全面接管，退出时自动恢复后台	--override-bg
--stop-after	前台运行指定时长后自动退出	--stop-after 2h30m
--stop-at	前台运行至指定时间自动退出	--stop-at "2026-03-25 08:00:00"

使用示例：

# 临时将目标 IP 改为 8.8.8.8，60 秒无响应触发
smart-shutdown --target-ip 8.8.8.8 --window-sec 60

# 接管后台，30 分钟后自动退出并恢复后台
smart-shutdown --override-bg --stop-after 30m

# 接管后台，运行至明早 8 点自动退出并恢复后台
smart-shutdown --override-bg --stop-at "2026-03-25 08:00:00"

---

其他

update

联网拉取最新版本并热部署更新。

smart-shutdown update

--version / -V

查看当前版本号并拉取最新发布状态。

smart-shutdown --version

--verbose / -v

打印底层部署及环境追溯 Debug 信息（对所有子命令生效）。

smart-shutdown status --verbose

---

日志文件位置

场景	Windows	Linux
后台服务日志	C:\ProgramData\SmartNetworkMonitor\logs\network_monitor.log	/var/log/smart-network-monitor/network_monitor.log
前台临时监控日志	C:\ProgramData\SmartNetworkMonitor\logs\network_monitor_front.log	/var/log/smart-network-monitor/network_monitor_front.log

程序按日自动切割日志，默认保留最近 30 天。