Lenovo XClarity Integrator for Proxmox

Lenovo XClarity Integrator for Proxmox 是一个基于 Python 的工具，可以为运行在 Lenovo ThinkSystem 服务器上的 Proxmox 集群环境自动更新固件。它与 Lenovo XClarity Administrator (LXCA) 集成，确保您的基础设施始终保持最新硬件更新，最大限度减少停机时间，降低人工干预。

本方案适用于希望简化 Proxmox 集群更新管理的 IT 管理员。

功能特色

与 Lenovo XClarity Administrator REST API 无缝集成
根据 Lenovo XClarity Administrator 应用的策略自动更新固件
支持集群感知的更新操作，减少服务中断
更新结果日志记录与报告
可通过 config.ini 文件自定义配置

工作原理

当您运行该程序时，会执行以下步骤：

从 config.ini 文件加载运行参数
如果密码以安全方式（加密）存储，则会要求输入主密码
验证主机是否由 LXCA 管理，并已关联固件合规策略
检查主机是否符合分配的合规策略
- 如果不符合，依次迁移主机上的虚拟机和 CT，LXCA 执行固件更新，更新后再将虚拟机迁回主机

需求

Python：3.x（已在 Python 3.11 和 Python 3.13（严格 SSL）测试）
requirements.txt 中列出的 Python 库
已运行的 Lenovo XClarity Administrator 实例，并有相应的 API 凭据
运行在 Lenovo XClarity Administrator 支持服务器上的 Proxmox VE 集群 或 Proxmox VE 单节点（仅在 Lenovo ThinkSystem 服务器上测试）
集群中每台服务器都分配了 合规策略
用于运行此工具的操作系统实例（推荐 Linux，但 Windows 也可用）。注意：不支持/不建议直接在 Proxmox 服务器上运行。

安装步骤

在您的系统上解压安装包（建议基于 Linux）
（可选但推荐）设置 Python 虚拟环境 2.1. 在项目目录下创建新的虚拟环境：
```
python -m venv venv
```
2.2. 激活虚拟环境：
- Linux/Mac 下：
```
source venv/bin/activate
```
- Windows 下：
```
venv\Scripts\activate
```
安装依赖库：
```
pip install -r requirements.txt
```
准备您的配置文件（见下方 配置文件 部分）。

配置文件

查看示例配置文件 config.ini.sample。该文件包含所有可配置参数，包括：
- LXCA 主机名或 IP
- LXCA API 凭据
- Proxmox 集群节点列表
复制示例文件并自定义：
```
cp config.ini.sample config.ini
```

使用您喜欢的编辑器编辑 config.ini，声明特定环境的设置。

字段说明

Proxmox 部分

PROXMOX_USER - 必填 - 此字段填写有权访问 Proxmox 集群（集群内每个节点）并执行如迁移虚拟机等操作的用户名。必须是 Linux 用户，因为还需要设置节点维护模式。默认值为 root@pam（不带引号）。
PROXMOX_PASS - 必填 - 需在此处存储 PROXMOX_USER 字段声明用户的密码。密码可明文存储（最简单但安全性低），也可加密存储（更安全）。关于如何在配置文件中加密存储密码，请参见下方“安全性”部分。
PROXMOX_VERIFY_SSL - 必填 - 如果想跳过 SSL 证书验证，可将此字段设为 False。通常自签名证书时会这样设置，如果您使用自签名证书且 Python > 3.11，必须将此参数设为 False。如需设为 True，请参见“CA 证书验证”部分说明。
CLUSTER_NODES - 必填 - 此字段包含可由工具更新的主机。该字段为数组，每个元素为 JSON 格式对象，描述主机的三个参数： -- xcc = 主机 XCC 的 IP 地址（必须为 IP 地址，不能是主机名） -- pve_ip = PVE 主机的 IP 地址 -- pve_host = PVE 主机名

主机的预期格式为： {"xcc":<IP_xcc_node>, "pve_ip": <IP_node> , "pve_host": <NAME_node>}

TIMEOUT_HOST - 可选 - 指定升级过程最大等待时间（秒）。默认值为 3600
TIMEOUT_VM - 可选 - 指定虚拟机操作（迁移、关机）最大等待时间（秒），超时则返回错误。默认值为 300 秒
VM_LOCAL_DISKS - 必填 - 允许值为：POWEROFF，授权工具关机带有本地磁盘（如 cdrom、本地存储虚拟机磁盘）的虚拟机；FAIL，则停止流程并允许手动处理。默认值为 FAIL
VM_LOCAL_RESOURCES - 必填 - 允许值为：POWEROFF，授权工具关机带有本地资源（如 PCIe 适配器）的虚拟机；FAIL，则停止流程并允许手动处理。默认值为 FAIL
VM_LOCAL_DISKS_EXPERT - 实验性 - 可选 - 风险自负！！仅限专家使用 - 除非您非常清楚，否则不要使用。此参数允许迁移带有本地磁盘（非 cdrom）的虚拟机。您需自行确保运行时所有要求都满足（如存储名称一致、磁盘空间充足等）。允许值为：True，程序会尝试迁移带本地磁盘（非本地 cd-rom）的虚拟机，或 False，程序会遵循 VM_LOCAL_DISKS 的设置。默认值为 False

LXCA 会话

LXCA_HOST - 必填 - 此字段填写管理 Proxmox 服务器的 Lenovo XClarity Administrator (LXCA) 实例的 IP 地址（或 DNS 可解析的主机名）。
LXCA_USER - 必填 - 此字段填写有权对 Proxmox 管理服务器进行更新的 LXCA 管理用户名。
LXCA_PASS - 必填 - 在此处填写 LXCA_USER 字段指定用户的密码。密码可明文存储（最简单但安全性低），也可加密存储（更安全）。关于如何在配置文件中加密存储密码，请参见下方“安全性”部分。
LXCA_VERIFY_SSL - 必填 - 如果想跳过 SSL 证书验证，可将此字段设为 False。通常自签名证书时会这样设置，如果您使用自签名证书且 Python > 3.11，必须将此参数设为 False。如需设为 True，请参见“CA 证书验证”部分说明。

安全性部分

SALT - 可选 - 可在此处存储 SALT，以支持加密密码存储。

请注意：如果您担心在 config.ini 文件中存储明文密码，可以通过以下方法加密存储。如果在配置文件中声明了 SALT 选项，程序会要求输入主密码以解密配置中的密码字段。

如何在 `config.ini` 中加密密码（可选）

如果您希望在配置文件中加密存储密码，可以运行 create_encrypted_password.py 程序。

python create_encrypted_password.py

程序会要求输入主密码（后续运行 integrator 时需要），并加密 PVE 和 LXCA 密码，输出需放入配置文件的内容（示例）：

Add the following three lines to your config.ini:

LXCA_PASS = gAAAAABonuj0JNenRko_DS-HTcZkFfoho_ZID6RcwLTFPNn7A2QYsNgtE3-wjzCE8R0_bpVquZLDGpe9ARpJdZ7tSEWoNXTOQg==
PROXMOX_PASS = gAAAAABonuj0aXh5IYUhClWjBaOBh9HgcvtmwyB9rYzlvnSO-NAS51rNQXaBH0CjlgvF4lkwpPsXSIi2SLpozKmueTtpV_uQJQ==
SALT = E3T1B/Ty6nk3RJq7dQq8Pg==

CA 证书验证

如果您的环境使用自定义证书，可以选择验证 Proxmox 主机和/或 LXCA 实例的证书，以满足安全合规要求。

为此，需在工具目录下创建名为 custom_cacert.pem 的文件，并手动存储环境的 CA 证书（pem 格式，见下方示例）：

请注意：自 Python 3.13 起，SSL 管理实现了更严格的默认设置。这使底层 OpenSSL 实现更符合 RFC 5280 标准，但与旧版 X.509 证书存在一定不兼容。SSL 上下文现在默认使用 VERIFY_X509_PARTIAL_CHAIN 和 VERIFY_X509_STRICT 验证标志。这意味着 CA 证书必须符合所有严格规则（如 X509v3 Key Usage、X509v3 Basic Constraints = Critical 等）。

使用方法

python lxca_proxmox_integrator.py

不带参数运行时，会显示如下使用帮助：

usage: lxca_proxmox_integrator.py [-h] (-d | -x) [-v] [-c] [-V]

LXCA Proxmox integrator command line parameters

options:
  -h, --help      show this help message and exit
  -d, --dry-run   Simulate the upgrade
  -x, --execute   Perform the upgrade
  -v, --verbose   Add verbosity to the ouput
  -c, --clearlog  Move current log to backup and start a clean log file
  -V, --version   Show program version

您必须指定 -d | --dry-run 或 -x | --execute 参数。

dry-run 参数（-d | --dry-run）允许您模拟完整流程，但不会对集群执行任何操作。 dry-run 期间会进行模拟，列出环境中的所有发现（建议与 -v 选项一起使用）。

强烈建议在使用 -x | --execute 参数运行前，务必先执行 dry-run（-d | --dry-run），因为后者会实际运行固件更新。

-v | --verbose 参数可增加输出详细度（控制台和日志均适用）。

-c | --clearlog 参数会备份当前日志，并初始化一个新的空日志文件。

工具主要流程如下：

如有需要，要求输入主密码（可选）
连接到您的 LXCA 实例
检查 ThinkSystem 节点是否有可用更新
协调集群/节点的固件更新

请注意：目前不支持 CT 容器的在线迁移，因此迁移时会先关闭容器，然后立即在目标主机上重启。

日志记录

所有操作都会记录到控制台和日志文件（lxca_proxmox_integrator.log）。请查阅日志以确认更新成功或排查问题。

免责声明

最佳实践建议：在集群范围内推送固件和驱动更新前，务必先在测试或非生产环境中进行验证。您也可以利用 DRY_RUN 执行模拟其他操作，但不会实际应用固件更新。
流程中遇到任何错误，工具会停止运行，便于 IT 管理员检查并修复问题。唯一例外是虚拟机/CT 的“开机”操作，相关信息会记录在日志中，但流程会继续。恢复正确状态可能需要手动干预。
除非适用法律要求或书面同意，依据许可证分发的软件均按“原样”提供，不附带任何明示或暗示的担保。具体权限和限制请参见许可证条款。

许可证

根据 Apache License, Version 2.0（“许可证”）授权：http://www.apache.org/licenses/LICENSE-2.0

功能特色​

工作原理​

需求​

安装步骤​

配置文件​

字段说明​

Proxmox 部分​

LXCA 会话​

安全性部分​

如何在 config.ini 中加密密码（可选）​

CA 证书验证​

使用方法​

日志记录​

免责声明​

许可证​