课程二：掌握核心 - 私有数据目录与命令行实战
在第一课中，我们初步接触了私有数据目录，知道它是 Runner 存储输入和输出的地方。本课将深入剖析它的标准结构，并学习 Runner 提供的多种运行模式，让你能够灵活地管理 Ansible 任务的执行。
2.1 私有数据目录深度解析
私有数据目录（Private Data Directory）是 Ansible Runner 的核心设计。当你执行 ansible-runner run . 时，Runner 会期望在 . 目录下存在特定的子目录和文件，用于提供执行所需的数据。同时，Runner 也会在该目录下生成输出。
一个完整的私有数据目录结构通常如下：
.
├── inventory/ # 清单文件存放目录
│ ├── hosts # 静态清单文件
│ └── group_vars/ # 组变量目录
├── env/ # 环境配置目录
│ ├── settings # Runner 本身的配置（如超时、进程隔离）
│ ├── envvars # 环境变量文件
│ ├── ssh_key # SSH 私钥文件
│ └── cmdline # 传递给 ansible-playbook 的额外命令行参数
├── project/ # Playbook 项目目录
│ ├── playbook.yml # 要执行的 Playbook
│ └── roles/ # 角色目录（如果有）
├── artifacts/ # 输出工件目录（自动生成）
│ └── <执行ID>/ # 每次执行的唯一目录
│ ├── job_events/ # 事件 JSON 文件
│ ├── stdout # 标准输出文本
│ ├── status # 执行状态
│ └── rc # 返回码
└── ./
inventory/：存放 Ansible 清单文件。可以是单个文件hosts，也可以是包含多个文件的目录。env/：存放 Runner 执行时的环境配置。例如，你可以通过env/settings设置 Runner 的超时时间，通过env/envvars设置传递给 Ansible 的环境变量。project/：存放要执行的 Playbook 及其依赖（如角色、模块）。Runner 在执行时会自动将project目录的内容复制到一个临时位置，以确保每次执行的隔离性。artifacts/：Runner 自动生成的目录，存放每次执行的结果。每次执行会创建一个以UUID命名的子目录，里面包含stdout、status、rc以及详细的job_events
注意：并不是所有子目录都必须存在。Runner 会根据需要自动创建缺失的目录，并提供合理的默认值。例如，如果你没有提供
inventory，Runner 会默认使用localhost。
2.2 命令模式详解：run、start、stop、is-alive
ansible-runner 提供了多种执行模式，以适应不同的使用场景。
| 命令 | 作用 | 特点 |
|---|---|---|
run | 前台运行一个任务 | 阻塞当前终端，直到任务完成，输出实时显示。 |
start | 后台启动一个任务 | 立即返回任务标识符（UUID），任务在后台执行。 |
stop | 停止一个后台任务 | 通过任务标识符停止正在执行的任务。 |
is-alive | 检查后台任务是否存活 | 通过任务标识符查询任务状态。 |
2.2.1 run 命令
你已经用过 run 命令了。它会在前台执行 Playbook，输出实时打印到终端。这对于调试和交互式使用非常方便。
ansible-runner run /path/to/private_data_dir -p playbook.yml
2.2.2 start 命令
当你的 Playbook 需要长时间运行，或者你希望将任务放到后台而不阻塞当前终端时，可以使用 start。这是异步执行模式，立即返回并在后台运行
ansible-runner start /path/to/private_data_dir -p playbook.yml
运行start后，日志会写入到文件（如 daemon.log）
2.2.3 is-alive 命令
要检查后台任务是否还在运行，使用 is-alive 并指定任务标识符
检查默认标识符的进程状态：
ansible-runner is-alive .
检查特定标识符的进程状态：
ansible-runner is-alive -i 7a91a613-7fa4-46f2-a563-c597e8f583ad
启用调试模式检查：
ansible-runner is-alive . --debug
返回值说明
- 退出码 0 - 进程正在运行
- 退出码 1 - 进程未运行或已停止
- 其他退出码 - 检查过程中出现错误
2.2.4 stop 命令
如果需要强制停止一个正在执行的后台任务，可以使用 stop：
ansible-runner stop .
2.3 实操案例：手动创建私有数据目录并使用多种命令
案例1：手动创建私有数据目录结构
-
创建一个新目录
runner_deepdive并进入：mkdir runner_deepdive cd runner_deepdive -
创建必要的子目录：
mkdir -p inventory project env -
在
project目录中创建一个简单的 Playbooktest.yml：cat > project/test.yml << 'EOF' --- - name: 长时间运行的任务 hosts: localhost gather_facts: no tasks: - name: 等待 10 秒 ansible.builtin.pause: seconds: 10 - name: 打印完成消息 ansible.builtin.debug: msg: "任务完成！" EOF -
在
inventory目录中创建一个清单文件hosts：echo "localhost ansible_connection=local" > inventory/hosts现在，我们有了一个完整的私有数据目录。
案例2：使用 run 前台执行
# 注意：该路径为私有数据目录下，-p直接指定playbook即可，它会自动从project/下找到该文件
ansible-runner run . -p test.yml
你会看到 pause 任务等待 10 秒，然后打印完成消息。同时，注意观察 artifacts 目录下是否生成了新目录。
案例3：使用 start 后台执行
ansible-runner start . -p test.yml
记下输出的任务标识符，是一个PID。
案例4：检查任务状态
ansible-runner is-alive .
在任务执行期间，退出码为0；正常退出或者未运行，则为1；
案例5：停止任务（可选）
如果你在任务执行期间想停止它，可以使用 stop。但我们的 test.yml 只执行 10 秒，你可以快速在另一个终端执行 stop 来体验：
ansible-runner stop .
2.4 探索工件：从 JSON 事件中获取信息
执行完成后，进入 artifacts 目录下的最新目录，查看 job_events 中的文件。你会发现每个事件文件都对应 Playbook 执行的一个步骤。尝试用 jq 或 python -m json.tool 查看最后一个事件文件（通常是 -complete 或 -finished 事件），里面包含了最终的执行统计信息。
// cat 9-85ec1837-d39f-4f49-b863-385f7f56c80a.json | jq
{
"uuid": "85ec1837-d39f-4f49-b863-385f7f56c80a",
"counter": 9,
"stdout": "(ctrl+C then 'C' = continue early, ctrl+C then 'A' = abort)",
"start_line": 8,
"end_line": 9,
"runner_ident": "b45cc5eb-4aac-44b3-aab1-eb88cc899f4c",
"event": "verbose",
"pid": 20681,
"created": "2026-03-18T02:23:35.655809+00:00",
"parent_uuid": "000c293a-cf94-5035-b71b-000000000003",
"event_data": {
"playbook": "test.yml",
"playbook_uuid": "c7071528-d7e1-44dd-b259-873c0ebccc71",
"play": "长时间运行的任务",
"play_uuid": "000c293a-cf94-5035-b71b-000000000001",
"play_pattern": "localhost",
"task": "等待10秒",
"task_uuid": "000c293a-cf94-5035-b71b-000000000003",
"task_action": "ansible.builtin.pause",
"resolved_action": "ansible.builtin.pause",
"task_args": "",
"task_path": "/usr/local/src/py_projects/automatic/ansible-runner/tip2-私有数据目录与命令行实战/runner_deepdive/project/test.yml:6",
"uuid": "85ec1837-d39f-4f49-b863-385f7f56c80a"
}
}
2.5 小结
本课我们深入学习了：
- 私有数据目录的标准结构及其作用。
run、start、is-alive、stop四种命令的使用方法。- 如何手动构建私有数据目录，并灵活运用不同命令管理任务执行。
掌握这些内容后，你已经能够独立地组织 Runner 的执行环境，并控制任务的运行方式了。
