Skip to content

环境与配置管理 ​

本篇要点:让同一份构建产物在开发、测试、预发、生产上都跑出预期行为,且密钥不进仓库。前置文章:[《流水线提速:并行、缓存与增量》](/guide/cicd/pipeline-speed-optimization.html)我们把流水线压到了 9 分钟,这一章处理这条流水线沿途的环境差异。

一、为什么需要它 ​

2026 年 2 月,一个做餐饮 SaaS 的团队发版后,订单导出功能在生产返回 500,错误日志只有一句 connect ETIMEDOUT 10.0.3.41:5432。同样的镜像在预发环境跑了一周,导出功能一切正常。

排查结果是三处差异叠在一起。预发连单机 PostgreSQL,生产连 PgBouncer 连接池,代码里写死 max: 20——预发够用,生产被 pool_size 卡住。配置来源不同:预发的数据库地址在 application-prod.yml 里,生产的由运维用环境变量覆盖,两边优先级不同,实际生效的不是团队以为的那份。密钥也过期了:CI 里存的生产库密码两个月前轮换过,留在流水线里的是旧的,而旧密码恰好还能读、不能写,于是「查询正常,导出超时」。

三个环境的配置由三个人用三种方式维护,没有一处能回答「生产到底生效了什么」。

环境(environment)在这里指一套独立的运行目标,包含它自己的计算资源、数据库、域名、证书和配置。配置管理(configuration management)要解决的是:哪些东西随代码走,哪些东西随环境走,以及这个边界怎么被机器检查,而不是靠人记。

二、核心概念 ​

6.1 环境分级:分级不是为了仪式 ​

环境的数量与命名常被当成流程问题,其实是风险预算问题。

环境英文主要用途数据来源谁能部署典型寿命
本地local编码与调试合成数据开发者分钟级
预览preview / ephemeral每个合并请求一套合成数据CI 自动合并后销毁
集成integration联调,验证服务间契约脱敏数据CI 自动周级
预发staging上线前最终验证,尽量等同生产脱敏数据CI 自动长期
生产production真实用户真实数据审批后执行长期

分级只有一个判据:每个环境的用途能用一句话说清,且不与另一个重复。做不到就该合并。见过一家公司有 test、test2、qa、uat 四套环境,工程师说不清该往哪套部署,结果是四套都过期。

预发环境的价值取决于它与生产的相似度。相似度不是「用同一份 Dockerfile」就算达成,还包括节点数量、数据库版本、连接池中间件、TLS 终止位置。相似度低到某个程度,预发就退化成第二套测试环境,通过它不代表什么。

预览环境对「环境太多没人管」给出了解法:不为分支保留长期环境,而是每个合并请求临时创建一套,合并即销毁。代价是需要基础设施即代码(infrastructure as code)先就位,否则创建一套环境要手工点二十下。

6.2 配置外置:十二要素里的第三条 ​

配置外置(externalized configuration)指把随环境变化的值从代码里拿出来,通过运行时注入。

十二要素应用(The Twelve-Factor App)的第三条讲的就是这件事:配置存于环境。它的反例是把配置写成代码里的常量或提交进仓库的 config/prod.yml,因为那意味着改一个数据库地址要走一次完整发布。

配置、环境变量、密钥三者边界要分清:

  • 配置(config):不同环境不同、不敏感。数据库主机、日志级别、功能开关。
  • 构建期常量(build-time constant):所有环境相同、编进产物。API 的路径前缀、国际化文案。
  • 密钥(secret):不同环境不同、敏感。数据库密码、第三方 API Key、签名私钥。

最常犯的错是把构建期常量和配置混在一起,典型场景是前端项目:VITE_API_BASE_URL 在 vite build 时被字面量替换进 JS 包,所以「同一个镜像部署到测试和生产」在前端根本做不到,必须在构建时定死。解决办法是运行时注入——把地址放到容器启动时生成的 /config.js 里,或由 Nginx 反向代理掉路径前缀。

配置优先级也要定死并写进文档。常见的层级从低到高:代码内默认值 → 配置文件 → 环境变量 → 命令行参数。Spring Boot 的 application.yml 加环境变量覆盖、Node 的 dotenv 加 process.env 都是这个模型。不写清优先级,prod.yml 里那一行到底生效没有就没人知道。

6.3 密钥注入:从「存哪」到「怎么给」 ​

密钥(secret)管理分两件事:存放和注入。两侧都做对才算数。

存放侧的选项按复杂度递增:CI 平台内置的 secret(GitHub Actions Secrets、GitLab CI Variables,勾选 masked 与 protected)、云厂商的密钥管理服务(AWS Secrets Manager、阿里云 KMS)、自建 Vault、以及 Kubernetes 里的 External Secrets Operator。选择依据是轮换需求和审计要求,不是团队规模。

注入侧的原则是密钥不进镜像、不进构建日志、不落在磁盘上。三条具体做法:

一是构建期密钥与运行期密钥分开。NPM_TOKEN 只在 pnpm install 那一刻需要,用 BuildKit 的 secret 挂载而不是 ARG。ARG 和 ENV 的值都会留在镜像历史和层里,docker history 一查就有。

二是运行期密钥用文件挂载或环境变量注入,且优先文件。环境变量会被 ps e、/proc/<pid>/environ、异常堆栈里的环境转储带走;挂载文件(/run/secrets/db_password)只在进程内可读,泄露面更小。

三是日志脱敏要有兜底。CI 平台会自动屏蔽注册过的 secret,但只认完全匹配,拼接过的字符串(比如带前缀的 DSN)会漏出来。所以 echo 调试密钥的习惯必须禁止,加载配置后只打印长度或哈希前缀。

轮换(rotation)是这套机制的试金石:密钥应能定期更换,不改代码、不停机。做不到通常是因为密钥被写进了三处——仓库的 .env、镜像的 ENV、某个人的备忘录。轮换一次能把这三处全部暴露出来,所以不少团队第一次轮换反而先出事故,这恰好说明之前的密钥管理只在纸面上。

6.4 环境漂移:配置腐化的具体形态 ​

漂移(drift)指环境的实际状态偏离了它的声明状态。

图 6-1 漂移的产生与检测:手工改动能立刻让实际状态偏离声明状态,检测只能事后发现

如图 6-1 所示,漂移的来源全是「紧急情况下的手工操作」,而手工操作在事故里是合理的。问题不在于禁止它,而在于它有没有回到声明状态。

三个检测手段,由轻到重:

定时 diff。用 terraform plan 的 -detailed-exitcode(返回 2 表示有变更)、helm diff upgrade、或 Argo CD 的 OutOfSync 状态,每天跑一次,有差异就开单。

资源指纹。把关键资源的 spec 哈希存进一张表,隔一段时间比对。这个办法粗糙但便宜,适合还没有 IaC 的团队起步。

变更审计。从 API Server 的审计日志或云厂商的操作日志里筛出「不经流水线的写操作」,按人聚合。三个月内手工变更超过十次的人,需要的是培训或权限收回,不是更好的检测。

漂移治理的顺序是:先让声明状态成为唯一可写入口,再谈检测。检测做得再好,只要发布流程允许手工改,差距每天会重新长出来。

6.5 本地与 CI 一致:容器是唯一可靠的答案 ​

「我本地是好的」这句话背后通常是四处差异:语言运行时版本、系统库、环境变量、依赖安装方式。

最省事的解法是让本地和 CI 跑在同一个容器镜像里。docker compose 起依赖服务(数据库、缓存、消息队列),应用本身用与 CI 相同的 Dockerfile 的 builder 阶段跑。这样 node --version 在两边一致,glibc 版本一致,连时区都一致。

版本文件要单一来源。.nvmrc、.node-version、package.json 的 engines、FROM node:22.20.0 这四处写同一个版本号,迟早会不一致。做法是选定一个文件作为来源,其余用脚本或 CI 检查同步;或者干脆只保留 Dockerfile 里的版本,本地也走 docker compose run。

环境变量同理。本地 .env 与 CI 的 Variables 有差异可以接受,但要有一份 .env.example 把键列全,并在启动时校验缺失的键直接失败——DATABASE_URL 是 undefined 却能让服务启动,这类问题能在预发耗掉半天。

三、动手实践 ​

环境:Docker 27、BuildKit、GitHub Actions、Node 22。

步骤一:用 BuildKit secret 装私有依赖 ​

密钥不落进镜像层,靠的是 --mount=type=secret:

dockerfile
# syntax=docker/dockerfile:1.7
FROM node:22.20.0-bookworm-slim AS builder
WORKDIR /app
COPY package.json pnpm-lock.yaml .npmrc ./
RUN --mount=type=secret,id=npm_token,required=true \
    NPM_TOKEN="$(cat /run/secrets/npm_token)" \
    corepack enable && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build

构建命令把 token 从文件传入,而不是 --build-arg:

bash
docker buildx build \
  --secret id=npm_token,src="$HOME/.npm_token" \
  -t registry.corp.example.com/pay:1.5.0 .

运行结果:构建成功,日志里 pnpm install 正常完成,docker history 中看不到 token。对照实验:把同样的值改成 --build-arg NPM_TOKEN=... 并写进 Dockerfile 的 ARG,执行 docker history --no-trunc registry.corp.example.com/pay:1.5.0 | grep -i npm_token,能直接看到明文。

required=true 的作用是缺 secret 时立刻失败,而不是打出一个装不上依赖的镜像。忘了传 --secret 时的报错是 failed to solve: secret npm_token not found,比装到一半 401 更容易定位。

步骤二:配置优先级写死并自检 ​

下面这段代码做两件事:按固定优先级合并配置,缺关键键就退出。

javascript
// config.js
const required = ['DATABASE_URL', 'REDIS_URL', 'JWT_SECRET'];

const config = {
  port: Number(process.env.PORT ?? 3000),
  logLevel: process.env.LOG_LEVEL ?? 'info',
  databaseUrl: process.env.DATABASE_URL,
  redisUrl: process.env.REDIS_URL,
  jwtSecret: process.env.JWT_SECRET,
};

const missing = required.filter((k) => !process.env[k]);
if (missing.length > 0) {
  console.error(`缺少必需的环境变量: ${missing.join(', ')}`);
  process.exit(1);
}

// 打印时只输出长度,不输出值
console.log(`config loaded: port=${config.port} logLevel=${config.logLevel} jwtSecret=***(${config.jwtSecret.length})`);
module.exports = config;

运行结果:直接 node config.js 时输出 缺少必需的环境变量: DATABASE_URL, REDIS_URL, JWT_SECRET,退出码 1。补上三个变量后输出 config loaded: port=3000 logLevel=info jwtSecret=***(48),服务继续启动。

退出码 1 这一步是关键。默认行为是带着 undefined 一路跑下去,等到第一次查询数据库才报错,那时候错误现场已经离根因很远了。

步骤三:一个 compose 文件同时服务本地与 CI ​

yaml
# compose.yaml
services:
  app:
    build:
      context: .
      target: builder
    command: pnpm dev
    env_file: [.env]
    ports: ["3000:3000"]
    depends_on:
      db: { condition: service_healthy }
  db:
    image: postgres:17.2-alpine
    environment:
      POSTGRES_PASSWORD: devonly
      POSTGRES_DB: app
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 3s
      retries: 10

CI 里的集成测试用同一条命令:

bash
docker compose up -d --wait db
docker compose run --rm app pnpm test:integration
docker compose down -v

运行结果:本地 docker compose up 后 curl localhost:3000/healthz 返回 {"status":"ok","db":"up"};CI 里 --wait 等 db 健康后跑集成测试,输出 Test Files 12 passed,退出码 0。-v 清掉数据卷,保证下一次是干净状态。

--wait 依赖 healthcheck,没有 healthcheck 时它会立即返回,测试连不上数据库报 ECONNREFUSED。postgres 的 pg_isready 是最省事的健康检查,别用 sleep 5 顶替——慢机器上照样失败。

步骤四:检测一次漂移 ​

bash
helm diff upgrade pay deploy/helm/pay -f values-prod.yaml --detailed-exitcode; echo "exit=$?"

运行结果(存在漂移时):

text
Defaulted container "pay" out of: pay, istio-proxy
  Deployment/pay
  -   replicas: 6
  +   replicas: 4
exit=2

replicas 被人从 4 手工调到 6 应急,之后再没改回来。退出码 2 是脚本的判断依据,定时任务据此开单。把这条命令放进每日定时流水线,才算真正开始治理漂移。

四、常见误解 ​

很多人以为多建几个环境更安全。实际上环境越多,单个环境越不像生产,越少有人维护,最后没人敢用它做判断。四个比生产简单得多的环境,安全性不如一个真正接近生产的预发。判断该不该多一个环境,问一句:它能不能拦住一个其他环境拦不住的问题。

很多人以为把密钥放进 CI 平台的 secret 就安全了。实际上 secret 只保护了「存」这一段,泄露往往发生在「用」这一侧:echo 调试打进日志、--build-arg 留在镜像层、异常堆栈转储环境变量、子进程继承后写进临时文件。审计时应该搜日志里的密钥形态,而不是只看 secret 列表。

很多人以为配置写进 prod.yml 提交到仓库就是配置外置。实际上按环境的配置文件一旦提交,它就变成了代码的一部分:改数据库地址要发一次版,且改测试环境的配置会污染所有人的工作副本。真正的分界是同一个产物能否在多个环境运行,不能就说明配置还没外置。

还有人以为漂移只能靠人盯。terraform plan 的退出码、helm diff 的 --detailed-exitcode、Argo CD 的 OutOfSync 都是机器可读的信号,缺的只是把它们接进定时任务和工单系统。

五、小结 ​

[《流水线提速:并行、缓存与增量》](/guide/cicd/pipeline-speed-optimization.html)让流水线跑得快,这一章保证它跑到哪里都跑得对。

  • 环境按「用途一句话说清且不重复」来分,预发的价值取决于它与生产的相似度,不取决于它存在。
  • 配置、构建期常量、密钥三者的边界要写下来。前端项目最容易把配置误当构建期常量。
  • 密钥优先挂文件不挂环境变量;构建期密钥用 --mount=type=secret,不用 ARG。
  • 漂移源于应急手工操作,治理顺序是先收口入口,再上 terraform plan、helm diff、Argo CD 的检测。
  • 本地与 CI 一致靠同一个容器镜像加一个 compose.yaml;必需的环境变量缺失时让进程直接退出,比带着 undefined 跑更省时间。

六、相关文章 ​

到这一章,构建能复现、速度快、各环境的配置也分清了口径。但还有一条线没碰:我们构建出来的镜像里到底装了什么?依赖树里有几个已知漏洞?镜像推到仓库后有没有人能悄悄换掉?[《供应链安全:SBOM、签名与扫描》](/guide/cicd/supply-chain-security-sbom.html)讲供应链安全:用 SBOM 说清成分,用 Cosign 签名固定身份,用扫描和准入把有问题的镜像挡在部署之前。

继续阅读:[《供应链安全:SBOM、签名与扫描》 供应链安全:SBOM、签名与扫描](/guide/cicd/supply-chain-security-sbom.html)