Ubuntu 22.04 安装 DebOps 3.3 指南

Ubuntu 22.04 控制器上安装 DebOps 3.3.2 全实测：pip/pipx/Galaxy 三方案、项目初始化、被管节点准备、首次下发与幂等验证、python-ldap/iproute2 排障实录。

DebOpsDebOpsAnsible自动化运维2026/10/25

Ubuntu 22.04 安装 DebOps 3.3 指南

目标：在一台 Ubuntu 22.04 服务器（Ansible 控制器视角）上从零安装 DebOps 3.3.2 与 Ansible 依赖链，完成项目初始化，并向一台 Ubuntu 22.04 被管节点真实下发一次角色变更。全文命令与回显均来自 2026-10-25 的真实环境实测。

一、环境信息

  • 控制器操作系统：Ubuntu 22.04.5 LTS（x86_64），Python 3.10.12，pip 22.0.2，git 2.34.1
  • 被管节点：Ubuntu 22.04.5 LTS（systemd 运行中），IP 10.89.74.3，主机名 node1.debops.local
  • 安装目标：DebOps 3.3.2（PyPI 当前最新稳定版，2026-09-28 发布）、ansible 10.7.0 / ansible-core 2.17.14
  • 说明：DebOps 是「Ansible 控制器侧」的框架，控制器上无常驻服务；被管节点只需 SSH 可达 + Python 3 + sudo

二、前置条件

控制器侧需要：Ubuntu 22.04（或其他 Linux/macOS/WSL）、可联网下载 PyPI 包、root 或可 sudo 的账号。被管节点侧需要：sshd 运行、Python 3、一个可 sudo 的管理账号（本文演示账号 admin，密码 q1w2e3r4，已在 node1 上配置好免密 sudo 与 SSH 密钥登录）。

先在控制器上装好基础工具（实测回显节选）：

apt-get update -qq
DEBIAN_FRONTEND=noninteractive apt-get install -y python3 python3-pip python3-venv git openssh-client tree sshpass
python3 --version   # Python 3.10.12
pip3 --version      # pip 22.0.2 from /usr/lib/python3/dist-packages/pip (python 3.10)
git --version       # git version 2.34.1

三、版本选型说明

DebOps 通过 PyPI 发布，2026 年内保持活跃维护（实查 PyPI/GitHub Releases，2026-10-25）：

版本发布日期说明
3.3.22026-09-28当前最新稳定版，本文安装目标
3.3.12026-09-143.3 系列补丁版
3.2.82026-09-283.2 维护分支最新
3.1.92026-09-283.1 维护分支最新

官方要求搭配「最新稳定版 Ansible」使用，老版本 Ansible 不保证支持（docs.debops.org 安装文档，2026-10-25 实查）。debops[ansible] 这个 pip extra 会把 ansible 全套依赖一并装齐，是省心之选。

四、方案 A：pip 系统级安装（本文实测主路径）

适合单用户的专用控制器/管理机，直接装进系统 Python 的 dist-packages。

4.1 安装构建依赖（关键，缺了会编译失败）

debops[ansible] 依赖链中的 python-ldap 是 C 扩展，需要编译环境。官方文档给出的依赖清单（docs.debops.org，实测一致）：

DEBIAN_FRONTEND=noninteractive apt-get install -y \
  build-essential python3-dev libffi-dev libssl-dev libsasl2-dev libldap2-dev

⚠️ 排障实录：跳过本步直接 pip3 install "debops[ansible]==3.3.2"，会在 python-ldap 处失败，报错原文为 error: command '/usr/bin/x86_64-linux-gnu-gcc' failed with exit code 1 与 ERROR: Failed building wheel for python-ldap——补上上面 6 个包后重试即成功。

4.2 安装 DebOps 与 Ansible

pip3 install "debops[ansible]==3.3.2"

实测安装结果回显（输出节选，实测尾部）：

Successfully built python-ldap
Installing collected packages: resolvelib, pyxdg, passlib, typing-extensions, toml, smmap, pyyaml, python-dotenv, pycparser, pyasn1, packaging, netaddr, MarkupSafe, future, dnspython, distro, pyasn1-modules, jinja2, gitdb, cffi, python-ldap, gitpython, cryptography, pyopenssl, debops, ansible-core, ansible
Successfully installed MarkupSafe-3.0.4 ansible-10.7.0 ansible-core-2.17.14 cffi-2.1.1 cryptography-50.0.2 debops-3.3.2 distro-1.9.0 dnspython-2.8.0 future-1.0.0 gitdb-4.0.12 gitpython-3.2.1 jinja2-3.1.6 netaddr-1.3.0 packaging-26.3 passlib-1.7.4 pyasn1-0.6.4 pyasn1-modules-0.4.2 pycparser-3.11 pyopenssl-26.4.0 python-ldap-3.4.4 pyxdg-0.28 pyyaml-6.0.3 resolvelib-1.0.1 smmap-5.0.3 toml-0.10.2 typing-extensions-4.16.0

4.3 验证安装

debops --version
# debops 3.3.2

ansible --version | head -3
# ansible [core 2.17.14]
#   config file = None
#   configured module search path = ['/root/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']

debops --help

debops --help 实测回显（这是 CLI 的全貌，命令详解见本专栏《DebOps 3.3 常用 CLI 命令与工具详解》）：

usage: debops <section> [<args>]

Sections:
    project  manage project directories
    exec     run Ansible commands directly against hosts
    run      run Ansible playbook(s) against hosts
    check    run Ansible playbook(s) in check mode
    env      run shell commands in project environment
    config   display DebOps configuration options

DebOps CLI

五、方案 B：pipx 隔离安装（官方推荐）

适合日常管理用机：pipx 把 DebOps 装进独立虚拟环境，不污染系统 Python。

DEBIAN_FRONTEND=noninteractive apt-get install -y pipx   # 实测装得 pipx 1.0.0
pipx ensurepath        # 把 ~/.local/bin 写入 PATH（新开 shell 生效）
pipx install "debops[ansible]"

实测回显（输出节选，实测尾部）：

done! ✨ 🌟 ✨
  installed package debops 3.3.2, installed using Python 3.10.12
  These apps are now globally available
    - debops

验证：

~/.local/bin/debops --version
# debops 3.3.2

六、方案 C：仅装 Ansible Collection（Galaxy）

如果只想在现有 Ansible 项目里用 DebOps 的角色，不需要 debops CLI，可以直接装 Collection：

ansible-galaxy collection install debops.debops

或在项目的 requirements.yml 中声明后批量安装（DebOps 项目初始化时就是用这个机制安装 ansible.posix 等依赖 Collection 的）：

collections:
  - name: debops.debops
    version: "3.3.2"

ansible-galaxy collection install -r requirements.yml

⚠️ 网络说明：实测期间（2026-10-25）galaxy.ansible.com 直连不稳定——debops project init 内置的 Collection 下载实测成功（见第七章回显），但手工 ansible-galaxy collection install debops.debops 多次出现 The read operation timed out。若遇到同样情况，直接用方案 A/B 即可：pip 包已内置完整 debops.debops Collection（203 个角色），Galaxy 安装并非必需。

七、项目初始化与首次下发（安装后验证）

7.1 初始化项目目录

debops project init ~/debops-data-center

实测回显（输出节选，实测尾部）——可见 CLI 自动按 ansible/collections/requirements.yml 从 Galaxy 安装依赖 Collection，最后落盘项目：

Starting galaxy collection install process
Downloading https://galaxy.ansible.com/api/v3/plugin/ansible/content/published/collections/artifacts/ansible-mysql-5.2.0.tar.gz to /root/.ansible/tmp/...
Installing 'ansible.mysql:5.2.0' to '/root/debops-data-center/ansible/collections/ansible_collections/ansible/mysql'
ansible.mysql:5.2.0 was installed successfully
Created new DebOps project in /root/debops-data-center

初始化后的目录结构（tree -L 3 -d 实测）：

.
`-- ansible
    |-- collections        # 项目级 Ansible Collection（requirements.yml 安装）
    |-- inventory          # 主机清单：hosts + group_vars/ + host_vars/
    |-- keyring            # GPG 密钥环（secrets 加密用）
    |-- overrides          # 角色文件/任务/模板的本地覆盖
    |-- playbooks          # 自定义 playbook 与本地角色
    |-- resources          # 角色 resources 查找路径
    `-- secret             # 角色生成的密码/证书等敏感物

同时生成 ansible.cfg（DebOps 托管，刷新会重建）与 .debops.cfg（项目级 DebOps 配置，详见本专栏《DebOps 3.3 配置参数详解》）。目录已自动 git init，首个提交为 Initialize new DebOps project directory。

7.2 登记被管节点

编辑 ansible/inventory/hosts，把节点加入 debops_all_hosts 组与要下发的服务组（本文以轻量的 cron 角色为例）：

[debops_all_hosts]
node1.debops.local ansible_host=10.89.74.3 ansible_user=admin

[debops_service_cron]
node1.debops.local

7.3 连通性验证（debops exec）

cd ~/debops-data-center
debops exec -- all -m ping

实测回显：

node1.debops.local | SUCCESS => {
    "ansible_facts": {
        "discovered_interpreter_python": "/usr/bin/python3.10"
    },
    "changed": false,
    "ping": "pong"
}

7.4 干跑预演（debops check）

debops check service/cron

实测回显（输出节选，实测尾部）——check 模式预演出 5 项变更，包括 crontab 的 diff 预览：

changed: [node1.debops.local]

PLAY RECAP *********************************************************************
node1.debops.local         : ok=7    changed=5    unreachable=0    failed=0    skipped=5    rescued=0    ignored=0

⚠️ 排障实录：若被管节点是极简安装的系统，debops check 可能在「Save cron local facts」任务失败，报 'ansible_all_ipv4_addresses' is undefined——原因是节点缺 iproute2（Ansible 采集网络事实需要 ip 命令）。在节点上 apt-get install -y iproute2 后重跑即通过。

7.5 正式下发（debops run）

debops run service/cron

实测回显（输出节选，实测尾部）：

TASK [debops.debops.cron : Generate crontab configuration file] ****************
changed: [node1.debops.local]

PLAY RECAP *********************************************************************
node1.debops.local         : ok=7    changed=5    unreachable=0    failed=0    skipped=5    rescued=0    ignored=0

Playbook run took 0 days, 0 hours, 0 minutes, 7 seconds

在被管节点上验证落地结果：

dpkg -l cron | tail -1
# ii  cron           3.0pl1-137ubuntu3 amd64        process scheduling daemon

ls /etc/crontab*
# /etc/crontab
# /etc/crontab.dpkg-divert        # 原 crontab 被角色 divert 备份

head -1 /etc/crontab
# # This file is managed remotely, all changes will be lost

7.6 幂等性验证

同一 playbook 再跑一次，应全部 ok 而无 changed：

debops run service/cron

node1.debops.local         : ok=6    changed=0    unreachable=0    failed=0    skipped=5    rescued=0    ignored=0

changed=0 即幂等达成——重复执行不会产生重复变更。

八、方案对比与选择建议

维度A：pip 系统级B：pipx 隔离C：Galaxy Collection
命令pip3 install "debops[ansible]"pipx install "debops[ansible]"ansible-galaxy collection install debops.debops
含 debops CLI是是否（只有角色/playbook）
含 Ansible是是需已有 Ansible
环境隔离否（进系统 dist-packages）是（独立 venv）取决于现有环境
适用专用控制器/CI 节点日常管理用机（官方推荐）已有 Ansible 项目，只想复用角色

选择建议：专用管理机选 A（简单直接）；日常使用机选 B（官方推荐、隔离干净）；只想在自研 Ansible 工程里用 DebOps 角色选 C。

九、配置说明

  • 控制器侧配置文件：项目内 ansible.cfg（由 DebOps 生成/刷新，勿直接改，永久改动写 .debops.cfg）；项目内 .debops.cfg（本项目行为）；全局 ~/.config/debops/conf.d/*.yml（跨项目默认）。四层合并规则与全部可用键见本专栏《DebOps 3.3 配置参数详解》。
  • 被管节点准备清单：openssh-server、sudo、python3、python3-apt、iproute2；管理账号配免密 sudo（/etc/sudoers.d/90-admin 写 admin ALL=(ALL) NOPASSWD:ALL）。
  • 升级：pip 路径用 pip3 install -U "debops[ansible]"；pipx 路径用 pipx upgrade debops；项目目录内用 debops project refresh 刷新 ansible.cfg 与 Collection 依赖。
  • 降级/多版本：pipx 可用 pipx install "debops[ansible]==3.2.8" --suffix @3.2 之类并存多版本；pip 系统级只能单版本，降级先 pip3 uninstall debops 再装指定版本。

十、常见问题（FAQ）

Q1：pip 安装时报 Failed building wheel for python-ldap？ 缺编译依赖。执行 4.1 节的 6 个系统包安装后重试即可（官方文档同样列了这组依赖）。

Q2：debops check/run 报 'ansible_all_ipv4_addresses' is undefined？ 被管节点缺 iproute2。极简安装的系统可能没有，节点上 apt-get install -y iproute2 后重跑。

Q3：被管节点需要装 DebOps 吗？ 不需要。DebOps 是控制器侧框架，被管节点只要 SSH + Python 3 + sudo。

Q4：debops project init 必须联网吗？ 是，它会从 Galaxy 拉取 ansible.posix/community.general 等依赖 Collection（约 10 个）。完全离线环境可用 --no-requirements 跳过，后续再手动 debops env ansible-galaxy collection install -r ansible/collections/requirements.yml。

Q5：能管 CentOS/RHEL 或 Windows 节点吗？ 不能。DebOps 角色主线只支持 Debian/Ubuntu 被管端；异构环境请回到 Ansible 原生方案（选型对比见 《DebOps 3.3 介绍与选型指南》）。

十一、卸载与清理

pip 系统级安装（方案 A）的卸载：

pip3 uninstall -y debops ansible ansible-core
# 可选：移除构建依赖（如控制器不再做其他编译）
apt-get remove -y build-essential python3-dev libffi-dev libssl-dev libsasl2-dev libldap2-dev

pipx 安装（方案 B）的卸载：

pipx uninstall debops

项目目录与被管状态清理：

rm -rf ~/debops-data-center          # 删除项目（含 inventory、secret，注意先备份）
rm -rf ~/.ansible/collections        # 删除用户级 Collection 缓存

被管节点上已下发的变更（如 cron 配置）由 Ansible 管理，卸载控制器不影响其运行；如需回滚，cp /etc/crontab.dpkg-divert /etc/crontab 即可恢复原 crontab。

十二、参考链接