# 自动化

> 在设备启动、连接变化和停止时运行脚本，并通过执行记录查看结果。

来源: https://www.widewired.com.cn/page/docs/automation

## 开始前

设备自动化让脚本在指定设备进入关键执行阶段时自动运行。它适合初始化系统配置、启动或停止第三方组件、在网络恢复后刷新配置，以及在持续断网后执行告警或降级操作。

自动化脚本直接在你的设备上运行。脚本所操作的软件、系统配置及其回滚由你负责。

- 只有账号所有者可以管理自动化。
- 自动化只在 Linux（含 OpenWrt）和 Windows 设备上运行；macOS、iOS、Android 和 HarmonyOS 设备不运行自动化脚本。
- 脚本使用 `wwnet` 后台服务的权限运行，通常拥有管理员或系统权限。请先在非关键设备上验证，再逐步应用到生产设备。
- 建议让脚本具备幂等性，使同一事件再次发生时可以安全地重复执行。
- 不要在脚本、参数或输出中写入密码、API 密钥等敏感信息。

## 添加脚本

进入「配置 → 自动化」，打开目标设备，在相应执行阶段选择「添加脚本」：

1. 选择解释器。OpenWrt 使用 `sh`，Windows 使用 PowerShell；Linux 可选择 `sh` 或 `bash`。
2. 输入脚本内容，设置超时或选择不超时；默认超时为 60 秒。
3. 设置启用状态并保存，脚本追加到该设备、该阶段的队尾；取消会放弃尚未保存的输入。

保存后，核对脚本位于正确设备和阶段且已启用。脚本在下次进入该阶段时执行，保存本身不会立即运行；事件发生后，在执行记录核对结果。

## 编辑与排序

脚本块中的解释器、超时、启用状态和内容可就地编辑；保存内容会生成新的修订版本，历史执行记录仍对应当时实际运行的版本。

同一阶段拖动脚本块的拖柄调整顺序；键盘可按空格选中、方向键移动、空格放下。脚本按显示顺序逐条运行；一条失败不会阻止后续脚本。不同设备分别执行，彼此不会等待。

设备进入新的执行阶段时，上一阶段尚未完成的脚本会被取消。不要让两个阶段依赖同时运行。

## 选择执行阶段

### 服务启动后

`wwnet` 后台服务完成一次新启动并取得当前网络配置后触发。设备在服务已经运行时加入网络，不会补执行这次启动脚本。

适合检查依赖、生成本机配置，或启动由系统服务管理器托管的第三方组件。

### 网络恢复连接

设备首次与任意其他设备建立可用连接时触发；设备曾经与所有其他设备断开，并在断连事件确认后重新连上任意一台设备时也会触发。

网络抖动后如果在 30 秒内恢复，只会取消尚未触发的断连事件，不会再次运行连接脚本。

### 网络持续断连 30 秒

设备曾经至少连接过一台其他设备，之后与所有其他设备的连接连续不可用 30 秒时触发。30 秒内恢复连接则不触发。

以下情况不会触发断连脚本：

- 服务启动后一直没有连接过其他设备；
- 仍有至少一台其他设备保持连接；
- 主动停止或重启服务、更新或回滚、离开网络、从控制台移除设备或卸载软件。

### 服务停止前

正常停止或重启服务、更新或回滚、离开网络、从控制台移除设备，以及卸载软件时触发。停电、系统崩溃或进程被强制终止时，停止脚本无法运行。

所有停止脚本共用最多 5 秒的退出等待时间，之后仍在运行的脚本会被强制终止。停止阶段适合快速保存状态或通知系统服务管理器停止组件，不适合执行耗时任务。

## 运行常驻组件

自动化脚本适合完成一次操作后退出。如果第三方组件需要长期运行，请让脚本通过操作系统的服务管理器安装、启动或停止它：

- Linux：systemd；
- OpenWrt：procd；
- Windows：Windows 服务管理器。

不要使用 `setsid` 等方式让脚本子进程脱离本次执行，否则 WideWired 无法在超时、取消策略或服务退出时正确清理它。

## 查看执行结果

点击设备自动化页面顶部的「全部执行记录」，按时间倒序查看该设备的执行，包括已删除脚本留下的记录。可按策略与状态筛选；打开一条记录可查看状态、脚本修订、触发原因、开始和结束时间、退出码，以及 stdout 和 stderr。

脚本块的执行记录入口会带上当前策略筛选。选择「全部策略」可恢复该设备全部记录；删除策略不会删除其保留期内记录，页面标注「策略已删除」。达到行数上限时会提示仅显示最近记录。

输出和记录有以下限制：

- stdout 和 stderr 各保留开头最多 256 行、4 MiB；
- 单行最多保留 16 KiB；
- 每条策略保留最近 30 天内最多 100 次执行记录；
- 单台设备启用的策略及其脚本内容合计最多 512 KiB，超过时控制台会拒绝保存。

脚本应把简短、可操作的信息写入输出。大量日志请交给第三方组件自身的日志系统管理。

## 故障速查

| 现象 | 检查与处理 |
| --- | --- |
| 脚本没有启动 | 确认策略已启用、设备与脚本平台匹配，并核对设备是否实际进入了所选执行阶段 |
| 断连脚本没有运行 | 确认设备此前连接过其他设备，并且所有连接连续中断已超过 30 秒；主动停止等操作不会触发断连脚本 |
| 执行记录显示已取消 | 设备进入了新的执行阶段，或后台服务已经开始退出 |
| 执行记录显示超时 | 缩短脚本执行时间，或在确认风险后调整脚本或策略的超时设置 |
| 输出内容提前结束 | 检查每个输出流 256 行、4 MiB及单行 16 KiB 的限制，并将大量日志写入组件自己的日志系统 |
| 停止脚本被强制终止 | 所有停止脚本共用 5 秒等待时间；缩短脚本，或让系统服务管理器处理耗时的停止工作 |