90%解法:彻底告别环境变量引发的头疼故障

工具就是外化的肌肉记忆
环境配置校验

我整整熬了三个小时,就为了搞明白为什么预发环境(staging)一直挂,而生产环境偏偏跑得好好的。

同一份代码。同一个Kubernetes集群。同一批Docker镜像。

差别在哪儿?ConfigMap里有一个环境变量,在预发环境拼成了 DATABASE_URL,在生产环境拼成了 DATABASE_URI。

三个小时,就栽在一个拼写错误上。就在那一刻,我懒得再跟自己较劲了,转身动手写了envcheck。

没完没了的老毛病

环境配置文件是最折磨人的那种技术债。它看着简单,到处都是,而且每次出问题都悄无声息,非得等到凌晨三点才给你炸个大的。

这套剧本我见过太多次了:

场景实际后果你什么时候才会发现
变量名拼错应用默默退回默认值线上事故爆发时
漏配变量启动当场崩溃部署上线那一刻
重复定义同名键一个生效,另一个被覆盖查日志发现死活对不上号
多环境配置漂移"在我机器上明明好好的"代码评审阶段

那种"本地跑得好好的、一上预发就挂"的诡异bug,只要系统规模一上来,迟早会变成家常便饭。你的环境配置其实一直在给你敲警钟。

大多数团队都是不疼不改。我是真被折腾够了。

我最开始试过的招

起初我也跟大伙儿一样:把 .env.example 复制成 .env,填上值,然后双手合十祈祷别出事。

后来我加上了pre-commit钩子,又写了shell脚本去比对文件,还试过靠脑子硬记到底哪些变量不能漏。

可现在的环境变量早就散落在七种完全不同的配置格式里了:

  • .env 文件
  • Kubernetes的ConfigMap与Secret(SecretKeyRef、ConfigMapKeyRef)
  • Terraform变量定义(TF_VAR_*)
  • Ansible Vault查询(lookup('env', 'VAR'))
  • GitHub Actions工作流(env: 代码块)
  • Helm Chart配置(values.yaml 里的全大写下划线键名)
  • ArgoCD应用配置清单(plugin.env)

我的配置七零八落地摊在七个地方,既没有单一事实来源,也没法验证它们是不是还保持同步。

于是我做了任何正常工程师都会做的事。

我自己造了个工具。

envcheck的思路

我用Rust写了envcheck,图的就是一个快字。快到离谱的那种快。

# Install
cargo install envcheck

# Lint a file
envcheck lint .env

# Compare environments
envcheck compare .env.example .env.prod

# Fix automatically
envcheck fix .env --commit

envcheck真正看家的本事是跨配置同步校验。

# Check Kubernetes manifests against .env
envcheck k8s-sync k8s/*.yaml --env .env.example

# Check Terraform against .env
envcheck terraform infra/ --env .env

# Check GitHub Actions workflows
envcheck actions .github/workflows --env .env

现在我再也不用瞎猜Kubernetes配置清单跟环境变量文件对不对得上了,跑一下心里就有底,耗时大概3.3微秒。

设计哲学

这世上的Linter早就够多了,我压根儿没打算再凑一个热闹。

我想解决的是协调问题。

环境配置本质上是个分布式系统问题。你手头攥着好几个事实来源(.env、Kubernetes、Terraform),偏偏缺一套机制去核实它们彼此一致。

envcheck直接把环境变量当成协调问题来治:

  1. 只定义一次(把 .env.example 立为唯一事实来源)
  2. 到处做校验(覆盖Kubernetes、Terraform、Ansible、GitHub Actions、Helm、ArgoCD)
  3. 全自动修复(按键名排序、剔除重复项、自动提交)

秩序靠你亲手搭建,混乱留着让你半夜排查。环境配置文件天生就会往混乱里漂移,全靠你在中间把它们拽住。

上线之后发生了什么

我把envcheck开源放了出去,慢慢攒了点人气,陆续有人在真实项目里用上了它。

最让我意外的收获,其实是踏实感。

我不再惦记预发环境跟生产环境到底对不对得上,不再犯嘀咕是不是在Kubernetes清单里漏写了一个变量,也不用再熬到凌晨三点跟一个拼写错误死磕。

披萨挺香。能一觉睡到天亮更香。

90%解法

把丑话说在前头:EnvCheck解决不了100%的环境配置难题。

底下这几件事依然得另想办法:

  • 密钥管理(真实的敏感值到底存在哪儿?)
  • 凭据轮换(需要定期改密码时怎么平滑切换?)
  • 审计留痕(谁在什么时候改了哪个值?)

但envcheck干净利落地解决了每周都在折磨我的那90%破事:

  • 变量名拼写错误
  • 跨环境漏配字段
  • .env.example 跟实际配置文件越跑越偏
  • 格式乱七八糟导致git diff根本没法看

有时候最好的自动化就是别瞎搞自动化。但一旦决定动手自动化,就得挑那个真正在天天给你找麻烦的痛点下手。

快速上手

要是你也受够了环境配置漂移,两行命令就能跑起来:

cargo install envcheck
envcheck lint .env

如果你平时更习惯用npm:

npm install -g envcheck
envcheck lint .env

文档地址:envcheck.github.io。

GitHub仓库:github.com/envcheck/envcheck

这件事教会了我什么

工具就是外化的肌肉记忆。你真正动手造出来的工具,往往对应着那些你已经手工干了无数遍、发誓这辈子再也不想人肉重复第二次的苦差事。

我写envcheck,是因为我在同一个坑里反复摔过好几回。花三小时查一个拼写错误之后,我暗下决心绝不让这种事重演。

这种具体的一线经验没法靠抄袭学来,非得自己结结实实疼过几回才算数。

绝大多数系统天生都会走向溃散,全靠你在中间把它们拢住。


觉得这篇对胃口?你可能也会喜欢我的周刊 SeekingSota,专门聊聊当工程师放下样板代码、拿起指挥棒调度AI代理之后会发生什么。

平时也在造工具?不妨看看 envcheck、NerfStatus 或 HCT。

Search stefanwiest.de

Type to search