CI/CD / 系统课时

设计流水线日志

设计流水线日志

流水线日志的目标不是“打印得越多越好”,而是让值班人员在一次失败后快速回答:失败在哪个步骤、执行了什么关键参数、对应哪次提交,以及是否需要进一步查看外部系统,同时保证令牌、密码和凭据不会进入日志。

学习目标

  • 设计能定位到流水线、任务和步骤的结构化日志字段
  • 在日志产生源头屏蔽令牌、密码和带凭据的地址
  • 用一次可运行示例验证正常步骤的日志格式与可检索性

先确定日志要回答的问题

每条日志至少要能关联到一次流水线执行,并明确当前任务与步骤。推荐保留 timestamp、level、pipeline_id、job、step、status、commit、environment、duration_ms 和稳定的 error_code。错误正文可以记录,但不要只依赖一长段自然语言判断故障类型。

同一字段要保持稳定语义。例如 status 只使用 started、succeeded、failed 这类有限值;耗时统一使用毫秒或秒;提交标识统一记录完整或固定长度的 commit SHA。这样后续才能按字段过滤、聚合和告警,而不是依赖全文搜索。

用结构化事件代替零散输出

下面的 Bash 示例用统一函数输出 JSON Lines。示例故意定义了部署令牌,但日志只记录“令牌已配置”,从源头避免把值写入标准输出。

bash
set -euo pipefail

PIPELINE_ID="${PIPELINE_ID:-pipeline-<ID>}"
COMMIT_SHA="${COMMIT_SHA:-<ID>}"
DEPLOY_TOKEN="${DEPLOY_TOKEN:-<VALUE>}"

log_event() {
  local level="$1"
  local job="$2"
  local step="$3"
  local status="$4"
  local message="$5"
  local duration_ms="$6"
  local ts

  ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
  printf '{"timestamp":"%s","level":"%s","pipeline_id":"%s","job":"%s","step":"%s","status":"%s","commit":"%s","environment":"production","duration_ms":%s,"message":"%s"}\n' \
    "$ts" "$level" "$PIPELINE_ID" "$job" "$step" "$status" "$COMMIT_SHA" "$duration_ms" "$message"
}

log_event "INFO" "build" "package" "succeeded" "artifact created" 18420

if [[ -n "$DEPLOY_TOKEN" ]]; then
  log_event "INFO" "deploy" "credentials" "succeeded" "deploy token configured; value omitted" 0
fi

预期输出

text
{"timestamp":"<TIME>","level":"INFO","pipeline_id":"pipeline-<ID>","job":"build","step":"package","status":"succeeded","commit":"<ID>","environment":"production","duration_ms":18420,"message":"artifact created"}
{"timestamp":"<TIME>","level":"INFO","pipeline_id":"pipeline-<ID>","job":"deploy","step":"credentials","status":"succeeded","commit":"<ID>","environment":"production","duration_ms":0,"message":"deploy token configured; value omitted"}

实际时间与流水线 ID、提交 ID 会不同。日志采集器按“一行一个 JSON 对象”读取后,可以直接用 pipeline_id、job、step 和 status 做过滤。

把敏感信息挡在输出之前

不要把“CI 平台会自动打码”当作唯一保护。平台通常只能识别已登记的 secret,经过编码、拼接、截断或写入 URL 后可能无法可靠遮蔽。脚本本身应遵循最小暴露原则:不打印环境变量全集,不开启带密钥命令的 set -x,不记录 Authorization 头,也不把 https://user:password@host 这类地址写入日志。

对于必须辅助定位的敏感参数,记录类别和状态即可,例如“凭据存在”“目标仓库为 production”“证书校验失败”。如果确实需要关联某个对象,优先记录不可逆且经过安全评估的内部标识,而不是原值。

让失败日志形成固定上下文

失败事件应在同一条或相邻几条结构化日志中包含故障步骤、稳定错误码和必要上下文。例如镜像推送失败可以记录 error_code=REGISTRY_PUSH_DENIED、目标环境和镜像标签,但不要附带 registry 密码。长堆栈可以保留给调试日志,面向检索和告警的错误事件仍应保持短而稳定。

日志设计完成后,可以用三个问题验收:能否只靠字段定位失败步骤;能否从一次执行关联到提交和环境;随机抽查日志时是否完全看不到密码、令牌、私钥和认证头。三项都满足,日志才真正具备可运维性。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计流水线日志

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通