Handlers 是 Ansible 中延迟触发的特殊任务,仅在被 notify 且对应 task 标记 changed 时,于 play 结束前统一执行一次;而普通 task 每次运行都执行,无变更感知与去重机制。

Handlers 是什么,和普通 task 有什么区别
Handlers 就是 Ansible 里的“延迟触发任务”,只在被 notify 且实际发生了变更时才执行。它不是每次运行都跑,也不是写在哪就从上到下执行——这点和普通 task 有本质区别。如果你把重启服务写成普通 task,哪怕配置没变,每次 play 都会重启,这在生产环境是危险的。
- Handler 必须定义在
handlers:区块里,且名字必须和notify:后的字符串完全一致(包括空格和大小写) - 一个 task 可以
notify多个 handler,但同一个 handler 在一次 play 中只执行一次,哪怕被多次 notify - Handler 的执行时机是整个 play 结束前的「handler flush 阶段」,不是紧跟在 notify 它的 task 后面
写一个能真正触发重启的 handler 示例
关键不在“怎么写 restart”,而在于“怎么让 Ansible 认为配置变了”。比如用 copy 或 template 更新了 Nginx 配置文件后,才该重启 nginx:
- name: Deploy nginx config
template:
src: nginx.conf.j2
dest: /etc/nginx/nginx.conf
notify: restart nginx
<p>handlers:</p><ul><li>name: restart nginx
service:
name: nginx
state: restarted注意:
-
service模块用state: restarted而不是restarted(后者会报错) - 如果目标系统是 systemd,
service模块底层调用的是systemctl,没问题;但若用command直接跑systemctl restart nginx,Ansible 就无法感知服务是否真重启成功,也失去幂等性 - 不要用
state: reloaded代替,reload 和 restart 行为不同(比如某些 daemon 不支持 reload,或 reload 不重读所有配置项)
为什么改了配置却没触发 handler
这是最常踩的坑,根本原因通常是:Ansible 判断“没变更”,所以跳过 notify。
常见情况包括:
- 源模板或文件内容和目标文件完全一致(比如 jinja2 变量没变、注释没动、空行/缩进差异被忽略)→ Ansible 不标记 changed,自然不 notify
- 用了
copy但忘了加force: yes(默认force: yes,但若源文件时间戳旧于目标,且内容相同,仍不会 changed) -
template中用了lookup('file', ...)等动态内容,但 lookup 结果没变 → 整体渲染结果不变 - handler 名字拼错,比如
notify: Restart nginx对应name: restart nginx(大小写不匹配)
验证方法:加 -v 运行,看对应 task 输出里有没有 changed: [host];没有,就说明 handler 根本不会触发。
多个服务依赖同一配置时怎么安全重启
比如更新了一个通用配置片段,影响 nginx 和 haproxy,但你希望先 reload nginx,再 reload haproxy,且中间不能有失败中断。
- 不能靠顺序定义 handler,因为所有 handler 统一在最后批量执行,且无序
- 正确做法:用单个 handler 做串行操作,或拆成两个独立 notify
- name: Deploy shared config
copy:
src: common.conf
dest: /etc/shared.conf
notify:
- reload nginx
- reload haproxy
<p>handlers:</p><ul><li><p>name: reload nginx
service:
name: nginx
state: reloaded</p></li><li><p>name: reload haproxy
service:
name: haproxy
state: reloaded</p>注意:如果其中一个 reload 失败(比如 haproxy 配置语法错),整个 play 会失败,nginx 的 reload 不会回滚——Ansible 没事务。所以更稳妥的是:把高风险 reload 放在单独 play,或用 ignore_errors: yes + 后续检查,但得自己承担后果。
Handler 的设计初衷就是“最小化扰动”,它不负责编排复杂依赖,只负责“变了就做一次”。真要控制顺序或失败策略,得靠 play 划分或 block/rescue。

















