CI/CD / 系统课时
设计流水线日志
设计流水线日志
流水线日志的目标不是“打印得越多越好”,而是让值班人员在一次失败后快速回答:失败在哪个步骤、执行了什么关键参数、对应哪次提交,以及是否需要进一步查看外部系统,同时保证令牌、密码和凭据不会进入日志。
学习目标
- 设计能定位到流水线、任务和步骤的结构化日志字段
- 在日志产生源头屏蔽令牌、密码和带凭据的地址
- 用一次可运行示例验证正常步骤的日志格式与可检索性
先确定日志要回答的问题
每条日志至少要能关联到一次流水线执行,并明确当前任务与步骤。推荐保留 timestamp、level、pipeline_id、job、step、status、commit、environment、duration_ms 和稳定的 error_code。错误正文可以记录,但不要只依赖一长段自然语言判断故障类型。
同一字段要保持稳定语义。例如 status 只使用 started、succeeded、failed 这类有限值;耗时统一使用毫秒或秒;提交标识统一记录完整或固定长度的 commit SHA。这样后续才能按字段过滤、聚合和告警,而不是依赖全文搜索。
用结构化事件代替零散输出
下面的 Bash 示例用统一函数输出 JSON Lines。示例故意定义了部署令牌,但日志只记录“令牌已配置”,从源头避免把值写入标准输出。
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预期输出
{"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 密码。长堆栈可以保留给调试日志,面向检索和告警的错误事件仍应保持短而稳定。
日志设计完成后,可以用三个问题验收:能否只靠字段定位失败步骤;能否从一次执行关联到提交和环境;随机抽查日志时是否完全看不到密码、令牌、私钥和认证头。三项都满足,日志才真正具备可运维性。