使用 Ansible 自动化管理服务器
Ansible 入门:安装、清单、playbook、角色,以及使用 Ansible Vault 加密 Debian 和 Ubuntu 服务器的机密信息。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
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---
- 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: truebecome: 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:
---
web_domain: 您的域名.com
web_root: /var/www/demo
app_config_dir: /etc/demo-app任务
文件 roles/web/tasks/main.yml:
---
- 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: trueno_log: true 可防止机密信息出现在 Ansible 的输出中。
处理程序(Handler)
文件 roles/web/handlers/main.yml。处理程序只有在被某个任务通知时才会执行,并且在这一系列任务结束时只执行一次:
---
- name: 重新加载 Nginx
ansible.builtin.service:
name: nginx
state: reloadedJinja2 模板
文件 roles/web/templates/site.conf.j2:
server {
listen 80;
listen [::]:80;
server_name {{ web_domain }};
root {{ web_root }};
index index.html;
location / {
try_files $uri $uri/ =404;
}
}主 playbook
文件 site.yml,位于项目根目录:
---
- name: 配置 Web 服务器
hosts: web
become: true
roles:
- web使用 Ansible Vault 保护机密信息
将普通变量与加密变量分开存放。文件 group_vars/web/vars.yml 保持可读,并引用机密信息:
---
app_token: "{{ vault_app_token }}"创建加密文件。命令提示时请选择一个强密码:
EDITOR=nano ansible-vault create group_vars/web/vault.yml在其中写入机密信息:
---
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 您的用户名@您的服务器IPMissing 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。