服务器Ansible主机清单怎么组织,如何支持分组变量和批量执行?
首次部署时,建议把 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-01 | 192.0.2.21 | 第一台 Web 服务器 |
| Web 节点 | web-02 | 192.0.2.22 | 第二台 Web 服务器 |
| 数据库节点 | db-01 | 192.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 仓库中:

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:
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.yml | Web 节点共用参数 | 软件包、服务名、站点目录 |
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 中写入:

---
- 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 的关键点有三个:
hosts: web只作用于 Web 组,不会误操作db组;serial默认是 1,先部署一台,验证成功后再继续下一台;- 页面模板失败或本地 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: productionrelease: stableversion: 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 --graph | Web、DB 归属正确 |
| SSH 连接 | ansible web -m ping | 每台返回 pong |
| 软件包 | dpkg -l nginx cron | 两个软件包已安装 |
| 服务状态 | systemctl is-active | Nginx 和 Cron 为 active |
| 页面版本 | uri 或本机 curl | HTTP 200 且包含发布版本 |
| 分组变量 | 页面内容或 debug | Web 节点加载 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 验证。如果后续任务失败:

- 目标文件原本存在时,优先恢复
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