来源：哇哈哈12138 | 发布日期：2026-05-20

Jenkins + Ansible 集成实战：把配置管理焊进流水线里

概述

Jenkins 做调度中心（触发时机、参数管理、流程编排、结果通知），Ansible 做执行引擎（在目标机器上干活）。集成后实现配置即代码（Configuration as Code）的 CI/CD 工作流。本文基于 Ubuntu 24.04 LTS 环境。

环境准备

安装 Ansible

Ubuntu 24.04 仓库自带 Ansible，版本够用；也可用 pip 安装新版。

sudo apt update
sudo apt install ansible -y
ansible --version  # 验证

安装 Jenkins（官方源）

需 JDK 17+，从官方仓库装而非系统仓库：

sudo apt install openjdk-17-jdk -y
curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key | sudo tee /usr/share/keyrings/jenkins-keyring.asc > /dev/null
echo "deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] https://pkg.jenkins.io/debian-stable binary/" | sudo tee /etc/apt/sources.list.d/jenkins.list > /dev/null
sudo apt update && sudo apt install jenkins -y
sudo systemctl enable --now jenkins

SSH 免密配置

Jenkins 运行用户 jenkins 需能免密 SSH 到被管节点：

sudo su - jenkins -s /bin/bash
ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519
ssh-copy-id -i ~/.ssh/id_ed25519.pub [email protected]

⚠️ Ubuntu 24 的 ssh-copy-id 对 ED25519 密钥偶有抽风，失败时手动追加公钥到目标机器 ~/.ssh/authorized_keys。目标机器需确认 PubkeyAuthentication yes。

集成配置四步走

① 插件安装

管理 Jenkins → 插件管理 → 搜索安装 Ansible plugin（官方维护）。重启后验证 Global Tool Configuration 中出现 Ansible 配置区域。

② 全局工具配置

管理 Jenkins → Global Tool Configuration → Ansible 区域：

• 名称：如 ansible-ubuntu24
• 路径：Ansible 可执行文件所在目录（which ansible 输出 /usr/bin/ansible，则路径填 /usr/bin）

支持多版本 Ansible（通过 virtualenv 隔离），路径填虚拟环境的 bin/ 目录即可。

③ 项目结构 — Playbook 进 Git

ansible-config-repo/
├── inventory/         # dev.ini, staging.ini, prod.ini
├── group_vars/        # 按环境变量文件
├── playbooks/         # init-env.yml, deploy-app.yml
├── roles/             # common/, nginx/, java/
├── ansible.cfg
└── Jenkinsfile

ansible.cfg 建议放仓库根目录，Ansible 自动优先读取：

[defaults]
inventory = inventory/prod.ini
host_key_checking = False
forks = 20
timeout = 30
log_path = /var/log/ansible.log

[privilege_escalation]
become = True
become_method = sudo

④ Pipeline 代码化

核心 Jenkinsfile 模板（支持参数化构建）：

pipeline {
    agent any

    parameters {
        choice(name: 'ENV', choices: ['dev', 'staging', 'prod'], description: '目标环境')
        string(name: 'VERSION', defaultValue: 'latest', description: '部署版本号')
        choice(name: 'TAGS', choices: ['all', 'deploy', 'config', 'restart'], description: '执行标签')
        booleanParam(name: 'DRY_RUN', defaultValue: false, description: '是否试运行')
    }

    environment {
        ANSIBLE_DIR = "ansible-config-repo"
    }

    stages {
        stage('拉取 Playbook 仓库') {
            steps { git branch: 'main', url: 'https://your-repo/ansible-config-repo.git' }
        }
        stage('语法检查') {
            steps {
                sh """
                    cd ${ANSIBLE_DIR}
                    ansible-playbook playbooks/deploy-app.yml \
                        --syntax-check \
                        --inventory inventory/${params.ENV}.ini
                """
            }
        }
        stage('执行 Playbook') {
            steps {
                script {
                    def extraArgs = ""
                    if (params.TAGS != 'all') { extraArgs += " --tags ${params.TAGS}" }
                    if (params.DRY_RUN) { extraArgs += " --check --diff" }
                    ansiblePlaybook(
                        playbook: "${ANSIBLE_DIR}/playbooks/deploy-app.yml",
                        inventory: "${ANSIBLE_DIR}/inventory/${params.ENV}.ini",
                        extraVars: [env: "${params.ENV}", version: "${params.VERSION}"],
                        extraArgs: extraArgs,
                        colorized: true
                    )
                }
            }
        }
        stage('执行结果通知') {
            steps { echo "部署完成，环境：${params.ENV}，版本：${params.VERSION}" }
        }
    }
    post {
        failure { echo "❌ Playbook 执行失败，请检查日志！" }
    }
}

参数说明：

• ENV：控制目标环境（dev/staging/prod），一套 Pipeline 覆盖全线
• TAGS：控制 Ansible 执行哪些标签任务
• DRY_RUN：试运行开关，--check --diff 组合模拟执行不实际修改
• extraVars：Jenkins 参数注入 Ansible 变量（{{ env }}、{{ version }}）

踩坑实录

生产铁律

1. Playbook 必须走 Git — 版本可追溯，变更可回滚
2. 测试环境验证完再上生产 — 生产 Job 加人工审批环节，挡住 80% 低级错误
3. 敏感信息用 Ansible Vault — ansible-vault encrypt 加密，Jenkins 凭据管理存密码，vaultCredentialsId 参数传递
4. 定期清理过期 Inventory — 机器下线同步更新；或用动态 Inventory（CMDB/云 API 自动拉取）

关联页面

参考来源

• 哇哈哈12138. Jenkins + Ansible 集成实战：把配置管理焊进流水线里. 公众号：耕云躬行录, 2026-05-20.