DebOps 3.3 配置参数详解

目标：讲清 DebOps 3.3.2 的完整配置体系——CLI 自身的四层配置合并、项目内 .debops.cfg 与生成的 ansible.cfg、inventory 变量层叠与优先级、modern 项目的视图配置。全文配置键与回显均来自 2026-10-25 真实环境实测（DebOps 3.3.2 / ansible-core 2.17.14）。

一、环境信息

• 控制器：Ubuntu 22.04.5 LTS，Python 3.10.12，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（Ubuntu 22.04，用于变量下发实测）

二、前置条件

已按安装篇完成控制器安装并初始化至少一个项目目录。本文命令均在项目目录内执行：

cd ~/debops-data-center

三、配置查看与修改方式（四种途径）

DebOps 的配置分为「DebOps 自身行为」与「Ansible 行为」两类，全部通过统一的配置树管理。查看与修改途径：

1. 看当前生效配置：debops config get / debops config list
2. 改项目级配置：编辑项目根的 .debops.cfg
3. 改全局（用户级）默认：~/.config/debops/conf.d/*.yml（或 .toml）
4. 改全局（系统级）默认：/etc/debops/conf.d/
5. 环境变量注入：/etc/default/debops、~/.config/debops/environment

改完后用 debops project refresh 让变更渲染进 ansible.cfg 等生成文件（实测回显：Refreshed DebOps project in /root/debops-data-center）。

3.1 查看配置：debops config

列出参与合并的配置文件（实测）：

debops config list

# Configuration files:
~/.config/debops/conf.d/99-local.yml
~/debops-data-center/.debops.cfg

按键树逐级探查（-k 列出某层的键，点号寻址，实测）：

debops config get -k                 # 顶层键：binaries、git、syslog、project、views
debops config get -k binaries        # ansible、ansible-galaxy、ansible-playbook、gpg、encfs、git、git-crypt、umount、fusermount
debops config get project            # 输出当前项目信息

debops config get project 实测回显（legacy 项目）：

path = "/root/debops-data-center"
name = "debops-data-center"
type = "legacy"
view = "system"

还支持 --format json|toml|yaml|unix 四种输出格式（默认 unix），便于脚本化读取。

3.2 配置合并顺序（四层 + 环境文件）

DebOps 启动时按以下顺序合并配置，后者覆盖前者（依据 debops/config.py 源码与实测）：

环境变量文件 /etc/default/debops 与 ~/.config/debops/environment 在配置加载前注入进程环境，defaults.toml 里的 Jinja 表达式（如 {{ env['DEBOPS_CMD_UMOUNT'] | d('umount') }}）会读取它们。

层叠实测：在用户级写入 forks 覆盖，验证其穿透到生成的 ansible.cfg——

mkdir -p ~/.config/debops/conf.d
cat > ~/.config/debops/conf.d/99-local.yml <<'EOF'
views:
  system:
    ansible:
      defaults:
        forks: 20
EOF
debops config get views.system.ansible.defaults.forks   # 20
debops project refresh
grep forks ansible.cfg                                  # forks = 20

四、参数总览（配置树结构）

debops config get -k 实测的顶层键共 5 个，职责如下：

五、核心配置详解

5.1 项目级 .debops.cfg（legacy 项目）

debops project init 生成的 .debops.cfg 实测全文分四段（逐键解释）：

[override_paths] 段——自定义覆盖文件的查找位置：

[ansible defaults] 段——渲染进 ansible.cfg 的 [defaults]：

[ansible diff] 段：always = false——设为 true 等价于每次执行都带 --diff。

[ansible inventory] 段：host_pattern_mismatch = ignore——抑制 playbook 引用了清单中不存在的组时的告警（DebOps playbook 大量引用各服务组，建议保持）。

[ansible privilege_escalation] 段：become_ask_pass = false——不在每次执行时询问 sudo 密码。

5.2 生成的 ansible.cfg

ansible.cfg 由 refresh 从配置树渲染，直接改动会在下次 refresh 丢失（文件头注释明示）。实测关键路径键：

[defaults]
collections_path = ansible/collections:~/.ansible/collections:/usr/local/lib/python3.10/dist-packages/debops/_data/ansible/collections:/usr/share/ansible/collections
roles_path = ansible/playbooks/roles:~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles
inventory = ansible/inventory

要点解读：collections_path 第三段指向 pip 包内置的 debops.debops Collection（203 个角色即在此），这就是 pip 安装后无需再装 Galaxy Collection 的原因；library/action_plugins/filter_plugins 等 8 类插件路径同样指向包内置插件目录（完整清单见安装篇实测）。

5.3 inventory 与变量优先级

项目清单固定在 ansible/inventory/：

ansible/inventory/
├── hosts          # INI 格式主机清单
├── group_vars/    # 组变量（目录内文件名任意，建议与组同名）
└── host_vars/     # 主机变量

变量生效遵循 Ansible 标准优先级（由低到高）：角色 defaults（包内 roles/<role>/defaults/main.yml）< group_vars/all < group_vars/<组名> < host_vars/<主机> < 命令行 -e extra vars。

DebOps 角色变量命名约定为 <角色名>__<参数>（双下划线），例如 cron 角色的 cron__crontab_jobs。

层叠实测：给 debops_service_cron 组下发一个定时任务——

mkdir -p ansible/inventory/group_vars/debops_service_cron
cat > ansible/inventory/group_vars/debops_service_cron/cron.yml <<'EOF'
cron__crontab_jobs:
  - name: "disk-usage-report"
    minute: "30"
    hour: "6"
    job: "df -h > /var/log/disk-usage.log 2>&1"
EOF
debops run service/cron

在控制器上查证变量已生效（实测回显）：

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"
        }
    ]
}

在被管节点上确认落点（实测）：

grep "disk-usage" /etc/crontab
# 30  6  *  *  *  root	df -h > /var/log/disk-usage.log 2>&1

💡 技术拓展：Ansible 变量优先级共 22 级（官方 "Understanding variable precedence"），日常只需记住主干——

层级	位置	典型用途
role defaults	角色 defaults/main.yml	角色出厂值，永远可被覆盖
group_vars/all	inventory/group_vars/all/	全站通用值（时区、域名）
group_vars/<组>	inventory/group_vars/<组>/	一类节点的服务参数
host_vars/<主机>	inventory/host_vars/<主机>/	单台特例
-e extra vars	命令行	临时覆盖，优先级最高

本文实验用的是 group_vars/<组> 层——一组节点共享同一个 cron 任务的场景。

5.4 modern 项目与视图配置

debops project init -t modern 创建的项目用 YAML 配置文件 + 视图目录 取代单一 .debops.cfg（实测结构）：

.debops/conf.d/
├── project.yml          # 项目级配置
├── view-system.yml      # system 视图配置
└── view-staging.yml     # staging 视图配置（mkview 生成）
ansible/views/
├── system/    {ansible.cfg, inventory/, playbooks/, resources/, secret/}
└── staging/   {ansible.cfg, inventory/, playbooks/, resources/, secret/}

每个视图有独立的 inventory、secret 与 ansible.cfg，适合「一个项目管理生产/预发多套环境」。实测 debops config get project 在 modern 项目中额外返回 git.auto_commit: true 与 default_view: system（legacy 项目无这两个键）。视图执行用 debops run -V staging site。

5.5 敏感物与密钥目录

ansible/secret/ 是角色运行时自动生成密码、CA 证书的存放点（如 PKI 角色的根证书）。初始化时加 --encrypt encfs 或 --encrypt git-crypt 可启用加密，日常用 debops project unlock / debops project lock 解锁与锁定。未启用加密时这两个命令静默跳过（实测无输出即返回）。

六、生产配置模板

适用场景：16GB 内存控制器、管理约 50–200 台 Debian/Ubuntu 节点、多人共用一套用户级默认。

~/.config/debops/conf.d/00-site.yml（用户级默认，实测可生效的写法）：

views:
  system:
    ansible:
      defaults:
        forks: 50                 # 并发数，节点多时提速（默认 5）
        timeout: 30               # SSH 超时秒数
      diff:
        always: true              # 所有变更显示 diff，便于审计
git:
  init_message: "Initialize DebOps project for example.com"

项目级 .debops.cfg 追加段（legacy 项目）：

[ansible defaults]
pipelining = true

[ansible diff]
always = true

改完执行 debops project refresh 渲染进 ansible.cfg，用 grep -E "forks|pipelining" ansible.cfg 复核。

七、常见问题（FAQ）

Q1：直接改了 ansible.cfg，为什么改动丢了？ ansible.cfg 是生成文件，debops project refresh（以及项目初始化）会用配置树重建它。永久改动请写 .debops.cfg 或 conf.d，见 5.2。

Q2：legacy 项目里 debops project commit 报 The "project.git.auto_commit_message" option is not defined？ 实测复现：legacy 项目的 INI 配置无法表达 project.git.auto_commit_message 这种嵌套键（.debops.cfg 的 [project] 段只支持扁平键）。处理方式：用 git add -A && git commit 手工提交；或改用 debops project init -t modern 的 modern 项目（其配置树自带 project.git.auto_commit: true 与提交信息，支持自动提交）。

Q3：想让所有项目默认 forks=50，改哪里？ 写用户级 ~/.config/debops/conf.d/*.yml（见六章模板），不用逐项目改 .debops.cfg。

Q4：怎么临时换一种参数值做验证？ 最高优先级是命令行 extra vars：debops run service/cron -- -e "cron__crontab_jobs=[]"；不需要改任何配置文件。

Q5：.debops.cfg 里以 ansible 开头的段名是什么规则？ 段名以 ansible （带空格）开头时，后半截映射为 ansible.cfg 的段名（如 [ansible privilege_escalation] → [privilege_escalation]），其余段名映射为 DebOps 配置树顶层键（如 [override_paths]）。

八、参考链接

• 官方配置文档：https://docs.debops.org/en/stable-3.3/introduction/configuration.html
• 项目目录说明：https://docs.debops.org/en/stable-3.3/user-guide/project-directories.html
• Ansible 变量优先级：https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html
• 《DebOps 3.3 介绍与选型指南》、《Ubuntu 22.04 安装 DebOps 3.3 指南》（本专栏）