run_once: true 仅在本轮play中对第一个匹配主机执行一次任务，需配合明确主节点组（如db_primary）使用，而非依赖hosts: all或误用delegate_to。
在大规模集群中，数据库初始化这类操作通常只需在主节点（如主控数据库服务器）上执行一次，而非在所有节点重复运行。Ansible 的 run_once: true 是实现该目标的核心机制，但它常被误用或与其他特性（如 delegate_to、serial、组限制）混淆。正确使用需明确“谁执行”和“在哪执行”两个维度。
理解 run_once 的实际作用范围
run_once: true 并不指定“在哪个主机上运行”，而是让该任务在本轮 play 中**仅对第一个匹配的主机执行一次**，其余主机跳过该任务（但仍会参与 play 的其他任务）。因此，它依赖于主机列表的顺序和分组逻辑：
- 若未显式控制主机顺序，Ansible 按 inventory 中定义顺序或字母序选取第一个主机；
- 若 play 的
hosts直接写成all或包含数百台机器的组，run_once可能随机选中一台非主节点，导致失败； - 它不能替代角色委派（
delegate_to），也不改变任务实际执行位置——任务仍会在被选中的那台主机上运行。
精准定位主节点：用 group_by + run_once 组合
最可靠的方式是先通过动态分组明确主节点身份，再在其所属组上应用 run_once。例如，假设你的 inventory 中主数据库节点标记了 db_role: primary：
- name: Initialize database on primary node only
hosts: databases
tasks:
- name: Ensure only primary node runs init
command: /opt/db/init.sh
run_once: true
when: db_role == "primary"但上述写法仍有风险：若多个节点满足 db_role == "primary"，run_once 仍只选其一，无法保证是“唯一”的那个。更稳妥做法是先过滤出唯一主节点：
- name: Initialize database on designated primary
hosts: databases
tasks:
- name: Find the single primary node
set_fact:
primary_node: >-
{{ groups['databases'] | map('extract', hostvars, ['db_role']) | list
| zip(groups['databases'] | list) | selectattr(0, 'equalto', 'primary')
| map(1) | first | default(omit) }}
run_once: true
delegate_to: localhost
<pre class="brush:php;toolbar:false;"><pre class="brush:php;toolbar:false;">- name: Run init script on primary node
command: /opt/db/init.sh
delegate_to: "{{ primary_node }}"
when: primary_node is defined</code></pre>推荐方案：用 limit + 显式主机组 + run_once
生产环境中最清晰、可审计的方式是分离职责：
- 在 inventory 中明确定义主节点组，例如：
[db_primary] db-master-01； - Play 的
hosts直接指向该组：hosts: db_primary； - 配合
run_once: true—— 此时因组内仅一个主机，效果等价于“在指定主节点执行一次”； - 若需在初始化后通知其他节点（如更新配置、触发从库同步），可用
delegate_to: all或后续 play 处理。
示例：
- name: DB init on primary
hosts: db_primary
become: true
tasks:
- name: Create initial schema
mysql_db:
name: myapp
state: present
run_once: true
<pre class="brush:php;toolbar:false;"><pre class="brush:php;toolbar:false;">- name: Load seed data
mysql_query:
login_user: admin
login_password: "{{ db_admin_pass }}"
query: "SOURCE /tmp/seed.sql;"
run_once: true</code></pre>避免常见陷阱
以下做法易引发问题，应避免：
-
在
hosts: all 下直接加 <code>run_once：无法保证选中主节点，且违反职责分离原则； -
仅靠
delegate_to: db-master-01而不加run_once：任务虽在目标主机执行，但会为每台主机重复触发一次连接和委托（低效且可能报错）； - 忽略幂等性设计：即使只执行一次，脚本也应支持重复调用（如检查 schema 是否已存在），防止误操作重跑失败；
-
未设置
become: true或权限上下文：数据库初始化常需 root 或 dba 权限，委托后权限不自动继承，需显式声明。
本质上，run_once 是“执行频次控制”，不是“目标主机选择器”。真正决定“在哪做”的是 hosts、delegate_to 和 inventory 结构。把主节点抽象为独立组，再结合 run_once，是最简洁、可读、可维护的实践。
