Ansible 技能

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

快速开始

先决条件

# Install Ansible
pip install ansible

# Or on macOS
brew install ansible

# Verify
ansible --version

运行你的第一个 Playbook

# Test connection
ansible all -i inventory/hosts.yml -m ping

# Run playbook
ansible-playbook -i inventory/hosts.yml playbooks/site.yml

# Dry run (check mode)
ansible-playbook -i inventory/hosts.yml playbooks/site.yml --check

# With specific tags
ansible-playbook -i inventory/hosts.yml playbooks/site.yml --tags "security,nodejs"

目录结构

skills/ansible/
├── SKILL.md              # This file
├── inventory/            # Host inventories
│   ├── hosts.yml         # Main inventory
│   └── group_vars/       # Group variables
├── playbooks/            # Runnable playbooks
│   ├── site.yml          # Master playbook
│   ├── openclaw-vps.yml  # OpenClaw VPS setup
│   └── security.yml      # Security hardening
├── roles/                # Reusable roles
│   ├── common/           # Base system setup
│   ├── security/         # Hardening (SSH, fail2ban, UFW)
│   ├── nodejs/           # Node.js installation
│   └── openclaw/         # OpenClaw installation
└── references/           # Documentation
    ├── 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:

Playbooks

自动化的入口点：

# playbooks/site.yml - Master playbook
---
- name: Configure all servers
  hosts: all
  become: yes
  roles:
    - common
    - security

- name: Setup OpenClaw servers
  hosts: openclaw
  become: yes
  roles:
    - nodejs
    - openclaw

角色

可复用、模块化的配置：

# roles/common/tasks/main.yml
---
- name: Update apt cache
  ansible.builtin.apt:
    update_cache: yes
    cache_valid_time: 3600
  when: ansible_os_family == "Debian"

- name: Install essential packages
  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角色安装）
• OpenClaw npm安装
• Systemd服务
• 配置文件设置

使用模式

模式1：新VPS设置（OpenClaw）

# 1. Add host to inventory
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. Run OpenClaw playbook
ansible-playbook -i inventory/hosts.yml playbooks/openclaw-vps.yml \
  --limit newserver \
  --ask-vault-pass

# 3. After initial setup, update inventory to use key auth
# 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：滚动更新

# Update one server at a time
ansible-playbook -i inventory/hosts.yml playbooks/update.yml \
  --serial 1

模式4：临时命令

# Check disk space on all servers
ansible all -i inventory/hosts.yml -m shell -a "df -h"

# Restart service
ansible openclaw -i inventory/hosts.yml -m systemd -a "name=openclaw state=restarted"

# Copy file
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
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"

密码库

# Create encrypted vars file
ansible-vault create inventory/group_vars/all/vault.yml

# Edit encrypted file
ansible-vault edit inventory/group_vars/all/vault.yml

# Run with vault
ansible-playbook site.yml --ask-vault-pass

# Or use vault password file
ansible-playbook site.yml --vault-password-file ~/.vault_pass

密码库文件结构：

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

通用模块

最佳实践

1. 始终命名任务

# Good
- name: Install nginx web server
  apt:
    name: nginx
    state: present

# Bad
- apt: name=nginx

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

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

# Acceptable but less clear
- apt:
    name: nginx

3. 明确状态

# Good - explicit state
- ansible.builtin.apt:
    name: nginx
    state: present

# Bad - implicit state
- ansible.builtin.apt:
    name: nginx

4. 幂等性

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

# Good - idempotent
- name: Ensure config line exists
  ansible.builtin.lineinfile:
    path: /etc/ssh/sshd_config
    regexp: '^PasswordAuthentication'
    line: 'PasswordAuthentication no'

# Bad - not idempotent
- name: Add config line
  ansible.builtin.shell: echo "PasswordAuthentication no" >> /etc/ssh/sshd_config

5. 使用处理程序进行重启

# tasks/main.yml
- name: Update SSH config
  ansible.builtin.template:
    src: sshd_config.j2
    dest: /etc/ssh/sshd_config
  notify: Restart SSH

# handlers/main.yml
- name: Restart SSH
  ansible.builtin.systemd:
    name: sshd
    state: restarted

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

- name: Security tasks
  ansible.builtin.include_tasks: security.yml
  tags: [security, hardening]

- name: App deployment
  ansible.builtin.include_tasks: deploy.yml
  tags: [deploy, app]

故障排除

连接问题

# Test SSH connection manually
ssh -v user@host

# Debug Ansible connection
ansible host -i inventory -m ping -vvv

# Check inventory parsing
ansible-inventory -i inventory --list

常见错误

"权限被拒绝"

• 检查SSH密钥权限：chmod 600 ~/.ssh/id_*
• 验证用户是否具有sudo访问权限
• 添加become: yes到playbook中

"主机密钥验证失败"

• 添加到ansible.cfg：host_key_checking = False
• 或者添加主机密钥：ssh-keyscan -H 主机 >> ~/.ssh/known_hosts

“找不到模块”

• 使用完全限定集合名称：ansible.builtin.apt而不是apt
• 安装集合：ansible-galaxy collection install community.general

调试剧本

# Verbose output
ansible-playbook site.yml -v    # Basic
ansible-playbook site.yml -vv   # More
ansible-playbook site.yml -vvv  # Maximum

# Step through tasks
ansible-playbook site.yml --step

# Start at specific task
ansible-playbook site.yml --start-at-task="Install nginx"

# Check mode (dry run)
ansible-playbook site.yml --check --diff

与 OpenClaw 集成

来自 OpenClaw 代理

# Run playbook via exec tool
exec command="ansible-playbook -i skills/ansible/inventory/hosts.yml skills/ansible/playbooks/openclaw-vps.yml --limit eva"

# Ad-hoc command
exec command="ansible eva -i skills/ansible/inventory/hosts.yml -m shell -a 'systemctl status openclaw'"

存储凭据

使用 OpenClaw 的 Vaultwarden 集成：

# Get password from vault cache
PASSWORD=$(.secrets/get-secret.sh "VPS - Eva")

# Use in ansible (not recommended - use ansible-vault instead)
ansible-playbook site.yml -e "ansible_ssh_pass=$PASSWORD"

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

参考资料

• 参考资料/最佳实践.md- 详细的最佳实践指南
• 参考资料/模块速查表.md- 常用模块快速参考
• 参考资料/故障排除.md- 扩展故障排除指南

外部资源

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