lpgonzalez/corosync-qnetd

corosync-qnetd Docker镜像

一个轻量级Docker镜像，提供Corosync QDevice仲裁器（corosync-qnetd）——为双节点Proxmox VE集群添加外部打破平局的投票，使其成为真正的高可用性（HA）设置。

---

目录

• 为什么需要这个镜像
• QDevice工作原理（两分钟了解）
• 特性
• 支持的标签和架构
• 快速启动
• Proxmox VE完整设置
  • 1. 前置条件
  • 2. 部署qnetd容器
  • 3. 提供PVE节点公钥
  • 4. 从PVE引导QDevice
  • 5. 验证法定票数
• 配置参考
  • 卷
  • 端口
  • 环境变量
• 备份与恢复
• 部署方案
  • QNAP Container Station
  • Synology / TrueNAS / 通用Docker主机
  • 树莓派作为QDevice主机
• 故障排除
• 从源码构建
• 安全注意事项
• 常见问题
• 许可证
• 致谢

---

为什么需要这个镜像

Proxmox VE集群需要法定票数（多数投票）才能安全地做出HA决策。双节点集群有2票，若其中一个节点无法通信，双方都无法获得多数票，集群会冻结HA管理的VM以防止脑裂。

Proxmox官方推荐的解决方案是QDevice：在第三台机器上运行的小型进程，添加1票，使任何存活的单节点获得3票中的2票，保持法定状态。

但Proxmox文档假设你有第三台Linux机器，而大多数家庭实验室或小型企业没有——他们只有NAS。corosync-qnetd没有官方容器镜像，因此用户不得不添加树莓派或在NAS主机OS上安装包。本镜像解决了这个问题：可部署在任何支持Docker的主机（QNAP Container Station、Synology、TrueNAS、树莓派等）上，让NAS成为仲裁器。

QDevice工作原理（两分钟了解）

   ┌──────────────┐                       ┌──────────────┐
   │   pve01      │◄───── corosync ──────►│   pve02      │
   │  (1票)       │                       │  (1票)       │
   └──────┬───────┘                       └───────┬──────┘
          │                                       │
          │   corosync-qdevice（每个节点）        │
          └────────────┬──────────────────────────┘
                       │
                       │  TCP/5403（TLS，NSS证书）
                       ▼
              ┌─────────────────────┐
              │  corosync-qnetd     │   <-- 本容器
              │  (1票，仲裁器)       │
              └─────────────────────┘

部署本镜像后的法定票数计算：

特性

• 最小化镜像（基于debian:13-slim + corosync-qnetd + openssh-server），大小约120 MB。
• 内置SSH服务器，使pvecm qdevice setup <ip>可直接使用——Proxmox使用22端口（硬编码）安装NSS证书。
• 仅公钥SSH：禁用密码、PAM和挑战响应认证。
• 自动初始化：首次启动时生成持久化SSH主机密钥并初始化qnetd NSS数据库；后续启动时复用这些密钥。
• 防御性权限修复：强制/root/.ssh/authorized_keys的所有权为root:root，避免SMB上传的非root UID文件被SSH StrictModes静默拒绝。
• 内置健康检查（验证两个端口是否监听）。
• OCI元数据标签（源码、版本、修订版、许可证等）。
• 多架构支持：linux/amd64、linux/arm64。

支持的标签和架构

标签遵循https://semver.org/。`latest`标签始终指向最新稳定版本。

快速启动

若仅需验证容器运行：

bash
docker run -d \
  --name corosync-qnetd \
  -p 5403:5403/tcp \
  -p 22:22/tcp \
  -v ./configs/qnetd-nssdb:/etc/corosync/qnetd/nssdb \
  -v ./configs/ssh-host-keys:/etc/ssh/keys \
  -v ./configs/ssh-authorized-keys:/root/.ssh \
  docker.xuanyuan.run/lpgonzalez/corosync-qnetd:latest

容器将启动，生成密钥，暴露5403/tcp（qnetd）和22/tcp（SSH），等待pvecm qdevice setup填充NSS数据库。

这本身不足以完成设置——请阅读Proxmox VE完整设置部分以实现与PVE的集成。

Proxmox VE完整设置

1. 前置条件

• 运行中的双节点Proxmox VE集群（运行pvecm status——应列出两个节点且Quorum: 2）。
• 在每个PVE节点上安装QDevice客户端：

  bash
  apt update && apt install -y corosync-qdevice
  

• 第三台支持Docker的主机，TCP/22和TCP/5403端口空闲。若22端口已被主机SSH占用（NAS设备常见），请参考QNAP Container Station方案中的解决方法。
• 两个PVE节点与Docker主机之间的网络连通性（TCP/22和TCP/5403）。

2. 部署qnetd容器

选择与主机匹配的部署方案并启动容器。容器将：

1. 在configs/ssh-host-keys/下生成持久化SSH主机密钥。
2. 在configs/qnetd-nssdb/下初始化空的qnetd NSS数据库。
3. 启动sshd和corosync-qnetd（前台运行）。

验证容器健康状态：

bash
docker ps --filter name=corosync-qnetd
# 状态列应显示“Up X minutes (healthy)”（约30秒后）

3. 提供PVE节点公钥

Proxmox通过root用户SSH引导QDevice。容器仅允许公钥认证，因此每个PVE节点的root公钥需添加到容器的authorized_keys中。

在每个PVE节点上：

bash
# 若不存在密钥则生成：
[ -f /root/.ssh/id_rsa ] || ssh-keygen -t rsa -b 4096 -N "" -f /root/.ssh/id_rsa
cat /root/.ssh/id_rsa.pub

将输出的公钥添加到容器的authorized_keys文件中：

<主机路径>/configs/ssh-authorized-keys/authorized_keys

每个节点一行。容器的入口点将在下次重启时重新应用正确的所有权（root:root）和权限（600），因此上传文件的UID无关紧要。

若文件通过SMB/CIFS或NFS上传，容器内的所有权可能显示为UID 1000等。重启容器让入口点修复，或运行docker exec corosync-qnetd chown -R root:root /root/.ssh。

从每个PVE节点测试SSH连接容器：

bash
ssh -o IdentitiesOnly=yes -i /root/.ssh/id_rsa root@<qnetd主机> hostname

应输出容器的主机名。若提示接受主机密钥，请输入yes——该指纹对应configs/ssh-host-keys/中的密钥。

4. 从PVE引导QDevice

在任意一个PVE节点上运行一次（通过Corosync自动配置两个节点）：

bash
pvecm qdevice setup <qnetd主机>

幕后，pvecm将：

1. SSH进入容器，生成集群证书。
2. 将证书放置在/etc/corosync/qnetd/nssdb/（持久化卷）中。
3. 更新两个PVE节点的/etc/corosync/corosync.conf以声明QDevice。
4. 重新加载Corosync。

5. 验证法定票数

bash
pvecm status

预期输出：

Votequorum information
----------------------
Expected votes:   3
Highest expected: 3
Total votes:      3
Quorum:           2
Flags:            Quorate Qdevice

Membership information
----------------------
    Nodeid      Votes    Qdevice Name
0x00000001          1    A,V,NMW <node1>
0x00000002          1    A,V,NMW <node2>
0x00000000          1            Qdevice

若Flags显示Quorate Qdevice且Total votes:3，设置完成。

配置参考

卷

端口

两个端口必须从每个PVE节点可达容器。qnetd端口（5403）必须保持可达；SSH端口在证书引导后可关闭以减少***面。

环境变量

本镜像不接受运行时环境变量——所有行为由持久化NSS数据库和授权密钥文件驱动。Compose文件中的configs/env/vars.env为未来扩展预留。

备份与恢复

唯一值得备份的状态是NSS数据库。没有它需重新运行pvecm qdevice setup；有了它可在几分钟内重建主机。

备份：

bash
docker compose stop                       # 快速停止以避免写入中捕获
tar czf qnetd-state-$(date +%F).tar.gz \
    configs/qnetd-nssdb \
    configs/ssh-host-keys \
    configs/ssh-authorized-keys
docker compose start

主机上每周一次的Cron任务通常足够——NSS数据库在集群设置后几乎不变化。

在新主机上恢复：

bash
tar xzf qnetd-state-YYYY-MM-DD.tar.gz
docker compose up -d

PVE端无需操作——两个节点将在下次Corosync轮询时重新连接到恢复的qnetd。若qnetd移至新IP，需在PVE端更新Corosync：

bash
pvecm qdevice remove
pvecm qdevice setup <新qnetd主机>

部署方案

QNAP Container Station

旧款QNAP型号（如TS-x63系列）的Container Station有两个已知问题：

1. 无法从应用UI可靠构建Dockerfile——粘贴含build:的Compose时，Container Station将YAML复制到临时目录而无其他文件，导致构建失败（open Dockerfile: no such file or directory）。
2. 非root用户的docker CLI可能无法创建$HOME——运行docker build时可能看到ERROR: mkdir /share/CACHEDEV1_DATA/.qpkg/.../homes/<user>: permission denied。

推荐方法：

1. 使用Docker Hub预构建镜像（无需Dockerfile）：

   yaml
   services:
     corosync-qnetd:
       image: docker.xuanyuan.run/lpgonzalez/corosync-qnetd:latest
       container_name: corosync-qnetd
       restart: unless-stopped
       ports:
         - "5403:5403/tcp"
         - "22:22/tcp"
       volumes:
         - /share/Container/corosync-qnetd/configs/qnetd-nssdb:/etc/corosync/qnetd/nssdb
         - /share/Container/corosync-qnetd/configs/ssh-host-keys:/etc/ssh/keys
         - /share/Container/corosync-qnetd/configs/ssh-authorized-keys:/root/.ssh
   

2. 释放NAS的22端口：将QTS自身的SSH移至自定义端口（如7000），路径为控制面板 → 网络与文件服务 → Telnet/SSH。QTS SSH移至7000后，上述22:22映射无冲突。
3. 通过SMB将目录（含Compose文件）上传至/share/Container/corosync-qnetd/，然后在Container Station中创建指向该Compose的应用。

替代方案（无需拉取DockerHub）： 在工作站本地构建镜像，通过docker save/docker load上传至NAS。参见从源码构建——包含的Makefile通过make nas-deploy自动完成此流程。

Synology / TrueNAS / 通用Docker主机

标准docker compose up -d即可。需检查主机的22端口是否空闲，或重新映射容器SSH到其他端口（如2222:22）。但**pvecm qdevice setup硬编码SSH 22端口**，若重新映射需手动引导证书：

bash
# 在PVE节点上仅生成证书文件（SSH步骤将失败）：
pvecm qdevice setup <主机> 2>/dev/null || true

# 将/etc/pve/qnetd-cacert.crt通过scp -P 2222复制到容器，然后：
ssh -p 2222 root@<主机> \
  corosync-qnetd-certutil -s -c /tmp/qnetd-cacert.crt -n <集群名称>

# 在PVE上重新运行以完成设置：
pvecm qdevice setup <主机>

树莓派作为QDevice主机

30欧元的树莓派运行Docker是最便宜且可靠的QDevice主机。标准安装：

bash
sudo apt install -y docker.io docker-compose-plugin
git clone https://github.com/lpgonzalez/corosync-qnetd-docker
cd corosync-qnetd-docker
docker compose up -d

镜像的arm64变体原生运行于树莓派3/4/5（64位Raspberry Pi OS）。压缩包约50MB。

故障排除

从PVE SSH连接时出现Permission denied (publickey)

按可能性排序：

1. authorized_keys所有权非root：SSH的StrictModes会静默拒绝非目标用户所有的授权密钥。修复：

   bash
   docker exec corosync-qnetd chown -R root:root /root/.ssh
   docker exec corosync-qnetd chmod 700 /root/.ssh
   docker exec corosync-qnetd chmod 600 /root/.ssh/authorized_keys
   

   重启容器让入口点固化这些权限。
2. authorized_keys中的公钥与PVE的id_rsa.pub不匹配：比较指纹：

   bash
   # 在容器主机上：
   docker exec corosync-qnetd ssh-keygen -lf /root/.ssh/authorized_keys
   # 在每个PVE节点上：
   ssh-keygen -lf /root/.ssh/id_rsa.pub
   

3. 绑定挂载指向错误的主机路径：检查实际挂载：

   bash
   docker inspect corosync-qnetd --format '{{ range .Mounts }}{{ .Source }} -> {{ .Destination }}{{ "\n" }}{{ end }}'
   

pvecm qdevice setup失败并显示No route to host

容器健康但PVE节点无法访问TCP/22端口。常见原因：

• Docker主机防火墙阻断22端口入站。
• 容器位于macvlan网络，其父网卡未连接电缆。
• 管理型交换机因端口安全丢弃容器的新MAC。

日志中出现exec: corosync-qnetd: not found（容器重启循环）

若从源码构建，确保Dockerfile使用Debian bookworm或更新版本——旧版本中二进制路径为/usr/sbin/corosync-qnetd，当前Debian移至/usr/bin/corosync-qnetd。包含的入口点使用exec corosync-qnetd -f（无绝对路径），兼容两种布局。

容器重建后PVE提示主机密钥更改

容器仅在/etc/ssh/keys卷为空时重新生成SSH主机密钥。若未持久化该卷（或已清空），新密钥为全新。在每个PVE节点上清除过时条目：

bash
ssh-keygen -R <qnetd主机>

手动运行sshd -d时出现bind: address already in use

忘记终止入口点的sshd。使用：

bash
docker exec corosync-qnetd pkill sshd
docker exec -d corosync-qnetd /usr/sbin/sshd -d -e -E /tmp/sshd.log

从源码构建

克隆并使用Makefile：

bash
git clone https://github.com/lpgonzalez/corosync-qnetd-docker
cd corosync-qnetd-docker
make help                       # 列出所有目标

常见流程：

bash
# 本地单架构构建（当前主机架构）：
make build

# 构建、保存为tar.gz、通过SSH上传至NAS并加载：
make nas-deploy
# （先编辑Makefile顶部的nas-user、nas-host、nas-ssh-port、nas-dest）

# 多架构发布至Docker Hub：
docker login
make release

release目标使用Docker Buildx生成覆盖platforms变量（默认：linux/amd64,linux/arm64）所有平台的清单列表，并推送到release-tags（默认：当前image-version和latest）。

要更新版本，编辑Makefile中的image-version并重新运行make release。

安全注意事项

• 容器内置sshd监听22端口，仅允许root用户通过公钥登录。禁用密码、PAM和挑战响应。root无密码。
• 仅将操作员/PVE公钥添加到authorized_keys。切勿将私钥放入容器。
• TCP/22仅在初始pvecm qdevice setup期间需要。引导后可防火墙阻断，集群仍正常工作——corosync-qnetd本身使用TCP/5403。
• configs/qnetd-nssdb/中的NSS数据库包含集群证书颁发机构。视为机密：不要推送到公共Git仓库（包含的.gitignore默认排除）。

常见问题

Q: 能否用一个qnetd容器仲裁多个PVE集群？
可以。corosync-qnetd原生支持多个集群——每个集群以不同名称注册。只需从每个集群运行pvecm qdevice setup <主机>。

Q: qnetd容器宕机会发生什么？
只要两个PVE节点仍能通信（仍有3票中的2票），集群继续工作。HA故障转移停止，直到qnetd恢复。无数据丢失。

Q: qnetd需要连接UPS吗？
不严格需要。最坏情况（qnetd宕机+一个PVE节点宕机）仅冻结存活节点，这是正确行为。若希望NAS电源中断时HA仍可用，可将NAS连接UPS。

Q: 能否在PVE节点上运行qnetd？
不能。QDevice的核心是外部于集群。若qnetd随节点宕机，则无任何法定票数收益。

Q: 镜像支持IPv6吗？
支持。corosync-qnetd默认监听双栈。在Compose中相应暴露端口即可。

Q: 容器内为何包含SSH服务器？是否有额外开销？
Proxmox的pvecm qdevice setup脚本通过SSH引导证书。无容器内SSH需手动操作，但官方工具无法使用。sshd的开销约5MB空间和3MB空闲RAM。

许可证

MIT © Lisardo Prieto

致谢

• Cluster Labs团队（corosync-qnetd开发者）。
• Proxmox VE项目（使HA对小型基础设施可用）。
• Debian项目（13-slim镜像）。

---

发现 bug 或想贡献？ 在https://github.com/lpgonzalez/corosync-qnetd-docker提交issue或PR。