SimpleRemoter/docs/CrashProtection.md

崩溃保护与 MTBF 统计设计文档

概述

本文档描述服务端代理进程的崩溃保护机制和可靠性统计功能。

功能目标

1. 崩溃保护：防止代理进程连续崩溃导致的无限重启循环
2. 崩溃统计：记录崩溃次数、时间、退出代码等信息
3. MTBF 计算：收集数据用于计算平均故障间隔时间（Mean Time Between Failures）

---

一、崩溃保护机制

1.1 触发条件

参数	值	说明
窗口期	5 分钟	CRASH_WINDOW_MS = 300000
阈值	3 次	CRASH_THRESHOLD = 3
快速崩溃定义	30 秒内退出	FAST_CRASH_TIME_MS = 30000

触发逻辑：在 5 分钟窗口期内，代理进程发生 3 次快速崩溃（启动后 30 秒内异常退出），则触发崩溃保护。

1.2 判定标准

只有同时满足以下条件才计入崩溃：

• 退出代码 ≠ 0（正常退出不计入）
• 运行时间 < 30 秒（长时间运行后退出不计入）

设计原则：程序正常退出必须返回 0，任何非 0 退出代码都视为异常退出。包括：

• Windows 异常（如 0xC0000005 ACCESS_VIOLATION）
• 自定义错误码（如 1001 CONFIG_ERROR）
• 其他非零退出码

1.3 保护行为

触发崩溃保护后：

1. 服务停止自动重启代理进程
2. 写入 AgentCrashProtected = 1 到配置
3. 下次程序启动时检测到此标志，切换到普通运行模式
4. 弹出提示框告知用户

1.4 状态持久化

崩溃窗口状态持久化到注册表，确保服务重启后状态不丢失：

配置 section: [crash]

配置键	类型	说明
winCount	int	窗口期内崩溃次数
winStart	string (uint64)	窗口起始时间 (GetTickCount64)

服务重启时的恢复逻辑：

加载保存的状态
↓
检查 savedFirstCrashTime <= 当前时间？
├─ 否 → 系统重启过，清除状态
└─ 是 → 检查是否仍在 5 分钟窗口内？
         ├─ 否 → 窗口已过期，清除状态
         └─ 是 → 恢复状态，继续计数

注意：GetTickCount64() 在系统重启后会重置为 0，因此如果保存的时间戳大于当前时间，说明系统重启过，需要清除状态重新开始。

---

二、崩溃统计

2.1 记录内容

每次崩溃时记录以下信息（section: [crash]）：

配置键	类型	说明	示例
count	int	总崩溃次数	15
lastTime	string	最后崩溃时间	"2024-01-15 10:30:45"
lastCode	string	最后退出代码	"0xC0000005 (ACCESS_VIOLATION)"
lastRunMs	string (uint64)	最后运行时间(ms)	"25000"

2.2 退出代码描述

常见的 Windows 异常代码：

代码	描述
0xC0000005	ACCESS_VIOLATION（访问违规）
0xC0000094	INTEGER_DIVIDE_BY_ZERO（整数除零）
0xC00000FD	STACK_OVERFLOW（栈溢出）
0xC0000409	STACK_BUFFER_OVERRUN（栈缓冲区溢出）
0xC000001D	ILLEGAL_INSTRUCTION（非法指令）
0x80000003	BREAKPOINT（断点）

正常退出：

代码	描述
0	NORMAL（正常退出）

自定义错误代码（1000-1999）：

代码	描述
1001	CONFIG_ERROR（配置错误）
1002	NETWORK_ERROR（网络错误）
1003	AUTH_FAILED（认证失败）
1004	RESTART_REQUEST（请求重启）
1005	MANUAL_STOP（手动停止）

---

三、MTBF 统计

3.1 数据收集

配置键	类型	说明
starts	int	启动次数
totalRunMs	string (uint64)	累计运行时间(ms)
count	int	崩溃次数

注意：totalRunMs 和 lastRunMs 使用字符串存储 64 位整数，避免 32 位整数的限制（最大约 49 天）。

3.2 计算公式

MTBF（平均故障间隔时间）：

MTBF = 累计运行时间 / 崩溃次数

失败率（Failure Rate）：

失败率 = 崩溃次数 / 启动次数

3.3 示例

假设：

• 启动次数：100 次
• 崩溃次数：5 次
• 累计运行时间：30 天

计算结果：

• MTBF = 30 天 / 5 = 6 天（平均每 6 天发生一次崩溃）
• 失败率 = 5 / 100 = 5%（每次启动有 5% 概率崩溃）

---

四、回调函数设计

4.1 回调类型

回调	触发时机	参数
onAgentStart	代理进程启动成功	processId, sessionId
onAgentExit	代理进程退出（任何原因）	exitCode, runtimeMs
onCrash	检测到快速崩溃	exitCode, runtimeMs
onCrashWindowChange	崩溃窗口状态变化	crashCount, firstCrashTime
onCrashProtection	触发崩溃保护	无

4.2 调用顺序

正常退出：

onAgentExit(exitCode=0, runtime)

快速崩溃：

onAgentExit(exitCode, runtime)
    ↓
onCrash(exitCode, runtime)
    ↓
[如果 count >= 3]
onCrashProtection()
    ↓
onCrashWindowChange(count, startTime)

---

五、配置键汇总

Section: [crash]

配置键	类型	用途	持久性
count	int	总崩溃次数	永久
lastTime	string	最后崩溃时间	永久
lastCode	string	最后退出代码	永久
lastRunMs	string	最后运行时间	永久
totalRunMs	string	累计运行时间	永久
starts	int	启动次数	永久
winCount	int	窗口期崩溃次数	临时*
winStart	string	窗口起始时间	临时*
protected	int	崩溃保护标志	一次性**

* 临时：窗口期过期或系统重启后自动清除 ** 一次性：程序启动时读取并清除

---

六、文件改动

文件	改动内容
CrashReport.h	配置键定义、退出代码常量、MTBF 计算函数
ServerSessionMonitor.h	回调类型定义、监控器结构体
ServerSessionMonitor.cpp	崩溃检测逻辑、回调调用
ServerServiceWrapper.cpp	回调实现、状态持久化/恢复
2015Remote.cpp	启动时检查崩溃保护标志

---

七、使用场景示例

场景 1：连续崩溃

T=00:00  代理启动 (startCount=1)
T=00:05  代理崩溃 (crashCount=1, 窗口开始)
T=00:10  代理重启 (startCount=2)
T=00:15  代理崩溃 (crashCount=2)
T=00:20  代理重启 (startCount=3)
T=00:25  代理崩溃 (crashCount=3, 触发保护!)
         → 服务停止重启代理
         → 写入 AgentCrashProtected=1
T=00:30  用户手动启动程序
         → 检测到保护标志，切换到普通模式
         → 弹出提示框

场景 2：服务重启后恢复

T=00:00  代理崩溃 (crashCount=1)
T=00:30  代理崩溃 (crashCount=2, 保存到注册表)
T=01:00  服务重启（非系统重启）
         → 加载状态: count=2, elapsed=1分钟
         → 仍在5分钟窗口内，恢复状态
T=01:30  代理崩溃 (crashCount=3, 触发保护!)

场景 3：窗口过期

T=00:00  代理崩溃 (crashCount=1)
T=02:00  代理崩溃 (crashCount=2)
T=08:00  代理崩溃
         → 距离第一次崩溃已超过5分钟
         → 重置窗口: crashCount=1, 新窗口开始

---

八、设计决策记录

问题	决策	理由
窗口期时长	5 分钟，不可配置	足够检测连续崩溃，避免误判
崩溃阈值	3 次，不可配置	平衡敏感度和容错
快速崩溃定义	30 秒	覆盖大多数初始化场景
系统重启处理	清除窗口状态	系统重启后问题可能已修复
统计数据重置	暂不实现	需求不明确，后续按需添加
日志记录	使用 Mprintf	与现有日志系统一致
非零退出码	都算崩溃	正常退出必须返回 0
lastRunMs 类型	string (uint64)	支持超过 24 天的运行时间