文档说明

本指南专为刚接触 Linux 和容器技术的小白用户设计，使用 CTyunOS（或 CentOS 系统）部署轻量级 Kubernetes（K3s）。只需按照步骤操作即可完成部署。

第一部分：环境准备

1.1 登录服务器

打开终端（命令行窗口），使用以下命令登录你的 CTyunOS 服务器。

1.2 切换到 root 用户（获取最高权限）

# 查看当前用户
whoami
​
# 如果显示不是 root，切换到 root 用户
sudo su -
​
# 输入密码（注意：输入时不会显示字符，正常输入即可）

1.3 更新系统软件包

# 更新软件包列表和已安装的软件包
yum update -y
​
# 安装一些常用工具（可选但推荐）
yum install -y vim wget curl net-tools

1.4 检查网络连接

# 测试网络是否通畅
ping -c 3 baidu.com
​
# 如果无法 ping 通，检查网络配置
ip addr show
​
# 查看网络连接状态
netstat -tulpn

第二部分：安装 K3s

2.1 一键安装 K3s（推荐方法）

使用国内镜像加速安装，避免网络问题：

# 使用国内镜像源安装 K3s
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh -

2.2 自定义安装方法（可选）

如果你需要更多控制选项，可以使用以下方法：

# 下载安装脚本
curl -o k3s-install.sh https://get.k3s.io
​
# 给脚本添加执行权限
chmod +x k3s-install.sh
​
# 安装 K3s（使用 Docker 作为容器引擎）
export INSTALL_K3S_EXEC="--docker"
./k3s-install.sh

第三部分：验证安装

3.1 检查 K3s 服务状态

# 检查 K3s 服务是否正常运行
systemctl status k3s
​
# 如果显示 active (running) 表示成功

3.2 查看 K3s 版本信息

# 查看 K3s 版本
k3s --version
​
# 查看 kubectl 版本（K3s 自带的 Kubernetes 命令行工具）
k3s kubectl version

3.3 查看集群状态

# 查看集群节点状态
kubectl get nodes
​
# 查看所有运行中的服务
kubectl get pods --all-namespaces
​
# 查看系统组件状态
kubectl get pods -n kube-system

3.4 预期输出示例

正常情况下的输出应该类似这样：

# kubectl get nodes 的输出
NAME        STATUS   ROLES                  AGE   VERSION
localhost   Ready    control-plane,master   5m    v1.27.4+k3s1
​
# kubectl get pods -n kube-system 的输出
NAME                                      READY   STATUS    RESTARTS   AGE
local-path-provisioner-5b5579c644-xxxxx   1/1     Running   0          5m
coredns-5c4f5c4f8b-xxxxx                  1/1     Running   0          5m
metrics-server-7c5f5b5b5b-xxxxx           1/1     Running   0          5m

第四部分：K3s 基本操作

4.1 K3s 服务管理命令

# 启动 K3s 服务
systemctl start k3s
​
# 停止 K3s 服务
systemctl stop k3s
​
# 重启 K3s 服务
systemctl restart k3s
​
# 查看 K3s 服务状态
systemctl status k3s
​
# 设置 K3s 开机自启
systemctl enable k3s
​
# 禁止 K3s 开机自启
systemctl disable k3s

4.2 查看日志信息

# 实时查看 K3s 日志
journalctl -u k3s -f
​
# 查看最近 100 行日志
journalctl -u k3s -n 100
​
# 查看从今天开始的日志
journalctl -u k3s --since today
​
# 查看错误日志
journalctl -u k3s -p err

4.3 配置 kubectl 命令别名

# 为 kubectl 设置别名（简化输入）
echo 'alias k="kubectl"' >> ~/.bashrc
echo 'alias k3s="k3s kubectl"' >> ~/.bashrc
​
# 使别名立即生效
source ~/.bashrc
​
# 现在可以使用 k 代替 kubectl
k get nodes

第五部分：安装 Docker（可选）

虽然 K3s 默认使用 containerd，但安装 Docker 可以方便学习和调试。

5.1 安装 Docker

# 1. 安装依赖包
yum install -y yum-utils device-mapper-persistent-data lvm2
​
# 2. 添加 Docker 仓库
yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
​
# 3. 安装 Docker 引擎
yum install -y docker-ce docker-ce-cli containerd.io
​
# 4. 启动 Docker 服务
systemctl start docker
​
# 5. 设置 Docker 开机自启
systemctl enable docker
​
# 6. 验证 Docker 安装
docker version
​
# 7. 运行测试容器
docker run hello-world

5.2 配置 Docker 镜像加速

# 创建 Docker 配置文件目录
mkdir -p /etc/docker
​
# 创建镜像加速配置文件
cat > /etc/docker/daemon.json << EOF
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://mirror.baidubce.com"
  ]
}
EOF
​
# 重启 Docker 使配置生效
systemctl restart docker

第六部分：部署第一个应用

6.1 部署 Nginx Web 服务器

# 1. 创建 Nginx 部署
kubectl create deployment nginx --image=nginx:alpine
​
# 2. 将服务暴露到集群外部
kubectl expose deployment nginx --port=80 --type=NodePort
​
# 3. 查看部署状态
kubectl get deployments
​
# 4. 查看服务状态
kubectl get services nginx
​
# 5. 查看 Pod 状态
kubectl get pods

6.2 访问部署的 Nginx

# 查看服务的 NodePort 端口
kubectl get svc nginx
​
# 输出示例：
# NAME    TYPE       CLUSTER-IP     EXTERNAL-IP   PORT(S)        AGE
# nginx   NodePort   10.43.xx.xx   <none>        80:3xxxx/TCP   2m
​
# 使用 curl 访问（将 3xxxx 替换为实际的端口号）
curl http://localhost:3xxxx
​
# 或者获取具体的端口号
NODE_PORT=$(kubectl get svc nginx -o jsonpath='{.spec.ports[0].nodePort}')
curl http://localhost:${NODE_PORT}

6.3 使用 YAML 文件部署应用

**创建文件 **myapp.yaml：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myweb
spec:
  replicas: 2
  selector:
    matchLabels:
      app: myweb
  template:
    metadata:
      labels:
        app: myweb
    spec:
      containers:
      - name: myweb
        image: nginx:alpine
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: myweb-service
spec:
  selector:
    app: myweb
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
      nodePort: 30080
  type: NodePort

应用配置：

# 1. 创建 YAML 文件
vim myapp.yaml
# 按 i 进入编辑模式，粘贴上面的内容，按 ESC，输入 :wq 保存退出
​
# 2. 部署应用
kubectl apply -f myapp.yaml
​
# 3. 查看部署状态
kubectl get deployments
kubectl get pods
kubectl get services
​
# 4. 访问应用
curl http://localhost:30080

第七部分：常见问题解决

7.1 安装时网络超时或失败

# 方法1：使用阿里云镜像
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
  INSTALL_K3S_MIRROR=cn \
  INSTALL_K3S_EXEC="--docker" \
  sh -
​
# 方法2：手动下载安装
# 首先下载脚本
wget https://rancher-mirror.rancher.cn/k3s/k3s-install.sh
# 然后执行
chmod +x k3s-install.sh
INSTALL_K3S_MIRROR=cn ./k3s-install.sh

7.2 kubectl 命令找不到或权限错误

# 方法1：复制配置文件到用户目录
mkdir -p ~/.kube
cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
chmod 600 ~/.kube/config
​
# 方法2：设置环境变量
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
​
# 方法3：使用 k3s 自带的 kubectl
k3s kubectl get nodes

7.3 端口被占用导致安装失败

# 查看端口占用情况
netstat -tulpn | grep :6443
​
# 如果 6443 端口被占用，指定其他端口安装
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--https-listen-port=8443" sh -

7.4 系统资源不足

# 查看系统资源使用情况
free -h    # 查看内存
df -h      # 查看磁盘
top        # 查看实时资源占用
​
# 最小化安装（禁用不需要的组件）
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--disable=traefik,servicelb,local-storage" sh -
​
# 或者只安装最核心功能
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--disable=traefik --disable=servicelb --disable=local-storage --disable=metrics-server" sh -

7.5 查看 K3s 相关进程

# 查看 K3s 相关进程
ps aux | grep k3s
​
# 查看容器运行时状态
k3s crictl ps
k3s crictl images

第八部分：卸载 K3s

如果需要重新安装或卸载 K3s，使用以下命令：

# 如果是 server 节点（主节点）
/usr/local/bin/k3s-uninstall.sh
​
# 如果是 agent 节点（工作节点）
/usr/local/bin/k3s-agent-uninstall.sh
​
# 清理残留文件和目录
rm -rf /etc/rancher
rm -rf /var/lib/rancher
rm -rf /var/lib/cni
​
# 清理网络配置
ip link delete cni0
ip link delete flannel.1

第九部分：学习资源

9.1 官方文档

• K3s 官方文档：https://docs.k3s.io
• Kubernetes 官方文档：https://kubernetes.io/zh-cn/docs/home/
• CTyunOS 文档：请访问天翼云官方网站

9.2 常用命令速查

# 查看集群信息
kubectl cluster-info
​
# 查看节点详细信息
kubectl describe nodes
​
# 查看 Pod 详细信息
kubectl describe pod <pod名称>
​
# 查看服务详细信息
kubectl describe service <服务名称>
​
# 查看部署历史
kubectl rollout history deployment/<部署名称>
​
# 查看容器日志
kubectl logs <pod名称>
​
# 进入容器内部
kubectl exec -it <pod名称> -- /bin/sh
​
# 删除资源
kubectl delete deployment <部署名称>
kubectl delete service <服务名称>
kubectl delete -f <文件名.yaml>

9.3 下一步学习建议

1. 学习 Kubernetes 基本概念：Pod、Deployment、Service、Namespace
2. 尝试部署多节点 K3s 集群
3. 学习使用 Helm 包管理器
4. 部署有状态应用（如数据库）
5. 配置持久化存储

第十部分：故障排查检查清单

遇到问题时，按照以下顺序检查：

1. 检查 K3s 服务状态：systemctl status k3s
2. 查看最近日志：journalctl -u k3s -n 50
3. 检查网络连接：ping -c 3 baidu.com
4. 检查端口占用：netstat -tulpn | grep -E '6443|10250'
5. 检查系统资源：free -h && df -h
6. 检查防火墙设置：systemctl status firewalld
7. 检查 SELinux 状态：getenforce

如果以上步骤无法解决问题，请将错误信息完整记录下来，在技术社区或搜索引擎中查找解决方案。