name: ansible
description: "使用 Ansible 进行基础设施自动化。适用于服务器配置、配置管理、应用部署和多主机编排。包含用于 OpenClaw VPS 设置、安全加固和常见服务器配置的 Playbook。"
metadata: {"openclaw":{"requires":{"bins":["ansible","ansible-playbook"]},"install":[{"id":"ansible","kind":"pip","package":"ansible","bins":["ansible","ansible-playbook"],"label":"安装 Ansible (pip)"}]}}

Ansible 技能

用于服务器配置、配置管理和编排的基础设施即代码自动化工具。

快速开始

前置条件

# 安装 Ansible
pip install ansible

# 或在 macOS 上
brew install ansible

# 验证安装
ansible --version

运行你的第一个 Playbook

# 测试连接
ansible all -i inventory/hosts.yml -m ping

# 运行 Playbook
ansible-playbook -i inventory/hosts.yml playbooks/site.yml

# 模拟运行（检查模式）
ansible-playbook -i inventory/hosts.yml playbooks/site.yml --check

# 使用特定标签
ansible-playbook -i inventory/hosts.yml playbooks/site.yml --tags "security,nodejs"

目录结构

skills/ansible/
├── SKILL.md              # 本文档
├── inventory/            # 主机清单
│   ├── hosts.yml         # 主清单文件
│   └── group_vars/       # 组变量
├── playbooks/            # 可运行的 Playbook
│   ├── site.yml          # 主 Playbook
│   ├── openclaw-vps.yml  # OpenClaw VPS 设置
│   └── security.yml      # 安全加固
├── roles/                # 可复用的角色
│   ├── common/           # 基础系统设置
│   ├── security/         # 安全加固（SSH, fail2ban, UFW）
│   ├── nodejs/           # Node.js 安装
│   └── openclaw/         # OpenClaw 安装
└── references/           # 参考文档
    ├── best-practices.md
    ├── modules-cheatsheet.md
    └── troubleshooting.md

核心概念

清单

在 inventory/hosts.yml 中定义你的主机：

all:
  children:
    vps:
      hosts:
        eva:
          ansible_host: 217.13.104.208
          ansible_user: root
          ansible_ssh_pass: "{{ vault_eva_password }}"
        plane:
          ansible_host: 217.13.104.99
          ansible_user: asdbot
          ansible_ssh_private_key_file: ~/.ssh/id_ed25519_plane

    openclaw:
      hosts:
        eva:

Playbook

自动化的入口点：

# playbooks/site.yml - 主 Playbook
---
- name: 配置所有服务器
  hosts: all
  become: yes
  roles:
    - common
    - security

- name: 设置 OpenClaw 服务器
  hosts: openclaw
  become: yes
  roles:
    - nodejs
    - openclaw

角色

可复用、模块化的配置单元：

# roles/common/tasks/main.yml
---
- name: 更新 apt 缓存
  ansible.builtin.apt:
    update_cache: yes
    cache_valid_time: 3600
  when: ansible_os_family == "Debian"

- name: 安装基础软件包
  ansible.builtin.apt:
    name:
      - curl
      - wget
      - git
      - htop
      - vim
      - unzip
    state: present

包含的角色

1. common

基础系统配置：
- 系统更新
- 基础软件包
- 时区配置
- 创建用户并添加 SSH 密钥

2. security

遵循 CIS 基准的安全加固：
- SSH 加固（仅密钥登录，禁止 root）
- 使用 fail2ban 防御暴力破解
- UFW 防火墙配置
- 自动安全更新

3. nodejs

通过 NodeSource 安装 Node.js：
- 可配置版本（默认：22.x LTS）
- npm 全局包
- pm2 进程管理器（可选）

4. openclaw

完整的 OpenClaw 设置：
- Node.js（通过 nodejs 角色）
- 通过 npm 安装 OpenClaw
- Systemd 服务配置
- 配置文件设置

使用模式

模式 1：新 VPS 设置（OpenClaw）

# 1. 将主机添加到清单
cat >> inventory/hosts.yml << 'EOF'
        newserver:
          ansible_host: 1.2.3.4
          ansible_user: root
          ansible_ssh_pass: "initial_password"
          deploy_user: asdbot
          deploy_ssh_pubkey: "ssh-ed25519 AAAA... asdbot"
EOF

# 2. 运行 OpenClaw Playbook
ansible-playbook -i inventory/hosts.yml playbooks/openclaw-vps.yml \
  --limit newserver \
  --ask-vault-pass

# 3. 初始设置后，更新清单以使用密钥认证
# ansible_user: asdbot
# ansible_ssh_private_key_file: ~/.ssh/id_ed25519

模式 2：仅安全加固

ansible-playbook -i inventory/hosts.yml playbooks/security.yml \
  --limit production \
  --tags "ssh,firewall"

模式 3：滚动更新

# 一次更新一台服务器
ansible-playbook -i inventory/hosts.yml playbooks/update.yml \
  --serial 1

模式 4：临时命令

# 检查所有服务器的磁盘空间
ansible all -i inventory/hosts.yml -m shell -a "df -h"

# 重启服务
ansible openclaw -i inventory/hosts.yml -m systemd -a "name=openclaw state=restarted"

# 复制文件
ansible all -i inventory/hosts.yml -m copy -a "src=./file.txt dest=/tmp/"

变量与密钥管理

组变量

# inventory/group_vars/all.yml
---
timezone: Europe/Budapest
deploy_user: asdbot
ssh_port: 22

# 安全设置
security_ssh_password_auth: false
security_ssh_permit_root: false
security_fail2ban_enabled: true
security_ufw_enabled: true
security_ufw_allowed_ports:
  - 22
  - 80
  - 443

# Node.js
nodejs_version: "22.x"

使用 Vault 管理密钥

# 创建加密的变量文件
ansible-vault create inventory/group_vars/all/vault.yml

# 编辑加密文件
ansible-vault edit inventory/group_vars/all/vault.yml

# 运行 Playbook 时提供 Vault 密码
ansible-playbook site.yml --ask-vault-pass

# 或使用 Vault 密码文件
ansible-playbook site.yml --vault-password-file ~/.vault_pass

Vault 文件结构示例：

# inventory/group_vars/all/vault.yml
---
vault_eva_password: "y8UGHR1qH"
vault_deploy_ssh_key: |
  -----BEGIN OPENSSH PRIVATE KEY-----
  ...
  -----END OPENSSH PRIVATE KEY-----

常用模块

最佳实践

1. 始终为任务命名

# 好
- name: 安装 nginx 网页服务器
  apt:
    name: nginx
    state: present

# 不好
- apt: name=nginx

2. 使用 FQCN（完全限定集合名称）

# 好
- ansible.builtin.apt:
    name: nginx

# 可以接受，但不够清晰
- apt:
    name: nginx

3. 明确指定状态

# 好 - 状态明确
- ansible.builtin.apt:
    name: nginx
    state: present

# 不好 - 状态隐式
- ansible.builtin.apt:
    name: nginx

4. 幂等性

编写可以安全运行多次的任务：

# 好 - 幂等
- name: 确保配置行存在
  ansible.builtin.lineinfile:
    path: /etc/ssh/sshd_config
    regexp: '^PasswordAuthentication'
    line: 'PasswordAuthentication no'

# 不好 - 非幂等
- name: 添加配置行
  ansible.builtin.shell: echo "PasswordAuthentication no" >> /etc/ssh/sshd_config

5. 使用处理器处理重启

# tasks/main.yml
- name: 更新 SSH 配置
  ansible.builtin.template:
    src: sshd_config.j2
    dest: /etc/ssh/sshd_config
  notify: 重启 SSH 服务

# handlers/main.yml
- name: 重启 SSH 服务
  ansible.builtin.systemd:
    name: sshd
    state: restarted

6. 使用标签进行选择性运行

- name: 安全任务
  ansible.builtin.include_tasks: security.yml
  tags: [security, hardening]

- name: 应用部署
  ansible.builtin.include_tasks: deploy.yml
  tags: [deploy, app]

故障排除

连接问题

# 手动测试 SSH 连接
ssh -v user@host

# 调试 Ansible 连接
ansible host -i inventory -m ping -vvv

# 检查清单解析
ansible-inventory -i inventory --list

常见错误

"Permission denied"
- 检查 SSH 密钥权限：chmod 600 ~/.ssh/id_*
- 确认用户有 sudo 权限
- 在 Playbook 中添加 become: yes

"Host key verification failed"
- 在 ansible.cfg 中添加：host_key_checking = False
- 或添加主机密钥：ssh-keyscan -H host >> ~/.ssh/known_hosts

"Module not found"
- 使用 FQCN：ansible.builtin.apt 而非 apt
- 安装集合：ansible-galaxy collection install community.general

调试 Playbook

# 详细输出
ansible-playbook site.yml -v    # 基础
ansible-playbook site.yml -vv   # 更多
ansible-playbook site.yml -vvv  # 最详细

# 逐步执行任务
ansible-playbook site.yml --step

# 从特定任务开始
ansible-playbook site.yml --start-at-task="安装 nginx"

# 检查模式（模拟运行）
ansible-playbook site.yml --check --diff

与 OpenClaw 集成

从 OpenClaw Agent 执行

# 通过 exec 工具运行 Playbook
exec command="ansible-playbook -i skills/ansible/inventory/hosts.yml skills/ansible/playbooks/openclaw-vps.yml --limit eva"

# 执行临时命令
exec command="ansible eva -i skills/ansible/inventory/hosts.yml -m shell -a 'systemctl status openclaw'"

存储凭据

使用 OpenClaw 的 Vaultwarden 集成：

# 从 vault 缓存获取密码
PASSWORD=$(.secrets/get-secret.sh "VPS - Eva")

# 在 ansible 中使用（不推荐 - 应使用 ansible-vault）
ansible-playbook site.yml -e "ansible_ssh_pass=$PASSWORD"

更好的做法：存储在 Ansible Vault 中并使用 --ask-vault-pass。

参考文档

• references/best-practices.md - 详细的最佳实践指南
• references/modules-cheatsheet.md - 常用模块速查表
• references/troubleshooting.md - 扩展的故障排除指南

外部资源

• Ansible 官方文档
• Ansible Galaxy - 社区角色
• geerlingguy 角色 - 高质量角色
• Ansible for DevOps - Jeff Geerling 的书籍