1

ansible-playbook -i hosts nginx.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# 先搞清楚两个包名：
#   ansible-core —— 引擎本体 + 少量核心模块（很轻）
#   ansible      —— ansible-core + 官方收录的几百个集合（日常推荐装这个）

# Ubuntu/Debian（用官方 PPA，发行版自带的版本通常很旧）
sudo apt install -y software-properties-common
sudo add-apt-repository --yes --update ppa:ansible/ansible
sudo apt install -y ansible

# RHEL/Rocky/Alma（需要 EPEL）
sudo dnf install -y epel-release
sudo dnf install -y ansible

# macOS
brew install ansible

# pip 方式（想用最新版时）
# ⚠️ Debian 12 / Ubuntu 23.04 之后系统 Python 是"受管理环境"，
#    直接 pip install 会报 externally-managed-environment 错误，
#    正确姿势是用 pipx 或虚拟环境：
pipx install --include-deps ansible
# 或者
python3 -m venv ~/.venvs/ansible && ~/.venvs/ansible/bin/pip install ansible

# 验证安装（会显示版本、配置文件位置、模块搜索路径）
ansible --version
# 只记版本号可以这样写：
ansible --version | head -1

# 查看某个模块的用法（比搜索引擎快）
ansible-doc apt
ansible-doc -l | grep nginx

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 安装额外的集合（很多云模块、Docker 模块都在集合里）
ansible-galaxy collection install community.general community.docker amazon.aws

# 团队协作时把依赖写进 requirements.yml，一条命令装齐
# requirements.yml:
#   collections:
#     - name: community.general
#       version: ">=8.0.0"
ansible-galaxy collection install -r requirements.yml

# 所有依赖（角色 + 集合）一起装
ansible-galaxy install -r requirements.yml

1
2
3
4
5
6
7
8
9

# 1. SSH 免密登录已经配好（推荐，最省事）
ssh-copy-id ubuntu@web1.example.com
ssh ubuntu@web1.example.com 'echo ok'   # 能免密执行才算成功

# 2. 目标机有 Python（Ansible 模块要在上面跑）
ssh ubuntu@web1.example.com 'python3 --version'

# 目标机没有 Python 时，只有 raw 模块能用（不依赖 Python）
ansible all -i hosts -m raw -a "which python3" -b

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# 文件：hosts（INI 格式）
# 定义单个主机
web1.example.com

# 定义主机组
[webservers]
web1.example.com
web2.example.com
web3.example.com

[dbservers]
db1.example.com
db2.example.com

[loadbalancers]
lb1.example.com

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 使用端口
web1.example.com:2222

# 使用 IP 地址
192.168.1.101

# 主机范围
web[1:3].example.com  # web1, web2, web3

# 定义变量
[webservers]
web1.example.com ansible_user=ubuntu ansible_port=22

[dbservers]
db1.example.com ansible_user=root

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

[webservers]
web1.example.com
web2.example.com

[dbservers]
db1.example.com

# :children 表示"这个组由哪些组组成"
[prod:children]
webservers
dbservers

[prod:vars]
env_name=prod

# 全局变量（所有主机都生效）
[all:vars]
ansible_python_interpreter=/usr/bin/python3

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 看清 Inventory 展开后的结构，比读文件直观得多
ansible-inventory -i hosts --graph
# @all:
#   |--@ungrouped:
#   |--@webservers:
#   |  |--web1.example.com
#   |  |--web2.example.com
#   |--@prod:
#   |  |--@webservers:
#   |  |--@dbservers:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

[all:vars]
ansible_user=admin
ansible_python_interpreter=/usr/bin/python3
# ⚠️ 不要写 ansible_password=明文密码！
#    优先用 SSH 密钥，确实需要密码时把变量加密（见 61.8 ansible-vault）
#    如果非要用密码，让它从命令行询问：ansible-playbook -k

[webservers:vars]
nginx_port=80
app_path=/var/www/app

[dbservers:vars]
db_port=3306
db_name=myapp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# ⚠️ 注意：老的 ec2.py / ec2.ini 脚本早已从 Ansible 仓库移除，
#    网上很多教程还在教这个，照抄会 404。
#    现代做法是"Inventory 插件"（plugin），配置文件就是清单本身。

# 1. 安装 AWS 集合和依赖
ansible-galaxy collection install amazon.aws
pipx install --include-deps ansible   # boto3/botocore 会一并装好

# 2. 写插件配置 aws_ec2.yml
# plugin: amazon.aws.aws_ec2
# regions:
#   - us-east-1
# aws_profile: prod                 # 用 profile，别把密钥写进文件
# filters:
#   tag:Env: prod
# keyed_groups:
#   - key: tags.Role                # 按标签自动分组：Role=web 归入 role_web 组
#     prefix: role
# compose:
#   ansible_host: public_ip_address  # 用公网 IP 作为连接地址

# 3. 确认它能跑通（--graph 只查询、不执行任何任务）
ansible-inventory -i aws_ec2.yml --graph

# 4. 直接当 Inventory 用
ansible -i aws_ec2.yml all -m ping

1

ansible <host-pattern> -m <module> -a <arguments>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 测试主机连通性
ansible all -m ping
# 输出各主机的 "pong" 就说明 SSH 通了、Python 能跑、模块能下发
# 注意：这里的 ping 不是 ICMP，而是"跑一个最简单的 Ansible 模块"

# 指定 Inventory
ansible all -i hosts -m ping

# 只对部分主机执行（--limit 支持通配和逗号分隔）
ansible all -i hosts --limit 'web1,web2' -m ping
ansible all -i hosts --limit 'webservers:!web3' -m ping   # 排除某台

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 执行命令
ansible all -m command -a "uptime"

# 指定用户
ansible webservers -m command -a "whoami" -u ubuntu

# sudo 执行
ansible all -m command -a "apt update" -b -K

# 幂等写法：判断"文件不存在才执行"（重跑时不会重复执行）
ansible all -m command -a "creates=/opt/app/bin/app /opt/app/install.sh"

1
2

# 执行 shell 命令（支持管道等）
ansible all -m shell -a "ps aux | grep nginx"

1
2
3
4
5

# 复制文件到远程
ansible all -m copy -a "src=./app.conf dest=/etc/app.conf"

# 带权限
ansible all -m copy -a "src=./app.conf dest=/etc/app.conf mode=0644"

1
2
3
4
5
6
7
8

# 创建目录
ansible all -m file -a "path=/data state=directory"

# 创建链接
ansible all -m file -a "path=/link dest=/target state=link"

# 删除
ansible all -m file -a "path=/tmp/cache state=absent"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 安装包（CentOS）
ansible all -m dnf -a "name=nginx state=present"
# 老写法 yum 模块仍可用（RHEL 系已把 yum 软链到 dnf），新代码建议用 dnf；
# 想跨发行版通用，用 package 模块或 FQCN：ansible.builtin.package

# 安装包（Debian）
ansible all -m apt -a "name=nginx state=present update_cache=yes"

# 安装多个包
ansible all -m apt -a "name=nginx,git,vim state=present"

1
2
3
4
5
6
7
8

# 启动服务
ansible all -m service -a "name=nginx state=started"

# 重启服务
ansible all -m service -a "name=nginx state=restarted"

# 停止服务
ansible all -m service -a "name=nginx state=stopped"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 文件名就叫 ansible.cfg
[defaults]
inventory = hosts
remote_user = ubuntu
timeout = 10
# 每隔 60 秒复用一次 SSH 连接，避免几十个任务反复握手（对多主机提速明显）
forks = 20
host_key_checking = False   # ⚠️ 见下方说明

[privilege_escalation]
become = true
become_method = sudo
become_user = root
become_ask_pass = False

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# playbook.yml
---
- hosts: webservers        # 目标主机
  become: true            # 提升权限
  vars:                   # 变量
    nginx_port: 80
    app_path: /var/www
  
  tasks:                  # 任务列表
    - name: 安装 Nginx
      apt:
        name: nginx
        state: present
        update_cache: yes

    - name: 配置 Nginx
      template:
        src: nginx.conf.j2
        dest: /etc/nginx/nginx.conf
      notify: 重启 Nginx

    - name: 启动 Nginx
      service:
        name: nginx
        state: started
        enabled: yes

  handlers:               # 处理器
    - name: 重启 Nginx
      service:
        name: nginx
        state: restarted

1
2
3
4
5
6
7

# 第一次执行
TASK [安装 Nginx] ***************************************
changed: [web1.example.com]

# 第二次执行（什么都没变）
TASK [安装 Nginx] ***************************************
ok: [web1.example.com]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# 执行
ansible-playbook playbook.yml

# 指定 Inventory
ansible-playbook -i hosts playbook.yml

# 语法检查
ansible-playbook --syntax-check playbook.yml

# 模拟执行（dry run）+ 显示文件差异，强烈推荐组合使用
ansible-playbook -C --diff playbook.yml
# 注意：check 模式下，依赖前一步执行结果的命令类任务可能显示 skipped，属正常现象

# 显示执行的主机
ansible-playbook playbook.yml --list-hosts

# 只对部分主机执行
ansible-playbook playbook.yml --limit webservers

# 列出所有任务（不执行），快速检查流程
ansible-playbook playbook.yml --list-tasks

# 指定标签
ansible-playbook playbook.yml --tags=nginx

# 跳过标签
ansible-playbook playbook.yml --skip-tags=config

# 逐步确认每一步（调试用，每执行一个任务问一次）
ansible-playbook playbook.yml --step

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 滚动发布的典型写法：一批 2 台，一批批替换，失败超过 20% 就停
- hosts: webservers
  serial: 2
  max_fail_percentage: 20
  any_errors_fatal: true
  tasks:
    - name: 部署新版本
      copy:
        src: app.jar
        dest: /opt/app/app.jar
      notify: 重启应用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

---
- hosts: all
  tasks:
    - name: RedHat 系安装 Nginx
      dnf:
        name: nginx
        state: present
      when: ansible_os_family == "RedHat"

    - name: Debian 系安装 Nginx
      apt:
        name: nginx
        state: present
      when: ansible_os_family == "Debian"

1
2
3
4
5
6
7

# 把某台主机的所有 facts 打印出来（调试 when 条件时的神器）
ansible web1.example.com -m setup
# 只看部分
ansible web1.example.com -m setup -a "filter=ansible_os_family"

# 主机很多时，收集 facts 会变慢；不需要时可以关掉
# play 里写：gather_facts: false

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

- hosts: webservers
  tasks:
    - name: 检查应用是否已安装
      stat:
        path: /opt/app/app.jar
      register: app_jar

    - name: 未安装才下载
      get_url:
        url: https://example.com/app.jar
        dest: /opt/app/app.jar
      when: not app_jar.stat.exists

    - name: 判断执行结果并给出提示
      debug:
        msg: "上一台机器的 IP 是 {{ ansible_default_ipv4.address }}"
      when: app_jar.stat.exists

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

---
- hosts: webservers
  tasks:
    - name: 创建多个用户
      user:
        name: "{{ item }}"
        state: present
        shell: /bin/bash
      loop:
        - alice
        - bob
        - charlie

    - name: 安装多个包
      apt:
        name: "{{ packages }}"
      vars:
        packages:
          - nginx
          - git
          - vim

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

---
- hosts: webservers
  tasks:
    - name: 忽略错误继续执行
      command: /might/fail
      ignore_errors: yes

    - name: 失败时执行其他任务
      block:
        - name: 执行可能失败的任务
          command: /might/fail
      rescue:
        - name: 失败时执行
          debug:
            msg: "任务失败了，我来接管"
      always:
        - name: 总是执行
          debug:
            msg: "无论成功失败我都会执行"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# 实用写法：命令模块默认"永远报 changed"，用 changed_when 修正
- name: 检查配置语法
  command: nginx -t
  register: nginx_test
  changed_when: false          # 只是检查，不算变更
  failed_when: "'syntax is ok' not in nginx_test.stdout"

# 重试：网络抖动、依赖还没就绪时特别有用
- name: 等待应用端口就绪
  wait_for:
    port: 8080
    delay: 2
    timeout: 60
  register: result
  retries: 5
  delay: 5
  until: result is succeeded

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

- hosts: webservers
  tasks:
    - name: 安装 Nginx
      apt: { name: nginx, state: present }
      tags: [nginx, packages]

    - name: 部署配置文件
      template:
        src: nginx.conf.j2
        dest: /etc/nginx/nginx.conf
      tags: [nginx, config]

1
2
3
4

ansible-playbook site.yml --tags nginx          # 只跑带 nginx 标签的任务
ansible-playbook site.yml --tags "config"       # 只更新配置
ansible-playbook site.yml --skip-tags packages  # 除了装包，其他都跑
ansible-playbook site.yml --list-tags           # 看看有哪些标签可用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

- hosts: webservers
  tasks:
    # 在控制机（本机）执行，比如调用云 API、发通知
    - name: 调用 API 把新实例加入负载均衡后端
      uri:
        url: https://lb.example.com/api/backend
        method: POST
      delegate_to: localhost
      run_once: true      # 只跑一次，不在每台主机上重复执行

    # 在数据库主机上执行，把本机数据导出过去
    - name: 导出备份到数据库机
      command: pg_dump mydb
      delegate_to: db1.example.com

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# copy 模块
- name: 复制文件
  copy:
    src: app.conf
    dest: /etc/app.conf
    owner: root
    group: root
    mode: '0644'
    backup: yes

# template 模块
- name: 复制模板
  template:
    src: app.conf.j2
    dest: /etc/app.conf

# lineinfile 模块
- name: 添加行
  lineinfile:
    path: /etc/sysctl.conf
    line: "vm.swappiness = 10"
    create: yes

# blockinfile 模块
- name: 添加代码块
  blockinfile:
    path: /etc/hosts
    marker: "# {mark} 我的标记"
    block: |
      192.168.1.100 server1
      192.168.1.101 server2

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# apt 模块
- name: 安装包
  apt:
    name:
      - nginx
      - git
    state: present
    update_cache: yes
    cache_valid_time: 3600

# yum 模块
- name: 安装包
  yum:
    name: nginx
    state: present
    enablerepo: epel

# pip 模块
- name: 安装 Python 包
  pip:
    name: django
    version: '4.0'
    # 用 Python 自带的 venv，避免依赖已被弃用的 virtualenv 包
    virtualenv: /opt/venv
    virtualenv_command: python3 -m venv

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# systemd/service 模块
- name: 启动服务
  systemd:
    name: nginx
    state: started
    enabled: yes
    daemon_reload: yes

# user 模块
- name: 创建用户
  user:
    name: deploy
    comment: "Deploy User"
    shell: /bin/bash
    groups: sudo
    password: "{{ 'password' | password_hash('sha512') }}"

# cron 模块
- name: 添加定时任务
  cron:
    name: "备份数据库"
    hour: 2
    minute: 0
    job: "/scripts/backup.sh"
    state: present

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# AWS EC2 模块（集合 amazon.aws；老的 ec2 模块已不再更新）
- name: 创建 EC2 实例
  amazon.aws.ec2_instance:
    key_name: mykey
    instance_type: t3.micro
    # 用 data 源动态取镜像，别写死 ami-12345678
    image_id: "{{ ami_id }}"
    region: us-east-1
    vpc_subnet_id: subnet-12345678
    assign_public_ip: true
    security_group: default
    tags:
      Name: web
    wait: true
  register: ec2_instances

# Docker 模块（集合 community.docker；老的 docker_container 不带前缀已不推荐）
- name: 启动容器
  community.docker.docker_container:
    name: web
    image: nginx:latest
    ports:
      - "80:80"
    state: started

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 方式一：Playbook 中定义
- hosts: webservers
  vars:
    app_name: myapp
    app_version: 1.0.0

# 方式二：文件定义
# group_vars/webservers.yml
---
app_name: myapp
nginx_workers: 4

1
2
3
4
5
6
7
8

---
- hosts: webservers
  vars:
    port: 8080
  tasks:
    - name: 显示变量
      debug:
        msg: "端口是 {{ port }}"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# ❌ 错误写法：每次执行都会生成不同的随机盐，
#    导致"同一个人设置的密码每次都不一样"，反复改动系统状态
- name: 创建用户
  user:
    name: deploy
    password: "{{ 'secret' | password_hash('sha512') }}"

# ✅ 正确写法一：盐固定下来，结果才稳定（幂等）
- name: 创建用户
  user:
    name: deploy
    # salt 用 vault 加密后存放，或从独立变量传入
    password: "{{ 'secret' | password_hash('sha512', vault_password_salt) }}"

# ✅ 正确写法二（更推荐）：只在"用户不存在"时设置随机密码，
#    然后强制首次登录改密码，密码本身不进代码库
- name: 创建用户
  user:
    name: deploy
    password: "{{ lookup('password', '/tmp/deploy_pw chars=ascii_letters,digits length=16') | password_hash('sha512') }}"
    update_password: on_create

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# roles/nginx/tasks/main.yml
---
- name: 安装 Nginx
  apt:
    name: nginx
    state: present
    update_cache: true

- name: 配置 Nginx
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
  notify: 重启 Nginx

- name: 启动 Nginx
  systemd_service:
    name: nginx
    state: started
    enabled: true

1
2
3
4
5
6

# roles/nginx/handlers/main.yml
---
- name: 重启 Nginx
  service:
    name: nginx
    state: restarted

1
2
3
4
5

# roles/nginx/defaults/main.yml
---
nginx_port: 80
nginx_workers: 4
nginx_user: www-data

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# roles/nginx/handlers/main.yml 里用到的变量同理，角色内直接引用即可
# roles/nginx/meta/main.yml —— 声明依赖和角色信息
---
galaxy_info:
  author: your_name
  description: 安装并配置 Nginx
  license: MIT
  min_ansible_version: "2.15"
  platforms:
    - name: Ubuntu
      versions: [jammy]
    - name: EL
      versions: ["9"]

dependencies:
  - role: common        # 先跑 common 角色，再跑本角色

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# site.yml
---
- hosts: webservers
  roles:
    - nginx
    - mysql
    - app

# 带参数
- hosts: databases
  roles:
    - role: mysql
      mysql_port: 3307
      when: ansible_os_family == "Debian"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# 下载他人共享的 Role
ansible-galaxy install geerlingguy.nginx
ansible-galaxy install geerlingguy.mysql

# 搜索 Role
ansible-galaxy search mysql

# 查看已安装（新版本用 role list）
ansible-galaxy role list

# 创建 Role 骨架
ansible-galaxy role init myrole

# 指定版本安装（生产环境一定锁定版本！）
ansible-galaxy role install geerlingguy.nginx,3.1.4

# 批量安装：把依赖写进 requirements.yml 一起装
ansible-galaxy install -r requirements.yml

1
2
3
4
5
6
7
8

# requirements.yml
---
roles:
  - name: geerlingguy.nginx
    version: "3.1.4"
collections:
  - name: community.general
    version: ">=8.0.0"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

# 1. 创建一个加密文件（会打开编辑器输入内容）
ansible-vault create group_vars/all/vault.yml
#   在编辑器里写：
#   vault_db_password: "s3cr3t-p@ss"
#   vault_api_key: "abcdef123456"

# 2. 加密已有文件
ansible-vault encrypt secrets.yml

# 3. 查看明文（临时看内容）
ansible-vault view group_vars/all/vault.yml

# 4. 修改加密文件
ansible-vault edit group_vars/all/vault.yml

# 5. 在命令行里加密单个字符串（用来填进别的文件）
ansible-vault encrypt_string --name 'vault_api_key' 'abcdef123456'

# 6. 解密（一般不需要，除非要放弃加密）
ansible-vault decrypt secrets.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 交互式输入密码
ansible-playbook site.yml --ask-vault-pass

# 密码存在文件里（注意：这个文件本身绝不能进 Git，权限设 600）
echo 'my-vault-password' > ~/.vault_pass
chmod 600 ~/.vault_pass
ansible-playbook site.yml --vault-password-file ~/.vault_pass

# CI/CD 里把密码放到环境变量或密钥管理服务，运行时注入
export ANSIBLE_VAULT_PASSWORD_FILE=/run/secrets/vault_pass
ansible-playbook site.yml

1
2
3

# group_vars/all/vars.yml（明文，可以进 Git）
db_user: myapp
db_password: "{{ vault_db_password }}"   # 引用加密文件里的变量

1
2
3
4
5
6
7
8

# 静态检查 Playbook（风格 + 潜在错误，装上后能省很多调试时间）
pipx install ansible-lint yamllint
ansible-lint site.yml

# 排查问题时的三档详细输出
ansible-playbook site.yml -v      # 显示任务结果
ansible-playbook site.yml -vv     # 显示模块参数
ansible-playbook site.yml -vvv    # 显示 SSH 连接细节（连不上时看这个）