容器云服务搭建

环境：内网 Linux，无需 TLS / 域名，IP + 端口直接访问架构：3 台 Server 节点（嵌入式 etcd 高可用，容忍 1 台故障） + Longhorn 分布式存储
日期：2026-09-01

一、环境信息

项目	值
节点数量	3 台 Server（etcd 高可用，无需单独 Agent 节点）
第 1 台节点 IP	`192.168.132.210`（初始 Master）
OS	Debian 13 (trixie) / amd64
K3s 版本	v1.36.4+k3s1
Helm 版本	v4.2.4
存储方案	Longhorn v1.8.1（分布式块存储）
Kite 版本	v0.15.0
Kite 访问地址	http://192.168.132.210:31367

二、安装 K3s（第 1 台节点）

2.1 使用国内镜像源初始化集群

bash

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh \
  | INSTALL_K3S_MIRROR=cn sh -s - --cluster-init

参数	作用
`INSTALL_K3S_MIRROR=cn`	使用国内镜像源下载 K3s
`--cluster-init`	以 etcd 集群模式初始化，支持后续添加 Server 节点

2.2 验证安装

bash

kubectl get nodes

预期输出：

NAME        STATUS   ROLES                AGE   VERSION
aicode-pc   Ready    control-plane,etcd   5m    v1.36.4+k3s1

2.3 配置 kubectl（可选）

bash

mkdir -p ~/.kube
cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
chmod 600 ~/.kube/config

三、添加第 2、3 台 Server 节点

3.1 在第 1 台节点上获取 Token

bash

cat /var/lib/rancher/k3s/server/node-token

输出示例：

K106a79864267ace60b6fc1a895cdfcc11cf41074dd83789b4e90bf8cdc0ce2b014::server:7ef7a9e113dba09b5ae6422d2927c2c1

3.2 在第 2、3 台节点上分别执行

将 <token> 替换为上面获取的实际值：

bash

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh \
  | INSTALL_K3S_MIRROR=cn \
     K3S_URL=https://192.168.132.210:6443 \
     K3S_TOKEN=<token> \
     sh -s - server

两台都执行相同命令，注意末尾的 server 表示加入为 Server 节点。

3.3 验证集群

在任意节点上执行：

bash

kubectl get nodes -o wide

预期输出（3 个节点均为 control-plane,etcd）：

NAME           STATUS   ROLES                AGE   VERSION
node-1         Ready    control-plane,etcd   10m   v1.36.4+k3s1
node-2         Ready    control-plane,etcd   3m    v1.36.4+k3s1
node-3         Ready    control-plane,etcd   1m    v1.36.4+k3s1

3.4 etcd 容错说明

Server 数量	可容忍同时故障数	quorum
3	1	2/3

四、安装 Helm

bash

curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-4 | bash

五、安装 Longhorn（分布式存储）

Longhorn 是 K3s 官方推荐的分布式块存储方案，数据在多节点间复制，支持节点故障时自动迁移。

5.1 安装 open-iscsi 依赖

Longhorn 依赖 open-iscsi，每台节点都要执行：

bash

apt-get update
apt-get install -y open-iscsi
systemctl enable --now iscsid
ln -sf /usr/sbin/iscsiadm /usr/bin/iscsiadm

5.2 部署 Longhorn

bash

kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/v1.8.1/deploy/longhorn.yaml

5.3 设置 Longhorn 为默认 StorageClass

bash

kubectl patch storageclass local-path \
  -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"false"}}}'

5.4 验证安装

bash

kubectl get pods -n longhorn-system
kubectl get sc

预期输出（longhorn 为 (default)）：

NAME                 PROVISIONER             RECLAIMPOLICY   VOLUMEEXPANSION   AGE
local-path           rancher.io/local-path   Delete          false             10m
longhorn (default)   driver.longhorn.io      Delete          true              2m

5.5 Longhorn 说明

项目	说明
数据复制	2+ 节点时自动 2 副本，单节点时 degraded（正常）
UI 面板	`kubectl port-forward -n longhorn-system svc/longhorn-frontend 8080:80`
卷大小	按需分配，写多少占多少
节点扩展	新节点加入后 Longhorn 自动利用其磁盘

六、安装 Kite

参考文档：https://kite.zzde.me/zh/guide/installation.html

6.1 添加 Helm 仓库

bash

helm repo add kite https://kite-org.github.io/kite
helm repo update

6.2 安装 Kite

bash

helm install kite kite/kite \
  -n kite-system \
  --create-namespace \
  --set service.type=NodePort \
  --set service.port=8080 \
  --set db.type=sqlite \
  --set db.sqlite.persistence.pvc.enabled=true \
  --set db.sqlite.persistence.pvc.storageClass=longhorn \
  --set db.sqlite.persistence.pvc.size=5Gi \
  --set anonymousUserEnabled=true

6.3 等待 Pod 就绪

bash

kubectl wait --for=condition=ready pod \
  -l app.kubernetes.io/name=kite \
  -n kite-system \
  --timeout=120s

6.4 获取访问地址

bash

# 获取节点 IP
NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')

# 获取 Kite NodePort
NODE_PORT=$(kubectl get svc kite -n kite-system -o jsonpath='{.spec.ports[0].nodePort}')

# 输出访问地址
echo "http://${NODE_IP}:${NODE_PORT}"

预期输出：

http://192.168.132.210:31367

浏览器打开即可访问 Kite 管理界面。

七、存储知识：PVC、StorageClass 与 Longhorn

7.1 核心概念

概念	说明
PV (PersistentVolume)	集群中的存储资源，由管理员或自动创建
PVC (PersistentVolumeClaim)	Pod 对存储的请求，声明需要多大空间、什么访问模式
StorageClass	定义存储的"类型"，不同的 StorageClass 对接不同的后端存储

PVC 的 5Gi 不是预分配磁盘空间。 它只是一个上限值/配额，实际磁盘占用取决于写入多少数据。比如当前 kite.db 只有 212KB，磁盘只用了 212KB。

7.2 K3s 可用存储方案对比

方案	分布式	多节点共享	数据复制	适用场景	复杂度
local-path	否	否	无	测试、单节点	最简单
NFS	否	是	无	共享文件、多 Pod 读写	简单
Longhorn	是	是	2+ 副本	生产环境、K3s 生态	中等
Ceph/Rook	是	是	可配置	大规模、企业级	复杂

7.3 Longhorn 工作原理

┌─────────────────────────────────────────────────────────────┐
│                      Longhorn Volume                        │
│                    (例如 kite-storage)                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │  Replica 1   │    │  Replica 2   │    │  Replica 3   │  │
│  │  (Node 1)    │    │  (Node 2)    │    │  (Node 3)    │  │
│  │  真实数据块   │←──→│  真实数据块   │←──→│  真实数据块   │  │
│  └──────────────┘    └──────────────┘    └──────────────┘  │
│                                                             │
│  写入时同步到多个副本，读取从任一副本读取                         │
│  节点故障时，自动从其他副本恢复                                  │
└─────────────────────────────────────────────────────────────┘

关键特性：

按需分配：声明 5Gi 不会立即占用 5Gi 磁盘，写多少占多少
副本数可配置：默认 3 副本（需 3+ 节点），单节点时只有 1 副本（degraded）
自动故障转移：节点挂了，Pod 在其他节点重建，数据不丢
快照备份：支持卷快照和备份到 S3/NFS

7.4 本项目的存储配置

bash

# Kite 的 PVC 配置
db.type=sqlite                              # 使用 SQLite 数据库
db.sqlite.persistence.pvc.enabled=true      # 启用 PVC 持久化
db.sqlite.persistence.pvc.storageClass=longhorn  # 使用 Longhorn 存储
db.sqlite.persistence.pvc.size=5Gi          # 容量上限 5Gi（非预分配）

实际磁盘占用：

时间	kite.db 大小	说明
刚安装	212KB	空数据库 + 基础 schema
使用中	逐步增长	随着添加集群、部署应用而增长
上限	≤ 5Gi	超过后 PVC 不允许写入更多数据

八、常用命令速查

bash

# 查看节点
kubectl get nodes -o wide

# 查看所有 Pod
kubectl get pods -A

# 查看 Kite 状态
kubectl get pods,svc -n kite-system

# 查看 Kite 日志
kubectl logs -n kite-system -l app.kubernetes.io/name=kite -f

# 查看 Longhorn 状态
kubectl get pods,sc,volumes.longhorn.io -n longhorn-system

# 备份 etcd
k3s etcd-snapshot save --name pre-upgrade

# 卸载 Kite
helm uninstall kite -n kite-system

# 卸载 Longhorn
kubectl delete -f https://raw.githubusercontent.com/longhorn/longhorn/v1.8.1/deploy/longhorn.yaml

# 卸载 K3s
k3s-uninstall.sh

# 节点维护（标记不可调度 + 驱逐 Pod）
kubectl cordon <node-name>
kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data

九、架构示意

                    ┌─────────────────────────────┐
                    │       Kite Web 界面          │
                    │  http://192.168.132.210:31367│
                    └──────────────┬──────────────┘
                                   │
          ┌────────────────────────┼────────────────────────┐
          │                        │                        │
┌─────────▼─────────┐  ┌──────────▼──────────┐  ┌─────────▼─────────┐
│   Server 1 (初始)   │  │     Server 2        │  │     Server 3      │
│ 192.168.132.210    │  │  (后续加入)          │  │  (后续加入)        │
│ control-plane,etcd │  │  control-plane,etcd │  │  control-plane,etcd│
│ + Longhorn         │  │  + Longhorn         │  │  + Longhorn        │
└───────────────────┘  └─────────────────────┘  └───────────────────┘
          │                        │                        │
          └────────────────────────┴────────────────────────┘
              etcd 集群 + Longhorn 分布式存储（2+ 副本）

十、注意事项

防火墙：确保 3 台节点间端口 6443（API Server）、2379-2380（etcd）、8472/UDP（Flannel）、10250（Kubelet）、9500（Longhorn Manager）互通
Token 安全：集群 Token 拥有完全管理权限，请勿外泄
节点加入顺序：先在第 1 台初始化（--cluster-init），再逐台添加其余节点，不要同时执行
匿名用户：anonymousUserEnabled=true 仅限内网测试使用，生产环境请关闭
镜像拉取：Kite 镜像来自 ghcr.io，内网如无法访问可配置镜像仓库代理
Longhorn 单节点状态：只有 1 个节点时 Longhorn 卷显示 degraded（正常），加入第 2 个节点后会自动创建副本变为 healthy

容器云服务搭建 ​

一、环境信息 ​

二、安装 K3s（第 1 台节点） ​

2.1 使用国内镜像源初始化集群 ​

2.2 验证安装 ​

2.3 配置 kubectl（可选） ​

三、添加第 2、3 台 Server 节点 ​

3.1 在第 1 台节点上获取 Token ​

3.2 在第 2、3 台节点上分别执行 ​

3.3 验证集群 ​

3.4 etcd 容错说明 ​

四、安装 Helm ​

五、安装 Longhorn（分布式存储） ​

5.1 安装 open-iscsi 依赖 ​

5.2 部署 Longhorn ​

5.3 设置 Longhorn 为默认 StorageClass ​

5.4 验证安装 ​

5.5 Longhorn 说明 ​

六、安装 Kite ​

6.1 添加 Helm 仓库 ​

6.2 安装 Kite ​

6.3 等待 Pod 就绪 ​

6.4 获取访问地址 ​

七、存储知识：PVC、StorageClass 与 Longhorn ​

7.1 核心概念 ​

7.2 K3s 可用存储方案对比 ​

7.3 Longhorn 工作原理 ​

7.4 本项目的存储配置 ​

八、常用命令速查 ​

九、架构示意 ​

十、注意事项 ​

容器云服务搭建

一、环境信息

二、安装 K3s（第 1 台节点）

2.1 使用国内镜像源初始化集群

2.2 验证安装

2.3 配置 kubectl（可选）

三、添加第 2、3 台 Server 节点

3.1 在第 1 台节点上获取 Token

3.2 在第 2、3 台节点上分别执行

3.3 验证集群

3.4 etcd 容错说明

四、安装 Helm

五、安装 Longhorn（分布式存储）

5.1 安装 open-iscsi 依赖

5.2 部署 Longhorn

5.3 设置 Longhorn 为默认 StorageClass

5.4 验证安装

5.5 Longhorn 说明

六、安装 Kite

6.1 添加 Helm 仓库

6.2 安装 Kite

6.3 等待 Pod 就绪

6.4 获取访问地址

七、存储知识：PVC、StorageClass 与 Longhorn

7.1 核心概念

7.2 K3s 可用存储方案对比

7.3 Longhorn 工作原理

7.4 本项目的存储配置

八、常用命令速查

九、架构示意

十、注意事项