DebOps 3.3 常用 CLI 命令与工具详解

目标：逐项讲透 DebOps 3.3.2 的 debops 命令族（project/exec/run/check/env/config 六大 section）与配套 ansible 工具，每个子命令给出实测帮助文本与真实执行回显。全部实测于 2026-10-25（DebOps 3.3.2 / ansible-core 2.17.14 / Ubuntu 22.04）。

一、环境信息

控制器：Ubuntu 22.04.5 LTS，DebOps 3.3.2，ansible-core 2.17.14（安装见《Ubuntu 22.04 安装 DebOps 3.3 指南》）
示例项目：~/debops-data-center（legacy）、~/debops-modern（modern）
被管节点：node1.debops.local（10.89.74.3，Ubuntu 22.04）

二、工具概览

debops 是一个「section + 子命令」结构的 CLI（实测 --help）：

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

options:
  -h, --help     show this help message and exit
  --version      show program's version number and exit

六大 section 的职责划分：project 管项目目录生命周期；exec/run/check 是执行面（ad-hoc 命令 / 正式跑 / 干跑）；env 与 config 是环境面（在项目环境里跑任意 shell / 查看配置树）。

三、前置条件

除 debops project init 与 debops --version/--help 外，其余命令都要求在项目目录内执行（或用 --project-dir 显式指定）：

cd ~/debops-data-center
# 或者：debops run --project-dir ~/debops-data-center service/cron

四、debops project：项目目录管理

4.1 init——初始化项目

帮助文本（实测）：

usage: debops project init [<args>] <project_dir>

options:
  -t [{legacy,modern}], --type [{legacy,modern}]
                        select project type (default: legacy)
  -V DEFAULT_VIEW, --default-view DEFAULT_VIEW
                        name of the default infrastructure view (default: system)
  --git / --no-git      enable/disable git support (default: --git)
  --requirements / --no-requirements
                        install Ansible Collections after initialization (default: --requirements)
  --encrypt [{encfs,git-crypt}]
                        enable encrypted secrets
  --keys KEYS           list of GPG recipients with secret access, delimited by commas

初始化一个 legacy 项目（默认类型，实测）：

debops project init ~/debops-data-center

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

初始化一个 modern 项目（跳过 Collection 安装，实测）：

debops project init -t modern --no-requirements ~/debops-modern
# Created new DebOps project in /root/debops-modern

关键选项取舍：-t modern 启用「基础设施视图」结构（多套环境共管）；--no-git 关闭 git 版本化（不建议）；--no-requirements 跳过约 10 个依赖 Collection 的 Galaxy 下载（离线/网络差时用）；--encrypt git-crypt --keys <GPG指纹> 直接以加密方式管理 secret。

4.2 mkview——新建基础设施视图（仅 modern）

cd ~/debops-modern
debops project mkview staging
# Created staging view in DebOps project debops-modern

实测生成 ansible/views/staging/（独立 inventory/secret/ansible.cfg）与 .debops/conf.d/view-staging.yml。在 legacy 项目执行会直接报错（实测）：Error: This functionality only works in "modern" DebOps project directory。

4.3 refresh——刷新项目

修改 .debops.cfg 或 conf.d 配置后，重建 ansible.cfg 并同步 Collection 依赖：

cd ~/debops-data-center
debops project refresh
# Refreshed DebOps project in /root/debops-data-center

4.4 commit——提交变更

modern 项目带 project.git.auto_commit: true，commit 会按配置自动提交。legacy 项目实测会报 The "project.git.auto_commit_message" option is not defined. Not committing any changes.——这是 legacy 的已知限制，直接用 git 手工提交即可（见配置篇 FAQ Q2）。

4.5 unlock / lock——secrets 解锁与锁定

仅在 init/mkview 时加了 --encrypt encfs|git-crypt 的项目有意义；未加密项目实测静默返回（无输出、退出码 0）。日常用法：

debops project unlock    # 解密 secret/ 使其可读
debops project lock      # 用毕重新加密

五、debops exec：直接执行 Ansible 命令

把参数透传给 ansible ad-hoc 命令，自动套用项目的 ANSIBLE_CONFIG 与 inventory。注意参数前要有 -- 分隔符。

连通性测试（实测）：

debops exec -- all -m ping

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

查看主机生效变量（配置排错利器，实测）：

debops exec -- node1.debops.local -m debug -a "var=cron__crontab_jobs"

node1.debops.local | SUCCESS => {
    "cron__crontab_jobs": [
        { "hour": "6", "job": "df -h > /var/log/disk-usage.log 2>&1",
          "minute": "30", "name": "disk-usage-report" }
    ]
}

采集事实子集：

debops exec -- node1.debops.local -m setup -a "filter=ansible_distribution*"

六、debops run：正式下发 playbook

帮助文本（实测节选）：

usage: debops run [<args>] [--] <[<namespace>.<collection>/]playbook> [playbook] ... [ansible_args]

options:
  -v, --verbose          increase output verbosity
  --project-dir [DIR]    path to the project directory
  -V VIEW, --view VIEW   select the infrastructure view
  -E, --bell             notify the user at the end of Ansible execution
  --eval                 print the Ansible command generated by DebOps

6.1 playbook 寻址规则

DebOps 自带的 playbook 直接按短名引用，CLI 会解析到包内 Collection：

写法	实际指向	用途
`site`	`debops.debops/playbooks/site.yml`	全量下发（bootstrap+common+所有已启用服务）
`common`	`playbooks/common.yml`	基础层（sshd、apt、防火墙等）
`bootstrap`	`playbooks/bootstrap.yml`	全新节点首次引导
`service/cron`	`playbooks/service/cron.yml`	单服务角色（共 200 个）
`layer/app`	`playbooks/layer/app.yml`	分层下发（agent/app/common/env/hw/net/srv/sys/systemd/virt 共 10 层）
`<namespace>.<collection>/<路径>`	任意 Collection	引用第三方 Collection 的 playbook

6.2 常用执行形态（实测）

先看 CLI 实际生成的命令，心里有数再执行：

debops run --eval service/cron

export ANSIBLE_CONFIG=/root/debops-data-center/ansible.cfg
ansible-playbook /usr/local/lib/python3.10/dist-packages/debops/_data/ansible/collections/ansible_collections/debops/debops/playbooks/service/cron.yml

正式下发单服务（实测回显节选）：

debops run service/cron

PLAY [Manage cron jobs] ********************************************************
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

-- 之后可追加任意 ansible-playbook 参数——限定主机、传额外变量、看 diff：

debops run service/cron -- --limit node1.debops.local
debops run service/cron -- -e "cron__crontab_jobs=[]" --diff
debops run site -- --tags "role::sshd" -vv

modern 项目里指定视图执行：debops run -V staging site。

七、debops check：干跑预演

等价于给 ansible-playbook 加 --check，用于变更前预演（实测回显节选）：

debops check 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

配合 -- --diff 可看到文件级改动预览（如 crontab 将新增的行）。

⚠️ 注意：check 模式下 changed 表示「正式跑会改这些」，但部分依赖注册变量的任务在 check 模式会被跳过，预演不等于百分百覆盖，关键变更仍建议在低峰期执行。

八、debops env：在项目环境里跑 shell

让任意命令继承项目环境变量（ANSIBLE_CONFIG、DEBOPS_PROJECT_PATH 等，实测）：

debops env printenv ANSIBLE_CONFIG
# ~/debops-data-center/ansible.cfg

debops env printenv | grep DEBOPS
# DEBOPS_PROJECT_PATH=~/debops-data-center
# DEBOPS_ANSIBLE_INVENTORY=~/debops-data-center/ansible/inventory
# DEBOPS_ANSIBLE_COLLECTIONS_PATH=/usr/local/lib/python3.10/dist-packages/debops/_data/ansible/collections

典型用途——在项目环境里管理 Collection 依赖（requirements.yml 的注释也推荐这种用法）：

debops env ansible-galaxy collection install -r ansible/collections/requirements.yml

⚠️ 排障实录：debops env 不接受 -- 分隔符（与 exec/run/check 相反），debops env -- printenv 实测报 /bin/sh: 0: Illegal option --，直接跟命令即可。

九、debops config：查看配置树

debops config list                                # 参与合并的配置文件
debops config get -k                              # 顶层键：binaries git syslog project views
debops config get -k binaries                     # 某层键清单
debops config get project.path                    # 取单个值（unix 格式默认）
debops config get --format json views.system.ansible.defaults   # JSON 整段导出

键用点号寻址，配置树结构与合并顺序见《DebOps 3.3 配置参数详解》。

十、配套 Ansible 工具（项目内直接用）

进入项目目录后，ansible.cfg 已就位，原生 ansible 命令全部可用：

ansible-inventory --graph

实测回显（主机分组一目了然）：

@all:
  |--@ungrouped:
  |--@debops_all_hosts:
  |  |--node1.debops.local
  |--@debops_service_cron:
  |  |--node1.debops.local

其他高频配套命令：

ansible all -m ping                                  # 等价 debops exec -- all -m ping
ansible-playbook <包内playbook绝对路径>              # 等价 debops run（--eval 可拿到路径）
ansible-galaxy collection list debops.debops         # 查 Collection 版本

十一、注意事项

debops run/check 的 ansible 参数必须放 -- 之后，且 playbook 名在 -- 之前；debops env 则相反、不能用 --。
重复执行是安全的：角色幂等，第二遍 changed=0（安装篇 7.6 有实测）。
debops run site 会跑全量 playbook（含 common 层的 sshd/防火墙/Postfix 等），首次对生产节点执行前务必先 debops check site -- --diff 预演。
项目目录即事实源：secret/ 含明文敏感物，务必加密（--encrypt）或严格控权。
所有命令都认 --project-dir，写定时任务/CI 时显式指定比依赖 cwd 稳妥。

十二、常见问题（FAQ）

Q1：执行时报 not a DebOps project directory 之类错误？ 没在项目目录里。cd 进项目或加 --project-dir <路径>。

Q2：怎么确认 debops 把我的短名 playbook 解析到哪了？ debops run --eval <短名> 原样打印生成的 ansible-playbook 命令（见 6.2）。

Q3：能只跑某个角色的部分任务吗？ 可以：debops run service/cron -- --tags "<tag>"，tag 清单用 debops run service/cron -- --list-tags 查看。

Q4：怎么把命令输出接进自己的脚本？ debops config get --format json 系列输出可直接 jq；执行类命令的机器可读输出可用 debops env ansible-playbook <playbook路径> 配合环境变量 ANSIBLE_STDOUT_CALLBACK=json 获得。

Q5：debops project commit 在 legacy 项目不工作？ 已知限制（legacy 无嵌套配置键），改用 git 手工提交，或换 modern 项目（实测细节见配置篇 FAQ Q2）。

十三、参考链接

官方 CLI 文档：https://docs.debops.org/en/stable-3.3/user-guide/debops-cli.html
Playbooks 说明：https://docs.debops.org/en/stable-3.3/user-guide/playbooks.html
《DebOps 3.3 介绍与选型指南》、《Ubuntu 22.04 安装 DebOps 3.3 指南》、《DebOps 3.3 配置参数详解》（本专栏）