目录:
概述编辑
常见问答编辑
问：非root用户运行fineKey需要什么权限？
优先推荐使用root用户运行finekey容器化部署工具。
如需使用非root用户运行finekey容器化部署工具，请参考文档配置用户权限：确认部署运维平台的用户权限
问：磁盘明明有100G，为什么还是部署失败呢？
1）目录不正确
默认安装目录为~/data，是安装用户主目录下的data文件夹，而不是根目录/data文件夹
例如使用root用户部署，则~/data代表的目录为/root/data，请确保yaml文件中配置了正确的目录
2）磁盘可用空间不足
必须确保配置的挂载卷目录剩余可用空间达到100G以上
服务器操作系统本身会占用一部分空间，所以如果只给该目录分配了100G空间，那么剩余可用肯定不足100G了
问：ops和项目能部署在一台服务器上嘛？
帮助文档所提供的资源要求，均按照标准部署方案提供，不建议也不提供此种配置分配方案。
如果运维平台和项目部署在同一台服务器上，无法达到异机备份等功能。
如果服务器出现故障，两者会同时宕机，无法实现运维平台拉起项目等功能。
因此强烈建议为运维平台和项目分别准备完全独立可用的服务器。
yaml文件规范性检查编辑
finekey.yaml文件中存在以下规范，如不遵守，会报错并自动终止部署
# 必填项
node:
# 必填项
ip: localhost
# 必填项，范围0-65535
port: 22
user:
password:
# 必填项
dataRootPath: ~/data
# 必填项
repo:
# 必填项，范围0-65535
port: 5000
url:
username:
password:
ssl: true
online: false
# 必填项，校验值必须为CN/TW/EN
language: CN
# 校验是否为CIDR
bip: 10.16.0.1/16
# 校验是否为CIDR
fip: 10.17.0.1/16
# 校验组件名称，必须为我们要求的组件
#components:
# nginx:
# portMapping: {80: 8080}
#
# ops_agent:
# portMapping: {9071: 9070}
#
# skywalking_oap:
# portMapping: {11800: 11800, 12800: 12800}
#
# elasticsearch:
# portMapping: {9200: 9200}
# password: elasticadmin
#
常见报错编辑
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
原因分析：
运维平台中存在很多组件，部分组件的端口需要映射到宿主机，占用服务器端口运行。
部署运维平台过程中，如检测到所需端口被占用，则会出现该报错。
解决方案：
请参考文档检查报错中提示的端口是否被占用：端口占用检查与防火墙配置
端口确实被占用：打开安装目录下 conf 文件夹里的 finekey.yaml文件，找到对应组件，修改portMapping中映射端口，保存退出后重新运行即可。
端口没有被占用：仔细排查安装目录下 conf 文件夹里的 finekey.yaml文件，是否是finekey.yaml中各处字符格式不对，比如漏加空格或用了中文符号等。
finekey is already running
报错语句：finekey is already running
原因分析：finekey工具正在运行，需要关闭工具占用的进程，方可重启。
解决方案：通过语句ps -ef|grep finekey，查看相关的进程号，kill -9 进程号 即可。
disk availlable capacity:xxx, less then 500G
报错语句：ERROR: 2022/05/18 17:08:36 node 192.168.1.24 disk availlable capacity:3789952, less then 500G
原因分析：安装时会自动检测finekey.yaml文件中配置的挂载卷目录所在磁盘分区空闲空间要≥500G，默认的~/data代表的目录是/root/data。
解决方案：这是容器化部署的前提，必须满足。请联系相关运维人员对服务器进行扩容。
memory avillable capacity: xxx, less then 16G
报错语句：ERROR: 2022/04/20 14:12:55 node 192.168.101.144 memory avillable capacity: 7302952, less then 16G
原因分析：服务器内存容量不足
解决方案：这是容器化部署的前提，必须满足。请联系相关运维人员对服务器进行扩容。
connection refused
报错语句：ERROR: 2022/05/18 17:33:07 finedb connect error:dial tcp 192.168.1.24:3306: connect: connection refused
原因分析：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 文件对格式的要求非常高，出现该错误，大概率都是由于内容格式存在错误。
解决方案：根据报错提示中的 line 号修改配置文件格式。
can't use localhost
报错语句：ERROR: 2022/04/20 13:58:14 can't use localhost，127.0.0.1 etc as node.ip in cluster mode.. must ensure ensure IP connectivity of all nodes
报错原因：集群下不能使用 localhost 等回环地址作为 IP
解决方案：修改 IP 为其他节点都能访问的真实 IP
add user to docker group error
报错语句：add user to docker group error：sudo：1次错误密码尝试
解决方案：
1）确保finekey.yaml文件配置的ssh用户和运行finekey的用户保持一致
2）检查finekey.yaml文件中配置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.yaml文件配置的ssh用户和运行finekey的用户保持一致
2）检查finekey.yaml文件中配置ssh用户名密码是否正确
3）远程连接工具问题，关闭重启远程工具并再次尝试
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:
报错原因：
如果部署过程中，检测到挂载目录磁盘可用空间不足100G，会提示「The current path capacity check failed, Please re-enter the path」
默认的~/data目录不代表/data目录，而是对应用户主目录下的/data目录。例如使用root用户部署，则~/data代表的目录为/root/data
解决方案：
用户无需退出部署环节，手动修改yaml文件。可直接输入满足条件的目录，即可继续部署。
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 文件对格式的要求非常高，出现该错误，大概率都是由于内容格式存在错误。
请根据报错提示中的 line 号修改配置文件格式。
排查方向二：未放开注释
如报错行，为待部署组件的端口配置行，说明需要调整组件端口配置。
请确保components所在行的#注释已删除、请确保组件名称所在行的#注释已删除、请确保组件端口配置所在行的#已删除
Do not use system directories as dataroot
报错语句：
Do not use system directories as dataroot!
报错原因：
/、/usr、/root、/usr/local四个目录，是系统目录，
不可以直接使用这四个目录作为 finekey.yaml 文件中的 dataRootPath 配置项
解决方法：
请使用其他目录，或在这些目录中新建文件夹，作为运维平台的挂载目录
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
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
升级运维平台常见问题编辑
在线升级需要开放的外网地址
对于内网环境，如需在线升级FineOps运维平台，需要自行开通网络白名单。
详情请参见：确认镜像仓库支持连接帆软云端仓库
升级提示docker engine报错
问题描述：
运维平台升级过程中，提示docker engine相关报错
原因分析：
由于docker引擎、FineOps运维平台、项目的ops_agent组件存在对应关系。
如需手动升级运维平台，必须确保运维平台所在服务器、运维平台对接的项目所在服务器，均支持升级docker引擎。
如在执行finekey update过程中，检测到系统禁止升级docker引擎，就会出现该报错，中断升级。
解决方案：
1）依次分别登录运维平台所在服务器、运维平台对接的项目所在的每一台服务器
2）执行语句，升级docker引擎：./finekey engine --update
3）再次参考上文使用语句启动升级：./finekey update
注意事项：
在升级FineOps运维平台时，在哪一台服务器触发了docker引擎升级，就会重启该机器上的容器。
因此会影响终端用户使用运维平台和项目。请选择非工作时间进行升级，降低业务影响。