bcleonard/proxmox-qdevice

Proxmox Qdevice Docker镜像

镜像概述和主要用途

该Docker镜像用于为Proxmox集群部署外部qdevice，解决偶数节点集群的仲裁（quorum）问题。Proxmox集群通常需要奇数个节点以确保仲裁，当集群节点为偶数（如2个节点）时，外部qdevice可作为额外投票设备，使集群总投票数变为奇数，确保节点启动时能获得足够的仲裁票，避免因节点同时启动导致的服务无法启动问题。

注意：需在非Proxmox服务器虚拟实例的设备上运行此容器。

有关Proxmox集群、外部qdevice及配置使用的更多信息，请参考Proxmox官方文档。

核心功能和特性

• 外部仲裁支持：为偶数节点Proxmox集群提供额外投票，确保集群启动时的quorum（如2个节点+1个qdevice=3票，首个节点启动时即可获得2票，满足quorum）。
• 容器化部署：支持通过Docker Compose或容器管理工具（如Portainer）部署，简化安装流程。
• 配置持久化：通过挂载corosync-data目录，实现配置在容器重启/重建间的持久化。
• 灵活网络配置：支持macvlan网络模式，可自定义网络接口、IP地址、子网等参数。

使用场景和适用范围

适用于具有偶数个Proxmox服务器节点的集群（如2个节点），需解决以下问题：

• 节点同时启动时，首个节点因投票数不足（1/2）无法启动服务，第二个节点可启动（2/2）。
• 通过外部qdevice，首个启动的节点可获得2/3的投票，满足quorum并正常启动服务。

详细使用方法和配置说明

前提条件

请查阅https://github.com/bcleonard/proxmox-qdevice/wiki#pre-requisites%E8%8E%B7%E5%8F%96%E6%9C%80%E6%96%B0%E7%9A%84%E7%B3%BB%E7%BB%9F%E8%A6%81%E6%B1%82%E5%92%8C%E5%89%8D%E7%BD%AE%E6%9D%A1%E4%BB%B6%E3%80%82

安装

该镜像支持通过Docker Compose或容器管理工具（如Portainer）部署。

配置

修改docker-compose.yml文件，需确保以下配置项正确设置：

1. 环境变量

• NEW_ROOT_PASSWORD：容器root用户的初始密码。

2. 持久化配置

• corosync-data目录：挂载本地目录以持久化qdevice配置（避免容器重启后配置丢失）。

3. 主机名

• 配置容器的hostname参数。

4. 网络配置（macvlan）

• parent：绑定macvlan的物理网络接口。
• ipv4_address：容器的IPv4地址。
• subnet：子网掩码。
• ip_range：IP地址范围。
• gateway：网关地址。

运行与部署

通过Docker Compose部署

执行以下命令启动容器：

bash
docker compose up -d

通过Portainer部署

将docker-compose.yml内容复制到Portainer的"Stacks"功能中，点击部署即可。

测试环境

已在以下环境中验证可用：

• Debian 12 (bookworm，所有点发布版本至12)（虚拟实例）
• Docker 24.0.5+（build ced0996及更高版本）
• Proxmox v8.0.4+
• Portainer Community Edition v2.18.4+

问题与故障排除

• 最新的问题、已知问题及故障排除信息，请查阅https://github.com/bcleonard/proxmox-qdevice/issues%E5%92%8Chttps://github.com/bcleonard/proxmox-qdevice/wiki#whats-not-supported%E3%80%82

安全注意事项

容器内安装并配置了sshd服务，允许root登录（与Proxmox默认配置一致）。启动时，若环境变量NEW_ROOT_PASSWORD存在，root密码将被设置为该变量的值。设置密码的方式如下：

设置密码的方法

1. 通过容器管理工具（如Portainer）：在环境变量中设置NEW_ROOT_PASSWORD，该变量会传递至容器。
2. 通过Docker Compose：参考Docker官方文档设置环境变量。注意：若在docker-compose.yml中硬编码密码，可能导致密码泄露。

手动修改密码（非持久化）

若未设置NEW_ROOT_PASSWORD，可在容器启动后手动修改密码（容器重建后需重新设置）：

bash
sudo docker exec -it proxmox-qdevice /bin/bash
root@proxmox-qdevice:/# passwd
New password:
Retype new password:
passwd: password updated successfully
root@proxmox-qdevice:/# exit

关于latest和beta标签的说明

不建议在生产环境中使用latest（bcleonard/proxmox-qdevice、bcleonard/proxmox-qdevice:latest）或beta（bcleonard/proxmox-qdevice:beta）标签。

这些标签可能不指向master分支的最新提交，且不保证稳定性，使用可能导致不可控的更新（如非向后兼容版本或破坏性变更）。请始终显式指定所需版本，以确保部署稳定性。

致谢

在开发过程中，以下资源提供了重要参考：

• Proxmox VE 7 Corosync QDevice in a Docker container
• https://github.com/modelrockettier/docker-corosync-qnetd

Wiki

项目Wiki提供了详细信息，可访问https://github.com/bcleonard/proxmox-qdevice/wiki%E6%9F%A5%E7%9C%8B%E3%80%82