Ansible 核心操作速查¶

用途：供 AI 助手快速查阅并编写/执行 Ansible 批量配置。场景：批量配置 Vagrant/Hyper-V 里的多台 Linux 虚拟机。版本基线：Ansible 14.6 / ansible-core 2.22（核对日期 2026-11-11，来源：docs.ansible.com）更新日期：2026-11-11

1. 安装与项目结构¶

# 控制机（Linux/WSL，Windows 宿主机建议在 WSL 里装）
# 官方推荐 pipx（Ubuntu 23.04+ 因 PEP 668 禁止裸 pip 装系统包）：
pipx install --include-deps ansible
# 也可用 pip install ansible（venv 内）或 apt install ansible
ansible --version

# 推荐项目结构
# my-inventory/
# ├── inventory.ini          # 主机清单
# ├── group_vars/all.yml     # 全局变量
# ├── playbooks/             # 剧本
# └── roles/                 # 角色（复用单元）

版本注意：ansible-core 2.19（对应 Ansible 12）起模板引擎有重大变更，旧 playbook/role 升级前先看 porting guide 验证兼容性。社区功能模块以 collection 形式分发，按需安装：ansible-galaxy collection install community.docker。

2. Inventory（主机清单）¶

# inventory.ini
[k8s]
node1 ansible_host=192.168.100.11
node2 ansible_host=192.168.100.12
node3 ansible_host=192.168.100.13

[k8s:vars]
ansible_user=vagrant
ansible_ssh_private_key_file=~/.vagrant.d/insecure_private_key

ansible all -m ping -i inventory.ini        # 连通性测试（第一步）
ansible k8s -m command -a "hostname" -i inventory.ini
ansible-inventory -i inventory.ini --list   # 查看解析后的清单

3. Ad-hoc 常用模块¶

ansible all -m apt -a "name=curl state=present update_cache=yes" -b -i inventory.ini  # -b 提权
ansible all -m service -a "name=docker state=started enabled=yes" -b
ansible all -m copy -a "src=./x.conf dest=/etc/x.conf" -b
ansible all -m shell -a "df -h | grep /$"                   # 需要管道时用 shell
ansible all -m get_url -a "url=... dest=/tmp/x"
ansible all -m file -a "path=/tmp/x state=absent" -b        # 删除
ansible all -a "free -h" -i inventory.ini                    # 默认 command 模块

4. Playbook 模板（装 Docker 示例）¶

# playbooks/install-docker.yml
- hosts: k8s
  become: yes
  tasks:
    - name: 安装依赖
      apt:
        name: [ca-certificates, curl, gnupg]
        state: present
        update_cache: yes

    - name: 安装 Docker
      shell: curl -fsSL https://get.docker.com | sh
      args:
        creates: /usr/bin/docker     # 幂等：已存在则跳过

    - name: vagrant 用户加入 docker 组
      user:
        name: vagrant
        groups: docker
        append: yes

    - name: 启动并自启
      service: { name: docker, state: started, enabled: yes }

ansible-playbook playbooks/install-docker.yml -i inventory.ini
ansible-playbook ... --check          # 演练（不实际执行）
ansible-playbook ... --limit node1    # 只跑某台
ansible-playbook ... -e "version=1.0" # 临时变量
ansible-playbook ... --tags=deploy    # 按 tag 执行

5. 变量、模板与条件¶

vars:
  app_port: 5000
- debug: msg="端口是 {{ app_port }}"
- template: src=app.conf.j2 dest=/etc/app.conf      # Jinja2 模板
- when: ansible_facts['os_family'] == "Debian"       # 条件
- loop:                                              # 循环
    - nginx
    - git
  apt: { name: "{{ item }}", state: present }
- register: result                                   # 捕获输出
- debug: var=result.stdout
- changed_when: false                                # 标记为"未变更"
- failed_when: result.rc not in [0, 2]

Handlers（服务重启，仅配置变更时触发）：

  tasks:
    - name: 更新 nginx 配置
      template: src=nginx.conf.j2 dest=/etc/nginx/nginx.conf
      notify: reload nginx
  handlers:
    - name: reload nginx
      service: { name: nginx, state: reloaded }

6. Roles（规模化复用）¶

ansible-galaxy init roles/docker     # 生成角色骨架
# tasks/main.yml 写任务，defaults/main.yml 写默认变量，handlers/、templates/ 各司其职
ansible-galaxy role install geerlingguy.docker -p roles/   # 装社区角色
ansible-galaxy collection install kubernetes.core          # 装社区 collection

- hosts: k8s
  roles:
    - { role: docker, become: yes }
    - { role: k3s, k3s_version: v1.30.0 }

7. AI 助手操作守则¶

核心原则是幂等：重复执行结果一致；shell 模块必须配 creates: 或 changed_when: 控制幂等。
改远程文件优先 template/copy + notify + handler，不要用 sed 远程改。
先 --check 演练，对生产/重要 VM 再实际执行；执行完检查 changed 数量是否符合预期。
私钥路径、密码放 ansible-vault 加密文件，不写明文进 playbook。
对 Vagrant 环境注意：Vagrant 自带 provisioner 可直接嵌 ansible（config.vm.provision "ansible"），批量管理多环境时优先独立 inventory + playbook。