开源项目日志，别只记版本号

开源项目日志这件事，最容易糊弄自己。装完一个开源项目，跑起来了，随手在文档里写一行「v2.3.1，正常」，然后关掉窗口去打游戏或者干别的活去了。三个月以后项目挂掉，你打开那行字，除了知道当时装的是哪个版本，什么信息都没有。配置文件改过哪里？数据库是本地还是远程？那台机器上还装着别的什么服务？全忘了。

开源项目日志最容易漏的是什么

不是版本号，是环境。版本号反而是最不值钱的那条，因为 go.mod、package.json、requirements.txt 这些文件本来就把依赖锁死了，你翻仓库比翻日志还快。真正会丢的是环境：操作系统哪个发行版、什么内核、装了哪几个系统级依赖、端口被谁占了、防火墙怎么配的、反向代理在哪一层做的。

我见过太多人把日志写成变更记录，只写「升级了数据库」。升级到哪个版本？有没有跑迁移脚本？升级前的备份放哪了？这仨问题任何一个答不上来，回滚就是一场灾难。日志的作用不是证明你干过活，是让未来的你能在二十秒内还原当时的现场。

日志记什么：三行就够，别写作文

我自己的习惯是每次动开源项目就记三行。第一行写时间加动作，第二行写改了什么文件或者什么配置，第三行写验证结果——不是「应该没问题」，是你实际敲了什么命令、看到了什么输出。比如「curl 本地 8080 返回 200」这种，比「服务正常」有用一百倍。

三行真的够。写多了反而没人看，最后日志变成装饰品。有人喜欢在日志里抄整段配置，那更糟，因为配置一改日志就过期了，过期日志比没日志更害人——它会给你错误的确定感。

顺带说一句，日志和备份是两码事。日志记「我做了什么」，备份是「出事了能退回去」。这俩经常被混在一起聊，实际上缺一个都不行。备份放在哪、保留几份、多久验证一次能恢复，这些也应该进日志，但别把备份文件本身当成日志。

版本号之外，还有一条时间线要留

开源项目最坑的地方不在装，在升级。你今天拉的 main 分支能跑，下个月别人拉同一个 main 就跑不起来了，因为中间合了几十个 commit，某个依赖悄悄改了大版本。这时候你要是有时间线，就能直接定位到「上次能跑是几号，那之后仓库多了哪些提交」。

所以我建议在日志里固定写一句「本次参照的 commit 或 tag」。不用写全哈希，前七位就够，能对上就行。用 Docker 的话把镜像的 digest 抄一下，比 latest 这个标签靠谱得多，latest 会漂移，digest 不会。

这件事在私有部署场景里尤其要紧。你在自己机器上折腾随便，但给客户或者团队内部部署，回头出了故障，运维问你「当初装的是哪个版本」，你说「最新的」，那对话基本就结束了。

日志写在哪，决定了你会不会去看

写在项目根目录一个 NOTES.md 里，跟着代码一起提交，这是最省事的做法。好处是换机器、换人接手都能看到，坏处是提交信息一多就乱。另一种做法是干脆用 git 的提交信息当日志，commit message 写清楚为什么改，比事后补日志真实。

我偏向折中：项目内放一个简短的 CHANGELOG 记版本和破坏性变更，环境相关的东西写进一份不提交的本地笔记。为什么本地笔记不提交？因为环境信息经常带内网 IP、路径、账号名，提交到公开仓库就是给自己找事。要提交就把这些脱敏掉，或者单独放一个私有仓库。

说到脱敏，提醒一句：日志里千万别抄 token、密码、私钥。有人图省事把完整的 docker-compose.yml 复制进日志，里面明晃晃写着数据库密码，这份文件再随手丢进公共仓库，那就不是日志问题了。

出错的时候，日志的用法和平时不一样

平时记日志是为了少走弯路，出事的时候翻日志是为了缩小范围。顺序大概是：先看最近改了什么，再看改动涉及的模块，最后才去翻项目自己的错误日志。很多人反过来，一上来就 tail -f 盯着错误输出，看半天全是无关警告，因为真正的问题在半小时前那次配置改动上。

开源项目日志的价值就在这一步体现。你不需要记得所有细节，只需要能在日志里快速找到「上一次正常运行」和「第一次出问题」之间发生了什么。这两条中间的那几行，基本就是答案。

有个小技巧：出完故障别急着关窗口，把当时的排查过程补记进日志，包括哪些方向排除了。下次遇到同类问题，省下的时间比第一次排查还多。这部分内容没人要求你写，但写了的人后来都很庆幸。

日志本身也要能活下去

最后提个容易忽略的点：日志会过期。半年前的日志里写的路径、端口、依赖版本可能全变了。所以要么定期清理，要么在每个项目开头写一行「本文档最后核对时间」。看到日期太久远的日志，先当参考，别当依据。

还有，日志别只放在一台机器上。机器重装、磁盘挂掉、机房迁移，日志跟着一起没的情况太常见了。同步一份到自己的笔记工具里，成本几乎为零。

把这几件事做完，你会发现日志不再是给领导看的作业，而是一份真正能救急的档案。版本号只是其中一行，环境和现场才是它值钱的地方。