设备自动化

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

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

自动化脚本直接在你的设备上运行。脚本所操作的软件、系统配置及其回滚由你负责；配置自动化不会关闭或替代 WideWired 的转发功能。

开始前

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

新建脚本

进入「配置 → 自动化」，在「脚本」区域选择「新建脚本」：

1. 填写名称和用途说明。
2. 选择运行平台和解释器。OpenWrt 使用 sh，Windows 使用 PowerShell；Linux 和 macOS 可选择 sh 或 bash。
3. 输入脚本内容，并设置默认超时。默认值为 60 秒，也可以改为其他时长或选择不超时。
4. 保存脚本。

编辑脚本内容会生成新的修订版本。之后触发的策略使用新版本，已有执行记录仍可对应到当时实际运行的版本。

新建策略

脚本保存后，在「策略」区域选择「新建策略」：

1. 选择要运行脚本的设备。
2. 选择执行阶段和脚本。列表只显示与设备平台兼容的脚本。
3. 按需填写参数，每行一个。脚本收到的参数顺序与这里的填写顺序一致。
4. 选择继承脚本超时、单独设置超时或不超时。
5. 保存并启用策略。

同一设备、同一执行阶段有多条策略时，使用「上移」和「下移」调整顺序。策略按显示顺序逐条运行；其中一条失败不会阻止后续策略。不同设备分别执行，彼此不会等待。

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

选择执行阶段

服务启动后

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

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

网络恢复连接

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

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

网络持续断连 30 秒

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

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

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

服务停止前

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

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

运行常驻组件

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

• Linux：systemd；
• OpenWrt：procd；
• macOS：launchd；
• Windows：Windows 服务管理器。

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

查看执行结果

点击自动化页面页头的「执行记录」，按时间倒序查看这个网络的全部执行，包括之后已被删除的策略留下的记录；可按策略与状态筛选。点击任意一条打开详情，其中显示状态、脚本版本、触发原因、开始和结束时间、退出码，以及分别捕获的 stdout 和 stderr。

策略行末尾的「执行记录 ›」打开同一列表，并已收窄到这条策略；策略筛选框显示当前范围，选「全部策略」即可放开。删除策略不会删除它的执行记录——记录仍可从页头入口找到，并标注「策略已删除」。列表达到服务端的条数上限时，会提示只显示了最近的若干条。

输出和记录有以下限制：

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

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

故障速查