[sys-BlueChi] docs | BluechiCtl命令行工具
链接：https://github.com/eclipse-bluechi/bluechi
docs：BlueChi
Eclipse BlueChi 是面向多节点分布式环境的systemd服务控制器。
-
它由管理多个
分布式代理的中央控制器构成。 -
用户主要通过
bluechictl命令行工具进行交互，该工具向中央控制器发送命令。 -
中央控制器
指示代理，代理进而与本地systemd交互以管理单元（服务/程序）。
BlueChi追踪节点（运行代理的机器）和作业（对单元的操作）状态。
-
组件间通过*
D-Bus API*进行通信。 -
监控功能允许
观察状态变更，代理服务支持跨节点单元依赖。 -
行为通过*
配置*定义。
概览
章节
- BluechiCtl命令行工具
- BlueChi控制器
- BlueChi代理
- 单元/服务
- 节点管理
- 作业系统
- D-Bus接口
- 监控机制
- 代理服务
- 配置管理
配置
1. 安装 Docker
如果系统还没有 Docker，可以用以下命令安装：
sudo apt update
sudo apt install docker.io
sudo systemctl enable --now docker
查询
2. 构建 Docker 镜像
在 BlueChi 项目根目录下执行：
docker build -t bluechi-deb-build -f debian/bluechi-deb-build .
3. 运行 Docker 容器并挂载 BlueChi 目录
假设当前在 bluechi 目录下，执行：
docker run -it -v $(pwd):/var/bluechi-build/bluechi bluechi-deb-build /bin/bash
这样会把本地的 bluechi 目录挂载到容器的
/var/bluechi-build/bluechi。
4. 在容器内创建源码包
进入容器后，执行：
cd /var/bluechi-build/bluechi
./build-scripts/create-archive.sh
mv bluechi-<version>.tar.gz ../bluechi_<version>.orig.tar.gz
<version>替换为实际版本号。
5. 在 BlueChi 目录下构建 deb 包
继续在容器内执行：
meson setup builddir
dpkg-buildpackage -uc -us -rfakeroot
6. 获取生成的 deb 包
生成的 .deb 包会在 /var/bluechi-build 目录下。可以在主机的 bluechi 目录下找到它们。
第1章：BluechiCtl命令行工具
欢迎来到BlueChi！
在本章中，我们将认识bluechictl工具。
可将bluechictl视为与BlueChi系统交互的主要工具，就像远程控制器一样。这是我们用来向BlueChi发送指令并获取信息的命令行程序。
类似cli前文传送：[Backlog] 命令行界面CLI vs Web界面及服务端
什么是BluechiCtl？
假设我们拥有多台互联的计算机或设备，并希望从中央位置统一管理这些设备上运行的程序或服务。这正是BlueChi的设计目标！
但如何与BlueChi沟通？
这就是bluechictl的作用所在。它是系统的接入网关，将我们的指令（例如"在指定设备上启动某程序"）发送给BlueChi的核心管理组件——BlueChi控制器，同时接收控制器返回的信息并呈现给我们。
简而言之，bluechictl是我们用来实现以下功能的命令行接口：
- 向BlueChi控制器发送指令
- 查看BlueChi管理的设备与程序信息
查看BluechiCtl版本
验证命令行工具是否安装的最简单方式通常是检查版本号。使用--version或-v选项即可实现：
bluechictl --version
该指令会让bluechictl工具报告其版本号，快速确认程序是否可正常执行。
(基于test_version_option_provided.py测试用例，此命令应输出版本信息)
首个任务：检查设备状态
管理多设备时，常见需求是确认设备的在线状态。在BlueChi中，受管设备称为节点。
通过status命令，bluechictl可轻松检查节点状态。
查看所有节点状态
要查看控制器管理的所有节点状态，只需执行：
bluechictl status
输出将展示节点列表、当前状态（如online在线或offline离线）及最后活动时间。
示例输出如下（具体节点名称取决于实际配置）：
节点 | 状态 | 最后活动时间
=========================================================================
laptop | online | 刚刚
pi | online | 刚刚
(此输出示例参考自test_bluechi_nodes_statuses.py和examples_bluechictl.md)
查看特定节点状态
若只需检查指定节点状态，可在status后附加节点名称：
bluechictl status pi
此指令仅显示名为pi的节点状态：
节点 | 状态 | 最后活动时间
=========================================================================
pi | online | 刚刚
(此功能演示参见test_bluechi_node_status.py和examples_bluechictl.md)
使用bluechictl status及bluechictl status <节点名称>是了解分布式系统运行状态的首要步骤。
BluechiCtl工作原理简析
当您在bluechictl输入指令时，系统内部如何将指令作用于远程设备上的程序？以下是简化版流程解析：
- 用户输入指令（如
bluechictl status pi） bluechictl工具将请求发送至BlueChi控制器（通常与控制器同机部署）- 控制器查找目标节点(
pi) - 控制器向
pi设备上的BlueChi代理发送消息 - 代理检查本地系统（如systemd）获取状态信息
- 代理将状态信息回传控制器
- 控制器将信息转发至
bluechictl bluechictl在终端显示状态信息
以下序列图直观展示该流程：
此交互过程展示了bluechictl如何作为用户友好前端与BlueChi系统组件协同工作。
BluechiCtl更多功能
除检查节点状态外，bluechictl可通过向控制器发送不同指令，实现对远程节点上程序/服务（BlueChi称为单元/服务）的多样化管理。
常用指令示例：
bluechictl list-units [<节点>]：列出所有/指定节点的程序服务（参见test_bluechi_list_units_on_all_nodes.py等测试用例）bluechictl start <节点> <单元>：在节点启动指定服务（参见test_bluechi_restart_unit.py等用例）bluechictl stop <节点> <单元>：停止节点上的指定服务（参见examples_bluechictl.md）bluechictl daemon-reload <节点>：让节点systemd重载配置文件（参见test_bluechi_daemon_reload.py）bluechictl reset-failed [<节点>] [<单元> ...]：重置服务的失败状态（参见test_bluechi_reset_failed.py等用例）bluechictl kill <节点> <单元>：向服务进程发送信号（参见test_bluechi_kill_unit.py）bluechictl enable/disable <节点> <单元>：设置服务开机自启（参见test_bluechictl_is_enabled.py）bluechictl reload <节点> <单元>：重载运行中服务的配置（参见test_bluechi_reload_unit_service.py）bluechictl get/set-default <节点> <目标>：获取/设置节点默认systemd目标（参见test_bluechictl_set_get_default_target.py）bluechictl set-loglevel [<节点>] <级别>：调整控制器/代理日志级别（参见test_bluechi_agent_set_loglevel.py等用例）
无需立即记忆所有指令！关键要理解bluechictl是操作BlueChi系统的主要方式，无论是查询状态（status, list-units）还是执行操作（start, stop, reload等）。
本章小结
本章我们了解到bluechictl是与BlueChi系统交互的核心命令行工具。我们学习了如何用它检查版本信息，更重要的是掌握了节点状态检查方法，并初步理解了bluechictl与BlueChi控制器的通信机制。
现在您已掌握主控工具bluechictl的基础用法，接下来让我们深入了解其通信对象——BlueChi控制器。
第2章：BlueChi控制器