190 lines
8.3 KiB
Markdown
190 lines
8.3 KiB
Markdown
# 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 部署稳定性，同时通过合理模块边界为后续平台扩展、检测器扩展与日志扩展保留空间。 |