Init: Migrate SimpleRemoter (Since v1.3.1) to Gitea
This commit is contained in:
yuanyuanxiang
272
docs/CrashProtection.md
Normal file
272
docs/CrashProtection.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# 崩溃保护与 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 天的运行时间 |
|
||||
Reference in New Issue
Block a user