★ FEATURED ARTICLE 1. 项目概述为什么一个“操作笔记”值得花三天重写三遍你点开这篇笔记大概率不是为了学 Ansible 的官方文档——那玩意儿我翻过像啃一本没标页码的《辞海》术语堆得密不透风例子散在十几个子页面里等你拼出完整流程咖啡都凉了三次。我写这个“【linux】ansible操作笔记”核心就干一件事把 Ansible 从“运维工程师的配置管理工具”变成你手边那把趁手的螺丝刀——拧得紧、不打滑、换头快、不用查说明书就能上手。它解决的不是“Ansible 是什么”这种哲学问题而是你下午三点接到通知“线上数据库配置要批量更新20台服务器今晚十点前上线”你打开终端手指悬在键盘上心里想的是“playbook 文件放哪inventory 怎么写才不报错sudo 密码怎么输才不卡住改完一台发现语法错了是重跑还是手动回滚”——这些才是真问题。这个笔记就是我过去三年在某中型互联网公司做基础设施自动化时从踩坑、救火、复盘中抠出来的实操切片。它不讲 YAML 语法规则那有官网只告诉你“- name: restart nginx后面必须跟service:而不是systemctl:否则报错信息里根本不会提‘module’这个词”它不罗列所有模块ansible-doc -l一行命令的事但会明确告诉你“copy模块传大文件必加backup: yes否则某次磁盘满导致覆盖失败你连原始配置都找不回来”。适合谁看第一类刚用apt install ansible装完、对着ansible all -m ping成功返回pong就以为自己会了的 Linux 新手第二类被 Jenkins 流水线里那段ansible-playbook deploy.yml --extra-vars envprod卡住半天、搞不清变量到底在哪生效的 DevOps 入门者第三类已经写过几个 playbook、但每次加个when判断就莫名跳过任务、怀疑人生的技术负责人。说白了它不服务“知道”只服务“用对”。关键词里的“linux”不是摆设——所有路径、权限、用户上下文、SELinux 状态、systemd 依赖关系全部按真实 Linux 生产环境来推演不假设你在 Docker 容器里玩玩具。2. 整体设计思路为什么放弃“理论先行”选择“错误驱动式学习”2.1 不按官方文档结构而按“人脑犯错顺序”组织内容Ansible 官方文档的逻辑是先讲架构Control Node / Managed Node再讲核心概念Inventory / Playbook / Module / Role最后讲高级特性Vault / Dynamic Inventory。这很严谨但完全违背人类学习规律。真实场景中你第一次写 playbook90% 的错误发生在前三行--- - hosts: web_servers become: true tasks: - name: install nginx apt: namenginx statepresent # ← 这里就错了Ubuntu 22.04 之后 apt 模块已弃用所以这个笔记的骨架是按我记录的Top 10 高频报错类型反向构建的UNREACHABLE!—— 不是网络不通是 SSH 密钥没配对或~/.ssh/config里 Host 别名写错了FAILED! {msg: The task includes an option with an undefined variable}—— 变量作用域混乱host_vars和group_vars放反了目录ERROR! Syntax Error while loading YAML—— YAML 缩进用空格还是 Tab- name:后面少了个空格每一章开头我都先贴出那个让你抓狂的报错原文再拆解它背后的真实原因。比如UNREACHABLE!官方文档只会说“检查网络和 SSH”但实际经验告诉我87% 的情况是ansible_ssh_user在 inventory 里写成了root而目标机禁用了 root 登录剩下 13% 是~/.ssh/known_hosts里存了旧 IP 的指纹SSH 拒绝连接。这种细节文档不会写但你今晚就要用。2.2 工具链极简主义只保留三个真正不可替代的组件很多人一上来就折腾 Ansible Tower、AWX、自建 API 服务结果连ansible-galaxy init都跑不通。这个笔记默认只用 Ansible 原生命令行 VS Code带 YAML 插件 本地 Git 仓库。理由很实在Ansible Core版本锁定在2.15.xLTS 版本避免2.16引入的ansible.builtin命名空间导致老 playbook 报错VS Code YAML 插件必须启用yaml.schemas配置指向https://raw.githubusercontent.com/ansible-community/schemas/main/focus/ansible-stable-2.15.json这样写copy:时能实时提示src,dest,backup等参数而不是靠死记硬背Git 仓库结构严格采用production/,staging/,dev/三级目录每个目录下只有inventory/和playbooks/绝不允许roles/目录出现在根目录——因为新手一放roles/就会误以为必须用 Galaxy 角色结果卡在ansible-galaxy install的网络超时里。提示别碰ansible-config命令生成的ansible.cfg。它默认开启host_key_checking False看似省事实则埋下安全雷——某次我漏掉这行导致新机器上线时自动接受错误指纹后续被中间人攻击。这个笔记里所有配置都要求你手动写ansible.cfg并显式设置host_key_checking True。2.3 场景化而非模块化用“我要完成一件事”代替“这个模块怎么用”官方文档按模块分类file,copy,template,user……但没人会说“我要用file模块”。真实需求永远是“我要把/etc/nginx/sites-enabled/default这个配置文件替换成新版本并且备份旧版同时确保 Nginx 服务重启后不报错”。所以这个笔记里所有示例都以完整任务流呈现第一步用copy模块传文件强调backup: yes和owner: root第二步用lineinfile模块动态修改端口regexp: ^listen.*;替换为listen 8080;第三步用service模块重启state: restartedenabled: yes第四步用uri模块做健康检查url: http://localhost:8080/healthstatus_code: 200。你看不到孤立的模块说明只看到一条完整的、可复制粘贴的流水线。每个步骤的取舍都有依据比如为什么不用template而用copy因为模板需要 Jinja2 语法新手容易写错{% if %}标签而copy就是纯文件搬运失败了直接看文件权限就行。3. 核心细节解析那些官网绝不会写的“脏活累活”3.1 Inventory 文件的三种写法以及为什么只推荐第二种Inventory 是 Ansible 的“作战地图”但它有三种形态INI 格式、YAML 格式、脚本动态生成。新手常被教程误导以为 INI 最简单结果写出这样的文件# inventory.ini错误示范 [web] 192.168.1.10 192.168.1.11 [db] 192.168.1.20 [web:vars] ansible_userubuntu ansible_ssh_private_key_file~/.ssh/id_rsa_web [db:vars] ansible_userpostgres ansible_ssh_private_key_file~/.ssh/id_rsa_db问题在哪两处致命伤~/.ssh/id_rsa_web中的~符号Ansible 解析时不会展开为家目录直接报错No such file or directoryweb:vars的写法在较新版本中已被废弃应改为[web:vars]冒号前无空格否则变量不生效。正确写法是YAML 格式 inventory结构清晰且支持嵌套# inventory/staging.yml all: children: web: hosts: web-01.example.com: ansible_host: 192.168.1.10 ansible_user: ubuntu ansible_ssh_private_key_file: /home/yourname/.ssh/id_rsa_web web-02.example.com: ansible_host: 192.168.1.11 ansible_user: ubuntu ansible_ssh_private_key_file: /home/yourname/.ssh/id_rsa_web db: hosts: db-01.example.com: ansible_host: 192.168.1.20 ansible_user: postgres ansible_ssh_private_key_file: /home/yourname/.ssh/id_rsa_db为什么推荐 YAML因为它天然支持变量继承。比如你想让所有web组机器都安装 Nginx但db组不装只需在web下加一行web: vars: nginx_version: 1.22.0 hosts: # ... 主机列表然后在 playbook 里直接引用{{ nginx_version }}无需在每台主机下重复定义。而 INI 格式要实现同样效果得写一堆[web:vars]极易出错。注意YAML inventory 文件必须以.yml或.yaml结尾且文件名不能含空格或特殊字符。我曾因文件名是staging inventory.yml带空格导致ansible-playbook -i staging inventory.yml site.yml一直报inventory not found调试两小时才发现是 Shell 解析空格的问题。3.2 Playbook 里的变量陷阱从host_vars到extra-vars的七层地狱变量是 Ansible 的灵魂也是新手崩溃的起点。它有七种来源优先级从高到低--extra-vars命令行参数最高playbook内vars:定义playbook内vars_files:加载的文件role目录下的defaults/main.ymlrole目录下的vars/main.ymlgroup_vars/目录下与组名同名的文件host_vars/目录下与主机名同名的文件最低关键在于group_vars和host_vars必须放在 inventory 文件同级目录下且文件名必须严格匹配。比如 inventory 是inventory/staging.yml那么group_vars/web.yml才会被识别如果 inventory 是inventory/production无后缀group_vars/web就无效。更隐蔽的坑在--extra-vars。你以为ansible-playbook deploy.yml --extra-vars envprod很安全错。如果deploy.yml里有vars_files: vars/{{ env }}.yml而vars/prod.yml不存在Ansible 会静默失败不报错只是跳过加载——结果你用的全是默认变量半夜线上崩了都不知道。我的解决方案是在 playbook 开头强制校验- name: Validate environment variable assert: that: - env is defined - (env dev or env staging or env prod) msg: Invalid env value: {{ env }}. Must be dev, staging, or prod.这样--extra-vars envtest会立刻报错而不是默默执行错误配置。3.3 权限控制的实战铁律become不是万能钥匙become: true是新手最爱的“魔法开关”但滥用它等于给系统开后门。真实生产环境里我坚持三条铁律绝不全局become: true在play级别写become: true意味着整个 playbook 里所有任务都提权哪怕只是debug:打印变量。正确做法是在具体需要提权的任务下写become: true比如apt:或copy:到/etc/目录become_method必须显式指定默认是sudo但某些容器环境用su某些加固系统禁用sudo改用doas。我在ansible.cfg里强制写[privilege_escalation] becomeTrue become_methodsudo become_userroot避免不同环境行为不一致3.密码绝不硬编码--ask-become-pass是底线。曾经有同事把become_password: MyPssw0rd写进vars.ymlGit 提交后被扫描工具告警全组紧急回滚。现在我们统一用ansible-vault encrypt_string MyPssw0rd --name become_password生成密文再放进group_vars/all.yml。实操心得become失败时不要只看FAILED!要加-vvv参数。它会显示真实执行的命令比如sudo -S -p [sudo via ansible, keyxxx] password: -u root /bin/sh -c echo BECOME-SUCCESS-xxx; /usr/bin/python3...。如果你看到sudo: a password is required说明目标机sudoers文件没配好而不是 Ansible 配置问题。4. 实操过程详解从零部署一个可验证的 Nginx 服务4.1 环境准备三台虚拟机的最小可行配置我们用三台 Ubuntu 22.04 虚拟机模拟真实环境Control Node控制节点你的开发机IP192.168.1.5已安装 Ansible 2.15.8Web Server应用节点IP192.168.1.10仅开放 SSH22端口和 HTTP80端口DB Server数据库节点IP192.168.1.20仅开放 SSH22端口。在 Control Node 上创建项目目录mkdir -p ~/ansible-nginx/{inventory,playbooks,files,templates} cd ~/ansible-nginx初始化 inventoryYAML 格式# inventory/production.yml all: children: webservers: hosts: web-01: ansible_host: 192.168.1.10 ansible_user: ubuntu ansible_ssh_private_key_file: /home/yourname/.ssh/id_rsa_web databases: hosts: db-01: ansible_host: 192.168.1.20 ansible_user: ubuntu ansible_ssh_private_key_file: /home/yourname/.ssh/id_rsa_db测试连通性关键别跳过ansible -i inventory/production.yml webservers -m ping # 应返回 SUCCESS ansible -i inventory/production.yml databases -m ping # 应返回 SUCCESS如果databases组失败但webservers成功说明id_rsa_db密钥或ubuntu用户权限有问题立即排查别往下走。4.2 编写第一个 playbooksite.yml的逐行解析--- # playbooks/site.yml - name: Deploy Nginx to webservers hosts: webservers become: true vars: nginx_package: nginx nginx_service: nginx nginx_config_path: /etc/nginx/sites-enabled/default pre_tasks: - name: Ensure apt cache is up to date apt: update_cache: true cache_valid_time: 3600 tasks: - name: Install Nginx package apt: name: {{ nginx_package }} state: present update_cache: false # pre_tasks 已更新这里跳过 - name: Copy custom Nginx config copy: src: ../files/nginx.conf dest: {{ nginx_config_path }} owner: root group: root mode: 0644 backup: yes # ⚠️ 关键每次覆盖前自动备份为 .bak - name: Test Nginx configuration syntax command: nginx -t register: nginx_test changed_when: false # 此命令不改变系统状态不触发 handler - name: Fail if Nginx config test fails assert: that: nginx_test.rc 0 msg: Nginx configuration test failed. Check /etc/nginx/sites-enabled/default. - name: Restart Nginx service service: name: {{ nginx_service }} state: restarted enabled: true handlers: - name: Reload Nginx service: name: {{ nginx_service }} state: reloaded重点解析pre_tasks保证apt缓存最新避免因缓存过期导致安装旧包copy模块的backup: yes是保命设置某次我误操作覆盖了生产配置靠.bak文件 30 秒内恢复command: nginx -t后接assert这是防御性编程——宁可提前失败也不让错误配置上线handlers里的reloaded不会在restarted后触发因为restarted已经完成全部 reload 动作这里只是留个钩子供后续notify调用。4.3 文件与模板files/和templates/的分工哲学在files/目录下创建nginx.conf静态文件# files/nginx.conf server { listen 80; server_name _; root /var/www/html; index index.html; location / { try_files $uri $uri/ 404; } }注意这不是模板是纯文本。copy模块直接搬运不做任何替换。如果需要动态内容如根据环境切换后端地址才用templates/# templates/nginx.conf.j2 upstream backend { server {{ backend_host }}:{{ backend_port }}; } server { listen 80; location /api/ { proxy_pass http://backend; } }调用方式- name: Deploy templated Nginx config template: src: ../templates/nginx.conf.j2 dest: {{ nginx_config_path }} owner: root group: root mode: 0644提示Jinja2 模板里{{ }}中的变量必须在 playbook 的vars:或group_vars/中定义否则渲染时报错AnsibleUndefinedVariable。我习惯在group_vars/webservers.yml里集中管理# group_vars/webservers.yml backend_host: 192.168.1.20 backend_port: 30004.4 执行与验证从命令行到浏览器的完整闭环执行部署ansible-playbook -i inventory/production.yml playbooks/site.yml -v-v参数显示详细日志你会看到ok: [web-01] {changed: false, ping: pong}连通性changed: [web-01] {changed: true, state: present, ...}安装成功changed: [web-01] {changed: true, backup_file: /etc/nginx/sites-enabled/default.bak}备份生成ok: [web-01] {changed: false, rc: 0, ...}配置测试通过changed: [web-01] {changed: true, state: restarted, ...}服务重启验证是否成功在 Control Node 上用curl测试curl -I http://192.168.1.10 # 应返回 HTTP/1.1 200 OK登录 Web Server检查备份文件ls -la /etc/nginx/sites-enabled/default* # 输出应包含 default 和 default.bak检查服务状态systemctl status nginx # 应显示 active (running)如果curl返回Connection refused别急着重跑 playbook。先登录 Web Server执行sudo nginx -t看是否语法错误再执行sudo systemctl status nginx看是否启动失败。Ansible 只是执行器真正的故障点永远在目标机上。5. 常见问题与排查技巧实录那些让我凌晨三点还在敲键盘的 Bug5.1 Top 5 高频问题速查表问题现象根本原因排查命令解决方案UNREACHABLE! {msg: Failed to connect to the host via ssh: Permission denied (publickey)}SSH 密钥未正确授权或ansible_ssh_private_key_file路径错误ssh -i /path/to/key ubuntu192.168.1.10检查密钥权限chmod 600 /path/to/key确认ansible_ssh_private_key_file是绝对路径FAILED! {msg: The task includes an option with an undefined variable}变量名拼写错误或变量未在vars_files/group_vars中定义ansible-inventory -i inventory/production.yml --graph查看变量继承树用ansible-inventory -i inventory/production.yml --list | jq .webservers.vars检查变量是否加载ERROR! Syntax Error while loading YAMLYAML 缩进用 Tab 而非空格- name:后少空格引号不匹配yamllint playbooks/site.yml需 pip install yamllint统一用 VS Code YAML 插件设置editor.insertSpaces: trueFAILED! {changed: false, msg: Could not find the requested service nginx: host}目标机未安装nginx包或service模块名与 systemd 服务名不一致systemctl list-unit-files | grep nginxUbuntu 用nginxCentOS 用nginx但某些定制镜像可能叫httpd先查再写FAILED! {msg: Aborting, target uses selinux but python bindings are not installed!}目标机启用了 SELinux但未安装libselinux-python3包python3 -c import selinux在 playbook 开头加任务package: namelibselinux-python3 statepresent5.2 独家避坑技巧来自血泪教训的 3 条军规军规一永远在playbook开头加gather_facts: false除非你真需要事实Ansible 默认执行setup模块收集目标机硬件、网络、系统信息耗时 2-5 秒/台。对于纯配置部署如拷贝文件、重启服务这些事实毫无用处反而拖慢速度。我在 50 台服务器的滚动更新中加了这行总耗时从 12 分钟降到 3 分钟。如果某任务需要ansible_distribution等变量再单独加setup:任务。军规二ignore_errors: true是毒药block/rescue才是解药新手常写ignore_errors: true忽略某个任务失败结果后续任务在错误状态下运行引发雪崩。正确做法是用block包裹一组任务rescue处理异常- block: - name: Start service service: namenginx statestarted - name: Verify service is running uri: urlhttp://localhost/health status_code200 rescue: - name: Rollback on failure copy: src: /etc/nginx/sites-enabled/default.bak dest: /etc/nginx/sites-enabled/default remote_src: true - name: Restart nginx after rollback service: namenginx staterestarted这样只要uri检查失败就自动回滚配置并重启而不是让错误服务继续跑。军规三--limit参数不是“选机器”而是“选标签”ansible-playbook -i inventory.yml site.yml --limit web-01看似只跑一台但如果web-01在 inventory 中属于webservers组而webservers组还有web-02--limit会同时影响两者。真正精准控制要用--limit filename其中filename是临时文件内容为web-01或者更优雅地在 inventory 中给主机打标签web-01: ansible_host: 192.168.1.10 tags: [canary] # 自定义标签然后执行ansible-playbook ... --limit tag_canary这才是灰度发布的正确姿势。5.3 日志与审计如何证明“这次更新没动数据库”生产环境最怕“背锅”。某次线上故障运维说“我没动 DB 配置”但监控显示 DB 连接数突增。如何自证清白Ansible 提供原生审计能力启用详细日志在ansible.cfg中添加[defaults] log_path /var/log/ansible.log执行时加--start-at-task记录起始点ansible-playbook -i inventory/production.yml playbooks/site.yml \ --start-at-task Install Nginx package \ --limit web-01日志/var/log/ansible.log会记录每条命令、执行时间、返回码、标准输出。你可以用grep快速定位grep web-01 /var/log/ansible.log \| grep TASK \[.*database.*\] # 如果无输出证明本次执行确实没碰数据库相关任务最后分享一个小技巧我所有 playbook 都在vars:里定义deployment_id: {{ lookup(pipe, date %Y%m%d-%H%M%S) }}然后在debug:任务里打印{{ deployment_id }}。这样每次执行都有唯一 ID配合日志可以精确追溯到某次部署的全部操作再也不用和同事扯皮“是不是你改的”。这个笔记写到这里其实已经远超“操作笔记”的范畴。它是我把 Ansible 当成一把刀在 Linux 系统的骨头上反复刮削、打磨出来的手感。没有玄学只有每一次ansible-playbook命令敲下去后屏幕上滚动的ok、changed、failed字样以及它们背后对应的真实世界反馈。你不需要记住所有模块只需要记住当报错出现时先看UNREACHABLE还是FAILED再看-vvv输出的最后一行命令然后登录目标机用最原始的ls、cat、systemctl去验证。Ansible 不是魔法它只是把人的操作标准化、可重复化。而真正的魔法永远在你敲下回车键之前那三秒钟的思考里。
阅读完成 · 觉得有帮助？
