服务器Ansible主机清单怎么组织,如何支持分组变量和批量执行?

发布人:A5数据发布时间:2026-10-30 09:09阅读量:79

首次部署时,建议把 Ansible 主机清单拆成三层:清单文件只描述服务器拓扑,group_vars 管理分组配置,host_vars 只保存单台服务器的例外参数。批量执行时再通过 --limit 选择目标范围,用 playbook 中的 serial 控制滚动批次,这样既能重复部署,也能在单台服务器失败时暂停后续发布。

下面以 Ansible 控制端管理 3 台 Ubuntu 22.04/24.04 服务器为例:web-01、web-02 提供 Web 服务,db-01 作为数据库节点。示例会完成清单组织、分组变量加载、Nginx 和定时任务部署、分批执行、审计记录、失败处理及配置回滚。

一、准备条件与实施边界

1. 控制端和被管理服务器

本例使用以下环境:

角色主机名示例地址用途
Ansible 控制端control管理端本地执行 Ansible 命令
Web 节点web-01192.0.2.21第一台 Web 服务器
Web 节点web-02192.0.2.22第二台 Web 服务器
数据库节点db-01192.0.2.31数据库服务器,仅加入清单示例

要求如下:

  • 控制端可以通过 SSH 访问所有被管理服务器;
  • 被管理服务器已经创建 deploy 用户,并具备执行 sudo 的权限;
  • 被管理服务器安装了 Python 3;
  • 控制端保存用于 SSH 登录的私钥;
  • 首次部署使用干净测试机,或者确认 /var/www/html/index.html 可以由本次 playbook 接管。

示例使用 Ubuntu/Debian 的 apt、nginx 和 cron。如果被管理服务器是 Rocky Linux、AlmaLinux 或其他发行版,需要将软件安装任务改为对应的 dnf 或 yum,并核对服务名是否为 crond。

控制端可以先安装 Ansible:

sudo apt-get update
sudo apt-get install -y ansible-core openssh-client
ansible-playbook --version

预期能看到 Ansible Core 版本及 Python 版本。具体版本以控制端软件源为准,首次部署时应在测试节点先完成一次验证。

2. 验证 SSH 和 Python

首次连接时,建议通过人工方式确认服务器指纹,不要为了跳过确认而关闭 SSH 主机密钥检查。

ssh -i ~/.ssh/id_ed25519 deploy@192.0.2.21 'python3 --version'
ssh -i ~/.ssh/id_ed25519 deploy@192.0.2.22 'python3 --version'
ssh -i ~/.ssh/id_ed25519 deploy@192.0.2.31 'python3 --version'

如果使用了不同的 SSH 用户、端口或私钥,应在清单中明确配置,不能依赖执行人员的临时环境。

3. 建立项目目录

建议把清单、变量、模板和 playbook 放在同一个 Git 仓库中:

一、准备条件与实施边界 / 3. 建立项目目录配图

ansible-project/
├── ansible.cfg
├── inventory/
│   └── production/
│       ├── hosts.yml
│       ├── group_vars/
│       │   ├── all.yml
│       │   ├── production.yml
│       │   └── web.yml
│       └── host_vars/
│           └── web-01.yml
├── playbooks/
│   └── site.yml
├── templates/
│   └── index.html.j2
└── logs/

创建目录:

mkdir -p ansible-project/inventory/production/group_vars
mkdir -p ansible-project/inventory/production/host_vars
mkdir -p ansible-project/playbooks
mkdir -p ansible-project/templates
mkdir -p ansible-project/logs
cd ansible-project

二、组织 Ansible 主机清单

1. 使用 YAML 描述主机和分组

在 inventory/production/hosts.yml 中写入:

从上到下展示 all → production → web 和 db 的层级关系;web 下连接 web-01 与 web-02,分别标注 192.0.2.21

all:
  children:
    production:
      children:
        web:
          hosts:
            web-01:
              ansible_host: 192.0.2.21
            web-02:
              ansible_host: 192.0.2.22
        db:
          hosts:
            db-01:
              ansible_host: 192.0.2.31

这里有三层关系:

  • all 是 Ansible 内置顶层组;
  • production 表示生产环境,下面可以继续包含多个业务分组;
  • web 和 db 是按服务器职责划分的子组。

ansible_host 是实际连接地址,主机名则作为 Ansible 内部标识。这样即使服务器 IP 发生变化,也只需要修改清单,不需要修改 playbook 中的业务逻辑。

如果 SSH 用户不是 deploy,可以在主机或组中添加:

ansible_user: ops

如果 SSH 使用非标准端口,可以添加:

ansible_port: 2222

不建议把 SSH 密码、数据库密码或 API 密钥直接写入 hosts.yml。

2. 设置默认配置和分组变量

inventory/production/group_vars/all.yml 用于所有主机共享的变量:

ansible_python_interpreter: /usr/bin/python3

app_name: "example-web"
deploy_version: "bootstrap"
deployment_environment: "production"
release_channel: "stable"

inventory/production/group_vars/production.yml 用于生产环境的公共参数:

deployment_owner: "operations"
audit_enabled: true

inventory/production/group_vars/web.yml 只对 web 组生效:

web_root: /var/www/html
http_port: 80

web_packages:
  - nginx
  - cron

web_service: nginx
cron_service: cron

inventory/production/host_vars/web-01.yml 用于单台主机的差异:

node_note: "primary"

如果 web-02 没有对应的 host_vars 文件,它会继承 all.yml、production.yml 和 web.yml 中的变量。

变量的常见使用边界如下:

文件位置适合保存的内容示例
hosts.yml主机地址、主机归属、连接参数ansible_host、ansible_port
group_vars/all.yml所有服务器通用参数Python 路径、应用名称
group_vars/web.ymlWeb 节点共用参数软件包、服务名、站点目录
group_vars/production.yml环境级参数环境名称、发布通道
host_vars/主机名.yml单机例外配置节点角色、特殊端口

变量覆盖时,主机变量通常优先于组变量,命令行传入的 -e 变量优先级更高。例如执行时传入 -e "deploy_version=release-2025-03-01",会覆盖 all.yml 中的默认版本。

3. 配置 Ansible 默认行为

在项目根目录创建 ansible.cfg:

[defaults]
inventory = ./inventory/production/hosts.yml
remote_user = deploy
private_key_file = ~/.ssh/id_ed25519
host_key_checking = True
forks = 10
interpreter_python = auto_silent

先确认当前目录下的配置文件已生效:

ansible-config dump --only-changed

预期能看到项目中的 inventory、remote_user 或 private_key_file 配置。若没有生效,先检查当前执行目录和 ANSIBLE_CONFIG 环境变量。

三、编写首次部署 Playbook

本例使用一个简单页面验证变量是否正确下发,同时安装 Nginx 和定时任务。页面文件由模板生成,定时任务每 5 分钟写入心跳日志,便于验证配置管理结果。

1. 创建模板文件

在 templates/index.html.j2 中写入:

<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <title>{{ app_name }}</title>
</head>
<body>
  <h1>{{ app_name }}</h1>
  <p>environment: {{ deployment_environment }}</p>
  <p>release: {{ release_channel }}</p>
  <p>version: {{ deploy_version }}</p>
  <p>node: {{ inventory_hostname }}</p>
  <p>note: {{ node_note | default('default') }}</p>
</body>
</html>

模板中同时使用了全局变量、环境变量、Web 分组变量间接提供的配置,以及主机变量。部署到 web-01 和 web-02 后,页面中的 node 和 note 应该不同。

2. 创建 Playbook

在 playbooks/site.yml 中写入:

三、编写首次部署 Playbook / 2. 创建 Playbook配图

---
- name: Configure web servers
  hosts: web
  become: true
  gather_facts: true
  serial: "{{ rollout_batch | default(1) }}"
  any_errors_fatal: true

  tasks:
    - name: Verify supported operating system
      ansible.builtin.assert:
        that:
          - ansible_facts.os_family == "Debian"
        fail_msg: "This example expects a Debian-family operating system."

    - name: Deploy web service and scheduled task
      block:
        - name: Install required packages
          ansible.builtin.apt:
            name: "{{ web_packages }}"
            state: present
            update_cache: true
            cache_valid_time: 3600

        - name: Ensure web root exists
          ansible.builtin.file:
            path: "{{ web_root }}"
            state: directory
            owner: root
            group: root
            mode: "0755"

        - name: Check whether the current page exists
          ansible.builtin.stat:
            path: "{{ web_root }}/index.html"
          register: page_before

        - name: Render application page
          ansible.builtin.template:
            src: index.html.j2
            dest: "{{ web_root }}/index.html"
            owner: root
            group: root
            mode: "0644"
            backup: true
          register: page_deploy

        - name: Configure heartbeat cron task
          ansible.builtin.cron:
            name: "example-web-heartbeat"
            user: root
            minute: "*/5"
            job: "/usr/bin/date -Is >> /var/log/example-web-heartbeat.log 2>&1"

        - name: Ensure web service is enabled and running
          ansible.builtin.service:
            name: "{{ web_service }}"
            enabled: true
            state: started

        - name: Ensure cron service is enabled and running
          ansible.builtin.service:
            name: "{{ cron_service }}"
            enabled: true
            state: started

        - name: Verify local HTTP response
          ansible.builtin.uri:
            url: "http://127.0.0.1:{{ http_port }}/"
            status_code: 200
            return_content: true
          register: http_check
          changed_when: false
          failed_when: >
            (http_check.status | default(0) != 200) or
            (deploy_version not in (http_check.content | default('')))
          when: not ansible_check_mode

      rescue:
        - name: Restore previous page from Ansible backup
          ansible.builtin.copy:
            src: "{{ page_deploy.backup_file }}"
            dest: "{{ web_root }}/index.html"
            remote_src: true
            owner: root
            group: root
            mode: "0644"
          when:
            - page_deploy is defined
            - page_deploy.backup_file is defined

        - name: Remove page created by a failed first deployment
          ansible.builtin.file:
            path: "{{ web_root }}/index.html"
            state: absent
          when:
            - page_before is defined
            - page_deploy is defined
            - page_deploy.changed | default(false) | bool
            - page_deploy.backup_file is not defined
            - not (page_before.stat.exists | default(false) | bool)

        - name: Ensure web service remains started after rollback
          ansible.builtin.service:
            name: "{{ web_service }}"
            state: started

        - name: Stop the play after rollback
          ansible.builtin.fail:
            msg: "Deployment failed. Managed page content was rolled back where possible."

这个 playbook 的关键点有三个:

  1. hosts: web 只作用于 Web 组,不会误操作 db 组;
  2. serial 默认是 1,先部署一台,验证成功后再继续下一台;
  3. 页面模板失败或本地 HTTP 验证失败时,rescue 会尝试恢复 Ansible 自动生成的备份。

backup: true 只对模板目标文件提供备份,不会自动撤销已经安装的软件包,也不会删除其他不由本 playbook 管理的文件。因此,软件包、系统服务和应用文件应分别定义回滚边界。

四、检查清单、变量和连接状态

1. 查看主机分组

ansible-inventory --graph

预期结构类似:

@all:
  |--@production:
  |  |--@db:
  |  |  |--db-01
  |  |--@web:
  |  |  |--web-01
  |  |  |--web-02

查看单台服务器的连接地址和主机变量:

ansible-inventory --host web-01

示例输出:

{
    "ansible_host": "192.0.2.21",
    "node_note": "primary"
}

如果主机没有出现在 ansible-inventory --graph 中,先修正清单结构,不要直接执行部署。

2. 验证连接和分组范围

先查看 Web 组包含哪些服务器:

ansible web --list-hosts

再执行 Ansible 的连接测试:

ansible web -m ansible.builtin.ping

预期每台服务器返回:

web-01 | SUCCESS => {
    "changed": false,
    "ping": "pong"
}

如果需要检查全部清单主机:

ansible all -m ansible.builtin.ping

这一步只验证 SSH、Python 和 Ansible 基本通信,不会安装软件或修改配置。

3. 使用 Check Mode 预演

首次运行先针对一台 Web 服务器执行:

ansible-playbook playbooks/site.yml \
  --limit web-01 \
  --check \
  --diff

重点检查:

  • 目标是否只有 web-01;
  • web_packages 是否正确加载;
  • 模板中的 deployment_environment、deploy_version 和 node_note 是否符合预期;
  • 是否出现未定义变量;
  • --diff 是否展示了不应修改的文件。

Check Mode 只用于预测变更,不能代替真实服务验证。示例中的 HTTP 检查在 --check 时会跳过,必须在实际执行后再验证。

五、按批次执行和保存审计记录

1. 先执行单台节点

将第一台服务器作为金丝雀节点:

set -o pipefail
run_id=$(date +%Y%m%d-%H%M%S)

ansible-playbook playbooks/site.yml \
  --limit web-01 \
  -e "deploy_version=release-2025-03-01" \
  2>&1 | tee "logs/${run_id}-web-01.log"

这里的版本号是示例值,用于确认模板内容确实是本次发布生成的版本。命令执行结束后,先检查日志中的 failed=0 和最终状态,再继续下一台。

2. 批量执行 Web 节点

确认 web-01 验证成功后,可以对整个 Web 组执行:

set -o pipefail
run_id=$(date +%Y%m%d-%H%M%S)

ansible-playbook playbooks/site.yml \
  --limit web \
  -e "rollout_batch=1" \
  -e "deploy_version=release-2025-03-01" \
  2>&1 | tee "logs/${run_id}-web.log"

serial 和 forks 的作用不同:

参数作用本例中的含义
--limit选择目标主机范围只执行 web
serial控制滚动批次大小1 表示一次一台
forks控制 Ansible 并发工作进程数影响并行执行能力
any_errors_fatal发生致命错误时停止当前 play防止错误继续扩散

如果 Web 节点数量较多,并且已经验证单台部署流程,可以使用两台一批:

ansible-playbook playbooks/site.yml \
  --limit web \
  -e "rollout_batch=2" \
  -e "deploy_version=release-2025-03-01"

即使 forks 设置为 10,只要 rollout_batch=1,本 playbook 仍会按照一台一台的方式执行。生产环境通常先使用小批次,确认服务指标和页面响应正常后再扩大批量。

3. 只执行指定节点或排除节点

只执行一台服务器:

ansible-playbook playbooks/site.yml \
  --limit web-02 \
  -e "deploy_version=release-2025-03-01"

执行 Web 组但排除一台服务器:

ansible-playbook playbooks/site.yml \
  --limit 'web:!web-02' \
  -e "deploy_version=release-2025-03-01"

--limit 是批量执行的重要安全边界。涉及数据库、缓存或其他高风险分组时,不应仅依靠操作人员口头确认,应在命令中明确目标组。

六、每一步的结果验证

1. 验证服务状态

ansible web -b -m ansible.builtin.shell \
  -a 'systemctl is-active nginx && systemctl is-active cron'

预期每台主机返回:

active
active

如果返回 inactive 或 failed,先不要扩大批次,使用以下命令查看服务日志:

ansible web-01 -b -m ansible.builtin.command \
  -a 'systemctl status nginx --no-pager'

2. 验证页面内容

ansible web -b -m ansible.builtin.uri \
  -a 'url=http://127.0.0.1:80/ status_code=200 return_content=true'

返回内容中应能看到对应的:

  • environment: production
  • release: stable
  • version: release-2025-03-01
  • 当前主机的 inventory_hostname

如果页面版本正确但节点名称不一致,优先检查 host_vars 文件名是否与清单中的主机名完全一致。

3. 验证定时任务

ansible web -b -m ansible.builtin.shell \
  -a "crontab -l -u root | grep -F 'example-web-heartbeat'"

等待一个执行周期后,检查心跳日志:

ansible web -b -m ansible.builtin.shell \
  -a 'tail -n 3 /var/log/example-web-heartbeat.log'

预期能看到类似以下格式的时间:

2025-03-01T10:05:00+00:00

这是示例输出,不代表实际执行记录。

4. 验收检查项

检查项验证方式通过条件
清单分组ansible-inventory --graphWeb、DB 归属正确
SSH 连接ansible web -m ping每台返回 pong
软件包dpkg -l nginx cron两个软件包已安装
服务状态systemctl is-activeNginx 和 Cron 为 active
页面版本uri 或本机 curlHTTP 200 且包含发布版本
分组变量页面内容或 debugWeb 节点加载 web.yml
主机变量页面内容web-01 显示 primary
定时任务crontab -l -u root任务表达式存在
审计记录logs/有本次执行日志且失败数为 0

七、常见异常和处理方式

1. UNREACHABLE 或 SSH 认证失败

先单独测试:

ssh -vv -i ~/.ssh/id_ed25519 deploy@192.0.2.21

重点检查:

  • ansible_host 是否为正确地址;
  • SSH 用户和私钥是否匹配;
  • 服务器 22 端口是否可达;
  • deploy 用户是否存在;
  • 主机密钥是否发生变化。

不要直接设置 host_key_checking = False,也不要使用跳过主机指纹校验的方式掩盖地址或密钥错误。

2. sudo 权限失败

使用以下命令验证提权:

ssh deploy@192.0.2.21 'sudo -n true'

如果服务器要求输入 sudo 密码,可以在执行 playbook 时使用:

ansible-playbook playbooks/site.yml --limit web-01 --ask-become-pass

首次部署不建议把 sudo 密码写入清单或普通文本变量。

3. 变量未定义或变量值不生效

按以下顺序检查:

ansible-inventory --host web-01
ansible-inventory --graph
ansible-playbook playbooks/site.yml --limit web-01 --check -vv

常见原因是:

  • group_vars 放错目录;
  • 文件名不是组名,例如写成 webservers.yml,但清单组名实际是 web;
  • host_vars 文件名与清单主机名不一致;
  • 命令行中的 -e 覆盖了文件变量;
  • YAML 缩进错误。

4. 软件包安装阶段失败

如果出现 apt 锁冲突,不要直接终止正在运行的系统更新进程,也不要删除锁文件。先检查:

ansible web-01 -b -m ansible.builtin.shell \
  -a 'ps -ef | grep -E "apt|dpkg" | grep -v grep'

确认没有其他包管理任务后,再查看服务和系统日志,等待自动更新结束后重试:

ansible-playbook playbooks/site.yml \
  --limit web-01 \
  -e "deploy_version=release-2025-03-01"

5. HTTP 验证失败

如果 Nginx 服务是 active,但 HTTP 返回不是 200,继续检查:

ansible web-01 -b -m ansible.builtin.shell \
  -a 'ss -lntp | grep ":80"'

可能原因包括:

  • 80 端口被其他服务占用;
  • Nginx 默认配置被修改;
  • http_port 与实际监听端口不一致;
  • /var/www/html/index.html 没有被正确写入;
  • 防火墙或本机安全策略阻止访问。

先在服务器本机使用 127.0.0.1 验证,再从外部验证,避免把网络路径问题误判成 Ansible 部署失败。

八、失败后的回滚处理

1. Playbook 内置回滚

本例在模板写入后执行服务和 HTTP 验证。如果后续任务失败:

八、失败后的回滚处理 / 1. Playbook 内置回滚配图

  • 目标文件原本存在时,优先恢复 template 模块生成的备份;
  • 首次部署且目标文件原本不存在时,删除本次创建的页面文件;
  • 保持 Nginx 服务处于启动状态;
  • 通过 any_errors_fatal: true 停止后续主机继续发布。

该回滚只覆盖本 playbook 管理的页面文件,不会自动卸载 Nginx、Cron,也不会撤销其他系统配置。

2. 成功发布后的人工回滚

如果本次 playbook 已成功结束,但业务验证后仍需要恢复上一版,先查看指定主机上的备份文件:

ansible web-01 -b -m ansible.builtin.shell \
  -a "find /var/www/html -maxdepth 1 -type f -name 'index.html.*' -printf '%T@ %p\n' | sort -nr | head"

确认备份文件路径后,再对单台主机恢复,不能直接使用未经确认的通配符:

ansible web-01 -b -m ansible.builtin.copy \
  -a "src=/var/www/html/index.html.2025-03-01@100500 dest=/var/www/html/index.html remote_src=true"

上面的备份文件名仅为示例,应替换为目标服务器上实际确认过的路径。恢复后重新执行:

ansible-playbook playbooks/site.yml \
  --limit web-01 \
  --check \
  --diff

如果备份不存在,推荐从 Git 中恢复上一版模板或变量,再使用相同的 playbook 重新部署,而不是直接在服务器上手工修改文件。这样回滚动作仍然可审计、可重复。

3. 需要注意的回滚边界

  • 页面文件可以通过备份恢复;
  • 软件包安装通常不自动卸载,避免误删其他服务依赖;
  • 清单地址和 SSH 连接配置不应跟随应用版本盲目回滚;
  • 数据库结构、数据文件和不可逆迁移不能使用本例的文件备份方式处理;
  • 任何删除或覆盖操作,都应先确认目标路径和影响主机,并保留执行日志。

九、上线验收与留档

首次部署完成后,应至少保留以下内容:

  • 本次使用的 Git 提交号;
  • hosts.yml 和分组变量版本;
  • 实际执行的 --limit、serial 和发布版本;
  • logs/ 中的 Ansible 输出;
  • 单台验证和批量验证结果;
  • 失败时生成的备份文件路径;
  • 如发生回滚,记录回滚主机、文件、时间和恢复结果。

当清单、变量、模板和 playbook 都纳入版本控制后,新增服务器只需要加入对应组并补充必要的主机变量;批量执行则通过 --limit 和 serial 控制范围与节奏。最终验收应确认清单拓扑正确、分组变量已加载、服务和定时任务正常、执行日志完整,并且在失败时能够恢复到上一份受控配置。

Ansible 清单、分组变量和批量执行能够帮助统一管理服务器配置;A5idc数据提供香港、美国、日本、韩国、中国台湾、新加坡及马来西亚等地区的物理服务器,涵盖常规建站、AMD 计算、存储及多 IP 等产品系列。不同配置可对应网站、业务后台、数据库和多任务运行等场景,为按地区和业务角色划分主机、组织自动化部署提供硬件与网络资源基础。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/6487.html