watchdog/docs/prd.md

Watchdog 项目 PRD

1. 项目概述

本项目目标是实现一个运行于 Linux 平台的守护型看门狗程序，用于监控一个或多个目标程序的运行状态，并在目标程序异常退出、未启动或持续不稳定时，按照预定义策略执行重启与回退。该程序首先服务于 Linux arm64 部署场景，要求支持在 x64 开发环境中交叉编译到 arm64 设备运行。系统设计时需保留未来扩展到 Windows 的可能，但第一版本不承担 Windows 兼容实现。

该项目不负责业务程序本身的逻辑，不承担升级平台、远程编排、图形界面或复杂运维平台职责。其定位是一个本地进程守护与回退执行器，提供稳定、可预测、可测试的最小核心能力。

2. 项目目标

第一版本的核心目标如下：

1. 支持监控多个目标程序。
2. 支持通过轮询方式检测程序是否处于有效运行状态。
3. 支持在目标程序未运行时自动拉起。
4. 支持对频繁崩溃或持续启动失败的程序执行 fallback。
5. fallback 顺序固定，但每一级 fallback 的目标内容由配置指定。
6. fallback 为临时运行时切换，不持久化到磁盘。
7. 支持固定 CLI 子命令执行。
8. 支持 stdout/stderr 日志输出。
9. 支持单元测试，保证核心状态机与策略逻辑可验证。

3. 非目标

第一版本明确不做以下内容：

• 不支持任意 shell 指令编排。
• 不支持动态插件系统。
• 不支持配置热更新。
• 不支持远程管理与网络 API。
• 不支持安装包管理、升级平台和复杂版本治理。
• 不支持集成测试框架自动化，仅要求单元测试。
• 不支持所有极端失败场景的复杂恢复决策；若最终 fallback 目标仍无法启动，则系统持续尝试最后一级 fallback 即可。

4. 核心业务场景

4.1 目标程序未启动

看门狗轮询检测目标程序状态；若检测失败，系统尝试执行该目标当前激活版本的启动命令。

4.2 目标程序启动后短时间退出

若程序启动后未达到“稳定运行判定窗口”，则该次行为视为启动失败，不计入 crash。

4.3 目标程序稳定运行后退出

若程序已连续存活至少 5 秒，再发生退出，则视为一次 crash 事件。看门狗根据配置统计检测窗口内 crash 次数，达到阈值后触发 fallback。

4.4 目标程序持续不稳定

当一个目标在给定检测窗口内达到阈值，例如默认 1 分钟内 3 次 crash，则切换到固定顺序中的下一级 fallback 目标。

4.5 fallback 已触发

一旦某目标切换到 fallback，除非整个 watchdog 进程重启，否则不主动恢复到主目标。系统继续守护当前 fallback 目标；若仍失败，则继续向后切换，直到最终 fallback 目标。最终 fallback 目标若仍无法启动，则持续尝试该最终目标。

5. 功能需求

5.1 多目标监控

系统需支持多个目标程序并发受管。第一版本允许采用单线程轮询模型，即每一轮按顺序遍历所有目标，分别执行检测、重启和 fallback 决策。每个目标需维护独立运行状态，互不影响。

5.2 启动方式

所有目标及 fallback 均采用 exec 方式启动。即配置明确给出：

• 可执行文件路径
• 参数列表
• 可选工作目录

第一版本不通过 shell 解释器启动，不依赖 sh -c 或类似方式，以降低转义复杂度、不确定性和命令注入风险。

5.3 检测机制

检测机制采用“provider + 配置项”的方式实现。第一版本不构建高度抽象的通用组合 DSL，而是定义若干固定检测方法，每个方法对应明确配置字段。一个目标可配置多个检测方法；所有检测方法均通过时，视为目标当前健康。

已确认需要支持或预留的检测维度包括：

• 进程是否存在
• 程序文件是否存在
• PID 文件是否存在
• 指定文件是否存在

“检测程序是否存在”属于检测条件之一，不等同于进程是否存在。

5.4 稳定运行与 crash 判定

系统需定义稳定运行窗口。当前约定为 5 秒：

• 启动后若存活不足 5 秒即退出，视为启动失败。
• 启动后若连续运行至少 5 秒再退出，视为 crash。

看门狗需统计检测窗口中的 crash 事件次数。默认策略为“1 分钟内 3 次 crash 触发 fallback”，该阈值与窗口长度应允许通过配置覆盖。

5.5 fallback 机制

fallback 顺序固定，第一版本定义为：

1. 主目标
2. 上一个版本
3. 更新后的出厂版本
4. 出厂版本

配置文件负责指定每一级实际启动目标，不负责改写顺序。fallback 的本质是运行时切换当前激活目标，不修改持久化配置、不覆盖原始程序文件、不执行安装动作。切换后仅影响当前 watchdog 生命周期内的行为。

5.6 CLI 子命令

程序需支持固定 CLI 子命令。第一版本至少应考虑以下命令集合：

• run：启动 watchdog 主循环
• check：执行一次检测
• start：手动启动指定目标
• check-env：检测运行环境

是否进一步开放 fallback 相关手工命令可在后续迭代决定，但不作为第一版本必需能力。

5.7 日志

第一版本日志输出目标为 stdout/stderr。日志需要覆盖以下关键信息：

• watchdog 启动与退出
• 每个目标的检测结果
• 启动尝试
• 启动失败
• 稳定运行判定通过
• crash 事件记录
• fallback 切换
• 最终 fallback 持续尝试

后续如需写文件或接入 journald，应通过独立日志层扩展，而不影响核心状态机。

5.8 测试

必须提供单元测试，覆盖以下核心逻辑：

• 启动成功与启动失败判定
• 稳定运行 5 秒后的 crash 判定
• 检测窗口内 crash 计数
• fallback 触发阈值
• fallback 顺序推进
• 多目标状态相互隔离

6. 状态机要求

每个目标必须维护独立状态。最少应包含以下运行态信息：

• 当前激活层级（主目标或某一级 fallback）
• 当前进程状态
• 最近一次启动时间
• 是否已达到稳定运行门槛
• 检测窗口内 crash 记录
• 当前是否处于 fallback 模式

watchdog 主循环根据检测结果和状态决定下一步动作：

1. 检测通过：保持当前状态。
2. 检测失败且当前无进程：尝试启动当前激活目标。
3. 启动后未满 5 秒退出：记为启动失败。
4. 启动后满 5 秒退出：记为一次 crash。
5. crash 在窗口内达到阈值：切换到下一级 fallback。
6. 已在最终 fallback：持续尝试最终 fallback，不再设计额外终止分支。

7. 架构原则

第一版本应坚持以下架构原则：

• Linux 优先，接口设计与平台实现分离，为未来 Windows 预留空间。
• 业务状态机与系统调用分离。
• 检测器、启动器、fallback 决策解耦。
• 多目标共享框架、独立状态。
• 配置驱动目标定义，避免业务逻辑硬编码。
• 第一版本优先简单可维护，不提前引入过度抽象。

8. 实施计划

阶段一：基础框架

完成项目骨架、CLI 入口、日志初始化、配置加载与最小多目标数据模型。

阶段二：核心运行闭环

实现目标轮询、exec 启动、基础检测器、稳定窗口判定、crash 记录。

阶段三：fallback 机制

实现固定顺序 fallback、目标切换、最终 fallback 持续尝试。

阶段四：测试与部署

补充关键单元测试，完善 x64 到 arm64 musl 交叉编译与部署脚本。

9. 成功标准

第一版本交付时，应满足以下标准：

1. 能在 Linux arm64 目标机上稳定运行。
2. 能同时监控多个目标程序。
3. 能对未启动程序自动拉起。
4. 能识别“启动失败”和“稳定运行后 crash”。
5. 能在检测窗口内依据 crash 次数触发 fallback。
6. 能按照固定顺序切换 fallback 目标。
7. 能输出足够定位问题的日志。
8. 核心状态机具备单元测试覆盖。

10. 结论

该项目第一版本定位为一个本地、轻量、配置驱动的多目标 watchdog。其核心价值在于以明确、稳定、低复杂度的方式实现进程守护、稳定性判定与临时 fallback 切换。设计上应优先保证 Linux 场景落地与 arm64 部署稳定性，同时通过合理模块边界为后续平台扩展、检测器扩展与日志扩展保留空间。