结构化日志的长期维护：升级、备份与迁移的顺序

字段名不统一（uid/userId/user_id）会让查询条件永远写不全

把升级、备份、迁移这三件事流程化，才敢长期用。

先说结论

升级前先备份，备份后先演练恢复；不能回滚的升级不做。

• 固定版本，改动前记录当前版本号
• 升级前：备份数据 + 备份配置
• 升级后：验证核心功能，不只看进程
• 迁移：先迁数据，再迁流量
• 回滚方案写在纸上，别只存在脑子里

升级策略

trace_id 要在入口生成并透传，缺了它跨服务排查只能靠时间猜。

备份的三层

三层分别是：数据备份、配置备份、以及「能重建这台机器」的文档。缺第三层，前两层迟早用不上。

这个服务的几个维护事实

和它自身机制相关的几条：

• 时间戳统一用 UTC 毫秒，本地时区只在展示层转，能省掉一半对时问题
• trace_id 要在入口生成并透传，缺了它跨服务排查只能靠时间猜
• debug 全量打开时日志量能涨 5-10 倍，磁盘往往先满
• 把手机号、身份证写进日志，等于给自己造了一个合规问题

迁移的步骤

把手机号、身份证写进日志，等于给自己造了一个合规问题。

• 新机器按文档重建环境，验证空跑
• 同步数据，做一次一致性校验（条数、校验和）
• 切换前用 hosts 指向新机器验证
• 切换 DNS 或反代，保留旧机器一周
• 观察日志与错误率，再决定是否下线旧机

维护日历

每月：看磁盘与日志；每季：升级 + 备份校验；每半年：恢复演练一次；每年：清理不再需要的服务。

还有几处容易忽略的

都是小地方，但出问题时往往就卡在这里。

• 多行堆栈在容器日志里会被拆成多条，采集端要配 multiline 才能合回去
• 日志里拼中文句子，想按字段统计时只能正则硬抠
• 生产长期开着 debug，一周写满 200GB
• 异常只打 message 不打堆栈，出问题时不知道哪一行

长期维护的秘诀很土：每次只改一件事，改完就验证。