自定义 Panic Hook：在系统崩溃时优雅捕获堆栈并持久化日志

自定义 Panic Hook：在系统崩溃时优雅捕获堆栈并持久化日志

在开发基于终端全屏 UI（如 ratatui + crossterm）的复杂系统工具时，最糟糕的用户体验莫过于：程序发生了一个未预期的 Panic，由于终端当时正处于原生裸模式（Raw Mode）和备用屏幕（Alternate Screen）中，Panic 堆栈信息直接与终端 ANSI 转义字符混杂在一起，导致整个终端控制台彻底花屏、键盘输入无响应，用户甚至无法看清崩溃的具体原因，只能强行关闭终端窗口。

此外，在生产环境部署的常驻守护进程中，一旦进程发生非正常 Panic 崩溃，崩溃现场的线程 ID、发生崩溃的代码行号以及调用栈信息如果仅仅打印在已关闭的控制台上，运维和开发人员将永远丢失事故现场的第一手线索。

为了彻底解决这一问题，Rust 标准库提供了 std::panic::set_hook 机制。今天这篇文章，我们来实战封装一个生产级的 自定义 Panic Hook 处理器，实现终端安全恢复与崩溃日志自动落盘归档。

1. 默认 Panic 行为与终端 TUI 的冲突

在全屏 TUI 模式下：

1. crossterm 开启了 enable_raw_mode() 并进入了备用屏幕 EnterAlternateScreen；
2. 如果此时代码发生 Panic，默认的 Panic 处理器会直接将文字输出到 stderr；
3. 但由于终端未退出 Raw Mode，换行符不会被正确解释为 \r\n，且退出备用屏幕的指令未被执行，最终导致整个终端处于“半瘫痪假死状态”。

[ 发生未捕获的 Panic! ] ──> 触发 std::panic::set_hook 注册的自定义闭包
                                    │
                                    ├─ 1. 紧急恢复终端: disable_raw_mode / LeaveAlternateScreen
                                    ├─ 2. 捕获完整 Backtrace 与线程崩溃元数据
                                    ├─ 3. 将详细 Crash Report 异步或同步落盘至 crash.log
                                    └─ 4. 在干净的标准控制台上输出对人类友好的排障指引

2. 编写生产级 Panic 处理器模块

在 crates/packet-core/src/panic_hook.rs 中完整实现：

// crates/packet-core/src/panic_hook.rs
use crossterm::{
    execute,
    terminal::{disable_raw_mode, LeaveAlternateScreen},
};
use std::backtrace::Backtrace;
use std::fs::OpenOptions;
use std::io::{stderr, Write};
use std::panic::{self, PanicInfo};
use std::path::PathBuf;
use std::time::SystemTime;

pub struct CrashReporter;

impl CrashReporter {
    /// 初始化并注册全局 Panic Hook
    pub fn setup_panic_hook(log_dir: Option<PathBuf>) {
        let default_log_path = log_dir.unwrap_or_else(|| PathBuf::from("crash_dumps"));

        panic::set_hook(Box::new(move |panic_info: &PanicInfo| {
            // 步骤一：最高优先级——恢复终端原始状态，防止花屏！
            let mut stdout = stderr();
            let _ = disable_raw_mode();
            let _ = execute!(stdout, LeaveAlternateScreen);

            // 步骤二：提取崩溃元数据
            let timestamp = SystemTime::now();
            let thread_info = std::thread::current();
            let thread_name = thread_info.name().unwrap_or("unnamed_worker");

            let payload_msg = if let Some(s) = panic_info.payload().downcast_ref::<&str>() {
                s.to_string()
            } else if let Some(s) = panic_info.payload().downcast_ref::<String>() {
                s.clone()
            } else {
                "未知 Panic 负载类型".to_string()
            };

            let location_str = if let Some(loc) = panic_info.location() {
                format!("{}:{}:{}", loc.file(), loc.line(), loc.column())
            } else {
                "未知代码位置".to_string()
            };

            let backtrace = Backtrace::force_capture();

            // 步骤三：格式化完整的崩溃报告
            let crash_report = format!(
                "================================================================================\n\
                 PACKET ANALYZER CRASH REPORT\n\
                 时间: {:?}\n\
                 崩溃线程: [{}]\n\
                 触发位置: {}\n\
                 Panic 原因: {}\n\
                 --------------------------------------------------------------------------------\n\
                 调用栈追踪 (Stack Backtrace):\n\
                 {}\n\
                 ================================================================================\n",
                timestamp, thread_name, location_str, payload_msg, backtrace
            );

            // 步骤四：持久化落盘至本地文件
            if let Ok(_) = std::fs::create_dir_all(&default_log_path) {
                let log_file = default_log_path.join(format!("crash_{}.log", std::process::id()));
                if let Ok(mut file) = OpenOptions::new().create(true).append(true).open(&log_file) {
                    let _ = file.write_all(crash_report.as_bytes());
                    let _ = file.flush();
                }
            }

            // 步骤五：在控制台输出优雅的对人类友好的提示
            eprintln!("\n 很抱歉，PacketAnalyzer CLI 遇到了未处理的内部异常并已安全终止。");
            eprintln!(" 崩溃原因: {}", payload_msg);
            eprintln!(" 发生位置: {}", location_str);
            eprintln!(" 完整诊断报告已持久化归档至目录: {:?}", default_log_path);
            eprintln!(" 请在 GitHub Issues 提交报告以帮助我们修复此问题。\n");
        }));
    }
}

3. 在主程序入口一行代码优雅接入

在 src/main.rs 的首行完成 Hook 挂载：

// src/main.rs
use packet_core::panic_hook::CrashReporter;
use std::path::PathBuf;

fn main() -> anyhow::Result<()> {
    // 必须在任何 TUI 初始化或异步运行时启动之前完成注册！
    CrashReporter::setup_panic_hook(Some(PathBuf::from("./logs/crashes")));

    // 接下来正常启动 TUI 与抓包引擎
    run_app()?;
    Ok(())
}

fn run_app() -> anyhow::Result<()> {
    // 业务代码
    Ok(())
}

4. 模拟测试与实测效果

为了验证该 Hook 的鲁棒性，我在一个深层异步子任务中故意构造了一个除以零的 panic!：

// 触发测试
std::thread::spawn(|| {
    let zero = 0;
    let _ = 100 / zero;
}).join().unwrap();

运行效果：

1. 终端瞬间安全退出了全屏备用屏幕，没有任何花屏或字符错乱；
2. 控制台输出了清晰友好的提示；
3. 打开 ./logs/crashes/crash_84120.log，里面工整地记录了崩溃发生时的线程名、精确行号以及几十级深度带有源代码路径的符号栈追踪。

总结

自定义 Panic Hook 是系统级 CLI 工具专业性的体现：

• 保障终端环境安全：无论内部怎么崩溃，始终确保终端状态 100% 恢复；
• 事故现场数据固化：在进程死亡前的最后微秒，将不可复现的 Panic 堆栈精准落盘；
• 提升开发者与用户体验：把冷冰冰的未定义崩溃，转化为规范、可溯源的排障工单。