多机管理概述
1Panel 的多机管理采用一主多从架构，所有请求先经过主节点，再由主节点转发到各个子节点。核心要点如下：
- 子节点无法独立访问，无需单独安装，直接在主节点中添加即可；
- 必须保证主节点到子节点的网络连接正常；
- 添加或升级子节点时，均由主节点下载安装/升级包后下发到子节点；
- 若主节点到子节点的网络较慢，可能导致任务失败。此时可在「面板设置」中配置代理，并在添加节点或节点列表中开启代理。
建议开启主节点的定时备份。当主节点出现故障时，可通过
1panel-migrator将存有备份文件的某个子节点直接升级为主节点。该功能仅用于主节点迁移。如果只需要节点升级，可以先在节点列表中删除节点（不删除数据），然后在子节点上执行安装脚本即可。
添加节点常见问题
检查节点 SSH 连接失败
请确认以下信息是否填写正确：
- 节点地址
- 用户名和密码
- SSH 端口
检查节点用户权限失败
如果使用非 root 用户添加节点，需要确保该用户已开启 root 免密。可在子节点上执行以下命令验证：
sudo -n ls
若提示需要密码，则说明免密未正确配置。
检查许可证状态失败
前往「面板设置 → 许可证」页面，点击同步许可证状态。
检查节点已存在服务信息失败
提示节点已作为主节点启用时，需要先将该节点降级为子节点，然后再添加。
检查节点端口可达失败
请检查：
- 服务器防火墙是否放行节点端口
- 云服务器安全组是否放行节点端口
同步节点基础数据失败
错误信息：sync base info from agent failed, err: invalid character 'w' looking for beginning of value
在失败节点上执行以下命令后重新添加：
rm -rf /etc/1panel/baseInfo
启动服务失败
错误信息：handle start agent failed, err: handle sync agent info to node failed, std: bash: line 1: /etc/1panel/.agent: Permission denied
请检查用户权限，查看子节点 /etc/1panel/.agent 文件权限是否正确。
节点列表常见问题
请求错误，请检查该节点状态
错误信息：client do request failed, err: Post "https://xxx:xxx/api/v2/...": dial tcp xxx:xxx: connect: connection refused
排查步骤：
- 在子节点上检查服务状态：
systemctl status 1panel-agent - 确认防火墙端口是否放行
- 确认云服务器安全组端口是否放行
升级节点常见问题
下发升级文件失败
错误信息：upload 1panel-agent failed, err: permission denied
在失败节点上执行以下命令后重新升级：
rm -rf ~/1panel-package
其他问题
进入多机管理出现 404
清理浏览器缓存后重试即可。