统一告警与日志轮转法
一、适用场景
凡是"吞异常"的容错点——except 块、后台线程、外部调用（Ollama/文件 IO/网络）——都必须留痕，且本机日志不能无限膨胀把磁盘撑爆。本系统是纯标准库零依赖，不能引第三方日志库，需要一个自带的、永不抛异常的告警出口。
二、操作步骤
- 在容错点调用
logutil.warn(where, exc=exc)或logutil.warn(where, note='说明')；where写"模块.函数"便于定位。 - 日志单文件上限
MAX_BYTES = 2*1024*1024（2MB），超限自动os.replace(p, p+'.1')轮转，不堆积历史。 - 双写：先写
sys.stderr（实时可见），再追加写config.LOG_PATH（落盘持久）。 - 单条明细截断
MAX_DETAIL = 200字符，异常信息里的长路径/长串不刷屏。 - 写日志本身包在
try/except Exception: pass中——写日志的动作永不抛异常，否则会掩盖原故障。
三、代码锚点
logutil.pyL11MAX_BYTES、L12MAX_DETAIL- L15
def warn(where, exc=None, note='') - L20-24 stderr 双写 + 吞异常
- L26-33 目录自动建 + 2MB 轮转
os.replace+ 追加写 - 落盘路径来自
config.LOG_PATH
四、注意边界
- 不写 traceback（只写
类型: 信息），避免一次异常刷几千行日志。 - 不要在 hot path 高频
warn却不节流，会拖慢主流程。 where必须能反向定位到代码，否则留痕无意义。
五、反例避雷
- ❶ 吞异常后静默
pass不记日志 → 故障不可查，排错靠猜。 - ❷ 用
print代替落盘日志 → 服务重启/后台线程丢失，事后无据。 - ❸ 异常信息不截断 → 单条撑爆日志、轮转频繁。
六、关联笔记
- 上层纪律：吞噬异常统一留痕治理法（04 开发）——规定哪些点必须留痕。
- 本方法是它的"底层出口实现"。
七、实战战绩 / 版本记录
- 全系统容错点统一接入
logutil.warn，stderr + 本机日志双写，2MB 自动轮转。 - v1.0.0（2026-10-03）：
logutil.py入栈归档。
