宝塔官方从未发布“集群版”，唯一可落地的多机统一管理方案是企业版的「多级联动」功能，采用主控端（企业版）+受控端（轻量bt_node服务）架构，依赖双向tls加密通信，仅企业版支持且需实名认证授权。
宝塔没有“集群版”这个官方产品，所谓集群版要么是旧版已下架的 bt_cluster 插件（2023年底停服），要么是第三方打包的无效安装包。当前唯一稳定、可落地的企业级多机统一管理方案，是宝塔企业版的「多级联动」功能，它不是面板集群，而是主控端 + 受控端架构。
用多级联动替代“集群版”：主控端必须是企业版
宝塔官方从未发布过名为“集群版”的安装包或分支版本。所有声称提供该版本的下载链接，实际指向的是早已失效的 bt_cluster 插件（依赖的后端服务返回 404）或伪造的 shell 脚本。真正支持批量纳管的只有企业版内置的【多级联动】模块，且仅在企业版中可用。
- 主控端必须安装宝塔企业版（非免费版），完成实名认证与授权绑定
- 受控端不装完整面板，只运行轻量
bt_node服务，监听默认8888端口 - 通信走双向 TLS 加密，密钥对由主控端生成并分发，不可跳过证书验证
- 免费版面板无法启用【多级联动】入口，点击即提示“请升级企业版”
受控端安装失败的三个典型原因
执行主控端下发的受控端安装命令后，常见报错如 Connection refused、command not found: bt 或服务未监听 8888，基本都卡在这三处：
- 目标服务器防火墙未放行
8888端口（CentOS 用firewall-cmd --add-port=8888/tcp --permanent，Ubuntu 用ufw allow 8888） - 主控端无法主动连通受控端——注意是“主控→受控”单向可达，不是 SSH 反向连接；需在主控端
telnet 受控IP 8888验证 - 受控端已存在旧版
bt_node进程但未清理干净，执行ps aux | grep bt_node后 kill 并删掉/www/server/bt_node目录再重装
同步网站配置时直接拷贝 vhost/conf 会失败
很多用户试图用 rsync 把 /www/server/panel/vhost/nginx/ 下的 conf 文件推到其他服务器，结果站点在面板里消失或反复还原。这是因为宝塔校验文件头注释中的 BT-CONF-VERSION 和隐式绑定的站点 ID，手动搬运会破坏一致性。
- 正确做法是用面板内置命令导出导入：
bt export_site site_name生成 zip，再在目标机执行bt import_site /path/to/site.zip - SSL 证书只同步
/www/server/panel/vhost/cert/域名/fullchain.pem和privkey.pem，导入后必须立刻执行bt reload_nginx - 不要用
curl http://127.0.0.1:8888/xxx调 API——默认关闭 CSRF，token 有效期极短，极易因超时或 session 失效中断
Ansible 执行 bt 命令常报 command not found 的真实原因
Ansible 的 shell 模块默认不加载 root 用户的 PATH 和环境变量，所以 bt 命令找不到。这不是权限问题，也不是没装宝塔，而是路径隔离导致的。
- 不能写
shell: bt restart_php，要显式调用完整路径：shell: /www/server/panel/pyenv/bin/python /www/server/panel/class/bt.py restart_php - 更稳妥的做法是封装成脚本放在受控端，再用 Ansible 触发：
shell: bash /root/bt_wrapper.sh restart_php - 如果坚持用原生
bt命令，必须在 play 中加environment: { PATH: "/usr/local/bin:/usr/bin:/bin:/www/server/panel/pyenv/bin" }
多级联动不是“一键集群”，它的权限粒度、证书分发、分组策略都需要逐项确认；一旦某台受控端的 private.key 文件被覆盖或权限改错（必须是 600），整个节点就会失联且无明确错误提示——这是最常被忽略的细节。
