搬瓦工 VPS 搭建 Semaphore Ansible Web 界面教程

Semaphore 是 Ansible 的现代化开源 Web 界面，提供了图形化的 Playbook 执行、任务调度和权限管理功能。对于不熟悉 Ansible 命令行的运维人员，Semaphore 大幅降低了自动化运维的门槛。通过 Web 界面可以管理 Inventory、配置密钥、创建任务模板并定时执行，所有操作历史都有完整的日志记录。本教程将介绍如何在搬瓦工 VPS 上使用 Docker 部署 Semaphore。部署前请确保已安装好 Docker 和 Docker Compose。

一、Semaphore 功能概览

项目管理：支持多项目隔离，每个项目独立管理 Inventory、密钥和任务模板。
任务模板：将 Playbook 封装为可复用的模板，支持参数化执行。
定时调度：内置 Cron 调度器，定时自动执行 Playbook。
权限控制：支持多用户和角色权限管理。
执行历史：完整记录每次任务执行的输出日志。
Git 集成：直接从 Git 仓库拉取 Playbook 代码。

二、Docker Compose 部署

mkdir -p /opt/semaphore && cd /opt/semaphore

cat > docker-compose.yml <<'EOF'
version: '3.8'

services:
  semaphore:
    image: semaphoreui/semaphore:latest
    container_name: semaphore
    restart: always
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      SEMAPHORE_DB_DIALECT: bolt
      SEMAPHORE_ADMIN_PASSWORD: admin_pass_2026
      SEMAPHORE_ADMIN_NAME: admin
      SEMAPHORE_ADMIN_EMAIL: admin@example.com
      SEMAPHORE_ADMIN: admin
      SEMAPHORE_ACCESS_KEY_ENCRYPTION: your_encryption_key_2026_abcdef
    volumes:
      - semaphore_data:/var/lib/semaphore
      - /root/.ssh:/root/.ssh:ro

volumes:
  semaphore_data:
EOF

docker compose up -d

2.1 使用 PostgreSQL 后端

cat > docker-compose.yml <<'EOF'
version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    container_name: semaphore-db
    restart: always
    environment:
      POSTGRES_DB: semaphore
      POSTGRES_USER: semaphore
      POSTGRES_PASSWORD: semaphore_db_2026
    volumes:
      - pgdata:/var/lib/postgresql/data

  semaphore:
    image: semaphoreui/semaphore:latest
    container_name: semaphore
    restart: always
    depends_on:
      - postgres
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      SEMAPHORE_DB_DIALECT: postgres
      SEMAPHORE_DB_HOST: postgres
      SEMAPHORE_DB_PORT: 5432
      SEMAPHORE_DB_USER: semaphore
      SEMAPHORE_DB_PASS: semaphore_db_2026
      SEMAPHORE_DB: semaphore
      SEMAPHORE_ADMIN_PASSWORD: admin_pass_2026
      SEMAPHORE_ADMIN_NAME: admin
      SEMAPHORE_ADMIN_EMAIL: admin@example.com
      SEMAPHORE_ADMIN: admin
      SEMAPHORE_ACCESS_KEY_ENCRYPTION: your_encryption_key_2026_abcdef
    volumes:
      - semaphore_config:/etc/semaphore
      - /root/.ssh:/home/semaphore/.ssh:ro

volumes:
  pgdata:
  semaphore_config:
EOF

docker compose up -d

三、Nginx 反向代理

cat > /etc/nginx/conf.d/semaphore.conf <<'EOF'
server {
    listen 443 ssl http2;
    server_name ops.example.com;

    ssl_certificate /etc/letsencrypt/live/ops.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ops.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_request_buffering off;
    }

    location /api/ws {
        proxy_pass http://127.0.0.1:3000/api/ws;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
EOF

nginx -t && systemctl reload nginx

四、项目配置流程

创建项目：在首页点击"New Project"，输入项目名称。
添加密钥：在 Key Store 中添加 SSH 密钥或密码凭据，用于连接目标服务器。
配置仓库：添加 Git 仓库地址，指向存放 Ansible Playbook 的代码仓库。
创建 Inventory：定义目标主机清单，支持静态 INI 格式和动态 Inventory。
创建任务模板：关联仓库、Inventory 和 Playbook 文件路径，配置运行参数。

4.1 Inventory 示例

[webservers]
web1.example.com ansible_host=192.168.1.10 ansible_user=root
web2.example.com ansible_host=192.168.1.11 ansible_user=root

[databases]
db1.example.com ansible_host=192.168.1.20 ansible_user=root

[all:vars]
ansible_python_interpreter=/usr/bin/python3

五、定时任务配置

在任务模板编辑页面，可以设置 Cron 表达式定时执行：

0 3 * * * - 每天凌晨 3 点执行
0 */6 * * * - 每 6 小时执行一次
0 9 * * 1-5 - 工作日上午 9 点执行

六、API 自动化

# 获取 API Token
curl -X POST http://localhost:3000/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"auth": "admin", "password": "admin_pass_2026"}'

# 触发任务执行
curl -X POST http://localhost:3000/api/project/1/tasks \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{"template_id": 1}'

# 查看任务状态
curl -s http://localhost:3000/api/project/1/tasks \
  -H 'Authorization: Bearer YOUR_TOKEN' | python3 -m json.tool

七、常见问题

SSH 连接目标主机失败

确认 Semaphore 容器内可以通过 SSH 密钥连接到目标主机。检查密钥权限和 known_hosts 配置。

docker exec -it semaphore ssh -i /home/semaphore/.ssh/id_ed25519 root@target-host

Git 仓库克隆失败

确保 Key Store 中配置了正确的 Git 访问凭据（SSH 密钥或 Access Token）。

总结

Semaphore 让 Ansible 自动化运维变得更加友好和高效，特别适合团队协作场景。如果需要更通用的作业调度系统，可以参考 Rundeck 教程。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的折扣，购买链接：bwh81.net。