#!/bin/bash# # 脚本名称: jenkins_diagnose.sh# 描述: 基于哲学元认知优化的 Jenkins (Docker Compose) 故障诊断脚本# 融合整体论、奥卡姆剃刀、实用主义、辩证法、道家无为与本体论# 用法: bash jenkins_diagnose.sh [compose项目目录]# 若不提供目录默认使用当前目录# set-uopipefail# ------------------------------# 颜色定义 (让输出更易阅读)# ------------------------------RED\033[0;31mGREEN\033[0;32mYELLOW\033[1;33mBLUE\033[0;34mNC\033[0m# No Color# ------------------------------# 配置区 (可根据实际环境修改)# ------------------------------COMPOSE_DIR${1:-.}# Docker Compose 项目目录JENKINS_SERVICE_NAME${2:-jenkins}# compose 中的服务名JENKINS_HOME_HOST${3:-/data/jenkins}# Jenkins 数据卷在宿主机上的挂载路径# ------------------------------# 辅助函数# ------------------------------info(){echo-e${GREEN}[INFO]${NC}$*;}warn(){echo-e${YELLOW}[WARN]${NC}$*;}error(){echo-e${RED}[ERROR]${NC}$*;}header(){echo-e\n${BLUE}${NC};echo-e${BLUE}$*${NC};echo-e${BLUE}${NC};}# 检查命令是否存在check_command(){command-v$1/dev/null21||{error命令$1未找到请先安装。;return1;}}# ------------------------------# 预检确保必要的命令可用# ------------------------------preflight(){header0. 预检依赖命令localmissing0forcmdindockerfreedfdmesggrepawktailheadjournalctl xmllintstat;doif!check_command$cmd;thenmissing1fidoneif[$missing-eq1];thenerror缺少必要命令脚本退出。exit1fiinfo所有依赖命令检查通过。}# # 第一步整体感知整体论# 目的在点状排查前先获取系统的全貌识别涌现行为。# step1_holistic_overview(){header第一步整体感知整体论原则# 1.1 系统负载与运行时间echo 1.1 系统负载与 uptimeuptime# 手工验证在服务器上直接执行 uptime观察负载是否超过 CPU 核心数。# 1.2 内存概况echo-e\n 1.2 内存使用概况free-h# 手工验证执行 free -h关注 available 列是否接近 0swap 是否大量使用。# 1.3 磁盘使用概况echo-e\n 1.3 磁盘使用概况df-h|grep-E^Filesystem|/$|/data# 手工验证执行 df -h检查根分区及 Jenkins 数据卷所在分区的使用率是否达到 100%。# 1.4 关键系统日志中的严重错误最近10分钟echo-e\n 1.4 最近10分钟的系统严重错误journalctl--since10 min ago-perr --no-pager2/dev/null|tail-20||dmesg|tail-30# 手工验证执行 journalctl -xe 或 dmesg 查看是否有 I/O 错误、文件系统只读等。# 1.5 Docker 守护进程状态echo-e\n 1.5 Docker 服务状态systemctl is-activedocker2/dev/null||servicedockerstatus2/dev/null# 手工验证systemctl status docker确保 daemon 正常运行。}# # 第二步自愈状态速查道家无为# 目的检查系统是否已自行恢复避免不必要的人工介入。# step2_self_healing_check(){header第二步自愈状态速查道家无为原则cd$COMPOSE_DIR||{error无法进入$COMPOSE_DIR;exit1;}echo 2.1 容器列表与状态dockercomposeps# 手工验证在 compose 目录下执行 docker compose ps查看 STATUS 列。# 提取 Jenkins 容器状态localstatusstatus$(dockercomposeps-q$JENKINS_SERVICE_NAME|xargsdockerinspect-f{{.State.Status}}2/dev/null||echounknown)echo-e\n当前 Jenkins 容器状态:$status# 根据状态判断自愈情况if[$statusrunning];theninfo容器正在运行。检查健康检查日志是否显示近期自愈...dockerinspect$JENKINS_SERVICE_NAME|grep-A5Health||true# 手工验证docker inspect 容器名 | jq .[0].State.Health 查看健康检查历史。echo如果服务已恢复且健康检查通过则无需紧急干预事后复盘即可。elif[$statusrestarting];thenwarn容器正处于重启循环中自愈未成功需深入排查。elif[$statusexited];thenwarn容器已退出自愈机制可能失效或未配置 restart: always需立即介入。elsewarn容器状态未知或已移除。fi}# # 第三步奥卡姆剃刀决策分支# 目的根据最直接的信号直击最常见根因避免过度诊断。# step3_occam_razor(){header第三步奥卡姆剃刀分支排查cd$COMPOSE_DIR||exit1# 3.1 获取退出码localexit_codeexit_code$(dockercomposeps-q$JENKINS_SERVICE_NAME|xargsdockerinspect-f{{.State.ExitCode}}2/dev/null||echo)echo 3.1 退出码分析if[-n$exit_code];thenecho容器退出码:$exit_codecase$exit_codein137)error退出码 137 表示进程被 SIGKILL 杀死几乎肯定是 OOM (内存不足)。echo--- 立即检查 OOM 记录 ---dmesg|grep-ioom|tail-20journalctl-k|grep-ioom|tail-20# 手工验证执行 dmesg | grep oom 或 grep -i oom /var/log/syslog。echo紧急恢复建议echo 1. 临时提高 Docker 内存限制修改 docker-compose.yml 中的 mem_limit 或 deploy.resources.limits.memoryecho 2. 调整 JVM 堆大小在 environment 中添加 JAVA_OPTS-Xmx1g -Xms512mecho 3. 立即重启: docker compose up -dreturn;;1)warn退出码 1 通常为应用自身错误查看容器日志可获得详细信息。;;0)warn退出码 0 为正常退出可能是入口脚本结束。检查启动命令或 entrypoint 是否正确。;;*)warn未知退出码。;;esacfi# 3.2 快速检查磁盘空间 (奥卡姆剃刀第二大杀手)echo-e\n 3.2 磁盘空间快检localuse_percentuse_percent$(df-h$JENKINS_HOME_HOST|awkNR2 {print $5}|tr-d%)echoJenkins 数据卷所在分区使用率:${use_percent}%if[$use_percent-ge95];thenerror磁盘空间即将耗尽这是容器异常的常见原因。echo紧急清理建议echo 1. 删除旧构建: find$JENKINS_HOME_HOST/jobs -type f -name *.log -mtime 30 -deleteecho 2. 清理工作空间: rm -rf$JENKINS_HOME_HOST/workspace/*echo 3. 清理 Docker 系统缓存: docker system prune -f# 手工验证执行 du -sh $JENKINS_HOME/* 定位空间占用大户。returnfi# 3.3 若非以上两种打印最近容器日志交由下一步深入分析echo-e\n 3.3 未命中常见模式打印容器最近日志dockercompose logs--tail50$JENKINS_SERVICE_NAME2/dev/null||\dockerlogs--tail50$JENKINS_SERVICE_NAME2/dev/null# 手工验证直接在目录下执行 docker compose logs --tail100 jenkins 查看详细日志。}# # 第四步本体实体化排查本体论# 目的按 Jenkins 核心实体配置、作业、凭证、插件分而治之。# step4_ontology_check(){header第四步本体实体化排查本体论原则[-d$JENKINS_HOME_HOST]||{errorJenkins 数据卷目录$JENKINS_HOME_HOST不存在;return;}cd$JENKINS_HOME_HOST||return# 4.1 实体全局配置 config.xmlecho 4.1 核心实体全局配置文件 config.xmlif[-fconfig.xml];thenxmllint--nooutconfig.xml2/dev/nullinfoconfig.xml 语法有效||errorconfig.xml 存在 XML 语法错误# 手工验证xmllint --noout $JENKINS_HOME_HOST/config.xml 检查完整性。若损坏可尝试从备份恢复。elseerrorconfig.xml 丢失Jenkins 将无法启动。fi# 4.2 实体凭证echo-e\n 4.2 安全实体凭证文件 credentials.xmlif[-fcredentials.xml];thenxmllint--nooutcredentials.xml2/dev/nullinfocredentials.xml 有效||errorcredentials.xml 损坏elsewarncredentials.xml 不存在可能是全新安装或未使用基于文件的凭证。fi# 4.3 实体作业定义echo-e\n 4.3 作业实体检查 jobs 目录if[-djobs];thenlocaljob_count0job_count$(findjobs-maxdepth2-nameconfig.xml|wc-l)echo发现$job_count个作业定义文件。# 随机抽查几个作业的 config.xmlforjob_xmlin$(findjobs-maxdepth2-nameconfig.xml|head-5);doxmllint--noout$job_xml2/dev/null||error作业$job_xml存在 XML 错误。done# 手工验证xmllint --noout jobs/*/config.xml 批量检查。若某个作业损坏可暂时移走其目录让 Jenkins 启动。elsewarnjobs 目录不存在所有流水线将不可见。fi# 4.4 实体插件echo-e\n 4.4 插件实体plugins 目录if[-dplugins];thenlocalplugin_countplugin_count$(lsplugins/*.jpi2/dev/null|wc-l)echo已安装插件数量:$plugin_count# 检查是否存在 .pinned 或 .disabled 文件可能影响加载iflsplugins/*.pinned plugins/*.disabled2/dev/null|grep-q.;thenwarn发现被固定或禁用的插件可能与版本冲突有关。fi# 手工验证查看 docker compose logs jenkins | grep -i plugin 中的错误。fi# 4.5 权限本体用户与文件属主echo-e\n 4.5 数据卷权限localownerowner$(stat-c%u:%g$JENKINS_HOME_HOST2/dev/null)echo数据卷$JENKINS_HOME_HOST属主为:$owner(期望 1000:1000)if[$owner!1000:1000];thenerror权限不正确Jenkins 容器用户 (uid 1000) 无法写入。echo修复命令: sudo chown -R 1000:1000$JENKINS_HOME_HOSTfi# 手工验证ls -la $JENKINS_HOME_HOST 查看文件属主确认是否为 1000。}# # 第五步编排与资源辩证调优# 目的检查 Compose 配置中的资源限制与策略矛盾做出最佳权衡。# step5_compose_dialectic(){header第五步编排配置辩证分析cd$COMPOSE_DIR||exit1localcompose_filedocker-compose.ymlif[!-f$compose_file];thenwarn未找到 docker-compose.yml跳过编排检查。returnfiecho 5.1 重启策略grep-A2restart:$compose_file||echo未显式设置 restart可能导致进程退出后容器不会自动恢复。echo-e\n 5.2 资源限制grep-Emem_limit|mem_reservation|memory|deploy:$compose_file||echo未设置内存限制容器可能耗尽宿主机内存触发 OOM。echo-e\n 5.3 卷挂载grep-A1volumes:$compose_file|grep-v^--||true# 手工验证对比 compose 文件中的卷映射与宿主机实际路径确保一致性。echo-e\n 5.4 JVM 参数grep-EJAVA_OPTS|JENKINS_OPTS$compose_file||echo未设置 JVM 堆大小Jenkins 会默认使用 1/4 物理内存可能导致内存压力。# 辩证法提示在内存限制与堆大小之间找到平衡。若限制了容器内存但未调整堆可能导致频繁 GC。echo-e\n推荐操作echo - 添加 restart: unless-stopped 实现自愈。echo - 设置合理内存限制如 deploy.resources.limits.memory: 2g。echo - 同时配置 JAVA_OPTS: -Xmx1g -Xms512m 避免 JVM 超过容器限制。}# # 第六步系统与内核兜底# 目的排查更深层次的系统级故障。# step6_system_kernel(){header第六步系统与内核深层排查echo 6.1 文件系统与 I/O 错误dmesg|grep-i-Eerror|fail|read-only|tail-15# 手工验证mount | grep ro, 检查是否有分区只读挂载。echo-e\n 6.2 SELinux/AppArmor 审计ifcommand-vausearch/dev/null;thenausearch-mavc--startrecent2/dev/null|grepjenkins|tail-10||truefiifcommand-vsestatus/dev/null;thensestatus|grepSELinux statusfi# 手工验证ausearch -m avc | grep jenkins 或查看 /var/log/audit/audit.log。echo-e\n 6.3 文件描述符限制localcontainer_idcontainer_id$(dockercomposeps-q$JENKINS_SERVICE_NAME2/dev/null)if[-n$container_id];thenecho当前容器内 PID 1 的限制:dockerexec$container_idcat/proc/1/limits2/dev/null|grepopen files||truefiecho宿主机限制: ulimit -n 当前值:$(ulimit-n)# 手工验证若容器无法启动可临时以 --ulimit nofile65536 启动测试。echo-e\n 6.4 系统时间与时钟同步timedatectl status2/dev/null|grepSystem clock||true# 时间不同步可能导致 SSL 证书、Kerberos 等认证失败。}# # 总结与后续建议# summary_and_recommendations(){header故障排查总结echo以上各步已完成。请根据输出中的 [ERROR] 和 [WARN] 信息定位问题。echoecho通用恢复流程按需选择echo 1. 紧急恢复: 修复明显错误后执行 docker compose up -decho 2. 若配置错误: 修改 docker-compose.yml 后重建 docker compose up -d --force-recreateecho 3. 数据损坏: 从备份恢复关键 XML 文件或暂时移除损坏作业目录echoecho长期预防建议哲学升华echo - 整体论: 部署 Prometheus Grafana cAdvisor 全面监控。echo - 无为: 配置 healthcheck、restart 策略和资源限制实现自愈。echo - 奥卡姆剃刀: 清理未使用插件和旧构建保持系统精简。echo - 本体论: 定期备份$JENKINS_HOME并验证 XML 完整性。echo - 实用主义: 建立故障手册将本次诊断脚本加入 CI 自动巡检。}# # 主函数# main(){echoJenkins 服务故障系统化排查脚本 (哲学增强版)echo开始时间:$(date)echo目标 Compose 目录:$COMPOSE_DIRechoJenkins 数据卷:$JENKINS_HOME_HOSTechopreflight step1_holistic_overview step2_self_healing_check step3_occam_razor step4_ontology_check step5_compose_dialectic step6_system_kernel summary_and_recommendations}main$