Ansible Deploy Pro 教程：Go + Ansible 批量运维部署平台

各种项目 24 分前 0 0

Ansible Deploy Pro 是一个基于 Go + Ansible 的企业级批量运维部署平台。它把 Ansible 的能力包装成一个带 Web 界面的服务：主机清单、SSH 密钥、Playbook 模板、文件分发、批量命令和实时任务日志都集中在一个页面里完成，不用再为每台机器手写 Inventory、也不用在终端里盯着 ansible-playbook 的输出翻屏。对于需要同时管理几十上百台服务器的运维团队，这类平台的价值在于把重复操作标准化、可审计、可复用。

一、项目简介

Ansible Deploy Pro 的后端用 Go 编写，前端是静态页面（web/dist/index.html），服务通过 HTTP API 对外提供能力，底层调用本地安装的 Ansible 执行 Playbook。部署形态很简单：一个二进制文件 + 一个配置文件 + 一个数据目录，跑起来就是一个完整的运维控制台。

平台的核心设计思路是“把 Ansible 的工作流搬进浏览器”：主机信息存在 hosts.json，分组存在 groups.json，SSH 私钥集中放在 inventory/ssh_keys/，Playbook 放在 playbooks/ 目录，模板库内置 20 多个常用场景。执行任务时，后端生成对应的 ansible-playbook 调用，通过 SSE（Server-Sent Events）把实时日志推到浏览器，任务可随时取消、可按名称、ID、Playbook 或主机检索。

技术栈：Go（后端服务与 HTTP API）、Ansible（执行引擎）、静态前端（暗色玻璃拟态界面）
数据存储：JSON 文件（hosts.json、groups.json），无外部数据库依赖
默认端口：8080，可通过启动参数修改
开源协议：MIT License

二、功能特性

功能模块	能力说明	入口
主机管理	密码 / SSH 密钥双认证，连接测试，分组管理	主机列表页 / /api/hosts
SSH 密钥库	集中管理 SSH 私钥，自动识别指纹	密钥库 / /api/sshkeys
Playbook 管理	在线编辑、变量解析、执行选项配置	Playbook 页 / /api/playbooks
模板中心	20+ 预置模板，一键创建 Playbook	模板中心 / /api/templates
文件分发	批量分发文件或文本内容到远程主机	文件分发 / /api/files/distribute
命令执行	批量并行 / 串行执行命令，快捷命令	命令执行 / /api/hosts 相关接口
任务中心	SSE 实时日志流，进度追踪，任务取消	任务中心 / /api/tasks/:id/stream
任务检索	按名称、ID、Playbook 或主机搜索，结合状态筛选并显示匹配数量	任务中心搜索框
仪表盘	主机状态概览、任务统计、系统信息	首页 / /api/system/info

值得单独说明的是任务检索：当任务数量变多之后，靠翻页找任务既慢又容易漏。平台支持按任务名称、任务 ID、关联的 Playbook 或目标主机搜索，再叠加状态筛选（如运行中、成功、失败、已取消），搜索结果会直接显示匹配数量，先定位再处理，排障效率高很多。

三、适用场景

批量部署中间件：新机器批量装 Docker、Nginx、MySQL、Redis，用模板中心一键下发，比逐台 SSH 快一个数量级。
批量巡检与基线检查：用 check-system.yml、check-cpu-mem-disk.yml 这类 Playbook 定期采集系统信息和资源使用率，输出统一格式的结果。
配置变更与补丁：update-packages.yml 批量升级软件包，配合任务中心看每台机器的实时输出，出问题立刻取消任务。
安全加固：安全加固模板统一做 SSH 加固、防火墙配置和 fail2ban 部署，避免每台机器配置漂移。
小团队的轻量 CMDB 入口：主机清单、分组、密钥集中管理，十几到几百台机器的规模下，不用上重型 CMDB 也能管得住。

不适用场景也要说清楚：它不适合替代 Jenkins、GitLab CI 做持续交付流水线，也不适合做大规模 CMDB（主机数据存在 JSON 文件里，几千台机器时检索和并发写入会吃力）。它的定位是“运维日常操作的控制台”，而不是全能平台。

四、系统架构与目录结构

服务是单体架构：Go 程序提供 HTTP 服务和前端静态文件，收到执行请求后调用本地 ansible-playbook 子进程，输出通过 SSE 实时推送给浏览器。主机、分组、密钥等数据以 JSON 文件持久化，没有引入数据库，部署和备份都很简单。

ansible-deploy/
├── cmd/
│   └── main.go                    # 主程序入口
├── config/
│   └── config.yaml                # 配置文件
├── internal/
│   ├── handlers/
│   │   └── handlers.go            # HTTP 处理器
│   ├── models/
│   │   └── models.go              # 数据模型
│   └── services/
│       ├── ansible.go             # Ansible 核心服务
│       ├── config.go              # 配置加载
│       └── templates.go           # Playbook 模板库
├── web/dist/
│   └── index.html                 # 前端界面
├── playbooks/                     # Playbook 目录
├── inventory/                     # 资产清单
│   ├── hosts.json                 # 主机数据
│   ├── groups.json                # 分组数据
│   └── ssh_keys/                  # SSH 密钥存储
└── README.md

数据流向很直观：浏览器调 /api/* 接口，后端 handlers 处理请求，services/ansible.go 负责组装 ansible-playbook 命令并执行，执行输出写入任务记录，同时通过 /api/tasks/:id/stream 以 SSE 推送。模板库（templates.go）里是 20 多个预置模板的定义，部署时先渲染成 Playbook 再执行。

五、安装部署

部署需要三样东西：Go 工具链、Ansible、SSH 客户端。README 要求 Go 1.21，Ansible 通过 pip 安装。建议把平台装在一台专门的运维跳板机或管理节点上，不要和业务服务混部。

# 1. 安装 Go（示例为 Go 1.21，可按需换更新版本）
curl -fsSL https://go.dev/dl/go1.21.linux-amd64.tar.gz | tar -C /usr/local -xzf -
export PATH=$PATH:/usr/local/go/bin
go version

# 2. 安装 Ansible
pip install ansible
ansible --version

# 3. 安装 SSH 客户端
apt install openssh-client  # Debian/Ubuntu
# yum install openssh-clients  # RHEL/CentOS/Rocky

# 4. 构建
cd ansible-deploy
go mod tidy
go build -o ansible-deploy cmd/main.go

# 5. 启动（默认端口 8080）
./ansible-deploy

# 自定义端口和配置文件
./ansible-deploy -port 9000 -config /path/to/config.yaml

# 浏览器打开 http://localhost:8080

仓库中还提供 scripts/install.sh 安装脚本（README 未说明其用法，使用前请先阅读脚本内容确认它会安装哪些依赖、做哪些系统改动）。生产环境建议用 systemd 托管服务，参考下面的单元文件。

# /etc/systemd/system/ansible-deploy.service
cat > /etc/systemd/system/ansible-deploy.service << 'EOF'
[Unit]
Description=Ansible Deploy Pro
After=network.target

[Service]
Type=simple
User=ops
WorkingDirectory=/opt/ansible-deploy
ExecStart=/opt/ansible-deploy/ansible-deploy -port 8080
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now ansible-deploy
systemctl status ansible-deploy --no-pager

六、配置详解

配置分两部分：命令行启动参数和 config.yaml。启动参数控制监听地址与端口，config.yaml 控制 Ansible 执行行为。两者要分开理解，出了问题先看是哪一层。

# 启动参数
./ansible-deploy -port 9000 -config /path/to/config.yaml
./ansible-deploy -bind 192.168.1.10 -port 8080  # 修改监听地址（默认仅 127.0.0.1）

# config/config.yaml 示例
# 以下三项省略时分别使用默认值：30 秒、10、json
ssh_timeout: 30        # SSH 连接超时时间（秒）
max_parallelism: 10    # 并发执行的主机数上限
callback_plugin: json  # Ansible 回调插件

ssh_timeout：默认 30 秒。目标主机网络较差或跨机房时适当调大，避免还没连上就超时；设为负数会阻止启动。
max_parallelism：默认 10。批量执行时同时操作的主机数。机器多、操作轻量（如采集信息）时可以调大；操作涉及重启服务或写磁盘时建议保持 10 左右，避免目标端被打爆。负数会阻止启动。
callback_plugin：默认 json。Ansible 的回调插件决定执行结果的输出格式，json 便于后端解析进度和结果。
启动校验：负数超时 / 并发数以及无效 YAML 会阻止启动；如果找不到配置文件，服务会回退到默认配置继续启动——这个行为要留意，改了配置却不生效时，先确认 -config 指向的路径是否真的存在。

七、主机与 SSH 密钥管理

主机是平台操作的基本单位。添加主机时支持密码认证和 SSH 密钥认证两种方式，生产环境强烈建议用密钥认证：密码存在 hosts.json 里本身就有泄露风险，而且密码认证在批量场景下还容易触发目标机的登录失败锁定。

# 生成一对专用密钥（不要复用个人日常使用的密钥）
ssh-keygen -t ed25519 -C "ansible-deploy" -f ~/.ssh/ansible-deploy
# 把公钥分发到目标主机
ssh-copy-id -i ~/.ssh/ansible-deploy.pub user@192.168.1.101

# 通过 API 添加主机（示例）
curl -s -X POST http://localhost:8080/api/hosts \
  -H 'Content-Type: application/json' \
  -d '{"name":"web-01","host":"192.168.1.101","port":22,"user":"ops","auth_type":"key","key_name":"ansible-deploy","groups":["web"]}' | python3 -m json.tool

# 测试连接
curl -s -X POST http://localhost:8080/api/hosts/test/1 | python3 -m json.tool

# 查看主机列表
curl -s http://localhost:8080/api/hosts | python3 -m json.tool

密钥库的使用要点：私钥通过 /api/sshkeys 集中上传，平台自动识别指纹，添加主机时直接引用密钥名称，不用每次粘贴私钥内容。密钥文件落在 inventory/ssh_keys/ 目录下，这个目录的权限和备份要重点看——它丢了，所有主机的免密登录都要重建；它泄露了，所有主机都面临风险。建议把 inventory/ 目录整体纳入备份，并且不要把真实私钥和 hosts.json 提交进 Git。

主机分组按业务维度划分最实用，比如 web、db、cache、k8s-node，或者按环境分 prod-web、staging-web。执行 Playbook 时按分组选择目标，分组即资产边界，误操作的影响范围也先被分组框住。

八、Playbook 与模板中心实战

模板中心是新手最快上手的入口：20 多个预置模板覆盖系统管理、Web 服务、数据库、容器化、DevOps、安全加固和监控告警七大类，选模板、填参数、一键创建 Playbook，不用从零写 YAML。

分类	模板	说明
系统管理	系统包更新、系统信息采集、资源监控检查、日志清理、时间同步（NTP）	日常巡检与基线维护
Web 服务	部署 Nginx、部署 Apache	安装配置 Web 服务与反向代理
数据库	部署 MySQL、部署 Redis、部署 PostgreSQL	数据库安装与基础优化
容器化	部署 Docker、部署 Portainer	Docker CE、镜像加速、容器管理面板
DevOps	部署 Node.js、部署 Python 应用、数据备份	应用运行环境与定时备份
安全加固	安全加固、SSL 证书部署	SSH 加固、防火墙、fail2ban、Let's Encrypt
监控告警	部署 Node Exporter、部署 Grafana	Prometheus 指标采集与可视化面板

以“部署 Nginx”为例：模板中心创建后生成一个可编辑的 Playbook，核心逻辑就是下面这段 YAML——先装包、再下发配置、最后确保服务处于运行状态并开机自启。理解这个结构后，改模板就是改这三个环节。

# 示例：部署 Nginx 的 Playbook 核心逻辑
- name: 部署 Nginx
  hosts: web
  become: true
  tasks:
    - name: 安装 Nginx
      package:
        name: nginx
        state: present

    - name: 下发站点配置
      template:
        src: nginx-site.conf.j2
        dest: /etc/nginx/conf.d/site.conf
      notify: 重载 Nginx

    - name: 确保 Nginx 运行并开机自启
      service:
        name: nginx
        state: started
        enabled: true

  handlers:
    - name: 重载 Nginx
      service:
        name: nginx
        state: reloaded

# 通过 API 执行 Playbook（示例）
curl -s -X POST http://localhost:8080/api/playbooks/execute \
  -H 'Content-Type: application/json' \
  -d '{"playbook":"deploy-nginx.yml","hosts":["web-01","web-02"],"extra_vars":{"server_name":"demo.local"}}' | python3 -m json.tool

# 查看 Playbook 内容
curl -s http://localhost:8080/api/playbooks/deploy-nginx.yml/content

# 从模板创建 Playbook
curl -s -X POST http://localhost:8080/api/templates/deploy \
  -H 'Content-Type: application/json' \
  -d '{"template_id":"deploy-nginx","name":"deploy-nginx-prod.yml"}' | python3 -m json.tool

写 Playbook 的几条经验：变量能参数化的不要写死（比如 server_name、端口、版本号走 extra_vars）；涉及重启服务的步骤一律用 handlers，只在配置真正变化时才触发；先在单台 staging 机器上跑通，再扩大到整个分组；执行前用平台的连接测试确认目标主机都在线，避免跑到一半才发现一半机器连不上。

九、文件分发与批量命令

不是所有操作都值得写一个 Playbook。改一行配置、分发一个脚本、批量查一个版本号，用文件分发和批量命令更快。文件分发支持直接传文件内容或指定本地文件，批量命令支持并行和串行两种模式。

# 文件分发：把本地脚本批量推到目标主机
curl -s -X POST http://localhost:8080/api/files/distribute \
  -H 'Content-Type: application/json' \
  -d '{"hosts":["web-01","web-02"],"dest_path":"/usr/local/bin/check-disk.sh","content":"#!/bin/bash\ndf -h | awk '\''$5+0 > 80 {print \"磁盘告警: \" $0}'\''\n","mode":"0755"}' | python3 -m json.tool

# 批量执行命令：并行采集各机器的系统版本
curl -s -X POST http://localhost:8080/api/playbooks/execute \
  -H 'Content-Type: application/json' \
  -d '{"playbook":"check-system.yml","hosts":["web-01","web-02","db-01"]}' | python3 -m json.tool

并行和串行的选择标准很简单：只读操作（采集信息、查版本、看日志）用并行，越快越好；写操作（改配置、重启服务、升级软件包）优先用串行或小批量并行，一旦某台出问题立刻停下来，不会把故障扩散到整个分组。max_parallelism 这个配置项就是控制并行度的上限，批量操作前先根据操作的风险等级调好它。

十、任务中心与实时日志

每次执行都会生成一个任务，任务中心展示任务列表、状态和进度。执行过程中的输出通过 SSE 实时推送到浏览器，不用反复刷新页面；任务支持取消，取消后后端会尝试终止对应的 ansible-playbook 进程。

# 查看任务列表
curl -s http://localhost:8080/api/tasks | python3 -m json.tool

# 查看单个任务详情
curl -s http://localhost:8080/api/tasks/42 | python3 -m json.tool

# 实时订阅任务日志（SSE 流，输出持续推送直到任务结束）
curl -s -N http://localhost:8080/api/tasks/42/stream

# 取消一个正在运行的任务
curl -s -X DELETE http://localhost:8080/api/tasks/42 | python3 -m json.tool

排障时先看任务中心再看目标机器：任务详情里能看到每台主机的执行结果、失败的 task 名称和 Ansible 返回的错误信息。常见失败原因就几类：SSH 连不上（密钥或端口问题）、become 提权失败（sudo 配置）、Playbook 变量未定义、目标机缺少依赖包。按这个顺序排查，多数问题十分钟内能定位。

十一、常见问题

启动后打不开页面？先确认服务是否在监听：ss -tlnp | grep 8080，再确认防火墙放行了端口。服务默认只监听 127.0.0.1，本机以外的浏览器打不开是正常的，见第十二节的安全建议。
改了 config.yaml 不生效？先确认启动时 -config 指向的路径是否正确；找不到配置文件时服务会静默回退到默认配置，这是最常见的坑。
Playbook 执行报变量未定义？检查执行时是否传了 extra_vars，以及 Playbook 里变量名拼写是否一致。平台的变量解析在执行前做一次校验，但动态生成的变量名查不出来。
任务一直卡在运行中？可能是目标主机 SSH 挂起（网络抖动或主机负载过高），先看任务日志最后输出在哪一步，再到目标机上检查对应进程；必要时取消任务后调大 ssh_timeout 重试。
主机连接测试失败？先在管理节点上手动 ssh 目标机验证密钥和端口，再检查目标机的 sshd 配置和防火墙。密码认证的主机还要确认账号没有被 fail2ban 封禁。
执行速度很慢？检查 max_parallelism 是否太小，以及目标主机的 DNS 反向解析是否超时（Ansible 收集 facts 时会解析主机名，DNS 有问题会显著拖慢）。

十二、安全与运维建议

这是最重要的一节。Ansible Deploy Pro 默认只监听 127.0.0.1，并且 README 明确说明：目前应用没有内置登录认证，不要把管理端口直接映射到公网。这个平台能对所有纳管主机执行任意命令，一旦暴露就等于把所有服务器的 root 权限交了出去。

# 本地使用：直接访问
./ansible-deploy -port 8080
# 打开 http://localhost:8080

# 远程使用：SSH 端口转发（推荐）
ssh -L 8080:127.0.0.1:8080 user@server
# 然后访问本机 http://localhost:8080

# 如确需修改监听地址（仍无内置认证，务必配合反向代理的认证与 HTTPS）
./ansible-deploy -bind 192.168.1.10 -port 8080

团队使用：在前方配置带身份认证和 HTTPS 的反向代理（Nginx + basic auth 或 OIDC），并限制只有管理网段能访问。
机密管理：主机清单和 Playbook 里不要写真实密码和私钥，改用 SSH 密钥与 Ansible Vault 管理机密。Vault 加密的变量文件可以这样处理：ansible-vault encrypt vars/secrets.yml，执行时传入 vault 密码。
备份：定期备份 inventory/（hosts.json、groups.json、ssh_keys/）和 playbooks/ 目录，丢了密钥目录就要逐台重建免密登录。
审计：任务中心保留了执行记录，定期检查谁在什么时候对哪些主机执行了什么操作，尤其是生产分组的操作。
版本管理：Playbook 建议放进 Git 管理，改动先走评审再同步到 playbooks/ 目录，不要直接在生产环境的平台上改完就跑。

另外说明一点：仓库文件清单里还有 internal/auth/（auth.go、captcha.go、handlers.go）与 web/dist/login.html，README 没有说明这些文件的启用方式。按 README 的说法，当前版本没有内置登录认证，上面给出的安全建议（本机监听、SSH 隧道、反向代理认证）是应当遵守的做法；如果后续版本启用了内置认证，以官方 README 更新为准。

总结：Ansible Deploy Pro 的定位很清晰——给中小规模运维团队一个开箱即用的批量操作台。主机、密钥、模板、任务四件事管好了，日常的部署、巡检、变更、加固就都有了统一入口。先把它跑在跳板机上，纳管几台 staging 机器跑通模板，再逐步推广到生产分组，是最稳妥的上线路径。

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。

ansible DevOps Go ssh