部署运维平台异常排查

版本说明

应用场景

本文将介绍部署升级运维平台的常见问题和解决方案。

问：非root用户运行fineKey需要什么权限？

优先推荐使用root用户运行finekey部署工具。

如需使用非root用户运行finekey部署工具，请参考文档配置用户权限：确认部署运维平台的用户权限

问：磁盘明明有100G，为什么还是部署失败呢？

1）目录不正确

默认安装目录为~/data，是安装用户主目录下的data文件夹，而不是根目录/data文件夹

例如使用root用户部署，则~/data代表的目录为/root/data，请确保yaml文件中配置了正确的目录

2）磁盘可用空间不足

必须确保配置的挂载卷目录剩余可用空间达到100G以上

服务器操作系统本身会占用一部分空间，所以如果只给该目录分配了100G空间，那么剩余可用肯定不足100G了

finekey is already running

报错语句：finekey is already running

原因分析：finekey工具正在运行，需要关闭工具占用的进程，方可重启。

解决方案：

• 如有其他用户正在运行finekey工具，请耐心等待对方执行完成。

• 如确定可以中断其他人的执行，请通过语句ps -ef|grep finekey，查看相关的进程号，kill -9 进程号 即可。

The current path capacity check failed

报错语句：

The current path capacity check failed, please re-enter the path
Enter the folder path and press ENTER to confirm, or enter g then ENTER to exit:

报错原因：

运维平台需要足够的服务器磁盘空间进行安装。

部署运维平台时，会自动检测finekey.yaml文件中dataRootPath对应的分区空闲空间是否充足

默认的dataRootPath是~/data目录，不代表/data目录，而是对应用户主目录下的/data目录。例如使用root用户部署，则~/data代表的目录为/root/data

解决方案：

如果是目录填写错误，用户无需退出部署环节去手动修改yaml文件。可直接输入满足条件的目录，即可继续部署。

如果不是目录填写错误，确实是磁盘空间不足，请联系相关运维人员对服务器进行扩容。这是部署运维平台的前提，必须满足。

disk availlable capacity:xxx, less then xxxG

报错语句：ERROR: 2022/05/18 17:08:36 node 192.168.1.24 disk availlable capacity:3789952, less then 100G

原因分析：

运维平台需要足够的服务器磁盘空间进行安装。

部署运维平台时，会自动检测finekey.yaml文件中dataRootPath对应的分区空闲空间是否充足

解决方案：

1）打开finekey安装目录下 conf 文件夹里的配置文件 finekey.yaml，查看dataRootPath对应的服务器目录是什么。

默认值为~/data，是安装用户主目录下的data文件夹。例如使用root用户部署，则~/data代表的目录为/root/data

2）使用df -h命令，检查服务器磁盘可用容量。

3）请确保dataRootPath对应磁盘分区的剩余可用容量超过提示值。这是部署运维平台的前提，必须满足。

如磁盘空间不足，请联系相关运维人员对服务器进行扩容，或更换有足够空间的dataRootPath

Do not use system directories as dataroot

报错语句：Do not use system directories as dataroot!

报错原因：/、/usr、/root、/usr/local四个目录，是系统目录，不可以直接使用这四个目录作为 finekey.yaml 文件中的 dataRootPath 配置项

解决方法：

打开finekey安装目录下 conf 文件夹里的配置文件 finekey.yaml，修改dataRootPath

请勿直接使用/、/usr、/root、/usr/local四个目录，请使用其他目录，或在这些目录中新建文件夹

memory avillable capacity: xxx, less then xxG

报错语句：ERROR: 2022/04/20 14:12:55 node 192.168.101.144 memory avillable capacity: 7302952, less then 12G

原因分析：运维平台需要足够的服务器内存支撑运行。部署运维平台时，会自动检测服务器剩余空闲物理内存是否充足。

解决方案：这是部署运维平台的前提，必须满足。请联系相关运维人员对服务器增加配置。

connection refused

报错语句：ERROR: 2022/05/18 17:33:07 finedb connect error:dial tcp 192.168.1.24:3306: connect: connection refused

原因分析：finekey.yaml文件中配置的相关端口，没有开放，无法连接。

解决方案：请参考文档检查报错中提及的相关端口的防火墙、安全组等设置是否开放：端口占用检查与防火墙配置

try bind ports xx error

报错语句示例：

ERROR: 2025/10/15 21:41:49 183.6.186.178 :try bind ports 80 error

ERROR: 2025/10/11 15:26:19 10.38.6.26 :try bind ports 9200,9071,12800,11800,80 error

原因分析：

运维平台由多个容器共同组成，部分容器端口需要映射到宿主机，占用服务器端口运行。

部署运维平台过程中，如检测到容器所需端口被占用，则会出现该报错。

解决方案：

请参考文档检查报错中提示的端口是否被占用：端口占用检查与防火墙配置

• 端口确实被占用：打开finekey安装目录下 conf 文件夹里的配置文件 finekey.yaml，找到对应组件，修改portMapping中映射端口，保存退出后重新运行即可。

• 端口没有被占用：打开finekey安装目录下 conf 文件夹里的配置文件 finekey.yaml，排查是否是finekey.yaml中各处字符格式不对，比如漏加空格或用了中文符号等。

mapping values are not allowed in this context

报错语句：ERROR: 2022/04/20 13:56:28 parse config file /Users/carly/finekey/conf/finekey.yaml error: yaml: line 14: mapping values are not allowed in this context

报错原因：yaml 文件对格式的要求非常高，出现该错误，大概率都是由于内容格式存在错误。

解决方案：打开finekey安装目录下 conf 文件夹里的配置文件 finekey.yaml，根据报错提示中的 line 号修改配置文件格式。

add user to docker group error

报错语句：add user to  docker group error：sudo：1次错误密码尝试

解决方案：

1）打开finekey安装目录下 conf 文件夹里的配置文件 finekey.yaml，检查node配置中的用户名密码是否正确

2）确保finekey所在服务器，与待部署运维平台的服务器，可通过ssh访问

3）远程连接工具问题，关闭重启远程工具并再次尝试

ssh connect error

报错语句：ERROR: 2022/04/20 13:58:14 node:192.168.101.144 ssh connect error:ssh: handshake failed: ssh: unable to authenticate, attempted methods

报错原因：SSH 连接失败，通常报错明细中出现 unable to authenticate 则代表密码有问题；出现 Connection refused 则代表网络不通等可能

解决方案：

1）打开finekey安装目录下 conf 文件夹里的配置文件 finekey.yaml，检查node配置中的用户名密码是否正确

2）确保finekey所在服务器，与待部署运维平台的服务器，可通过ssh访问

3）远程连接工具问题，关闭重启远程工具并再次尝试

did not find expected key

报错语句：

ERROR: 2022/04/20 13:58:14 parse config file /home/finekey/conf/finekey.yaml error: yaml: line 26: did not find expected key

排查方向一：yaml格式错误

yaml 文件对格式的要求非常高，出现该错误，大概率都是由于内容格式存在错误。

打开finekey安装目录下 conf 文件夹里的配置文件 finekey.yaml，根据报错提示中的 line 号修改配置文件格式。

排查方向二：未放开注释

此种情况大概率是由于指定组件端口时，没有完全放开注释。

打开finekey安装目录下 conf 文件夹里的配置文件 finekey.yaml，确认components所在行的#注释已删除、组件名称所在行的#注释已删除、组件端口配置所在行的#已删除

示例：修改nginx的端口80为8088

node xxx get runc command location not /usr/bin/runc but /usr/local/bin/runc

报错语句：

get runc command location not /usr/bin/runc but /usr/local/bin/runc

报错原因：

finekey 部署检测中，finekey 安装的 docker 及其组件需要是帆软提供的，这样才能保证 docker 及其组件之间的兼容可用，

如果服务器中其他软件安装了runc，runc版本过低，与帆软安装的docker冲突，就可能会导致部署失败。

解决方法：

1）which runc：检查 runc 是否是帆软提供的 /usr/bin/runc

2）rpm -qa | grep podman：检查是否安装podman，podman一般自带runc，版本过低

3）yum remove podman -y：确保无需使用podman的情况下卸载podman

docker bin path check not pass

报错语句：

docker bin path check not pass, using commands like [rpm -qa | grep podman] to find out other OCI management tools like [podman], using [yum remove podman] to remove them and retry

报错原因：

finekey 部署检测中，finekey 安装的 docker 及其组件需要是帆软提供的，这样才能保证 docker 及其组件之间的兼容可用，

如果服务器中其他软件安装了runc，runc版本过低，与帆软安装的docker冲突，就可能会导致部署失败。

解决方法：

1）which runc：检查 runc 是否是帆软提供的 /usr/bin/runc

2）rpm -qa | grep podman：检查是否安装podman，podman一般自带runc，版本过低

3）yum remove podman -y：确保无需使用podman的情况下卸载podman

node selinux status check got [enforcing] status

报错语句：

node selinux status check got [enforcing] status, please using [setenforce 0 && sed -i s/^SELINUX=enforcing/SELINUX=permissive/ /etc/selinux/config] to disable selinux

报错原因：

SELinux 是 Linux 内核中的一个安全模块，通过强制访问控制机制来严格限制程序和用户对系统资源的访问。在 SELinux 开启的情况下，可能会影响通过 systemctl 命令以服务方式启动 Docker 。

为确保 finekey 部署顺利进行，请在执行部署前先关闭 SELinux ，或至少将 SELinux 切换到 permissive 模式，确保违反 SELinux 策略的操作不会被阻止

解决方案：

1）优先考虑参考文档关闭 SELinux：确保关闭SELinux安全模块

2）或者根据报错语句中提示的命令，将 SELinux 切换到 permissive 模式。

命令：setenforce 0 && sed -i s/^SELINUX=enforcing/SELINUX=permissive/ /etc/selinux/config

• setenforce 0：临时将 SELinux 从 enforcing 模式切换到 permissive 模式

• ed -i s/^SELINUX=enforcing/SELINUX=permissive/ /etc/selinux/config：永久修改 SELinux 配置文件，将默认模式从 enforcing 改为 permissive

The network segment xxx is already in use by other machine.

报错语句：The network segment *.*.*.*/16 is already in use by other machine. Please choose another network segment.

原因分析：

BIP（Bridge IP） 是 Docker 默认网桥 docker0 的 IP 地址，所有未指定网络的容器会连接到这里，通过它分配子网 IP。

一般情况下无需指定，但出现此报错时，需要为BIP指定没有被占用的私有IP网段。

解决方案：

1）打开finekey安装目录下 conf 文件夹里的配置文件 finekey.yaml

2）删除bip所在行的#注释

3）修改bip指定网段：网段必须未被占用、网段必须是私有IP

IP address xxx is already in use within the network segment xxx.

报错语句：Conflict detected: IP address 172.18.8.175 is already in use within the network segment 172.18.0.0/16.

原因分析：

BIP（Bridge IP） 是 Docker 默认网桥 docker0 的 IP 地址，所有未指定网络的容器会连接到这里，通过它分配子网 IP。

一般情况下无需指定，但出现此报错时，需要为BIP指定没有被占用的私有IP网段。

解决方案：

1）打开finekey安装目录下 conf 文件夹里的配置文件 finekey.yaml

2）删除bip所在行的#注释

3）修改bip指定网段：网段必须未被占用、网段必须是私有IP

can not connect to ImageRegistry or CloudSite!

报错语句：ERROR: 2025/03/18 10:30:04 172.24.27.10 :can not connect to ImageRegistry or CloudSite!

原因分析：

运维平台由多个容器组成，这些容器依赖镜像进行安装。

如果使用在线版finekey部署运维平台，必须确保服务器可连接外网，从帆软云端镜像仓库拉取镜像到本地仓库。

出现此报错，说明既使用了在线版finekey，服务器又无法连接外网，没有办法获取镜像到本地进行部署。

解决方案：

1）如果服务器可开放外网白名单

请确保待部署运维平台的服务器/自备的镜像仓库服务器开通网络白名单，即可在部署项目时自动从帆软云端仓库拉取最新组件镜像。

详情请参见：确认镜像仓库支持连接帆软云端仓库

2）如果服务器不支持开放外网白名单

请不要使用在线版finekey安装包，重新下载全量版离线finekey安装包进行部署

registry is not ready!

报错语句：registry is not ready!

场景：对接自备镜像仓库

1）请确认镜像仓库的地址、用户、密码等配置完全正确。

• 打开 finekey 安装目录下 conf 文件夹里的配置文件 finekey.yaml

• 请逐一确认repo的相关信息填写正确。

2）请确认该镜像仓库正常运行。

场景：全新部署镜像仓库

finekey部署运维平台时，安装/对接的第一个容器就是registry，出现该报错有可能是容器安装问题，也有可能是系统网络问题。

执行该命令查看是否存在registry容器进程：docker ps -a | grep registry，然后根据返回值执行下一步解决方案

在线升级需要开放的外网地址

对于内网环境，如需在线升级FineOps运维平台，需要自行开通网络白名单。

详情请参见：确认镜像仓库支持连接帆软云端仓库

升级提示docker engine报错

问题描述：

运维平台升级过程中，提示docker engine相关报错

原因分析：

由于docker引擎、FineOps运维平台、项目的ops_agent组件存在对应关系。

如需手动升级运维平台，必须确保运维平台所在服务器、运维平台对接的项目所在服务器，均支持升级docker引擎。

如在执行finekey update过程中，检测到系统禁止升级docker引擎，就会出现该报错，中断升级。

解决方案：

1）依次分别登录运维平台所在服务器、运维平台对接的项目所在的每一台服务器

2）执行语句，升级docker引擎：./finekey engine --update

3）再次参考上文使用语句启动升级：./finekey update

注意事项：

在升级FineOps运维平台时，在哪一台服务器触发了docker引擎升级，就会重启该机器上的容器。

因此会影响终端用户使用运维平台和项目。请选择非工作时间进行升级，降低业务影响。