③ 安装被控 Agent（新杜甫全流程）

这是最常问的问题：「我又买了一台杜甫，怎么把它接进来？」 完整流程如下。

总览（5 步）

在杜甫上安装 Proxmox VE
在主控里登记节点（名称 / IP / 地区）
主控生成一键安装命令
在杜甫上粘贴执行（自动装被控 + 注册 + 开机自启）
回主控确认节点在线，创建云模板后即可卖机器

第 1 步：杜甫安装 Proxmox VE

被控依赖 PVE 的 qm / pvesh 来管理虚拟机。在 Debian 12/13 上执行：

bash

# 1) 配置 PVE 源（Debian 13 用 trixie，Debian 12 用 bookworm）
echo 'deb http://download.proxmox.com/debian/pve bookworm pve-no-subscription' > /etc/apt/sources.list.d/pve.list
curl -fsSL https://enterprise.proxmox.com/debian/proxmox-release-bookworm.gpg \
  -o /etc/apt/trusted.gpg.d/proxmox-release-bookworm.gpg

# 2) 安装
apt update
apt install -y proxmox-ve postfix open-iscsi

# 3) 验证
qm --version

注意

安装 PVE 会接管网络配置（生成 vmbr0 桥），操作前请确认你有 IPMI / KVM 控制台，避免网络中断后失联。
单 IP 的杜甫推荐把主 IP 放在 vmbr0 上，虚拟机走 IPv6 或 NAT（本系统的默认模式）。
如果杜甫只有 IPv4，也能用：系统会给虚拟机分配共享 IPv4 + NAT 端口映射。

第 2 步：在主控登记节点

主控后台 → 被控节点 → 新增，填写：

字段	说明
节点名称	如 `OVH-02`（会显示在机器总览与购买页机房列表）
IP / 主机	杜甫的公网 IP（主控用它访问节点 API 8443）
地区	如 `加拿大-OVH`（购买页「选择地区」按这个聚合）
备注	可选，如机房位置 / 配置
SSH 端口 / 用户 / 密码	可选，仅用于主控内置的网页终端与记录

保存后进入节点详情，点 生成安装命令，会得到一行命令（24 小时内有效）：

bash

curl -fsSk 'https://console.example.com/install.sh?code=XXXXXXXXXXXX' | bash

安装码是一次性的

被控注册成功后，安装码会立即失效并自动轮换（防止被重复注册）。需要重装时，回主控节点详情重新生成即可。

第 3 步：在杜甫上执行

用 root 登录杜甫，粘贴上面那行命令。脚本会自动完成：

检查 qm（没有 PVE 会给出安装提示并退出）
创建 Proxmox API 凭据：panel@pve 用户 + panel@pve!api Token，并授予 PVEVMAdmin 权限
生成初始配置 /opt/pvepanel/config.json（含 PVE Token、监听端口等；已存在则不覆盖）
下载被控程序到 /opt/pvepanel/nkx-panel
注册到主控（nkx-panel enroll -master ... -code ...）：
- 主控返回 节点 Token、IP 白名单（主控出口 IP）、节点 API 监听地址
- 被控把 Token/白名单写入本地配置与数据库
写入 systemd 服务并开机自启
打开转发（net.ipv4.ip_forward / IPv6 转发 / bridge-nf）

执行完成后你会看到：

✅ 被控安装完成：你的杜甫主机名
   主控面板中稍候即可看到该节点在线。

第 4 步：验证

在主控 被控节点 列表里，该节点应显示在线，并带延迟（毫秒）。点进节点详情可以看到宿主机资源（CPU / 内存 / 磁盘 / 温度）与机器列表。

被控端自检（可选）：

bash

systemctl status nkx-panel --no-pager      # 服务运行中
curl -sk https://127.0.0.1:8443/api/node/ping -H "Authorization: Bearer $(sqlite3 /opt/pvepanel/panel.db "select value from settings where key='node_token'")"

第 5 步：创建云模板（重要）

被控装好后，还不能卖机器——开虚拟机需要云模板（默认要求 VMID 9000）。见：

👉 创建 PVE 云模板

常见问题

节点一直显示离线？

检查主控「系统设置 → 主控出口 IP」是否填了主控 VPS 的真实出口 IP（用域名 + Cloudflare 时最容易填错成 CF 的 IP）。
在杜甫上确认节点 API 在监听：ss -tlnp | grep 8443。
确认杜甫防火墙 / 云厂商安全组放行了 8443（仅允许主控 IP）。
看被控日志：journalctl -u nkx-panel -n 50 --no-pager。

安装脚本报「未检测到 Proxmox VE」

先完成第 1 步装 PVE，再重新执行安装命令（安装码仍然有效）。

安装脚本报「注册失败：安装码无效或已过期」

安装码 24 小时过期或已被使用。回主控节点详情 重新生成安装命令，再执行一次（脚本可重复执行，会覆盖旧的被控程序）。

换主控 / 重装主控后，被控连不上了

在被控上重新注册即可（需主控生成新安装码）：

bash

/opt/pvepanel/nkx-panel enroll -master https://新主控地址 -code 新安装码 -config /opt/pvepanel/config.json
systemctl restart nkx-panel

手动安装（不用一键脚本）

bash

# 1) 上传 nkx-panel 到 /opt/pvepanel/
# 2) 准备 PVE Token 并写 /opt/pvepanel/config.json（参考脚本生成的内容）
# 3) 注册
/opt/pvepanel/nkx-panel enroll -master https://console.example.com -code 安装码 -config /opt/pvepanel/config.json
# 4) 建 systemd 服务（见下方）并启动

systemd 单元内容：

ini

[Unit]
Description=NKXCLOUD Agent (PVE Node)
After=network.target pve-cluster.service
Wants=pve-cluster.service

[Service]
Type=simple
WorkingDirectory=/opt/pvepanel
ExecStart=/opt/pvepanel/nkx-panel -config /opt/pvepanel/config.json
Restart=always
RestartSec=3
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

卸载被控

bash

systemctl disable --now nkx-panel
rm -rf /opt/pvepanel /etc/systemd/system/nkx-panel.service
# 需要的话清理 nft 规则：nft delete table inet nkxnode

注意：卸载前先在主控里删除该节点，避免主控继续轮询报错。

下一步：创建 PVE 云模板

③ 安装被控 Agent（新杜甫全流程） ​

总览（5 步） ​

第 1 步：杜甫安装 Proxmox VE ​

第 2 步：在主控登记节点 ​

第 3 步：在杜甫上执行 ​

第 4 步：验证 ​

第 5 步：创建云模板（重要） ​

常见问题 ​

③ 安装被控 Agent（新杜甫全流程）

总览（5 步）

第 1 步：杜甫安装 Proxmox VE

第 2 步：在主控登记节点

第 3 步：在杜甫上执行

第 4 步：验证

第 5 步：创建云模板（重要）

常见问题