18.8.4 存储与数据目录规划（JENKINS_HOME）

JENKINS_HOME 是 Jenkins 核心数据目录，包含配置、作业、插件、凭据、日志与构建产物。规划得当可提升可用性、I/O 性能与备份效率，并降低迁移风险。

原理草图（JENKINS_HOME 与存储分层）

目录结构与关键数据
- config.xml：全局配置，恢复后可重建大部分系统设置。
- jobs/：作业配置与构建历史，增长最快。
- plugins/：插件与依赖，影响启动与兼容性。
- secrets/、credentials.xml：密钥与凭据，必须加密备份。
- workspace/：构建工作区，适合独立盘或快速存储。
- logs/：系统与作业日志，建议日志轮转。
- fingerprints/：制品指纹索引，规模大时需清理。

存储规划原则（含示例）
1. 容量规划：计算增长率，预留 6–12 个月空间。
2. 性能优化：SSD 优先，workspace/ 高 IOPS 盘。
3. 可靠性：RAID/分布式存储 + 快照。
4. 分层存储：产物推送制品库，减少本地占用。
5. 权限一致：Jenkins 运行用户拥有读写。

安装与目录迁移示例（systemd）#

目标：将 JENKINS_HOME 从默认目录迁移到 /data/jenkins，并修正权限与服务配置。

# 1) 停止服务，确保数据一致
sudo systemctl stop jenkins

# 2) 创建新目录并迁移数据
sudo mkdir -p /data/jenkins
sudo rsync -aHS --info=progress2 /var/lib/jenkins/ /data/jenkins/

# 3) 设置权限（以 jenkins 用户为准）
sudo chown -R jenkins:jenkins /data/jenkins

# 4) 修改 systemd 环境变量
# /etc/default/jenkins 或 /etc/sysconfig/jenkins
sudo sed -i 's#^JENKINS_HOME=.*#JENKINS_HOME=/data/jenkins#' /etc/default/jenkins

# 5) 重新加载并启动
sudo systemctl daemon-reload
sudo systemctl start jenkins
sudo systemctl status jenkins -l

关键命令解释
- rsync -aHS：保留权限/硬链接/稀疏文件，避免构建历史损坏。
- sed：修改默认配置文件中的 JENKINS_HOME 路径。
- systemctl status：确认服务启动与路径生效。

容器化部署示例（Docker）#

# 1) 创建持久化目录
mkdir -p /data/jenkins

# 2) 启动容器并绑定 JENKINS_HOME
docker run -d --name jenkins \
  -p 8080:8080 -p 50000:50000 \
  -v /data/jenkins:/var/jenkins_home \
  -u root \
  jenkins/jenkins:lts

# 3) 验证数据落盘
ls -l /data/jenkins

说明
- -v /data/jenkins:/var/jenkins_home：将宿主机目录绑定到容器内 JENKINS_HOME。
- -u root 仅用于首次安装插件与修正权限，后续建议使用 Jenkins 用户。

Kubernetes 持久卷示例（PV/PVC）#

# jenkins-pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: jenkins-home-pvc
spec:
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 100Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: jenkins
spec:
  replicas: 1
  selector:
    matchLabels:
      app: jenkins
  template:
    metadata:
      labels:
        app: jenkins
    spec:
      containers:
        - name: jenkins
          image: jenkins/jenkins:lts
          ports:
            - containerPort: 8080
          volumeMounts:
            - name: jenkins-home
              mountPath: /var/jenkins_home
      volumes:
        - name: jenkins-home
          persistentVolumeClaim:
            claimName: jenkins-home-pvc

备份与恢复（命令可执行）#

备份脚本

# /opt/backup/jenkins_backup.sh
#!/usr/bin/env bash
set -euo pipefail
TS=$(date +%F_%H%M%S)
SRC=/data/jenkins
DST=/backup/jenkins
mkdir -p "$DST"

# 停止服务确保一致性（可结合维护窗口）
systemctl stop jenkins

tar -czf "$DST/jenkins_home_$TS.tar.gz" \
  --exclude='workspace/*' \
  --exclude='logs/*' \
  -C "$SRC" .

systemctl start jenkins
echo "Backup done: $DST/jenkins_home_$TS.tar.gz"

恢复示例

systemctl stop jenkins
tar -xzf /backup/jenkins/jenkins_home_2024-01-01_010101.tar.gz -C /data/jenkins
chown -R jenkins:jenkins /data/jenkins
systemctl start jenkins

常见问题与排错#

启动报错：Permission denied

# 解决：修正权限并重启
sudo chown -R jenkins:jenkins /data/jenkins
sudo systemctl restart jenkins

NFS 共享存储构建卡顿
- 症状：构建耗时升高、日志提示锁等待。
- 处理：使用本地 SSD 作为 workspace/，NFS 仅存放 jobs/ 与 config。
磁盘爆满导致构建失败

# 清理旧工作区（示例）
find /data/jenkins/workspace -maxdepth 1 -type d -mtime +7 -exec rm -rf {} \;

# 检查空间
df -h /data/jenkins

清理与归档策略（含配置示例）#

作业级构建保留策略

Jenkins Job -> Configure -> Discard old builds
- Days to keep builds: 14
- Max # of builds to keep: 50

系统级 Workspace 清理（插件）
- 插件：Workspace Cleanup Plugin
- 示例：构建后清理 workspace，保留最近 1 次构建

练习题#

将默认 JENKINS_HOME 迁移到 /data/jenkins 并验证构建历史未丢失。
使用 tar 备份并恢复 jobs/，验证作业配置是否完整。
模拟磁盘满（创建大文件），观察 Jenkins 日志并制定清理策略。
在 Docker 中部署 Jenkins 并持久化数据，重启容器验证数据保留。