Jenkins如何配置构建日志保留天数？

Question

在Jenkins中，如何配置构建日志的保留天数以避免磁盘空间过度占用？默认情况下，Jenkins会无限期保留所有构建记录和控制台输出，长期运行后可能导致磁盘资源耗尽。虽然可通过项目配置中的“保持构建天数”或“最大构建数”策略来自动清理旧构建，但若未正确设置，日志文件将持续累积。常见问题包括：配置项不生效、日志仍被保留超出预期时间、或跨节点环境下的清理不一致等。如何结合全局设置与单个项目策略，合理设定构建日志的保留周期，并确保日志清理机制稳定执行？

Answer 1

一、Jenkins构建日志保留机制概述

Jenkins作为持续集成与交付的核心工具，其构建历史和控制台输出是调试与审计的重要依据。然而，默认情况下，Jenkins会无限期保留所有构建记录及其日志文件（位于$JENKINS_HOME/jobs/[JOB_NAME]/builds/目录下），长期运行后极易导致磁盘空间耗尽。

为避免此问题，Jenkins提供了两种主要策略来管理构建日志生命周期：

• 按时间保留：设置“保持构建天数”
• 按数量限制：设置“最大构建数”

这些策略既可在单个项目中配置，也可通过全局插件或脚本统一管理，形成分层治理结构。

二、单项目级别的日志保留配置

在每个Jenkins Job的配置页面中，可通过以下步骤启用日志清理：

1. 进入Job配置页面
2. 勾选“Discard old builds”选项
3. 配置策略参数：
   • Days to keep builds：设定日志保留天数（如30天）
   • Max # of builds to keep：设定最大保留构建数（如50次）

示例配置如下表所示：

策略类型	参数名称	推荐值（生产环境）	说明
时间驱动	Days to keep builds	30	超过30天的构建将被自动删除
数量驱动	Max # of builds to keep	50	最多保留最近50次构建

三、全局策略与系统级自动化管理

对于多项目环境，逐一手动配置效率低下且易遗漏。Jenkins支持通过logrotate机制结合Groovy脚本实现集中化管理。

可使用Jenkins Script Console执行以下Groovy代码批量设置所有项目的保留策略：

import jenkins.model.*
import hudson.model.*

def daysToKeep = 30
def numToKeep = 50

Jenkins.instance.getAllItems(Job.class).each { job ->
    def logRotator = new hudson.tasks.LogRotator(daysToKeep, numToKeep, -1, -1)
    job.setLogRotator(logRotator)
    job.save()
    println "Updated: ${job.fullName}"
}

该脚本遍历所有Job并统一应用日志轮转策略，确保一致性。

四、常见问题分析与排查路径

尽管配置了保留策略，仍可能出现日志未及时清理的情况。以下是典型问题及成因分析：

• 配置未生效：Job未保存或SCM同步覆盖本地配置
• 跨节点不一致：分布式环境中主节点与Agent间文件同步异常
• 权限不足：Jenkins进程无权删除builds目录下的文件
• 构建正在运行：正在进行的构建不会被清理机制触发

建议定期检查$JENKINS_HOME/logs/tasks中的GC日志，确认HouseOfMirrors任务是否正常执行。

五、高级策略：结合外部监控与告警机制

为提升稳定性，可引入外部监控系统对磁盘使用率进行实时跟踪。例如，使用Prometheus + Node Exporter采集Jenkins主机磁盘数据，并设置阈值告警。

同时，可通过定时任务触发清理脚本：

# 每日凌晨清理陈旧构建（补充Jenkins自身机制）
find $JENKINS_HOME/jobs/*/builds/ -maxdepth 2 -type d \\
  -mtime +30 -name "[0-9]*" -exec rm -rf {} \;

注意：此类脚本需谨慎测试，避免误删活跃构建。

六、可视化流程：构建日志生命周期管理流程图

graph TD A[开始] --> B{是否启用日志保留策略?} B -- 否 --> C[日志无限增长 → 风险] B -- 是 --> D[判断保留条件] D --> E[按天数 or 按数量?] E --> F[满足任一条件则标记为可删除] F --> G[Housekeeping任务执行删除] G --> H[释放磁盘空间] H --> I[结束]