一、起源:人工登录逐台操作的问题

1.1 逐台操作产生的三类问题

在主机数量进入两位数之后,通过 SSH 登录逐台执行命令的方式会稳定地产生三类问题。

不一致

同一份配置在多台主机上的落地结果取决于操作时的因素:

  • 执行顺序与时机不同,中途被打断的任务只在一部分主机上完成
  • 操作者依据记忆或旧笔记执行,参数、路径、权限取值出现偏差
  • 主机自身的初始状态不同(已装的软件版本、已有的配置文件内容),同一条命令产生不同结果
  • 配置修改只覆盖了本次涉及的主机,遗漏了同类角色的其他主机

不一致的后果是同类主机行为分化,故障只在部分实例上出现,排查时需要逐台比对。

不可追溯

人工操作的过程记录通常只保留在终端历史或沟通记录中:

  • 缺少"谁在何时改动了哪台主机的哪个文件"的完整记录
  • 变更内容没有版本化,无法对比变更前后的差异
  • 无变更记录与故障时间的对齐依据,定位只能依靠猜测
  • 交接时无法说明某台主机的配置为何与同类主机不同

无法批量验证

变更之后的核对同样依赖逐台登录:

  • 期望状态与当前状态之间没有可重复执行的比对手段
  • 只能抽查若干台,无法给出全量结论
  • 部分主机的配置被重复执行或被人为回退后,没有机制发现

1.2 脚本化与配置管理的边界

用脚本封装批量操作是第一步。常见的形态是在控制机上用循环遍历主机列表,逐台通过 SSH 执行相同的命令:

for host in $(cat hosts.txt); do
  ssh "${host}" 'sudo sed -i "s/^#Port 22/Port 2222/" /etc/ssh/sshd_config'
done

脚本解决了"重复输入"的问题,但引入了新的缺陷:

  1. 缺少幂等判断。同一脚本执行两次,追加类操作会产生重复内容,sed 类操作的结果取决于当前文件内容
  2. 缺少结果聚合。循环输出中混杂多台主机的日志,失败主机需要人工翻找,且脚本通常不会因单台失败而中断或汇总退出码
  3. 缺少抽象。主机分组、变量、模板、敏感信息都写在脚本内部,新增一类主机需要复制并修改脚本
  4. 缺少状态语义。脚本不区分"已符合期望"与"本次发生了变更",无法判断变更影响面

配置管理工具解决的是上述四点,其与脚本化的边界在于:

  • 适合配置管理:主机可通过 SSH 或同类通道批量连接、配置项可描述为期望状态、需要周期性地复核与收敛
  • 不适合配置管理:需要交互式确认的一次性操作、无远程通道的设备初始化、图形界面操作、必须依赖人工判断的应急处置

二、原理

2.1 无代理架构

Ansible 采用无代理(agentless)模型,被控端不需要安装常驻进程。

连接模型

控制端通过 SSH 连接被控端,连接参数(地址、端口、用户、密钥)在 inventory 或命令参数中声明。所有任务由控制端发起,被控端不主动回连,也不需要开放除 SSH 之外的端口。

模块执行方式

每执行一个任务,控制端把对应的模块代码打包传输到被控端的临时目录(默认位于远端用户的 ~/.ansible/tmp),在该目录内以脚本方式执行,执行完成后删除临时目录。模块执行结果以 JSON 形式返回控制端,由控制端汇总输出。

实际执行过程可在目标端观察:

# 控制端执行
ansible web -m ping -vvv

# 被控端临时目录(执行期间可见)
ls -la ~/.ansible/tmp/

代价与收益

维度 无代理架构的表现
部署成本 被控端无需安装与升级代理,无需常驻进程占用内存
端口要求 仅需 SSH,不额外开放端口,网络策略与现有运维通道一致
单任务开销 每次任务需建立连接并传输模块,任务粒度越细开销占比越高
依赖条件 依赖 SSH 可达与远端具备可用的 Python 解释器
规模上限 并发受控制端进程数与远端负载约束,需要通过分批与优化参数控制

连接开销可通过 SSH 连接复用缓解,在 ansible.cfg 中启用:

[ssh_connection]
pipelining = True
ssh_args = -o ControlMaster=auto -o ControlPersist=60s
  • pipelining:省去模块文件的落盘步骤,减少一次往返,要求被控端的 requiretty 已关闭
  • ControlPersist:在多个任务间复用同一条 SSH 连接,任务数量越多收益越明显

2.2 幂等与期望状态

命令式脚本与声明式任务的差别

  • 命令式脚本描述"做什么动作":追加一行配置、把文件复制过去、执行一条命令。动作是否已经完成、是否会产生重复副作用,由脚本作者自行判断
  • 声明式任务描述"最终状态是什么":该文件存在且属主为 X、该软件包处于已安装状态、该服务处于运行且开机自启状态。是否执行动作由模块判断

changed 与 ok 的含义

模块接收参数后,先读取当前状态,与期望状态比对,仅在两者不一致时执行变更:

  • ok:当前状态已符合期望,本次未产生任何变更
  • changed:当前状态与期望不符,本次执行了变更动作
  • failed:模块判定执行失败,后续行为取决于错误处理策略
  • skipped:条件判断(when)或检查模式(--check)导致任务未执行

第二个字段就是判断幂等性的直接依据:同一 playbook 连续执行两次,第二次的变更项应全部为 ok。若第二次仍出现 changed,说明对应任务不具备幂等性。

# 第二次执行时全部为 ok
ansible-playbook -i inventory site.yml

重复执行的判定依据

幂等判定由模块实现承担,不同模块的判定维度不同:

模块 判定依据
file 路径是否存在、类型、属主属组、权限位是否一致
copy / template 源内容与目标内容的校验和是否一致
apt / dnf 软件包是否已安装、版本是否满足要求
service / systemd 单元是否处于期望的 active 与 enabled 状态
user / group 账户是否存在、UID、主组、附加组、Shell 是否一致
lineinfile 目标行是否已存在且内容一致

command 与 shell 模块不具备幂等性,它们不判断当前状态,每次执行都返回 changed。改造方式见第三章第 3 小节。

2.3 目录与作用域

配置管理代码需要明确的目录约定,否则变量来源与任务归属会随规模增长而失控。常用职责划分如下:

位置 职责
inventory 主机清单与分组,定义"对哪些主机执行"
group_vars/ 按分组划分的变量,定义"某一类主机的公共参数"
host_vars/ 按单台主机划分的变量,定义"某一台主机的差异参数"
roles/<role>/tasks/ 该角色要执行的任务序列
roles/<role>/handlers/ 该角色声明的处理器,由任务 notify 触发
roles/<role>/templates/ Jinja2 模板文件,渲染后下发
roles/<role>/files/ 静态文件,原样下发
roles/<role>/defaults/ 角色默认变量,可被外部覆盖,优先级最低
roles/<role>/vars/ 角色内部变量,优先级高于绝大多数外部变量
roles/<role>/meta/ 角色依赖关系声明
collections/ 第三方模块、插件与角色的打包集合

行为参数集中在 ansible.cfg 中,避免把路径与并发参数写在命令行上:

[defaults]
inventory = ./inventory
roles_path = ./roles
remote_user = ops
host_key_checking = True
forks = 20
retry_files_enabled = False

[privilege_escalation]
become = True
become_method = sudo
become_user = root

作用域原则:

  1. 与主机身份无关的公共参数放 group_vars/all
  2. 与角色相关的参数放该分组的 group_vars/<组名>.yml
  3. 单台主机的差异(地址、容量、编号)放 host_vars/<主机名>.yml
  4. 角色自身的默认值放 defaults/main.yml,使其可被调用方覆盖;只有确定不允许覆盖的参数才放 vars/main.yml

2.4 变量优先级与覆盖关系

同一变量名可在多处定义,最终取值由优先级决定。由低到高的常见层级如下,同层级内后出现者覆盖先出现者:

顺序 来源
1 角色 defaults/main.yml
2 inventory 的 group_vars/all
3 inventory 的 group_vars/<组名>
4 inventory 的 host_vars/<主机名>
5 play 中的 vars 与 vars_files
6 角色 vars/main.yml
7 block 级 vars 与 tasks 中的 vars
8 set_fact 与 register 注册的变量
9 命令行 -e 或 --extra-vars 传入的变量

排查变量取值问题的顺序:

  1. 确认是否通过 -e 传入了同名变量,该层优先级最高且常被忽略
  2. 查看 host_vars 是否覆盖了 group_vars 中的取值
  3. 检查同名变量是否在多处定义,尤其是角色 vars/main.yml 覆盖了调用方传入的值
  4. 确认模板或任务中引用的变量名拼写与作用域一致
# 查看某台主机的最终变量取值
ansible-inventory -i inventory --host web01

# 查看全部变量的合并结果
ansible-inventory -i inventory --list

# 任务执行时输出变量值(临时排查用)
ansible-playbook -i inventory site.yml --limit web01 -e "debug_var=1"
- name: 排查变量取值
  hosts: web01
  tasks:
    - name: 输出目标变量
      ansible.builtin.debug:
        var: app_config_path

2.5 模板与处理器

模板机制

Jinja2 模板用于生成内容随变量变化的目标文件。模板文件放在角色的 templates/ 目录,通过 template 模块下发:

- name: 下发服务配置
  ansible.builtin.template:
    src: app.conf.j2
    dest: /etc/myapp/app.conf
    owner: root
    group: root
    mode: "0644"
  notify: 重启 myapp
# templates/app.conf.j2 渲染结果示例
listen_port = {{ app_port | default(8080) }}
worker_num = {{ ansible_processor_vcpus * 2 }}
log_level = {{ 'debug' if app_debug | default(false) else 'info' }}
{% for node in app_backends %}
backend = {{ node }}
{% endfor %}

模板相关要点:

  • template 模块渲染后与目标文件比对校验和,只有内容不同才产生 changed,因此无需在任务中自行编写差异判断
  • 变量未定义时渲染报错,可选参数使用 | default(值) 提供兜底
  • {{ }} 中的表达式由 Jinja2 解析,{% %} 控制流程;{# #} 为注释,不出现在渲染结果中
  • 模板中使用的事实变量(如 ansible_processor_vcpus)来自被控端采集,可通过 gather_facts: false 关闭采集以减少开销

handler 的触发条件与执行时机

handler 是一类特殊任务,默认不在 tasks 列表中被直接调用,而是由其他任务的 notify 触发:

  1. 触发条件是被 notify 的那个任务返回 changed。任务返回 ok 时,handler 不被触发
  2. 执行时机默认在 play 的所有任务执行完成后,而非任务返回 changed 的当场
  3. 同名 handler 在一次 play 中被多次触发时只执行一次,因此多个配置文件的修改只会引起一次服务重启
- name: 应用配置
  hosts: web
  handlers:
    - name: 重启 myapp
      ansible.builtin.systemd:
        name: myapp
        state: restarted
  tasks:
    - name: 下发主配置
      ansible.builtin.template:
        src: app.conf.j2
        dest: /etc/myapp/app.conf
      notify: 重启 myapp

    - name: 下发证书
      ansible.builtin.copy:
        src: server.crt
        dest: /etc/myapp/server.crt
      notify: 重启 myapp

需要在 play 中途强制执行已触发的 handler 时,使用 flush_handlers 任务插入到指定位置;在 play 报错中断时需要执行 handler,可将其放入 always 块。

失败与重试策略

- name: 等待服务端口就绪
  ansible.builtin.wait_for:
    host: 127.0.0.1
    port: 8080
    timeout: 30
  register: wait_result
  until: wait_result is succeeded
  retries: 5
  delay: 5
  • until:重试判定条件,满足该条件即结束重试
  • retries:最大重试次数,超出后任务判定失败
  • delay:两次重试之间的等待秒数
  • 重试适用于依赖外部系统就绪的场景(等待端口监听、等待数据库可连、等待接口返回成功状态),不适用于掩盖持续存在的失败

三、实现

3.1 inventory 编写

静态清单与分组

INI 格式的清单以分组划分为主,组可嵌套:

# inventory/hosts
[web]
web01 ansible_host=10.0.1.11
web02 ansible_host=10.0.1.12

[db]
db01 ansible_host=10.0.2.11 ansible_port=2222

[db:vars]
ansible_user=dbadmin

[prod:children]
web
db

[prod:vars]
ansible_ssh_private_key_file=~/.ssh/id_ed25519_prod

YAML 格式适合定义结构较复杂的变量:

all:
  children:
    web:
      hosts:
        web01:
          ansible_host: 10.0.1.11
          app_role: frontend
        web02:
          ansible_host: 10.0.1.12
          app_role: frontend
    db:
      hosts:
        db01:
          ansible_host: 10.0.2.11
          ansible_port: 2222
      vars:
        ansible_user: dbadmin

常用连接参数:

参数 作用
ansible_host 实际连接地址,与清单中的主机别名区分
ansible_port SSH 端口,非 22 时必填
ansible_user 登录用户
ansible_ssh_private_key_file 私钥路径
ansible_python_interpreter 远端 Python 解释器路径,用于系统自带 Python 版本与默认路径不一致的环境
ansible_ssh_common_args 附加 SSH 参数,常用于声明跳板机

跳板机

通过 ProxyJump 复用 OpenSSH 的跳转能力,被控端无需额外配置:

[bastion:vars]
ansible_ssh_common_args=-o ProxyJump=ops@10.0.0.10

动态清单

主机数量随弹性伸缩变化、或已有 CMDB 与云平台维护主机信息时,静态清单需要人工同步,容易与实际资源脱节。动态清单由脚本或插件在每次执行时查询数据源生成主机列表。

适用场景:

  1. 云主机按标签或安全组划分,实例随扩缩容增删
  2. 主机信息由 CMDB 或资产系统统一维护,存在唯一的事实来源
  3. 环境频繁重建,主机名或地址不具备稳定性

需要权衡的点:

  • 动态清单引入了对上游接口的依赖,接口不可用时无法执行
  • 查询结果的缓存时间需与变更频率匹配,缓存过长会导致新主机不可见
  • 分组规则由标签或元数据推导,标签管理不规范时分组结果不可控
# 验证动态清单解析结果
ansible-inventory -i ./inventory/dynamic.py --graph

# 按标签限定范围
ansible-playbook -i ./inventory/dynamic.py site.yml --limit 'tag_role_web'

3.2 playbook 组织

任务、条件与循环

- name: 部署应用
  hosts: web
  become: true
  vars:
    app_port: 8080
  tasks:
    - name: 安装依赖包
      ansible.builtin.apt:
        name: "{{ item }}"
        state: present
      loop:
        - nginx
        - python3
        - curl

    - name: 仅在 Debian 系主机执行
      ansible.builtin.apt:
        name: net-tools
        state: present
      when: ansible_os_family == "Debian"

    - name: 查询已加载的内核模块
      ansible.builtin.command: lsmod
      register: lsmod_result
      changed_when: false
      check_mode: false

    - name: 模块未加载时的提示
      ansible.builtin.debug:
        msg: "nf_conntrack 未加载"
      when: "'nf_conntrack' not in lsmod_result.stdout"
  • when:条件表达式,为假时任务被跳过并记为 skipped
  • loop:遍历列表,循环变量为 item;with_dict、with_nested 等写法已归并到 loop 配合过滤器使用
  • register:把任务返回值保存为变量,供后续任务引用(stdout、rc、changed 等字段)
  • changed_when: false:显式声明该只读命令不产生变更,避免污染变更统计

错误处理

- name: 带恢复逻辑的部署
  hosts: web
  tasks:
    - name: 部署与回滚
      block:
        - name: 停止应用
          ansible.builtin.systemd:
            name: myapp
            state: stopped

        - name: 下发新版本
          ansible.builtin.copy:
            src: myapp.jar
            dest: /opt/myapp/myapp.jar

        - name: 启动应用
          ansible.builtin.systemd:
            name: myapp
            state: started

      rescue:
        - name: 记录失败
          ansible.builtin.command: logger -t deploy "部署失败,执行回滚"

        - name: 恢复上一版本
          ansible.builtin.copy:
            src: myapp.jar.bak
            dest: /opt/myapp/myapp.jar
            remote_src: true

        - name: 重新启动应用
          ansible.builtin.systemd:
            name: myapp
            state: restarted

      always:
        - name: 输出部署结束标记
          ansible.builtin.debug:
            msg: "部署流程结束"
  • block:把一组任务视为一个单元,便于统一施加条件与错误处理
  • rescue:block 中任一任务失败时执行,用于回滚与记录
  • always:无论成功、失败或跳过都会执行,用于清理与收尾

ignore_errors 的取舍

ignore_errors: true 使任务失败后继续执行后续任务,适用于:

  • 探测类任务,失败本身是有效信息(例如检查某个可选组件是否存在)
  • 已知在部分主机上必然失败、且失败无副作用的清理动作

不宜使用的情形:

  1. 任务失败会导致后续任务基于错误状态继续执行,最终失败点远离根因
  2. 用于掩盖尚未定位的报错,使失败从执行结果中消失
  3. 替代 failed_when:需要自定义失败判定时,用 failed_when 明确表达条件,比忽略错误后再判断更清晰
- name: 自定义失败判定
  ansible.builtin.command: /opt/myapp/health-check.sh
  register: hc
  failed_when: "'OK' not in hc.stdout"

any_errors_fatal: true 作用于 play 级别,任一主机失败即中断整个 play,适合不允许部分成功的不一致场景。

标签与分段执行

- name: 配置 web 主机
  hosts: web
  tasks:
    - name: 安装软件包
      ansible.builtin.apt:
        name: nginx
        state: present
      tags: [packages]

    - name: 下发配置
      ansible.builtin.template:
        src: nginx.conf.j2
        dest: /etc/nginx/nginx.conf
      tags: [config]
# 只执行指定标签的任务
ansible-playbook -i inventory site.yml --tags config

# 跳过指定标签
ansible-playbook -i inventory site.yml --skip-tags packages

# 列出将要执行的任务清单
ansible-playbook -i inventory site.yml --list-tasks

标签用于按变更内容分段执行,常见划分方式为安装、配置、服务、检查四类。标签应沿任务粒度标注,避免把整个角色的任务打上同一个标签。

3.3 常用模块与场景

包管理

- name: 安装软件包
  ansible.builtin.apt:
    name:
      - nginx
      - logrotate
    state: present
    update_cache: true

- name: 移除软件包
  ansible.builtin.apt:
    name: telnet
    state: absent

- name: 清理无用依赖
  ansible.builtin.apt:
    autoremove: true
  • state: present 表示处于已安装状态,版本不做约束
  • state: latest 表示升级到最新版本,会使每次执行的变更结果依赖源中版本,降低可重复性
  • update_cache 对应先刷新索引,跨发行版的模块名与参数差异需按目标系统选择(apt 与 dnf)
  • 包管理命令与源配置的细节参见 ../packageManagement/apt.html

文件与模板下发

- name: 创建目录
  ansible.builtin.file:
    path: /opt/myapp
    state: directory
    owner: myapp
    group: myapp
    mode: "0750"

- name: 下发静态文件
  ansible.builtin.copy:
    src: files/app.jar
    dest: /opt/myapp/app.jar
    owner: myapp
    group: myapp
    mode: "0644"
    backup: true

- name: 确保配置行存在
  ansible.builtin.lineinfile:
    path: /etc/myapp/app.conf
    regexp: '^max_connections='
    line: 'max_connections=500'
  • backup: true 在覆盖前保留一份带时间戳的副本,便于回退
  • lineinfile 的 regexp 用于定位已有行并替换,避免重复追加;成块的配置使用 blockinfile 配合标记,或改用模板整体渲染
  • 权限使用字符串形式("0644"),避免 YAML 把前导零解析为八进制数以外的含义

服务与 systemd

- name: 管理应用服务
  ansible.builtin.systemd:
    name: myapp
    enabled: true
    state: started

- name: 单元文件变更后重载并重启
  ansible.builtin.systemd:
    name: myapp
    daemon_reload: true
    state: restarted
  • 单元文件的依赖关系、daemon-reload 的执行时机与故障排查参见 ../processManagement/systemd.html
  • 仅修改单元文件而不触发 daemon_reload 时,systemd 使用的仍是旧配置

用户与权限

- name: 创建服务账户
  ansible.builtin.user:
    name: myapp
    system: true
    shell: /usr/sbin/nologin
    create_home: false

- name: 部署运维公钥
  ansible.posix.authorized_key:
    user: ops
    key: "{{ lookup('file', 'files/ops_ed25519.pub') }}"
    state: present

- name: 独立 sudoers 子配置
  ansible.builtin.copy:
    content: "ops ALL=(ALL) NOPASSWD: /usr/bin/systemctl restart myapp\n"
    dest: /etc/sudoers.d/myapp-ops
    owner: root
    group: root
    mode: "0440"
    validate: "visudo -cf %s"

命令模块的幂等改造

command 与 shell 每次执行都返回 changed,需要显式改造:

- name: 初始化数据目录(幂等)
  ansible.builtin.command: /opt/myapp/bin/init.sh
  args:
    creates: /var/lib/myapp/initialized

- name: 仅当配置缺失时执行迁移
  ansible.builtin.shell: |
    set -o pipefail
    /opt/myapp/bin/migrate.sh
  args:
    removes: /var/lib/myapp/legacy.lock
  • creates:目标路径已存在时跳过任务
  • removes:目标路径不存在时跳过任务
  • 判断类命令使用 changed_when: false;命令确实产生变更但不返回标准结果时,用 changed_when 按输出判定
- name: 按输出判定是否产生变更
  ansible.builtin.shell: /opt/myapp/bin/reload.sh
  register: reload_out
  changed_when: "'reloaded' in reload_out.stdout"

脚本自身的健壮性写法(set -euo pipefail、trap 清理、参数校验)参见 ../shell/shell_execution.html 中的脚本健壮性与生产实践小节。

定时任务管理

- name: 每日备份任务
  ansible.builtin.cron:
    name: "myapp backup"
    minute: "0"
    hour: "3"
    user: root
    job: "/usr/local/sbin/backup.sh >> /var/log/backup.log 2>&1"
    state: present
  • name 作为任务标识写入 crontab 注释,用于后续定位与删除,必填
  • 使用 cron 模块管理而非直接编辑 crontab,避免与其他来源的任务相互覆盖
  • cron 与 systemd timer 的机制差异、任务未执行的排查顺序参见 ../processManagement/scheduled_tasks_and_timers.html

3.4 批量执行与风险控制

高危 提醒:批量执行会把一次变更同时施加到清单内的全部主机,错误的内容会被等比例放大。执行前的兜底方式为:先以 --list-hosts 与 --limit 确认目标范围、以 --check --diff 预演变更内容、以 serial 将批次控制在可回滚的规模、确保配置目录处于版本控制且可回退,并在变更窗口内保留可直接回滚的上一版本。

预演

# 仅检查会产生哪些变更,不做实际修改
ansible-playbook -i inventory site.yml --check

# 检查并输出文件差异
ansible-playbook -i inventory site.yml --check --diff

# 预演结果中 changed 表示"将会变更",不代表可以全部自动应用

--check 依赖模块对检查模式的支持。command、shell 等模块默认跳过执行,需配合 creates、removes 或 check_mode: false 才能在预演中给出有意义的结果。

范围控制

# 确认目标主机清单
ansible-playbook -i inventory site.yml --list-hosts

# 限定主机或分组
ansible-playbook -i inventory site.yml --limit 'web01'
ansible-playbook -i inventory site.yml --limit 'web:!web03'

# 从失败主机开始重跑(retry 文件需启用)
ansible-playbook -i inventory site.yml --limit @site.retry

批次与失败控制

- name: 分批更新
  hosts: web
  serial: 3
  max_fail_percentage: 20
  tasks:
    - name: 更新应用
      ansible.builtin.apt:
        name: myapp
        state: latest
  • serial:每批处理的主机数量或比例,批次之间互不影响,适合需要灰度验证的场景
  • max_fail_percentage:单批失败比例超过该值时中断整个 play,避免继续向剩余批次扩散
  • forks:控制并发进程数,直接决定控制端同时连接的主机数量

本地执行与委派

- name: 在控制端生成汇总清单
  hosts: web
  tasks:
    - name: 汇总各主机版本
      ansible.builtin.command: /usr/bin/myapp --version
      register: ver
      changed_when: false

    - name: 写入本地汇总文件
      ansible.builtin.copy:
        content: "{{ ansible_play_hosts | map('extract', hostvars) | list | length }} 台主机已检查\n"
        dest: /var/log/ansible/summary.txt
      delegate_to: 127.0.0.1
      run_once: true
  • delegate_to:把任务委派到指定主机执行,常用 127.0.0.1 表示控制端
  • run_once: true:只在第一台主机上执行一次,适合只需执行一遍的注册动作

失败中断与继续的取舍

策略 适用场景 风险
默认中断该主机,继续其他主机 主机之间相互独立,部分失败不影响其余主机 清单内出现状态分化,需要按失败清单补做
any_errors_fatal: true 变更要求全量一致,部分成功即为失败 单台问题导致整体不落地,已变更的主机需要单独处理
serial 分批 需要控制影响面与验证节奏 执行时间随批次数线性增长
ignore_errors: true 探测类任务 后续任务可能基于错误状态继续执行

3.5 敏感信息

vault 加密

# 加密整个变量文件
ansible-vault encrypt group_vars/all/vault.yml

# 加密单个字符串,输出可直接粘贴到变量文件中
ansible-vault encrypt_string --name 'db_password' 'S3cretValue'

# 查看与编辑
ansible-vault view group_vars/all/vault.yml
ansible-vault edit group_vars/all/vault.yml

# 更换加密口令
ansible-vault rekey group_vars/all/vault.yml

加密后的文件内容以固定头部标识,可安全纳入版本控制:

# group_vars/all/vault.yml
$ANSIBLE_VAULT;1.1;AES256
66386439653...

执行时提供口令的方式:

# 交互输入
ansible-playbook -i inventory site.yml --ask-vault-pass

# 从文件读取
ansible-playbook -i inventory site.yml --vault-password-file ~/.vault_pass

# 从外部密钥管理系统动态获取(脚本输出口令)
ansible-playbook -i inventory site.yml \
  --vault-password-file ./scripts/fetch-vault-pass.sh
  • 口令文件不得提交到版本库,需加入忽略清单并限制文件权限(chmod 600)
  • 口令脚本从密钥管理系统或环境变量取值,避免把口令固化在脚本内部
  • --vault-id 可为不同环境指定不同口令来源,实现生产与测试的密钥隔离

密钥轮换与审计

轮换流程:

  1. 在密钥管理系统中新增一版口令,保留旧口令可解
  2. 对受影响的 vault 文件执行 ansible-vault rekey,按环境分批进行
  3. 更新各环境的口令来源(口令文件或取值脚本)
  4. 验证新口令可解密并完成一次部署
  5. 从密钥管理系统中吊销旧口令

审计要点:

  • 禁止在任务参数中直接写明文口令,command、shell 的 -p 类参数会出现在进程列表中,也会被日志记录
  • 对包含敏感参数的模块使用 no_log: true,避免返回值在标准输出与日志中回显
- name: 初始化数据库账号
  ansible.builtin.command: /opt/myapp/bin/set-password.sh
  environment:
    DB_PASSWORD: "{{ vault_db_password }}"
  no_log: true
  • 定期核对加密文件清单与实际使用范围,清理已下线的密钥
  • 排查阶段使用 -vvv 会增加输出内容,no_log 之外的任务参数可能被打印,该参数只应在受控环境临时使用

3.6 配置漂移治理

配置漂移指主机当前状态与声明的期望状态不一致,来源通常有三类:

  1. 应急排障时的手工修改,事后未回写到配置管理代码
  2. 其他自动化手段或软件包升级覆盖了受管文件
  3. 配置管理代码已更新,但部分主机未执行最新的 playbook

以检查模式定期复核

# 全量复核,输出将会被收敛的差异
ansible-playbook -i inventory site.yml --check --diff > /var/log/ansible/drift-$(date +%F).log 2>&1

# 仅复核配置类任务
ansible-playbook -i inventory site.yml --check --diff --tags config

复核结果的处理方式:

  • 输出中存在 changed 项即表示该主机存在漂移,--diff 给出了具体差异内容
  • 需要区分"预期外的漂移"与"代码已领先于主机"两类情况:前者需要确认手工变更是否应保留,后者属于正常的待发布变更
  • 差异日志按日期归档,与上一周期结果对比,定位新增漂移项

巡检与配置管理的衔接

巡检脚本负责发现差异(配置文件校验、计划任务清单比对、软件包版本核对),配置管理负责把差异收敛到期望状态,两者的分工如下:

环节 承担方 输出
发现差异 巡检脚本按周期执行 结构化记录与差异清单
判定取舍 人工确认 需回写的配置变更或需覆盖的漂移
收敛状态 playbook 执行 变更记录与执行结果
验证结果 再次以检查模式复核 全量一致的结论

巡检项的分类、频率与结果归档方式参见 ../monitoring/inspection_and_health_check.html,本节的复核命令可作为其配置完整性类检查项的实现手段。

执行巡检复核时同样受批量执行风险约束:--check 不产生变更,可以全量执行;一旦去掉 --check 转为收敛,需按前述范围控制与分批策略执行。

3.7 与流水线和监控的衔接

触发方式

触发方式 适用场景 需要控制的事项
人工执行 首次部署、应急变更 执行人、执行范围、变更记录
定时执行(cron 或 systemd timer) 定期收敛配置漂移 与业务高峰错开,避免与其他任务争抢资源
流水线触发 代码合并后的自动化发布 环境与分支的对应关系、审批环节
事件触发(Webhook) 资源创建完成后接入配置 上游事件的幂等性与重复投递处理
# /etc/systemd/system/ansible-converge.timer
[Unit]
Description=每日以检查模式复核配置漂移

[Timer]
OnCalendar=*-*-* 04:00:00
Persistent=true

[Install]
WantedBy=timers.target

对应单元文件的编写方式与定时器机制参见 ../processManagement/scheduled_tasks_and_timers.html。

# 流水线中的执行与记录示例
ANSIBLE_LOG_PATH=/var/log/ansible/run-$(date +%Y%m%d-%H%M%S).log \
  ansible-playbook -i inventory site.yml --limit "${TARGET_GROUP}"
echo "exit=$?"

执行记录

  • 控制端日志统一落盘并纳入轮转,保留周期与变更审计要求匹配
  • 一次执行需可回溯:目标范围、执行的代码版本、每台主机的 changed 与 failed 明细、执行人与时间
  • 代码版本与执行记录关联,通过提交标识标记本次部署对应的代码版本
  • 排查失败主机时按主机名过滤日志,而不是翻看整体输出

变更与告警联动

  1. 变更窗口内对受影响主机的告警设置静默或抑制,避免重启引起的短时抖动产生噪声
  2. 变更完成后主动执行验证任务(端口监听、接口返回、进程状态),把结论作为执行结果的一部分
  3. 变更引起的持续告警不应被静默掩盖,静默需设置明确的结束时间
  4. 把执行失败接入告警通道,避免失败任务只留在日志中无人查看
  5. 监控侧的规则构成与抑制机制参见 ../monitoring/monitoring_and_alerting.html

3.8 常见问题

首次连接与主机密钥

  • 首次连接时被控端的主机密钥不在本地信任列表中,默认配置下会被拒绝
  • 处置方式为提前采集并写入信任列表,或在受控环境下临时关闭校验
# 提前采集主机密钥
ssh-keyscan -t ed25519 10.0.1.11 >> ~/.ssh/known_hosts

# 重建机器后的旧密钥冲突,按行删除后重新采集
ssh-keygen -R 10.0.1.11
  • 长期关闭主机密钥校验会失去中间人攻击的防护,仅在首次批量初始化阶段临时使用
  • 主机密钥冲突的典型报错为 REMOTE HOST IDENTIFICATION HAS CHANGED,重装系统或更换主机后必然出现,需确认地址复用是预期行为后再清理旧记录

sudo 与 become 配置

# ansible.cfg
[privilege_escalation]
become = True
become_method = sudo
become_user = root
- name: 整体提权
  hosts: web
  become: true
  tasks:
    - name: 以服务账户执行
      ansible.builtin.command: /opt/myapp/bin/task.sh
      become: true
      become_user: myapp
  • 提权用户需在 sudoers 中具备对应授权,缺少授权时报错为 Missing sudo password 或 is not in the sudoers file
  • 使用免密提权时,前提是该账户的授权范围已按最小权限收敛,NOPASSWD: ALL 会放大凭据泄露的影响面
  • 部分发行版默认开启 requiretty,非交互式会话下提权被拒,需在 sudoers 中取消该项或启用 pipelining
  • sudoers 授权与提权审计参见 ../useAndGroupManagement/user_and_group_management.html

远端 Python 解释器缺失

  • 模块以 Python 执行,远端无可用解释器时报错为 /usr/bin/python: not found
  • 处置方式为显式声明解释器路径,或在安装解释器之前使用不依赖 Python 的模块
# 按主机或分组声明
[web:vars]
ansible_python_interpreter=/usr/bin/python3
- name: 安装 Python 解释器(不依赖 Python 的模块)
  hosts: newhosts
  gather_facts: false
  tasks:
    - name: 通过 raw 模块执行包安装
      ansible.builtin.raw: apt-get update && apt-get install -y python3
      changed_when: false
  • raw 直接通过 SSH 执行命令,不经过模块机制,因此不受解释器缺失影响,适合初始化阶段
  • gather_facts 依赖远端 Python,解释器不可用时必须先关闭事实采集

并发过大导致目标端负载升高

  • forks 决定控制端同时连接的主机数;单台主机上若同时执行多个任务,也会叠加资源开销
  • 现象为目标端负载升高、包管理器锁冲突(Could not get lock)、服务重启引起连接中断
  • 包管理相关的锁冲突成因与处置参见 ../packageManagement/apt.html 的常见问题小节
  • 控制方式为降低 forks 取值、使用 serial 分批、把批量任务安排在业务低峰期执行

编码与时区差异

  • 模板中的中文内容在目标端出现乱码,通常源于文件编码不一致,需统一为 UTF-8 并在目标端确认 locale 配置
  • 时间戳类变量在控制端与目标端时区不同时产生偏移,需要在模板中显式指定时区,或统一使用 UTC 记录
  • 时区不一致对日志时间线与认证校验的影响参见 ../troubleshooting/fault_case_library.html 中时间偏移案例的定位过程
  • 远端采集的系统信息受 locale 影响时,可在任务中通过 environment 显式设置:
- name: 统一执行环境
  ansible.builtin.command: /opt/myapp/bin/report.sh
  environment:
    LANG: C.UTF-8
    TZ: UTC

四、总结

  • 人工逐台操作的问题集中在不一致、不可追溯与无法批量验证三处,脚本化解决了重复输入,但缺少幂等、结果聚合、变量抽象与状态语义
  • 无代理架构以 SSH 为唯一通道,模块传输到被控端临时目录执行后删除;代价是每任务一次连接的开销与对远端 Python 的依赖,收益是无需部署与升级常驻进程
  • 幂等判定由模块完成,ok 表示已符合期望状态,changed 表示本次产生了变更;连续两次执行第二次应全部为 ok
  • 目录划分对应作用域:inventory 定义目标范围,group_vars 与 host_vars 定义变量差异,roles 内部按任务、处理器、模板、文件与默认值分层
  • 变量取值由优先级决定,-e 传入的值最高;排查顺序为命令行传参、host_vars 与 group_vars 的覆盖关系、角色内部变量的同名定义
  • handler 由 notify 触发且仅在任务返回 changed 时生效,默认在 play 末尾统一执行,同名 handler 只执行一次
  • 批量执行的风险控制手段为 --check --diff 预演、--limit 限定范围、serial 分批与 max_fail_percentage 限制失败比例;危险动作需预先确认目标范围与回滚路径
  • 敏感信息以 vault 加密后纳入版本控制,口令从外部密钥管理系统获取,轮换后吊销旧口令,含敏感参数的任务使用 no_log
  • 配置漂移的治理路径为定期以检查模式复核、人工确认取舍、由 playbook 收敛、再次复核确认一致;巡检负责发现,配置管理负责收敛
  • 常见问题集中在首次连接的主机密钥校验、提权授权与 requiretty、远端解释器缺失、并发与分批控制、以及编码与时区差异五处
  • 相关专题参见 ../packageManagement/apt.html、../processManagement/systemd.html、../useAndGroupManagement/user_and_group_management.html、../monitoring/inspection_and_health_check.html、./infrastructure_as_code.html