1Panel 多机管理功能问题排查指南

2 阅读

多机管理概述

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

排查步骤：

  1. 在子节点上检查服务状态：systemctl status 1panel-agent
  2. 确认防火墙端口是否放行
  3. 确认云服务器安全组端口是否放行

升级节点常见问题

下发升级文件失败

错误信息：upload 1panel-agent failed, err: permission denied

在失败节点上执行以下命令后重新升级：

rm -rf ~/1panel-package

其他问题

进入多机管理出现 404

清理浏览器缓存后重试即可。

评论