feat: add foreground mode, pause/resume commands, API docs
This commit is contained in:
191
API.md
Normal file
191
API.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# API Reference — Smart Network Shutdown Monitor
|
||||
|
||||
完整的 CLI 命令说明与参数参考文档。
|
||||
|
||||
> **注意：** 服务管理相关指令（`start`, `stop`, `restart`, `install`, `uninstall`）均需在**管理员 (Windows) / root (Linux)** 权限下执行。
|
||||
|
||||
---
|
||||
|
||||
## 服务生命周期
|
||||
|
||||
### `start`
|
||||
唤起并注册后台监控守护进程，服务将随系统开机自动启动。
|
||||
|
||||
```bash
|
||||
smart-shutdown start
|
||||
```
|
||||
|
||||
### `stop`
|
||||
停止当前运行的后台网络探测服务。
|
||||
|
||||
```bash
|
||||
smart-shutdown stop
|
||||
```
|
||||
|
||||
### `restart`
|
||||
重启后台服务（配置变更后需执行此命令以应用新配置）。
|
||||
|
||||
```bash
|
||||
smart-shutdown restart
|
||||
```
|
||||
|
||||
### `status`
|
||||
输出当前服务存活状态、载入的配置参数、日志存放路径及最近 10 条日志。
|
||||
|
||||
```bash
|
||||
smart-shutdown status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 安装与卸载
|
||||
|
||||
### `install`
|
||||
将可执行文件复制至系统目录并写入全局环境变量，同时注册为开机自启服务。
|
||||
|
||||
```bash
|
||||
smart-shutdown install
|
||||
```
|
||||
|
||||
### `uninstall`
|
||||
停止并注销后台服务，清理系统目录中的程序副本与环境变量。执行时将询问是否同时清除配置文件与日志。
|
||||
|
||||
```bash
|
||||
smart-shutdown uninstall
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 配置管理
|
||||
|
||||
### `config set <Key> <Value>`
|
||||
直接修改指定配置项，并执行合法性校验。改写后需执行 `restart` 使其生效。
|
||||
|
||||
```bash
|
||||
# 修改目标监控 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` 之一（或同时指定，以先到达的时间为准）。
|
||||
|
||||
```bash
|
||||
# 休眠 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 秒内）重新激活。
|
||||
|
||||
```bash
|
||||
smart-shutdown resume
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 前台临时监控模式
|
||||
|
||||
直接执行 `smart-shutdown`（不带子命令）可进入前台临时监控模式，日志将写入 `network_monitor_front.log` 与原后台日志隔离。
|
||||
|
||||
- 监控参数（`--target-ip` 等）未指定时，使用配置文件中的值。
|
||||
- **运行时长参数**（`--stop-after` / `--stop-at`）均未指定时，前台监控将**一直运行**，直到手动按 `Ctrl+C` 终止。
|
||||
|
||||
```bash
|
||||
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"` |
|
||||
|
||||
**使用示例：**
|
||||
|
||||
```bash
|
||||
# 临时将目标 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`
|
||||
联网拉取最新版本并热部署更新。
|
||||
|
||||
```bash
|
||||
smart-shutdown update
|
||||
```
|
||||
|
||||
### `--version` / `-V`
|
||||
查看当前版本号并拉取最新发布状态。
|
||||
|
||||
```bash
|
||||
smart-shutdown --version
|
||||
```
|
||||
|
||||
### `--verbose` / `-v`
|
||||
打印底层部署及环境追溯 Debug 信息（对所有子命令生效）。
|
||||
|
||||
```bash
|
||||
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 天。
|
||||
Reference in New Issue
Block a user