Go 1.25 runtime.SetCrashOutput 怎么接入故障留证：崩溃输出、轮转与恢复边界

线上服务最难补的一类证据，不是普通错误日志，而是进程已经准备退出时留下的最后一段堆栈。Go 1.25 继续提供 runtime/debug.SetCrashOutput，可以把未处理的 panic 和其他致命错误追加写到一个独立文件，同时保留标准错误输出。下面把它接进一个小型服务，让崩溃报告先落到 crash.log，再由监控进程归档，重点看清文件生命周期和“报告写完后程序仍然会退出”这个边界。

SetCrashOutput 适合做崩溃证据的第二出口，不是恢复机制，也不是替代结构化业务日志的采集器。文件句柄交给运行时后可以立即关闭，但轮转要在下一次启动或外部监控进程中完成。

先把故障留证的接口边界说清楚

SetCrashOutput(f, debug.CrashOptions{}) 配置的是一个额外的 crash 输出目标。它不会替换标准错误，也不会把普通 log.Printf 自动搬过去。调用再次发生时，新的目标会覆盖之前的目标；传入 nil 则关闭这个额外输出。

这个设计很适合“进程退出前留一份现场”的场景。它不适合用来承载高频业务日志，因为文件内容由运行时在崩溃路径上写入，应用没有机会给每条记录补订单号、租户号或自定义 JSON 字段。

从一个可写文件开始接入

package main

import (
    "log"
    "os"
    "runtime/debug"
)

func main() {
    crashLog, err := os.OpenFile("crash.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0600)
    if err != nil {
        log.Fatal(err)
    }
    if err := debug.SetCrashOutput(crashLog, debug.CrashOptions{}); err != nil {
        log.Fatal(err)
    }
    _ = crashLog.Close()

    panic("worker stopped unexpectedly")
}

这里的调用链是 debug.SetCrashOutput 把文件描述符交给运行时，运行时再把未处理的 panic 写入 crash.log。文档明确说明该函数会复制文件描述符，所以设置成功后关闭 crashLog 是安全的；不要因为关闭了变量就以为输出目标已经失效。

运行这个例子时，终端仍会看到 panic，当前目录还会留下 crash.log。进程不会因为配置了 crash 输出而自动恢复，退出码和服务拉起动作仍由外部进程管理。

轮转不要塞进已经崩溃的主进程

如果把轮转、压缩、上传都写在触发 panic 之后，通常来不及执行：未恢复的 panic 会让程序结束。更可靠的分工是让主进程只负责写入当前报告，让一个 monitor 进程负责读取、命名和归档。

func archiveCrash(report []byte) error {
    name := "crash-2026-08-27T21-40-00.log"
    return os.WriteFile(name, report, 0600)
}

func monitor() error {
    report, err := io.ReadAll(os.Stdin)
    if err != nil {
        return err
    }
    return archiveCrash(report)
}

生产代码可以让监控进程通过管道接收崩溃内容：monitor 读取标准输入，archiveCrash 写出带时间的归档文件。这里的时间名只是文件命名示例，真正的时间戳应由监控进程在收到报告时生成，避免主进程在退出路径上再做额外工作。

错误处理和兼容边界

SetCrashOutput 需要一个 *os.File。打开目录、只读文件或权限不足的目标时，应该在启动阶段直接失败，而不是等到真正崩溃后才发现没有证据。建议把报告目录的权限、磁盘空间和归档保留策略放进部署检查。

另一个容易误判的点是版本标题。这个 API 实际在 Go 1.23 中加入，Go 1.25 只是当前文章讨论的运行环境；如果项目还要兼容 Go 1.22，不能直接编译这段代码，应采用构建标签隔离实现，或把崩溃留证交给进程管理器。

运行时也可能在覆盖旧目标时与崩溃并发。官方说明这种情况下，旧文件仍可能收到已经开始的部分输出。因此轮转时不要原地截断同一个文件；让新进程打开新文件，旧文件在归档完成前保持只读更稳妥。

上线前用一个故障演练验收

1. 在与线上相同的用户和目录权限下启动服务，确认 crash.log 可以创建。
2. 主动触发一次未处理的 panic，确认终端仍有堆栈，且 crash.log 也有同一现场。
3. 启动 monitor，确认报告被写入归档文件，而不是覆盖上一份报告。
4. 连续演练两次，检查磁盘满、目录不可写和监控进程退出时的告警路径。

验收结果应该是“主进程确实退出、报告至少有一个可读副本、归档文件名可追踪”。如果测试只看服务是否自动恢复，就会把两个不同问题混在一起：恢复交给 supervisor、systemd 或容器编排；崩溃证据由 SetCrashOutput 和 monitor 负责。

相关问题

SetCrashOutput 会关闭标准错误吗？

不会。它增加一个额外的输出文件，标准错误仍然保留。

设置成功后可以关闭传入的文件吗？

可以，因为运行时会复制文件描述符。但关闭后不要再依赖这个 Go 文件变量进行普通写入。

它能让 panic 后的服务继续工作吗？

不能。它解决的是崩溃输出留证，进程恢复需要外部监督者重新启动。

把 SetCrashOutput 当作最后一道证据出口，接入会比较简单：启动时准备目标文件，配置成功后释放应用侧句柄，崩溃发生时由运行时写报告，再让 monitor 完成归档和告警。这样既不把重活压到退出路径，也不会把“留证”和“恢复”误认为同一件事。