1. 为什么我需要专门做一套“context-mode”而不是继续复制配置1.1 被复制粘贴配置文件坑到的那天我大概在把同一份配置复制成app-dev.yml、app-staging.yml、app-prod.yml之后才发现这三个文件里的数据库地址、缓存节点、日志级别全不一样也就算了最离谱的是每次改字段我都得手滑好几次——有一次直接在预发布环境里改错了连接池大小导致第二天上线时数据库连接被打满。那件事之后我就一直想能不能把“当前这个运行上下文到底处于哪种模式”这件事用一个统一的东西管起来而不是靠人肉判断更不是靠复制三份配置然后赌自己记得同步。这个统一的东西就是后来我一直在维护的小工具名字就叫 context-mode。它不是一个框架也不是需要常驻的服务甚至不是什么重量级平台它只是一套“如何根据当前运行环境的特征推导出应该使用哪套参数”的规则和配套脚本。你可以在 CI 流水线上用它可以在跳板机上用它也可以在本地开发环境里用它它就解决一个问题当前这个上下文到底应该按照哪种模式跑。1.2 它要管的不是“环境变量”这一个层面很多人第一反应是“那不就是判断ENVprod吗”对也不对。环境变量只是模式的一种表达方式不是全部。真正麻烦的是很多系统并不是通过环境变量来区分运行场景的而是要同时看主机名、IP 段、某个标记文件是否存在、当前用户是不是 root、当前进程是不是跑在容器里才能综合判断出这是哪一类环境。context-mode 要处理的就是这套判断逻辑的集合。换句话说我把它当成一个“上下文解释器”给它一堆零散的系统信号它输出一个确定性的模式名然后根据这个模式名把对应的配置键值对加载到当前 shell 里。用起来的感觉是你永远不需要在自己的脚本里再写一遍“如果主机名以 abc 开头并且存在某个文件就切到 A 配置”这种又臭又长的分支逻辑了。有朋友问我这算不算配置文件管理我说不算。配置文件管理关心的是“配置存在哪里、怎么同步、怎么加密”context-mode 关心的是“我现在到底在哪个上下文中”——上下文定不下来你把配置文件做得再漂亮也没用。所以它的核心价值其实是一个环境判定器配置加载只是它顺带帮你完成的福利。1.3 适合谁看这篇文章不适合那种“我只有一个开发环境、一个本地机器、一个云端服务器”的人——这种场景你说一句export ENVdev就够了。我写它更针对那些维护多个环境、经常被环境混淆坑到、又不想上重量级配置管理系统的朋友比如自己维护部署脚本的运维工程师、写小程序后端又同时管着多个客户环境的开发或者团队里负责瘦身 CI 流程的人。全文会围绕一个可落地的 Bash 实现展开也会把我在真实项目里踩过的坑都交代清楚。2. 模式判定顺序比规则本身还重要2.1 我把线上机器能提供的信号列了一张表在设计 context-mode 之前我先列了一张表把部署环境里能拿到的信号全部列出来再挨个判断哪些信号“硬”、哪些信号“虚”。结果发现很多信号看起来硬其实一点都不硬。比如 IP 段云厂商的分段规划一变你按 IP 写的判定就是失效的再比如 hostname如果你们的规矩是“生产机器一定要叫cmp-prod-01”那 hostname 是个好信号但如果遇到那种随机生成主机名的托管服务这一招直接完蛋。下面这张表是我当时对几个常用信号的真实感受信号代表性来源真实可靠程度主要风险命令行参数--contextprod极高只有人工场景才有CI 里容易忘传环境变量CONTEXT_MODEstaging高容易被上游任务遗留污染标记文件/etc/context-mode/prod中高并行任务共享同一台机器时会互相干扰主机名web-prod-01中云厂商随机主机名会失效规则写宽会误伤IP 段内网10.20.0.0/16中子网规划一调整代码就要跟着改当前用户名root/deploy低太不稳定人一换角色就错我当时看到这张表的第一反应是没有一个信号是能单独信的。所以 context-mode 的判定策略必须变成多级检测并且要给不同信号安排明确的优先级。2.2 判定优先级显式永远排在检测前面我最后定下来的判定优先级从高到低一共五层显式参数命令行传入--context prod之类显式环境变量CONTEXT_MODEprod标记文件比如/etc/context-mode/prod存在主机名/域名/IP 段这类系统特征默认模式兜底一般默认dev这个顺序不是拍脑袋定的。它的逻辑是信号越“显式”越可信。你自己在命令行里敲了--context prod那就不用再看机器是不是名字带 prod 了你通过环境变量注入过模式那也不需要去看标记文件了。只有显式信号全部为空时才轮到那些来历不明的系统特征上场。注意不要把“默认模式”放到优先级的前面。一旦默认值得到了执行后面再多的检测逻辑就全失去意义了。context-mode 的默认模式只能在“确实什么都检测不到”的时候出现。2.3 手动覆盖和自动检测的边界务必要写清楚这个设计里最关键的一条是“手动指定”永远最高。为什么因为实际运维里最常见的场景是我要在预发布环境里模拟生产模式做演练或者我要在本地临时把模式切到 preview 看效果。这个时候所有系统特征都指向本来的环境唯一能改变结果的就只能是显式指令。我见过不少同事在这个地方栽跟头他们写的脚本是先做自动检测、再允许手动覆盖。实际执行时检测逻辑因为主机名匹配先返回了 prod后面的覆盖分支压根没走到。顺序写反的后果就是项目一旦跑起来绝对会出现“我以为我指定了 staging但它还是用 prod 跑了”的诡异现象。所以我在 context-mode 里的实现严格把显式指定放在第一级自动检测只在没有任何显式指定的情况下才触发。另外还要提一个“覆盖粒度”的问题。有些场景里你只是想临时换一下日志级别不想把整个模式切换掉。context-mode 的配置加载是两层的先加载模式对应的基础配置然后叠加当前环境里已经存在的同名变量。同名的处理原则是“已存在的变量优先”——也就是说如果你已经在 shell 里手动export LOG_LEVELdebug了那么模式加载不会改掉它。这个规则让临时调试变得非常安全因为我永远不用担心 source 一段配置之后把我本来想手动覆盖的东西给顶掉。3. 落地实现一个不到两百行的 Bash 工具3.1 目录结构一个模式一个目录工具既然叫 context-mode它在仓库里的结构我就按“模式”来组织。一个模式一个子目录每个子目录里放env.sh和env.conf。env.conf是纯键值对风格的静态配置env.sh是可以被 source 的 shell 片段里面放需要动态计算的东西。context-mode/ ├── context.sh # 主逻辑需要被 source 进当前 shell ├── default.env # 默认配置兜底用 └── contexts/ ├── dev/ │ ├── env.sh │ └── env.conf ├── staging/ │ ├── env.sh │ └── env.conf └── production/ ├── env.sh └── env.conf拿production/env.conf当例子里面的内容就是一段一段键值对DATABASE_HOSTdb.production.internal DATABASE_PORT5432 REDIS_HOSTredis.production.internal LOG_LEVELinfo API_BASE_URLhttps://api.example.comenv.sh则放那些需要逻辑计算的东西比如根据 CPU 核数推导连接池大小# 这是 production/env.sh CPU_CORES$(nproc) DB_POOL_SIZE$(( CPU_CORES * 4 16 ))为什么要两个文件而不是只用一个因为env.conf是给所有子进程看的静态变量而env.sh里可能有动态计算甚至可能调用别的命令。把它们分开语义清楚排查问题的时候也方便。你一眼就能看出来哪个变量是写死的哪个变量是算出来的。3.2 context.sh 主逻辑一层一层往下探测主脚本的核心部分是模式解析函数。我把完整逻辑简化之后长这样#!/usr/bin/env bash # context-mode: 根据上下文信号推导当前模式并加载对应配置 set -euo pipefail _context_root$(cd $(dirname ${BASH_SOURCE[0]}) pwd) _resolve_mode() { local mode${DEFAULT_CONTEXT_MODE:-dev} # 第 1 层显式参数 if [[ $# -gt 0 ]]; then mode$1 echo $mode return 0 fi # 第 2 层环境变量 if [[ -n ${CONTEXT_MODE:-} ]]; then mode$CONTEXT_MODE echo $mode return 0 fi # 第 3 层标记文件 for candidate in dev staging production; do if [[ -f /etc/context-mode/$candidate ]]; then echo $candidate return 0 fi done # 第 4 层hostname 特征做规范化之后再匹配 local normalized normalized$(hostname | sed -E s/.*-([a-z])-[0-9]$/\1/; s/^([a-z])-[0-9]$/\1/) case $normalized in production|prod) echo production; return 0 ;; staging|stage) echo staging ; return 0 ;; dev) echo dev ; return 0 ;; esac # 第 5 层默认模式兜底 echo $mode }这段代码的意图非常直白哪一层先命中就用哪一层的结果。值得说一说的是第 4 层里我做的那一步规范化处理。因为生产环境的主机名在不同云厂商那里规则差别很大有的是cmp-prod-01有的是web-01-prod还有的是随机串加环境名。我用sed提取出中划线之间的那段环境标识再拿它去做case匹配这样就不用为了每一种命名风格写一条分支了。3.3 加载配置默认先行模式叠加模式定下来之后配置加载就简单了。我用一个函数做加载加载完把模式名写进CONTEXT_MODE_NAME方便后续脚本直接引用_load_context() { local mode$1 local root$2 # 先加载默认配置 if [[ -f $root/default.env ]]; then set -a # shellcheck disableSC1091 source $root/default.env set a fi # 再加载模式专属配置 local conf_dir$root/contexts/$mode if [[ -f $conf_dir/env.conf ]]; then set -a # shellcheck disableSC1091 source $conf_dir/env.conf set a fi # 最后加载需要计算的 env.sh if [[ -f $conf_dir/env.sh ]]; then # shellcheck disableSC1091 source $conf_dir/env.sh fi CONTEXT_MODE_NAME$mode export CONTEXT_MODE_NAME }这段逻辑的关键点是默认配置先垫底模式配置往上叠叠的时候不去强制覆盖任何已经存在的同名变量。也就是说如果你在自己的.bashrc里已经定义过DATABASE_HOSTcontext-mode 的env.conf不会顶掉它。这正是前面第 2 节说的“显式指定优先”的延续——你手动设过的变量工具默认认为你是有意为之。加载完可以顺手打印一段摘要方便 CI 日志里核对模式到底是谁决定的main() { local mode mode$(_resolve_mode $) _load_context $mode $_context_root echo [context-mode] mode${mode} context_root${_context_root} 2 env | grep -E ^(DATABASE|REDIS|LOG_LEVEL|API|CACHE)_ | sort 2 } main $这里的grep只是为了在日志里留下可读的摘要真正跑的时候模式名和关键配置会全部打到标准错误里方便你在 CI 页面里一眼定位问题。4. 实测里最容易踩的坑我一个个排过4.1 环境变量里的“模式污染”context-mode 跑起来之后我遇到的第一个坑其实就是CONTEXT_MODE这个环境变量本身。为什么它会成为坑呢因为很多 CI 系统里编译任务、测试任务、部署任务是在同一个 runner 上执行的。前面某个任务设置过一次CONTEXT_MODEstaging后面另一个无关任务起来的时候环境变量还挂着结果 context-mode 看到环境变量是 staging直接跳过其他检测整个下游任务全跑在 staging 模式下面连个提示都没有。我当时排查这个问题的方式也很笨翻了半天日志最后发现 deploy 任务用的数据库连接池大小明显是 staging 的量而部署目标明明应该是 dev。找来找去根源就是环境变量被上游任务遗留下来了。修法有两个方向我建议两个都做。第一把CONTEXT_MODE改成一个更不容易被别人顺手设置的名字比如CTX_ACTIVE_MODE降低误碰的概率。第二context-mode 在加载配置的时候强制打印一行模式标识包括模式名和它来源的层级这样 CI 日志一打开就能看到模式是谁决定的不用靠猜。4.2 hostname 规则写太宽误伤了构建节点第二个坑来自 hostname 匹配规则写得太宽。我在早期版本里写过一句case $(hostname) in *prod*) echo production;; esac听上去合理但实际跑起来很要命。CI 里经常会有这样的分支名出现比如feature/product-page然后 runner 的主机名恰好叫builder-prod01这两个信号叠加在一起 context-mode 就会把构建任务误判成 production。你可以说 hostname 匹配到了生产关键词就是 prod 没错但对一个构建节点来说它只是给产品分支打包不代表它这个任务就要连生产数据库。后来我把 hostname 规则改成前面给过的那条规范化表达式同时建议新上线的服务器统一按前缀-环境-编号来命名比如cmp-prod-01、web-stage-02。这样做的好处是你不再需要为每一类云厂商的随机主机名写单独的分支规则本身就把主机名规整成统一格式再去做匹配。我特别提这一点是因为见过太多人把 hostname 的 case 分支越写越长最后十几行全是针对不同云厂商的特殊写法维护起来苦不堪言。4.3 并行任务里的共享标记文件竞态第三个坑比较隐蔽出现在我帮同事写的一个动态检测分支里。那个分支会临时在目标机器上写一个标记文件用touch /etc/context-mode/staging来告知 context-mode 当前是 staging。结果两台任务并行执行的时候一台任务写了 staging 标记另一台任务恰好也在同一台机器上跑读取标记文件时读到了 staging就以为自己也是 staging——哪怕它根本不是。这个问题的根源在于标记文件是“共享可变状态”。凡是进入并行的场景共享可变状态就一定要避免。我的解决方案是并行任务不要用标记文件法直接用环境变量或者在命令行传显式参数只有串行部署、并且你确实想让“这次部署之后这台机器就一直是 staging”的场景才考虑用标记文件。这也是我在项目文档里写得很清楚的一条边界。4.4 忘了考虑“无配置文件”的机器还有一个很普通的坑说穿了不值钱但影响特别大context-mode 跑在一台完全没有/etc/context-mode/目录的机器上时会静默落到默认模式。如果默认模式写得不对比如默认是 dev而生产环境新机器还没来得及打标记文件那部署上去的配置就全部是 dev 的连数据库连接都会指向错误的地方。后来我加了一个--strict参数当严格模式开启时如果检测结果落在默认模式脚本会直接报错退出而不是硬着头皮继续跑。这个设计很关键因为它改变了“失败的模式”。原来是什么都拿不到就先按 dev 跑人类观察者很容易被表象迷惑现在是检测不到明确模式就停下来强制告诉你“这台机器的上下文我没有办法确认”。在部署场景里宁可让任务挂掉也不能让它带着错误模式偷偷跑完。5. 如何把 context-mode 扩展成一个可以被别人复用的库5.1 从脚本到函数库的转变context-mode 最开始只是我一个人用的脚本后来团队里别的人也想要我就把它从一个“进入就执行”的脚本改成了“被 source 之后提供函数”的函数库。区别在于函数库里你可以做更细粒度的控制比如source context-mode/context.sh mode$(context_mode::resolve --context $1) context_mode::load $mode这种函数化设计能非常方便地和 Ansible、Chef 或者自己写的 Go/Python 部署工具配合。你不需要每个工具都去解析一遍环境变量只要在入口处调用一次拿到mode后面该选哪套配置、该调用哪个 API就完全由 mode 决定了。我还加了一个进阶功能context_mode::with它可以让你在一个子 shell 里临时切换模式跑完自动恢复context_mode::with staging bash -c ./deploy.sh echo 现在又回到原来的模式了这个功能在早期版本里不太好做因为环境变量是继承制的一改就回不来。现在的做法是起一个子 shell在子 shell 里修改环境变量和 source 配置父 shell 完全不受影响。用起来就像给一个命令临时包了一层模式上下文跑完即弃。5.2 与 CI 平台、Docker Compose 的对接我实际用下来的经验是context-mode 和 CI 平台对接是最舒服的。GitHub Actions、GitLab CI 都可以在流水线最开始加一行- run: | source context-mode/context.sh context_mode::resolve ${CI_ENVIRONMENT_NAME:-}CI 平台自带的CI_ENVIRONMENT_NAME本身就是一种很显式的信号把它传给 context-mode优先级比环境变量检测还高正好符合我们前面定的“显式优先”规则。这样做之后整个流水线的后续步骤全都共享同一个模式上下文不会再出现一会儿加载生产配置、一会儿加载预发布配置的混乱情况。如果你用 Docker Compose还能用 context-mode 来决定 compose 文件的选择export CONTEXT_MODE_NAME$(context_mode::resolve) docker compose -f docker-compose.${CONTEXT_MODE_NAME}.yml up -d这种方式比cp docker-compose.prod.yml docker-compose.yml干净多了不会留下一堆复制出来的临时文件。5.3 做一个轻量 Python 包装最后我还给这个库写过一份约 30 行的 Python 包装内部用subprocess调用context.sh拿模式名再把关键配置写进os.environ方便 Python 脚本直接读取。对我这种习惯写 Python 的人来说这比每次都在 bash 里 source 一套逻辑要顺手很多。# python/context_mode.py import os import subprocess from pathlib import Path CONTEXT_ROOT Path(__file__).resolve().parent.parent def resolve(*args): script_path CONTEXT_ROOT / context.sh result subprocess.run( [bash, str(script_path), *args], env{**os.environ, CONTEXT_MODE: os.environ.get(CONTEXT_MODE, )}, capture_outputTrue, textTrue, checkTrue, ) # context.sh 会把模式名作为末行标准输出 lines result.stdout.strip().splitlines() return lines[-1] if lines else dev这个包装没有很复杂但它让 context-mode 从一个 Bash 小工具变成了 Python 生态里也能直接引用的组件。后面接 Click、Typer 之类的命令行框架都很方便。6. 做 context-mode 这几个月的几条实战心得做 context-mode 这段经历我最大的收获其实不是“如何写脚本”而是“如何设计规则”。以下几点是我在不断踩坑之后沉淀下来的。显式指定永远放在最高优先级。不管你的自动检测逻辑设计得多精巧都要记住--contextprod或CONTEXT_MODEprod一旦出现后面的任何检测都不该再执行。人给的指令如果不如机器的猜测重要那这个工具迟早会在某次深夜发布的时候背叛你。每一条自动检测信号都要提前想好失效场景。你写 hostname 分支的时候先别急着高兴反问自己一句如果平台方明天改了主机名命名规则我这段代码还有意义吗如果对这个问题的回答是“不知道”那这条规则大概率会在三个月后的某个凌晨变成事故的源头。尽量输出“模式决定依据”。我后来给 context-mode 增加了一个CONTEXT_MODE_SOURCE导出专门记录这次模式是通过哪一层信号得到的值可能是cli、envvar、marker-file、hostname或default。日志里有了这个字段排错的时候能少走一半弯路。配置加载永不强制覆盖已有变量。除非你刻意想要“模式覆盖一切”的强管控否则我建议默认遵守“已存在变量优先”。这个规则在测试环境里救过我很多次让我能在不修改工具配置的前提下临时覆盖掉某个连接参数做调试也不会在调试完之后忘记恢复。最后分享一个小技巧。我在所有自动化入口脚本里都会先 source context-mode并把解析出的模式名追加到日志文件名里。比如日志目录会出现deploy-2024-11-05_production.log这种命名。任何人在回看部署记录的时候第一眼就能知道当时跑的是什么模式。这个做法比很多监控报警都便宜但排查问题的时候能省下大量的推理时间。如果你也在维护多环境项目或者经常需要在几套不同参数之间切换我劝你至少把“环境判定”这件事从大脑里删掉交给一个固定工具去处理。这不只是少记一句ENVxxx的问题更重要的是让“当前在哪个上下文里”成为一条可以被系统验证的事实而不是一句靠人传来传去的话。