中文

应用程序

使用 Ansible 自动化管理服务器

Ansible 入门:安装、清单、playbook、角色,以及使用 Ansible Vault 加密 Debian 和 Ubuntu 服务器的机密信息。

阅读约 6 分钟, 更新于 2026年11月18日

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

Ansible 可以让您在 YAML 文件中描述服务器的配置,然后通过 SSH 将其应用到服务器上。被管理的服务器上无需安装任何代理:它们只需要 SSH 和 Python。

在本指南中,您将创建一个小型项目:安装 Nginx、发布一个演示页面,并使用 Ansible Vault 写入一个加密的机密信息。

术语 含义
控制节点 安装了 Ansible、并从中运行命令的机器
受管节点 由 Ansible 管理的服务器
清单(Inventory) 服务器及其分组的列表
任务(Task) 交由某个模块完成的单个操作
Playbook 将任务与服务器关联起来的 YAML 文件
角色(Role) 可重复使用的任务、模板和变量的集合
Vault 用于加密敏感数据的机制

前提条件

  • 一个运行 Linux 的控制节点:您的电脑或一台管理服务器
  • 一台或多台运行 Debian 12/13 或 Ubuntu 22.04/24.04 的受管服务器
  • 每台受管服务器上有一个属于 sudo 组的 SSH 用户
  • 使用密钥进行 SSH 身份验证
  • 控制节点可以访问 SSH 端口,以及用于演示页面的 80 端口

选择控制节点

可用的 Ansible 版本取决于控制节点上的 Python 版本:

控制节点系统 Python pipx 安装的版本 状态
Debian 13 3.13 Ansible 15(ansible-core 2.22) 推荐
Ubuntu 24.04 3.12 Ansible 14(ansible-core 2.21) 推荐
Debian 12 3.11 Ansible 12(ansible-core 2.19) 2026 年 11 月终止支持
Ubuntu 22.04 3.10 Ansible 10(ansible-core 2.17) 已终止支持

此限制仅针对控制节点。Debian 12 和 Ubuntu 22.04 仍可用作受管服务器。

安装 Ansible

在控制节点上,使用 pipx 安装 Ansible,这是官方文档中介绍的一种方法:

终端
sudo apt update
sudo apt install -y pipx
pipx ensurepath

请关闭并重新打开会话以使 PATH 生效,然后安装完整的软件包:

终端
pipx install --include-deps ansible
ansible --version

准备 SSH 访问

如果您还没有密钥,请先创建,然后将其复制到受管服务器:

终端
ssh-keygen -t ed25519 -C "ansible"
ssh-copy-id 您的用户名@您的服务器IP
ssh -t 您的用户名@您的服务器IP 'python3 --version && sudo -v'

首次连接时会要求您确认服务器的指纹:请认真核对,因为此后 Ansible 会拒绝未知主机。如需加固 SSH 访问,请参阅指南 保护您的服务器。

创建项目

终端
mkdir -p ~/infra/group_vars/web
cd ~/infra
nano ansible.cfg
配置
[defaults]
inventory = inventory.ini
roles_path = roles

编写清单

终端
nano inventory.ini
配置
[web]
web1 ansible_host=您的服务器IP ansible_user=您的用户名

如果您的 SSH 端口不是 22,请在服务器所在行添加 ansible_port=您的端口。然后检查清单和连接:

终端
ansible-inventory --graph
ansible all -m ansible.builtin.ping
ansible web -m ansible.builtin.command -a "uptime"

ping 模块应返回 pong。它检查的是 SSH 连接和 Python,而不是网络 ping。

编写第一个 playbook

终端
nano premier-playbook.yml
YAML
---
- name: 准备 Web 服务器
  hosts: web
  become: true
  tasks:
    - name: 安装 Nginx
      ansible.builtin.apt:
        name: nginx
        state: present
        update_cache: true
        cache_valid_time: 3600

    - name: 启用并启动 Nginx
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: true

become: true 会以 sudo 执行任务。请先在不做任何修改的情况下测试,然后再应用:

终端
ansible-playbook premier-playbook.yml --check --diff
ansible-playbook premier-playbook.yml

如果 sudo 需要密码,请添加 --ask-become-pass。然后再运行一次 playbook:汇总信息应显示 changed=0,因为目标状态已经达成。这就是幂等性的原理。

使用角色组织代码

生成一个名为 web 的角色结构:

终端
ansible-galaxy role init --init-path roles web

默认变量

文件 roles/web/defaults/main.yml:

YAML
---
web_domain: 您的域名.com
web_root: /var/www/demo
app_config_dir: /etc/demo-app

任务

文件 roles/web/tasks/main.yml:

YAML
---
- name: 安装 Nginx
  ansible.builtin.apt:
    name: nginx
    state: present
    update_cache: true
    cache_valid_time: 3600

- name: 创建站点目录
  ansible.builtin.file:
    path: "{{ web_root }}"
    state: directory
    owner: root
    group: root
    mode: "0755"

- name: 发布演示页面
  ansible.builtin.copy:
    dest: "{{ web_root }}/index.html"
    content: "<h1>由 Ansible 管理的服务器:{{ inventory_hostname }}</h1>\n"
    owner: root
    group: root
    mode: "0644"

- name: 部署站点配置
  ansible.builtin.template:
    src: site.conf.j2
    dest: /etc/nginx/sites-available/demo.conf
    owner: root
    group: root
    mode: "0644"
  notify: 重新加载 Nginx

- name: 启用站点
  ansible.builtin.file:
    src: /etc/nginx/sites-available/demo.conf
    dest: /etc/nginx/sites-enabled/demo.conf
    state: link
  notify: 重新加载 Nginx

- name: 创建应用配置目录
  ansible.builtin.file:
    path: "{{ app_config_dir }}"
    state: directory
    owner: root
    group: root
    mode: "0750"

- name: 写入应用的机密信息
  ansible.builtin.copy:
    dest: "{{ app_config_dir }}/app.env"
    content: "APP_TOKEN={{ app_token }}\n"
    owner: root
    group: root
    mode: "0600"
  no_log: true

- name: 启用并启动 Nginx
  ansible.builtin.service:
    name: nginx
    state: started
    enabled: true

no_log: true 可防止机密信息出现在 Ansible 的输出中。

处理程序(Handler)

文件 roles/web/handlers/main.yml。处理程序只有在被某个任务通知时才会执行,并且在这一系列任务结束时只执行一次:

YAML
---
- name: 重新加载 Nginx
  ansible.builtin.service:
    name: nginx
    state: reloaded

Jinja2 模板

文件 roles/web/templates/site.conf.j2:

Nginx
server {
    listen 80;
    listen [::]:80;
    server_name {{ web_domain }};
    root {{ web_root }};
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

主 playbook

文件 site.yml,位于项目根目录:

YAML
---
- name: 配置 Web 服务器
  hosts: web
  become: true
  roles:
    - web

使用 Ansible Vault 保护机密信息

将普通变量与加密变量分开存放。文件 group_vars/web/vars.yml 保持可读,并引用机密信息:

YAML
---
app_token: "{{ vault_app_token }}"

创建加密文件。命令提示时请选择一个强密码:

终端
EDITOR=nano ansible-vault create group_vars/web/vault.yml

在其中写入机密信息:

YAML
---
vault_app_token: "替换为您的密钥"

保存后,该文件以 $ANSIBLE_VAULT 开头,内容不可读。常用命令如下:

命令 作用
ansible-vault view group_vars/web/vault.yml 查看内容
ansible-vault edit group_vars/web/vault.yml 修改内容
ansible-vault rekey group_vars/web/vault.yml 更改密码

运行部署

如果受管服务器上的 UFW 处于启用状态,请先放行 Web 流量,然后执行模拟运行和部署:

终端
ssh -t 您的用户名@您的服务器IP 'sudo ufw allow 80/tcp'
ansible-playbook site.yml --syntax-check --ask-vault-pass
ansible-playbook site.yml --check --diff --ask-vault-pass
ansible-playbook site.yml --ask-vault-pass

如需自动化,请将密码保存在项目之外的文件中:

终端
install -m 600 /dev/null ~/.ansible-vault-infra
nano ~/.ansible-vault-infra
ansible-playbook site.yml --vault-password-file ~/.ansible-vault-infra

验证结果

终端
curl -H 'Host: 您的域名.com' http://您的服务器IP/
ansible web -b -m ansible.builtin.stat -a "path=/etc/demo-app/app.env"
ansible-playbook site.yml --ask-vault-pass

页面应显示名称 web1,app.env 文件的权限应为 0600,最后一次运行应以 changed=0 结束。

此演示页面通过 HTTP 提供。对于真实的站点,请按照指南 使用 Let's Encrypt 安装 SSL 证书 添加证书。

版本管理与备份项目

Ansible 不保存状态:您的项目就是基准。请将其放入私有 Git 仓库,并排除本地文件:

终端
cd ~/infra
git init
printf '%s\n' '*.retry' '.vault-pass*' > .gitignore
git add .
git status
git commit -m "初始 Ansible 项目"

在首次提交之前,请确认 group_vars/web/vault.yml 确实已加密:

终端
head -n 1 group_vars/web/vault.yml

请将 Vault 密码保存到密码管理器中,并与仓库分开存放:没有它,机密信息将无法恢复。

更新 Ansible

终端
pipx upgrade --include-injected ansible
ansible --version

如果您使用的是 PPA,请执行 sudo apt update,然后执行 sudo apt install --only-upgrade ansible。大版本更新之后,请参阅移植指南,并使用 --check --diff 重新运行您的 playbook。

故障排查

ansible: command not found

pipx 的目录不在 PATH 中。请执行 pipx ensurepath,然后打开一个新会话。

UNREACHABLE 和 Permission denied (publickey,password)

请使用相同的参数测试连接,然后以详细模式重新运行 Ansible:

终端
ssh -p 22 您的用户名@您的服务器IP
ansible all -m ansible.builtin.ping -vvv

请检查 ansible_host、ansible_user、ansible_port 以及所使用的密钥。

Host key verification failed

服务器的指纹未知或已更改。在合法重装之后,请删除旧条目,然后重新连接并核对新的指纹:

终端
ssh-keygen -R 您的服务器IP
ssh 您的用户名@您的服务器IP

Missing sudo password

请添加 --ask-become-pass,或根据您的安全策略配置 sudo。

Attempting to decrypt but no vault secrets found

playbook 读取了加密文件,但没有提供密码。请添加 --ask-vault-pass 或 --vault-password-file。

Decryption failed

密码与该文件的密码不一致。还请检查密码文件中是否包含了其他内容。

Could not get lock /var/lib/dpkg/lock-frontend

另一个 APT 操作正在进行,通常是自动更新。请等待该操作结束,或在 ansible.builtin.apt 任务中添加 lock_timeout: 300。

Ansible 忽略 ansible.cfg

如果当前目录对所有人可写,Ansible 会忽略该文件。请使用 chmod o-w ~/infra 修正权限,然后用 ansible --version 检查结果,它会显示所加载的文件。

延伸阅读

如需在配置之前创建基础设施或生成文件,请参阅指南 开始使用 Terraform。如需集中管理您的机密信息,请参阅 安装 HashiCorp Vault。

参考资料