修复指南

本指南用于在运行 ONES 前，对 Linux 主机进行必要的系统级修复与配置调整，适用于 envcheck 检测未通过 时的快速修复，确保系统满足 ONES 的最低运行要求。根据19项巡检条目按序说明如下：

1、CPU Resources

更换符合要求的CPU。

2、Memory Size

更换符合要求的内存。

3、Disk Space

提供符合大小要求的存储空间。

4、I/O Performance（Random 16K）

更换满足性能要求的存储。 如果检测不通过、也可自行安装fio命令、执行随机读写测试，其中bs 配置为16k、size为8GB（比envcheck的size更大、测试更接近实际），测试结果发给ONES工程师进一步确认。如未达标，应更换为更高性能的磁盘。

apt install fio #ubuntu22上安装命令，其他系统请自行安装

# cd / 进入系统盘挂载目录测试
# cd /data 进入数据盘挂载目录测试
# cd /data/ones/ones-local-storage/tidb 进入索引盘挂载目录测试
# cd /nfstest 进入NFS临时挂载目录进行测试
fio --randrepeat=1 --ioengine=libaio --direct=1 --group_reporting --name=test --filename=random_read_write.fio --bs=16k --iodepth=1 --size=8GB --time_based --runtime=120 --ramp_time=10 --readwrite=randrw --rwmixread=75


# 上述命令的测试结果基本等同于envcheck工具测试的效果；如果希望验证高并发下的磁盘IO性能，可将iodepth调整为64
# 测试之后删除临时文件，避免占用磁盘空间
rm random_read_write.fio

5、Operating System

更换符合要求的操作系统，只支持Linux 4.5 以上内核的操作系统，原因是自 Kubernetes 1.29 起，tcp_keepalive_time、tcp_keepalive_intvl、tcp_keepalive_probes等参数需要内核 4.5+。

6、Data Disk Separation

数据盘/data需独立挂载，并修复/etc/fstab确保持久生效，相关原理及具体操作参考Linux磁盘挂载说明。

7、Kernel Version

更换符合要求的操作系统。

8、DNS Resolver

Ubuntu 22.04 默认可能使用 systemd-resolved 管理 DNS，此时 /etc/resolv.conf 通常为软链接，指向 /run/systemd/resolve/stub-resolv.conf，其中可能配置 127.0.0.53。

K3s 启动时会检查 /etc/resolv.conf 和 /run/systemd/resolve/resolv.conf，选择适合 Pod 使用的 DNS 配置文件。

如果两个文件都没有配置可用的上游 DNS（比如只有127.0.0.53），可能导致 K3s 安装后 CoreDNS 无法正常解析业务域名，因此需要在安装 ONES 之前进行检查。检查命令如下：

# 查看 DNS 配置文件
ls -l /etc/resolv.conf

# 查看两个文件中的 DNS 服务器
grep -E '^[[:space:]]*nameserver[[:space:]]+' \
  /etc/resolv.conf /run/systemd/resolve/resolv.conf 2>/dev/null

# 验证域名解析（内网环境替换为客户实际业务域名）
getent ahostsv4 www.baidu.com

检查标准：

（1）至少存在一个可供 K3s 使用的 DNS 配置文件，其中包含可达的上游 DNS 服务器。

（2）如果 /etc/resolv.conf 只有 127.0.0.53，但 /run/systemd/resolve/resolv.conf 配置了有效的非回环 DNS，则无需调整。

（3）如果两个文件都没有有效 DNS、比如只有127.0.0.53这个回环地址，或者域名解析失败，则需要在安装 ONES 之前调整。

（4）内网环境需确保能够解析 ONES 依赖的内部业务域名。

注意： 宿主机域名解析成功仅代表宿主机 DNS 基本正常，不完全等同于 K3s 安装后的 CoreDNS 一定正常。

8.1 Ubuntu22 DNS 配置调整（仅异常时执行）

优先建议客户修复现有 DNS 配置，例如通过 systemd-resolved、Netplan 或云平台网络配置设置正确的上游 DNS。

如果客户环境允许使用静态 DNS，且不依赖 systemd-resolved 提供的动态 DNS 管理功能，可以参考以下操作。

# 备份当前配置
cp -L /etc/resolv.conf /root/resolv.conf.bak

# 关闭 systemd-resolved
systemctl disable --now systemd-resolved

# 删除原有软链接或文件
rm -f /etc/resolv.conf

# 创建静态 DNS 配置文件
vi /etc/resolv.conf

# 示例配置如下（仅适用于允许访问公网 DNS 的环境）：
# 内网环境应替换为客户提供的 DNS 服务器地址，不应直接使用上述公网 DNS。

nameserver 223.5.5.5
nameserver 223.6.6.6
nameserver 114.114.114.114

完成后执行如下命令确认：

# 验证 DNS 配置
cat /etc/resolv.conf

# 验证实际域名解析
getent ahostsv4 www.baidu.com

注意：

（1）关闭 systemd-resolved 可能影响 DHCP、VPN、内网域名及按网卡分配的 DNS 规则。此操作仅作为备选修复方案，执行前需确认网络配置管理方式，并在变更后验证客户业务域名解析正常。

（2）如果客户没有可用DNS，但仅需要解析少量固定域名，可根据实际情况使用 Kubernetes hostAliases 配置作为补充方案，参考Pod内部指定域名对应IP临时处理。

8.2 hosts 中添加主机名，避免 sudo 报错

vi /etc/hosts

192.168.1.100 k8s-node-01

9、Network Ports

9.1 ONES 端口使用列表

以下列表中的端⼝全部释放，避免部署产生端口占用造成端口冲突

端口号分类	端口号	功能
kubernetes/k3s	TCP 2379-2381	Etcd server client API
kubernetes/k3s	TCP 10250-10252、10256	Kubelet API\kube-scheduler\kube-controller-manager
kubernetes/k3s	TCP 10010	Containerd
kubernetes/k3s	TCP 5000	Docker Registry(镜像仓)
kubernetes/k3s	TCP/UDP 30000-32767	service-node-port范围(可选)
kubernetes/k3s/Flannel VXLAN	UDP 8472/8285	Flannel VXLAN
kubernetes/k3s	TCP 6443-6444/8443	K3s supervisor Kubernetes API Server
kubernetes/k3s	TCP 10248	Kubelet Healthz
kubernetes/k3s	TCP 10249	Kube-proxy Metrics
ONES业务端口	TCP 30011	ONES node-port 默认监听端口(可选)
ONES业务端口	TCP 80、443	ONES ingress-nginx 默认监听端口(可选)
ONES工具端口	TCP 5001	Jira迁移工具web服务(可选)
ONES工具端口	TCP 5601	日志查询 kibana默认端口(可选)
ONES工具端口	TCP 31380	监控面板 Grafana默认端口(可选)
ONES工具端口	TCP 30012	ONES运维工具箱端口(可选)
ONES工具端口	TCP 30013	ONES管理后台端口(可选)

9.2 端⼝释放步骤

端⼝释放前需要与客户确认是否可以kill进程。如果有进程⾃动拉起监听，需要先停⽌⾃动拉起服务，避免释放放反复重启

# 尝试通过kill 命令强制停止进程，请在合理场景下使用，确认冲突端口是否可以中断
# 如有守护服务：systemd supervisord需要通过守护服务停止
[root@ONES ~]#netstat -antpl |grep -w 8081 #检测端口使用者
[root@ONES ~]#kill -9 <pid>                #释放端口
[root@ONES ~]#netstat -antpl |grep -w 8081 #正常情况应该是没有回显

10、Swap Configuration

[root@ones ~]#swapoff -a # 关闭所有交换分区
[root@ones ~]#vi /etc/fstab # 永久关闭交换分区
#/dev/mapper/centos-swap swap                    swap    defaults        0 0
# 将其注释掉或删除，保存文件并退出。

# 重新启动服务器以应用更改。
[root@ones ~]#reboot

11、SELinux Policy

11.1 检查⽅法

sestatus -v
SELinux status: disabled

# 如果回显结果包含参数且值⼀致、或者提示无此命令，请跳过；如果提示 enables，请参考下文操作。

11.2 修复步骤

vi /etc/selinux/config

# 修改如下配置为disabled
SELINUX=disabled

# 重启生效
reboot

# 执⾏ sestatus -v 命令再次检查修改是否成功
sestatus -v

12、File Permissions (umask)

12.1 检查⽅法/命令

[root@ones ~]# umask
0022

12.2 修复步骤

编辑/etc/bashrc、/etc/profile⽂件，修改umask

[root@ones ~]# vi /etc/bashrc
[root@ones ~]# vi /etc/profile

####两个⽂件的内容是⼀样的
###搜索umask，找到如下代码，不算第⼀位的特殊权限
if [ $UID -gt 199 ] && [ "`id -gn`" = "`id -un`" ]; then umask 002 / /表示uid⼤于等于199的默认umask值，表示普通⽤户else
 umask 022 / /表示uid⼩于199的默认umask值，表示root
fi
####修改后需要重新读取⼀下/etc/bashrc或/etc/profile
[root@ones ~]# source /etc/profile
[root@ones ~]# source /etc/bashrc

13、Transparent Huge Pages

echo never > /sys/kernel/mm/transparent_hugepage/enabled
echo never > /sys/kernel/mm/transparent_hugepage/defrag

14、Firewall Services

systemctl stop ufw || systemctl stop firewalld
systemctl disable ufw || systemctl disable firewalld

注意：如果防火墙开启了，在关闭防火墙之后，必须参考第15条清理iptables规则

15、Firewall iptables Rules

iptables -F
iptables -X

iptables -t nat -F
iptables -t nat -X

iptables -t mangle -F
iptables -t mangle -X

iptables -t raw -F
iptables -t raw -X

nft flush ruleset

16、System Parameters (sysctl)

不合适的内核参数，可能导致请求偶发延时、端口监听失败、暴露端口失败、系统异常等情况。

结合ONES业务特点，推荐如下内核参数，需在安装 ONES 之前配置完成。

vi /etc/sysctl.conf

vm.swappiness=0
kernel.sysrq=1

net.ipv4.neigh.default.gc_stale_time=120

net.ipv4.conf.all.rp_filter=0
net.ipv4.conf.default.rp_filter=0
net.ipv4.conf.default.arp_announce=2
net.ipv4.conf.lo.arp_announce=2
net.ipv4.conf.all.arp_announce=2

net.ipv4.tcp_max_tw_buckets=5000
net.ipv4.tcp_syncookies=1
net.ipv4.tcp_max_syn_backlog=1024
net.ipv4.tcp_synack_retries=2
net.ipv4.tcp_slow_start_after_idle=0

net.ipv4.ip_forward=1
net.ipv4.tcp_keepalive_time=600
net.ipv4.tcp_keepalive_intvl=60
net.ipv4.tcp_keepalive_probes=20
net.ipv4.ip_local_reserved_ports=30000-32767
net.bridge.bridge-nf-call-iptables=1
net.bridge.bridge-nf-call-arptables=1
net.bridge.bridge-nf-call-ip6tables=1

fs.inotify.max_user_watches=10485760
fs.inotify.max_user_instances=8192

#配置生效
sudo sysctl -p
reboot

17、File Limits

vi /etc/security/limits.conf

root soft nofile 1000000
root hard nofile 1000000
* soft nofile 1000000
* hard nofile 1000000

18、Graphical Interface

ONES服务的运行，不依赖于操作系统的图形化界面，且图形化界面消耗系统性能、安全隐患较多。

部署ONES系统时，推荐开启默认的命令行界面；如果开启了图形化界面，需在安装 ONES 之前关闭图形化。

下文以Ubuntu22.04为例，提供关闭图形化的方法供参考。

# 设置默认启动目标为多用户模式（命令行）
systemctl set-default multi-user.target

# 立即停止当前图形界面（无需重启）
systemctl isolate multi-user.target


# 停用并禁用 GDM3（GNOME Display Manager）
systemctl stop gdm3
systemctl disable gdm3

# 可选：如果使用 lightdm（检查当前显示管理器）
cat /etc/X11/default-display-manager

# 若输出为 /usr/sbin/lightdm，则禁用：
systemctl stop lightdm
systemctl disable lightdm

19、Time Synchronization

在安装 ONES 之前，需检查服务器的时间与时区是否正确，或者参考该文档部署时间同步服务。本文使用 chrony 作为时间同步工具。

其中，集群环境的各个节点间可能会因为时间漂移等原因而时间不同步，导致集群异常；因此必须给集群内节点配置时间同步服务以自动对齐时间。对于离线集群，如果客户环境有ntp服务基础设施，可直接替换ntp服务器列表；如果没有，可将集群内的某个节点作为ntp服务器，其他节点对齐此节点的时间。

19.1 安装 chrony

yum install -y chrony || apt install -y chrony

19.2 备份旧配置文件

conf=/etc/chrony.conf
# 如果发现 /etc/chrony.conf 不存在，可换成：
# conf=/etc/chrony/chrony.conf
cp $conf ${conf}.bk.$(date +'%s')

19.3 替换默认配置

对于在线环境，直接替换配置即可。如果需要使用其他ntp服务器，则自行修改。

#  修改服务器配置⽂件
cat > $conf <<_EOF
server ntp1.aliyun.com iburst
server ntp2.aliyun.com iburst
server cn.pool.ntp.org iburst
server 210.72.145.44 iburst
server s1a.time.edu.cn iburst

driftfile /var/lib/chrony/drift
makestep 1.0 3
rtcsync
local stratum 10
logdir /var/log/chrony
_EOF

19.4 启动服务

# 启动chronyd
systemctl restart chronyd
systemctl enable chronyd

# 查看时间同步状态
timedatectl status
# 开启网络时间同步
timedatectl set-ntp true

# 确认ntp服务器状态
chronyc sources -v

19.5 验证⽅法

[root@ones ~]#date
Mon Jan 22 11:28:30 CST 2024 #时间必须与当地时区保持一致

19.6 服务器时区修复

# 查看时区,确认是否修改
timedatectl status

# 执行以下命令，查看时区列表。
ls /usr/share/zoneinfo/

# 执行以下命令，可以在时区列表中查看到Hong_Kong Shanghai时区。
ls /usr/share/zoneinfo/Asia

# 以修改Asia Shanghai时区为例
ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime

# 或者执行 timedatectl set-timezone Asia/Shanghai


# 更新硬件时钟（RTC）
hwclock -w

# 查看时区
timedatectl status