企业官网建设流程全解析

1. 为什么 Ansible 的 if 和 block 不是“写个判断”那么简单

很多人第一次在 Ansible 中写when:，以为就是 Python 里的if：条件成立就执行，不成立就跳过。结果部署到生产环境才发现，一个看似简单的when: inventory_hostname in groups['web']在 200 台服务器上跑起来，有 3 台没执行任务，日志里只有一行skipping: [host-107]，连为什么跳过都查不到源头。更糟的是，某次紧急回滚时，想用block包住一组关键操作加统一错误处理，结果rescue段根本没触发——不是因为没出错，而是因为那个报错发生在block外部的变量赋值阶段，压根没进到block里。

这背后暴露的是对 Ansible 执行模型的根本误判。Ansible 不是逐行解释 Python 脚本，而是一个声明式、分阶段、上下文隔离的编排引擎。它的“条件判断”和“块结构”不是语法糖，而是深度耦合在 playbook 生命周期里的控制原语。when的求值时机在 task 解析阶段（pre-task），而非运行时；block的作用域不覆盖变量注册、事实收集或 handler 触发；rescue只捕获 task 级异常，不捕获 Jinja2 模板渲染失败或变量未定义错误。这些细节，官方文档里散落在十几个章节的角落，新手照着示例抄三遍，照样在真实项目里栽跟头。

我带过的某跨平台系统自动化项目里，A同学就踩过这个坑：他用block包住copy+template+service三个 task，想实现“文件拷贝失败就 rollback 服务状态”。结果某次模板里引用了未定义的app_config.port，Jinja2 渲染直接报错，整个 playbook 中断，rescue根本没机会执行。后来我们花了整整两天时间，才定位到问题不在block内部，而在templatetask 加载模板前的变量解析阶段——那个阶段连block的边界都还没进入。

所以，理解when和block，本质是理解 Ansible 的执行流水线：从 inventory 加载、变量合并、事实收集、task 解析、条件求值、到实际模块调用、结果处理、handler 注册……每个环节都有其严格的时序和作用域。本文不讲“怎么写”，而是带你拆开 Ansible 的外壳，看清when在哪一刻计算、block的边界划在哪条线、rescue能接住什么、又漏掉什么。所有结论，都来自我们在上百个生产环境 playbook 中反复验证的真实行为，不是文档翻译，而是故障复盘。

2. when 条件判断：你以为的“运行时判断”，其实是“解析时快照”

2.1 时序陷阱：when 求值发生在 task 解析阶段，而非执行阶段

这是最常被误解的一点。很多开发者写：

- name: Get current user command: whoami register: current_user - name: Run admin task only for root command: systemctl restart nginx when: current_user.stdout == "root"

逻辑看起来天衣无缝：先获取用户，再判断是否为 root。但 Ansible 的执行流程决定了，when表达式是在task 解析完成、准备执行前就被求值的。而current_user这个变量，在commandtask 执行完之前，根本不存在。因此，上面的when实际求值时，current_user是一个未定义变量，Jinja2 引擎会静默将其转为空字符串""，导致"" == "root"为False，task 直接被跳过——哪怕目标主机上whoami真的返回root。

提示：Ansible 对未定义变量的默认处理是静默转空值，不会报错。这让你很难第一时间发现逻辑断裂点。

真正的解法，是利用 Ansible 的延迟求值机制，把依赖关系显式表达出来：

- name: Get current user command: whoami register: current_user - name: Run admin task only for root command: systemctl restart nginx when: current_user is defined and current_user.stdout | trim == "root"

这里多了两层防护：current_user is defined确保变量存在；| trim去除stdout可能存在的换行符。但请注意，这依然不能解决“current_user本身执行失败”的情况——如果whoami命令因权限问题退出非零码，current_user会被注册为一个包含failed: true的字典，此时current_user.stdout会是None，None | trim会报 Jinja2 错误。所以更健壮的写法是：

- name: Run admin task only for root command: systemctl restart nginx when: > current_user is defined and current_user.stdout is defined and current_user.stdout | trim == "root" and current_user.failed | default(false) | bool == false

2.2 上下文隔离：inventory_hostname 与 group_names 的本质区别

另一个高频误区是混淆inventory_hostname和group_names的作用域。看这个例子：

# inventory 文件 [web] web01 ansible_host=192.168.1.10 web02 ansible_host=192.168.1.11 [db] db01 ansible_host=192.168.1.20 [all:children] web db

有人会写：

- name: Install web server on web group apt: name: nginx state: present when: inventory_hostname in group_names

直觉上，inventory_hostname是当前主机名（如web01），group_names是它所属的组列表（如['web']），'web01' in ['web']显然为False，task 永远不会执行。正确写法是：

- name: Install web server on web group apt: name: nginx state: present when: "'web' in group_names"

或者更推荐使用 Ansible 内置的groups字典：

- name: Install web server on web group apt: name: nginx state: present when: inventory_hostname in groups['web']

groups['web']返回的是['web01', 'web02']这样的主机名列表，inventory_hostname（web01）自然在其中。group_names是当前主机的组标签集合，用于做“我是谁”的判断；groups是 inventory 的全局组映射表，用于做“谁属于我”的判断。二者语义完全不同，混用必错。

2.3 复杂条件组合：用括号明确优先级，避免隐式逻辑陷阱

Ansible 的when支持and/or/not，但它的运算符优先级与 Python 不同，且不支持&&/||。更危险的是，Ansible 会将多个when条件自动用and连接。比如：

- name: Configure firewall ufw: state: enabled when: ansible_distribution == "Ubuntu" when: ansible_distribution_version is version('20.04', '>=')

这等价于：

when: ansible_distribution == "Ubuntu" and ansible_distribution_version is version('20.04', '>=')

但如果写成：

- name: Configure firewall ufw: state: enabled when: > ansible_distribution == "Ubuntu" and ansible_distribution_version is version('20.04', '>=')

看起来一样，但>折行符会让 Jinja2 将其视为单个字符串表达式，内部空格会被保留，可能导致意外的字符串比较。最安全的做法，是用括号强制分组，并用| bool显式转换：

- name: Configure firewall ufw: state: enabled when: > (ansible_distribution == "Ubuntu") | bool and (ansible_distribution_version is version('20.04', '>=')) | bool

| bool的作用是确保左侧表达式的结果被强制转为布尔值，避免某些边缘情况（如空列表[]在 Jinja2 中为True，但在 Ansible 的when逻辑中可能被当作False）导致行为不一致。这是我们在某高校实验室的容器化教学平台中，为保证 Ubuntu 18.04/20.04/22.04 多版本兼容性而沉淀下来的硬性规范。

3. block 结构：不是代码块，而是执行域与错误边界的精确划分

3.1 block 的真实作用域：它只包裹 task，不包裹变量、事实或 handler

block最常被误用的地方，是把它当成 Python 的try/except块，认为里面的一切都受其保护。真相是：block只定义了一个task 执行序列的逻辑单元，它的边界严格限定在tasks:列表内。看这个反模式：

- block: - name: Set app config set_fact: app_port: "{{ app_config.port | default(8080) }}" - name: Deploy app copy: src: app.jar dest: /opt/app/ notify: restart app rescue: - name: Rollback on failure debug: msg: "Rolling back app deployment"

问题出在set_fact。set_fact是一个 task，它会在block内部执行，但app_config.port这个变量的解析，发生在block解析阶段——也就是set_facttask 还没开始执行的时候。如果app_config根本没定义，set_fact会因 Jinja2 渲染失败而中断，整个block都不会进入，rescue自然也不会触发。

真正受block/rescue保护的，只有那些成功进入block并开始执行的 task。set_fact的失败，属于playbook 解析期错误，而rescue只捕获task 运行期错误。要修复，必须把变量依赖前置到block外：

- name: Ensure app_config is defined set_fact: app_config: "{{ app_config | default({'port': 8080}) }}" # 这里可以加 when: app_config is not defined，但通常放在 vars: 更清晰 - block: - name: Set app port set_fact: app_port: "{{ app_config.port }}" - name: Deploy app copy: src: app.jar dest: /opt/app/ notify: restart app rescue: - name: Rollback on failure debug: msg: "Rolling back app deployment"

3.2 rescue 的捕获范围：它只接住 task 的 failed: true，不接住 skipped 或 unreachable

rescue的触发条件非常具体：只有当block内某个 task 的执行结果字典中failed: true时，才会进入rescue。这意味着以下三种情况，rescue都不会执行：

1. Task 被when跳过（skipped）：when条件为False，task 状态是skipped，不是failed。
2. Host 不可达（unreachable）：网络不通、SSH 失败，Ansible 标记为unreachable，这属于连接层错误，rescue无法捕获。
3. Handler 通知失败：notify: restart app只是注册 handler，实际执行在 play 结束后。如果 handler 执行失败，它发生在block之外。

我们曾在一个金融类模拟项目 X 中遇到典型场景：block里有copy和notify: start service，rescue里写了debug: msg="rollback"。测试时故意让copy失败，rescue正常触发；但当copy成功、start servicehandler 因端口占用失败时，rescue完全沉默，因为 handler 的失败不在block的管辖范围内。

解决方案是：把关键的、可能失败的 handler 动作，显式地写成block内的 task：

- block: - name: Deploy app copy: src: app.jar dest: /opt/app/ - name: Start app service service: name: myapp state: started enabled: yes rescue: - name: Stop service if start failed service: name: myapp state: stopped ignore_errors: true # 确保 rollback 本身不中断流程 - name: Clean up deployed files file: path: /opt/app/app.jar state: absent

这样，Start app service的失败就能被rescue捕获，rollback 流程才能完整闭环。

3.3 always 的设计哲学：它不是“finally”，而是“无论成功失败都执行的保障”

always常被理解为 Python 的finally，但它的设计意图更务实：提供一个 100% 可靠的清理或报告通道。always里的 task，只要block开始执行（即至少有一个 task 进入执行阶段），就一定会运行，无论前面是ok、changed、failed还是skipped。

这带来一个关键优势：always是唯一能可靠获取block执行结果的地方。Ansible 为每个block注入了一个特殊变量block_result，它是一个列表，包含block内所有 task 的结果字典。你可以用它做精准诊断：

- block: - name: Check disk space command: df -h / | tail -1 | awk '{print $5}' | sed 's/%//' register: disk_usage - name: Fail if disk usage > 90% fail: msg: "Disk usage {{ disk_usage.stdout }}% exceeds 90%" when: disk_usage.stdout | int > 90 always: - name: Log disk check result debug: msg: > Disk check on {{ inventory_hostname }}: usage={{ disk_usage.stdout | default('N/A') }}%, status={{ 'FAILED' if block_result | selectattr('failed', 'equalto', true) | list | length > 0 else 'OK' }}

block_result | selectattr('failed', 'equalto', true) | list | length > 0这段 Jinja2 代码，就是在遍历block_result列表，检查是否有任意 task 的failed字段为true。这是我们在某公司内部运维平台中，用于生成每日健康报告的核心技巧——always确保报告一定生成，block_result提供了原始数据源。

4. when 与 block 的协同实战：构建可审计、可回滚的生产级部署流

4.1 场景还原：一个真实的 Web 应用灰度发布流程

假设我们要部署一个 Web 应用，要求：

• 仅对web组中env: prod且role: primary的主机执行；
• 部署前检查磁盘空间和内存，任一不足则中止并告警；
• 部署过程分三步：备份旧包、拷贝新包、重启服务；
• 任何一步失败，必须回滚到上一版，并发送 Slack 告警；
• 无论成功失败，都要记录本次部署的完整日志到中央存储。

这个需求，单靠when或单靠block都无法满足，必须深度协同。

4.2 分层条件设计：用 when 做准入过滤，用 block 做过程控制

首先，用when做最外层的“准入闸门”，确保 playbook 只在符合条件的主机上启动：

- hosts: all gather_facts: no pre_tasks: - name: Validate host eligibility for prod deploy assert: that: - "'web' in group_names" - "env == 'prod'" - "role == 'primary'" msg: "Host {{ inventory_hostname }} does not meet prod deploy criteria: must be in web group, env=prod, role=primary" when: > (group_names is defined and 'web' in group_names) and (env is defined and env == 'prod') and (role is defined and role == 'primary')

注意这里用了assert模块配合when。when控制assert是否执行，assert则在条件不满足时主动报错，比单纯跳过更符合“准入”语义。gather_facts: no是为了提速，因为我们后续的检查（磁盘、内存）会自己调用命令。

4.3 block/rescue/always 全链路：从检查、部署到回滚、归档

核心部署逻辑封装在block中，rescue负责回滚，always负责日志归档：

- block: - name: Check available disk space on /opt command: df -B1 /opt | tail -1 | awk '{print $4}' register: disk_free_bytes changed_when: false - name: Fail if /opt has less than 1GB free fail: msg: "/opt has only {{ disk_free_bytes.stdout | int }} bytes free, less than 1GB required" when: disk_free_bytes.stdout | int < 1073741824 - name: Check available memory command: free -b | grep Mem: | awk '{print $7}' register: mem_free_bytes changed_when: false - name: Fail if free memory < 512MB fail: msg: "Free memory is {{ mem_free_bytes.stdout | int }} bytes, less than 512MB required" when: mem_free_bytes.stdout | int < 536870912 - name: Backup current app.jar command: cp /opt/app/app.jar /opt/app/app.jar.backup_{{ ansible_date_time.iso8601_basic_short }} args: creates: /opt/app/app.jar.backup_{{ ansible_date_time.iso8601_basic_short }} register: backup_result - name: Copy new app.jar copy: src: files/app.jar dest: /opt/app/app.jar owner: appuser group: appuser mode: '0644' - name: Restart app service service: name: myapp state: restarted enabled: yes rescue: - name: Attempt to restore from backup command: cp /opt/app/app.jar.backup_{{ ansible_date_time.iso8601_basic_short }} /opt/app/app.jar args: removes: /opt/app/app.jar.backup_{{ ansible_date_time.iso8601_basic_short }} ignore_errors: true - name: Ensure service is stopped after failed deploy service: name: myapp state: stopped ignore_errors: true - name: Send Slack alert for deployment failure uri: url: "{{ slack_webhook_url }}" method: POST body: > { "text": "DEPLOY FAILED on {{ inventory_hostname }}\nError: {{ block_result | last | default({}) | json_query('msg') | default('Unknown error') }}", "username": "Ansible Bot" } body_format: json when: slack_webhook_url is defined and slack_webhook_url != '' always: - name: Archive deployment log copy: content: | Deployment started at {{ ansible_date_time.iso8601 }} Host: {{ inventory_hostname }} Status: {{ 'FAILED' if block_result | selectattr('failed', 'equalto', true) | list | length > 0 else 'SUCCESS' }} Block result summary: {{ block_result | map(attribute='invocation.module_name') | list | join(', ') }} dest: /var/log/ansible/deploy_{{ inventory_hostname }}_{{ ansible_date_time.iso8601_basic_short }}.log

这个block展示了完整的生产级思维：

• 检查前置：disk_free_bytes和mem_free_bytes的changed_when: false避免无谓的changed状态污染；
• 精准回滚：rescue中的cp命令用removes参数确保只在备份文件存在时才执行，ignore_errors: true保证 rollback 本身不中断流程；
• 智能告警：json_query('msg')从block_result的最后一个失败 task 中提取错误信息，让 Slack 告警内容可读性强；
• 审计归档：always中的日志内容，包含了时间戳、主机名、最终状态和所有执行过的模块名，为事后审计提供完整线索。

4.4 关键经验：如何让 block_result 成为你最可靠的诊断助手

block_result是 Ansible 2.8+ 引入的隐藏宝藏，但它的结构容易让人困惑。它是一个列表，每个元素对应block内一个 task 的结果字典。例如，如果block有 3 个 task，block_result就是[task1_result, task2_result, task3_result]。

要从中提取有用信息，必须掌握几个核心 Jinja2 过滤器：

• | first/| last：取第一个或最后一个结果；
• | selectattr('failed', 'equalto', true)：筛选所有失败的 task；
• | map(attribute='msg') | first：取第一个失败 task 的msg字段；
• | map(attribute='invocation.module_name') | list：列出所有执行过的模块名。

我们在某图像处理 Demo 的 CI/CD 流程中，用block_result实现了自动化的失败原因分类。例如，区分是“资源不足”（df/freetask 失败）、“文件权限”（copytask 的msg包含Permission denied）还是“服务异常”（servicetask 的rc不为 0）。这比在rescue里写一堆when判断更简洁、更可靠。

注意：block_result只在rescue和always中可用，在block内部不可用。这是由执行时序决定的——block内部的 task 还在执行中，block_result还没生成完毕。

5. 高阶技巧与避坑指南：那些文档里不会写的实战心得

5.1 when 的性能优化：避免在循环中重复计算昂贵条件

当when用在loop或with_items中时，条件表达式会被每次迭代都重新求值。如果条件涉及lookup插件（如file、passwordstore）或外部命令（如command），性能会急剧下降。例如：

# 危险！每次循环都读取一次密码文件 - name: Create users with passwords user: name: "{{ item.name }}" password: "{{ lookup('file', '/etc/secrets/' + item.name + '_pwd') }}" loop: "{{ users }}" when: inventory_hostname in groups['prod'] # 这个条件其实对所有 item 都一样

优化方案是：把不变的条件移到 loop 外，用vars或set_fact预计算：

- name: Pre-calculate prod flag set_fact: is_prod_host: "{{ inventory_hostname in groups['prod'] }}" - name: Create users with passwords user: name: "{{ item.name }}" password: "{{ lookup('file', '/etc/secrets/' + item.name + '_pwd') }}" loop: "{{ users }}" when: is_prod_host

is_prod_host只计算一次，后续所有循环都复用这个布尔值。这是我们在处理数百个用户的批量创建任务时，将单次 playbook 执行时间从 12 分钟缩短到 2 分钟的关键技巧。

5.2 block 的嵌套艺术：用多层 block 构建细粒度错误处理

block支持无限嵌套，这为复杂流程提供了细粒度控制能力。例如，在数据库迁移场景中，你可能需要：

• 外层block：保障整个迁移事务的原子性；
• 内层block：针对每个 SQL 文件，单独做备份与回滚。

- block: - name: Dump current database schema command: mysqldump --no-data myapp > /tmp/schema_backup.sql args: creates: /tmp/schema_backup.sql - block: - name: Apply migration 001 mysql_db: name: myapp state: import target: migrations/001_add_users.sql - name: Verify migration 001 command: mysql -e "SELECT COUNT(*) FROM users" myapp register: users_count rescue: - name: Rollback migration 001 command: mysql myapp < /tmp/schema_backup.sql ignore_errors: true - block: - name: Apply migration 002 mysql_db: name: myapp state: import target: migrations/002_add_posts.sql rescue: - name: Rollback migration 002 command: mysql myapp < /tmp/schema_backup.sql ignore_errors: true rescue: - name: Final emergency rollback command: mysql myapp < /tmp/schema_backup.sql

这种嵌套结构，让每个迁移步骤都有自己的rescue，同时外层rescue作为兜底。它比把所有 SQL 文件塞进一个block更安全，也比每个 SQL 文件都写一个独立block更简洁。

5.3 终极避坑：永远不要在 when 中使用未定义的变量，除非你明确处理了它

这是最根本、也最容易被忽视的原则。Ansible 的when求值时，对未定义变量的静默处理（转为空）是最大的陷阱来源。看这个经典错误：

# inventory 中没有定义 max_connections - name: Configure database max_connections lineinfile: path: /etc/my.cnf line: "max_connections = {{ max_connections }}" when: max_connections is defined

when: max_connections is defined看似保险，但lineinfile的line参数里，{{ max_connections }}依然会尝试渲染。如果max_connections未定义，Jinja2 会报错，when根本没机会生效。

正确写法，必须在所有变量使用处都做防御：

- name: Configure database max_connections lineinfile: path: /etc/my.cnf line: "max_connections = {{ max_connections | default(100) }}" when: max_connections is defined or max_connections | default(100) != 100

或者，更推荐的方式是：在 vars 或 pre_tasks 中，用set_fact统一初始化所有可能缺失的变量：

- name: Set default variables set_fact: max_connections: "{{ max_connections | default(100) }}" db_host: "{{ db_host | default('localhost') }}" db_port: "{{ db_port | default(3306) }}"

然后所有when和 task 都可以直接使用这些已定义的变量。这是我们在所有生产 playbook 中强制推行的“变量守门员”模式，它让when的逻辑变得纯粹，不再承担变量容错的职责。

我在实际使用中发现，把set_fact初始化放在pre_tasks里，比放在vars里更灵活，因为它可以基于其他变量（如group_names）动态计算默认值。例如，web组的max_connections默认设为 200，db组设为 500，这在vars里做不到，但在pre_tasks的set_fact里，用when就能轻松实现。这种组合，才是 Ansible 条件判断与块结构的真正威力所在。