MoreRSS

site iconLixueduan | 李学端修改

博客 编程
博客名：指月小筑。专注云原生，Go，坚持分享最佳实践、经验干货。
RSS: https://www.lixueduan.com/index.xml
请复制 RSS 到你的阅读器，或快速订阅到 :

Inoreader Feedly Follow Feedbin Local Reader

Lixueduan | 李学端的 RSS 预览

LiteLLM：打造统一 AI 网关

2026-04-08 04:00:00

litellm-ai-gateway.png

为什么需要 LiteLLM？

当你在使用多个 AI 模型时，会遇到这些问题：

  • 每个 Provider 的 API 格式不同，需要维护多套代码
  • 无法统一监控所有模型的调用情况和成本
  • 切换模型需要修改业务代码

LiteLLM 通过统一的 OpenAI 兼容接口解决了这些问题，让你只需修改 model 参数就能切换模型。

核心功能：

  • 统一接口：一套 API 调用 OpenAI、Azure、Anthropic、Google 等多家模型
  • 成本追踪：实时监控各模型的使用量和成本
  • 负载均衡：自动在多个模型间分配请求
  • 速率限制：防止 API 滥用和成本失控

LiteLLM 作为统一网关，接收所有客户端请求，然后根据 model 参数自动路由到对应的后端模型服务。无论是本地部署的 vLLM，还是云端 API（OpenAI、Claude 等），都可以通过同一套接口调用。

本文将介绍如何在 Kubernetes 环境中部署 LiteLLM，并配置 PostgreSQL 作为数据库。

部署完成后，你可以像这样统一调用不同的模型：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# 请求 GLM-5 模型
curl -X POST http://example.com:8080/v1/chat/completions \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer xxx" \
 -d '{
 "model": "glm5",
 "messages": [{"role": "user", "content": "hello"}],
 "temperature": 0.1,
 "max_tokens": 100
 }'

# 请求 Qwen3.5 模型
curl -X POST http://example.com:8080/v1/chat/completions \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer xxx" \
 -d '{
 "model": "qwen3.5",
 "messages": [{"role": "user", "content": "hello"}],
 "temperature": 0.1,
 "max_tokens": 100
 }'

0. 安全警告：供应链投毒事件

⚠️ 重要安全提醒

ps：主要影响 PyPI 包，如果是 Docker Image 则不受影响。

如果你的环境中有 LiteLLM，请立即检查版本：

1

pip show litellm
  • 1.82.7 / 1.82.8 存在安全问题，可能导致凭证泄露

如果你不幸安装了 1.82.7 或 1.82.8，请假设所有凭证已泄露，立即：

  1. 切换到安全版本
  2. 轮换所有相关 API 密钥和凭证

详细信息请参考官方安全公告：LiteLLM Security Update - March 2026 Github Issue： https://github.com/BerriAI/litellm/issues/24518

1. 部署 PostgreSQL

1.1 部署 LocalPathStorage

PostgreSQL 需要 StorageClass，使用 LocalPathStorage：

1

kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.35/deploy/local-path-storage.yaml

查看部署状态：

1
2
3
4
5
6
7

$ kubectl -n local-path-storage get po
NAME READY STATUS RESTARTS AGE
local-path-provisioner-567b5f79b9-j2tcw 1/1 Running 0 27m

$ kubectl get sc
NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANSION AGE
local-path rancher.io/local-path Delete WaitForFirstConsumer false

1.2 部署 PostgreSQL

使用 Bitnami PostgreSQL Helm Chart 部署：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

REGISTRY_NAME=registry-1.docker.io
REPOSITORY_NAME=bitnamicharts
storageClass="local-path"
# user 为 postgres
adminPassword="Thinkbig1"

helm install pgsql oci://$REGISTRY_NAME/$REPOSITORY_NAME/postgresql \
 --set global.storageClass=$storageClass \
 --set global.postgresql.auth.postgresPassword=$adminPassword \
 --set global.postgresql.auth.database=litellm \
 --namespace litellm --create-namespace

查看部署状态：

1
2
3

$ kubectl -n litellm get po
NAME READY STATUS RESTARTS AGE
pgsql-postgresql-0 1/1 Running 0 2m57s

OK，准备工作完成，接下来可以开始部署 LiteLLM 了。

2. 部署 LiteLLM

2.1 配置文件

官方文档：入门指南 - 端到端教程 | liteLLM中文文档

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
 name: litellm-config
 namespace: litellm
data:
 config.yaml: |
 model_list:
 # GLM-5 模型（本地 vLLM 部署）
 - model_name: glm5
 litellm_params:
 model: openai/glm5
 api_base: http://1.1.1.1:8000/v1
 api_key: "xxx"

 # Qwen3.5 模型（本地 vLLM 部署）
 - model_name: qwen3.5
 litellm_params:
 model: openai/qwen3.5
 api_base: http://2.2.2.2:8000/v1
 api_key: "xxx"

 general_settings:
 master_key: "sk-xxx"
 database_url: "postgresql://postgres:Thinkbig1@pgsql-postgresql:5432/litellm"
 store_model_in_db: true

2.2 Deployment 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

apiVersion: apps/v1
kind: Deployment
metadata:
 name: litellm-proxy
 namespace: litellm
spec:
 replicas: 1
 selector:
 matchLabels:
 app: litellm
 template:
 metadata:
 labels:
 app: litellm
 spec:
 containers:
 - name: litellm-container
 image: ghcr.io/berriai/litellm:v1.82.3-stable
 imagePullPolicy: Always
 args:
 - "--config"
 - "/app/config.yaml"
 - "--port"
 - "4000"
 volumeMounts:
 - name: config-volume
 mountPath: /app/config.yaml
 subPath: config.yaml
 livenessProbe:
 httpGet:
 path: /health/liveliness
 port: 4000
 initialDelaySeconds: 120
 periodSeconds: 15
 successThreshold: 1
 failureThreshold: 3
 timeoutSeconds: 10
 readinessProbe:
 httpGet:
 path: /health/readiness
 port: 4000
 initialDelaySeconds: 120
 periodSeconds: 15
 successThreshold: 1
 failureThreshold: 3
 timeoutSeconds: 10
 volumes:
 - name: config-volume
 configMap:
 name: litellm-config
---
apiVersion: v1
kind: Service
metadata:
 name: litellm
 namespace: litellm
spec:
 selector:
 app: litellm
 ports:
 - port: 4000
 targetPort: 4000
 type: ClusterIP

查看 Pod 状态：

1
2
3
4

kubectl -n litellm get po
# NAME READY STATUS RESTARTS AGE
# litellm-proxy-744c98f4f4-2b6ll 1/1 Running 0 6m15s
# pgsql-postgresql-0 1/1 Running 0 63m

3. 验证

3.1 查看模型列表

LiteLLM 对外提供 OpenAI API 格式的端点，会根据 model 自动路由到不同的后端 Provider 上：

1
2

curl http://10.104.161.89:4000/v1/models \
 -H "Authorization: Bearer sk-xxx"

3.2 请求具体模型 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# 请求 glm5
curl http://3.3.3.3:4000/v1/chat/completions \
 -H "Authorization: Bearer sk-xxx" \
 -H "Content-Type: application/json" \
 -d '{
 "model": "glm5",
 "messages": [{"role": "user", "content": "你好，请介绍一下你自己"}]
 }'

# 请求 qwen3.5
curl http://3.3.3.3:4000/v1/chat/completions \
 -H "Authorization: Bearer sk-xxx" \
 -H "Content-Type: application/json" \
 -d '{
 "model": "qwen3.5",
 "messages": [{"role": "user", "content": "你好，请介绍一下你自己"}]
 }'

3.3 访问 UI

服务启动后，访问 4000 端口，进入 LiteLLM UI 界面：

1

http://3.3.3.3:4000/ui

账号 admin，密码为配置文件中指定的 MASTER_KEY：

litellm-login.png

登录后，跳转到界面上 Usage 页面可以看到不同模型的具体的使用情况：

litellm-usage.png

以及具体请求：

litellm-logs.png

4. 小结

本文详细介绍了 LiteLLM AI Gateway 的 Kubernetes 部署：

  • 供应链投毒事件：注意版本安全，避免使用存在问题的版本
  • 完整部署：从 LocalPathStorage 到 PostgreSQL 再到 LiteLLM 的完整流程
  • 统一管理：通过 LiteLLM 统一管理本地 vLLM 部署的多个模型

LiteLLM 的核心价值：

功能 说明
一行代码切换模型 只需修改 model 参数，无需改业务代码
可视化监控 Web UI 实时查看调用次数、Token 消耗、成本统计
多模型负载均衡 自动在多个模型实例间分配请求
OpenAI 兼容 无缝对接现有使用 OpenAI API 的应用

如果你已经在使用 vLLM 部署本地模型，可以参考我的其他文章：

Qwen3.5 选型 + vLLM 部署实战：从 0.8B 到 397B，哪款最适合你？

2026-03-31 04:00:00

deploy-qwen3.5-by-vllm.jpeg

Qwen3.5 是阿里云最新开源的大语言模型系列，提供了从 0.8B 到 397B 的多种规格，在推理能力和效率之间取得了良好平衡。

面对如此丰富的模型规格，该如何选择？本文将首先分析各规格模型的特点和适用场景，帮助你找到最适合的那一款，然后介绍如何使用 vLLM 在 Kubernetes 环境中部署 Qwen3.5 模型。

根据各大榜单排名以及实测表现，Qwen3.5 系列在性能和质量的权衡上表现出色。

qwen35-rank.png

1. 测试环境

本文所有测试均在以下环境完成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

+-----------------------------------------------------------------------------------------+
| GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |
|=========================================+========================+======================|
| 0 NVIDIA GB200 On | 00000008:01:00.0 Off | 0 |
| N/A 42C P0 395W / 1200W | 175750MiB / 189471MiB | 0% Default |
+-----------------------------------------+------------------------+----------------------+
| 1 NVIDIA GB200 On | 00000009:01:00.0 Off | 0 |
| N/A 42C P0 369W / 1200W | 175366MiB / 189471MiB | 0% Default |
+-----------------------------------------+------------------------+----------------------+
| 2 NVIDIA GB200 On | 00000018:01:00.0 Off | 0 |
| N/A 41C P0 354W / 1200W | 175366MiB / 189471MiB | 0% Default |
+-----------------------------------------+------------------------+----------------------+
| 3 NVIDIA GB200 On | 00000019:01:00.0 Off | 0 |
| N/A 42C P0 375W / 1200W | 179133MiB / 189471MiB | 0% Default |
+-----------------------------------------+------------------------+----------------------+

2. 模型选择

Qwen3.5 已形成从 0.8B 到 397B 的完整开源矩阵，分为三大梯队：

系列 模型 特点
轻量稠密系列 0.8B / 2B / 4B / 9B / 27B 全参数激活，部署简单，适合个人/边缘场景
中型 MoE 系列 35B-A3B / 122B-A10B 激活参数小，速度快成本低，适合企业级服务
旗舰 MoE 系列 397B-A17B 开源旗舰，全场景最强，对标闭源第一梯队

所有模型均支持视觉-语言多模态输入，原生上下文长度 256K tokens，最高可扩展至 1M tokens。

根据官方测评数据，比较推荐下面 4 个规格：

模型 激活参数 综合能力 代码能力 Agent 能力 中文能力
Qwen3.5-27B 27B 88.5 HumanEval 89.1 BFC-Lv4 48.5% 90.5
Qwen3.5-35B-A3B 3B 89.7 HumanEval 87.9 BFC-Lv4 52.3% -
Qwen3.5-122B-A10B 10B 90.8 HumanEval 88.7 BFC-Lv4 50.7% 91.7
Qwen3.5-397B-A17B 17B 91.5 HumanEval 89.3 BFC-Lv4 49.8% 92.3

选型建议：

  • Qwen3.5-27B：稠密架构最强，代码能力出色（HumanEval≈89.1，稠密代码第一），部署简单，适合代码/工程场景
  • Qwen3.5-35B-A3B：Agent/深度推理最强（BFC-Lv4≈52.3%，全系列最高），激活仅 3B，性价比极高
  • Qwen3.5-122B-A10B：接近旗舰性能，知识密集/多模态/视频场景优选，成本比旗舰低 40%
  • Qwen3.5-397B-A17B：开源旗舰，综合能力开源第一（对标 GPT-5.2），中文能力最强（92.3），支持 1M 上下文无损，适合企业级基座

3. 模型下载

3.1 安装 HuggingFace CLI

首先安装 HuggingFace CLI 工具用于下载模型：

1

curl -LsSf https://hf.co/cli/install.sh | bash

常见问题：安装失败

如果遇到 No module named pip 错误，通常是因为虚拟环境损坏：

1
2
3
4
5

# 删除损坏的虚拟环境
rm -rf /root/.hf-cli/venv

# 重新安装
curl -LsSf https://hf.co/cli/install.sh | bash

3.2 下载模型

Qwen3.5 提供多种规格和精度版本，根据你的硬件配置选择：

1
2

# INT4 版本（推荐：显存占用低）
hf download Qwen/Qwen3.5-397B-A17B-GPTQ-Int4 --local-dir /raid/lixd/models/Qwen/Qwen3.5-397B-A17B-GPTQ-Int4

4. Kubernetes 部署

官方文档：https://docs.vllm.ai/projects/recipes/en/latest/Qwen/Qwen3.5.html

以下以 Qwen3.5-397B-A17B-GPTQ-Int4 为例，展示如何在 Kubernetes 中部署：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

# qwen35-397b-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
 name: vllm-qwen35-397b
 namespace: default
spec:
 replicas: 1
 selector:
 matchLabels:
 app: vllm-qwen35-397b
 template:
 metadata:
 labels:
 app: vllm-qwen35-397b
 spec:
 nodeSelector:
 kubernetes.io/hostname: gb200-pod2-f06-node05
 containers:
 - name: vllm-server
 image: vllm/vllm-openai:cu130-nightly
 command: ["/bin/bash"]
 args:
 - "-c"
 - |
 vllm serve /Qwen3.5-397B-A17B-GPTQ-Int4 \
 --served-model-name qwen3.5 \
 --port 8000 \
 --tensor-parallel-size 4 \
 --gpu-memory-utilization 0.85 \
 --reasoning-parser qwen3 \
 --enable-auto-tool-choice \
 --max-model-len 262144 \
 --tool-call-parser qwen3_coder \
 --enable-prefix-caching \
 --quantization moe_wna16 \
 --host 0.0.0.0 \
 --api-key "your-api-key"
 resources:
 limits:
 nvidia.com/gpu: 4
 memory: "400Gi"
 cpu: "32"
 requests:
 nvidia.com/gpu: 4
 memory: "200Gi"
 cpu: "16"
 ports:
 - containerPort: 8000
 name: http
 volumeMounts:
 - name: model-storage
 mountPath: /Qwen3.5-397B-A17B-GPTQ-Int4
 readOnly: true
 - name: shm
 mountPath: /dev/shm
 volumes:
 - name: model-storage
 hostPath:
 path: /raid/lixd/models/Qwen3.5-397B-A17B-GPTQ-Int4
 type: Directory
 - name: shm
 emptyDir:
 medium: Memory
 sizeLimit: 64Gi
---
apiVersion: v1
kind: Service
metadata:
 name: vllm-qwen35-397b-service
spec:
 selector:
 app: vllm-qwen35-397b
 ports:
 - port: 8000
 targetPort: 8000
 type: ClusterIP

关键参数说明：

参数 说明
--tensor-parallel-size 张量并行数，通常等于 GPU 数量
--reasoning-parser qwen3 启用 Qwen3 推理能力
--tool-call-parser qwen3_coder 使用 Qwen3 工具调用解析器
--enable-auto-tool-choice 启用自动工具选择
--quantization moe_wna16 MoE 模型量化方式
--max-model-len 262144 最大上下文长度
--enable-prefix-caching 启用前缀缓存加速

5. 服务验证

5.1 基础验证 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# 查看可用模型列表
curl http://localhost:8000/v1/models \
 -H "Authorization: Bearer your-api-key"

# 基础对话测试
curl http://localhost:8000/v1/chat/completions \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer your-api-key" \
 -d '{
 "model": "qwen3.5",
 "messages": [
 {"role": "user", "content": "你好，请介绍一下你自己"}
 ],
 "max_tokens": 100,
 "temperature": 0.7
 }'

5.2 思考模式控制

Qwen3.5 支持开启/关闭思考模式：

开启思考模式（默认）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

curl http://localhost:8000/v1/chat/completions \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer your-api-key" \
 -d '{
 "model": "qwen3.5",
 "messages": [
 {"role": "system", "content": "You are a helpful assistant."},
 {"role": "user", "content": "Summarize Qwen3.5 in one sentence."}
 ],
 "temperature": 1,
 "max_tokens": 4096
 }'

关闭思考模式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

curl http://localhost:8000/v1/chat/completions \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer your-api-key" \
 -d '{
 "model": "qwen3.5",
 "messages": [
 {"role": "system", "content": "You are a helpful assistant."},
 {"role": "user", "content": "Summarize Qwen3.5 in one sentence."}
 ],
 "temperature": 1,
 "max_tokens": 4096,
 "chat_template_kwargs": {"enable_thinking": false}
 }'

6. 性能基准测试

6.1 测试方法

使用 vLLM 内置的 benchmark 工具进行测试：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

vllm bench serve \
 --model /Qwen3.5-397B-A17B-GPTQ-Int4 \
 --served_model_name qwen3.5 \
 --dataset-name random \
 --random-input 8000 \
 --random-output 1024 \
 --request-rate 10 \
 --num-prompts 32 \
 --trust-remote-code \
 --ignore-eos

6.2 INT4 版本测试结果 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

============ Serving Benchmark Result ============
Successful requests: 32
Failed requests: 0
Request rate configured (RPS): 10.00
Benchmark duration (s): 32.58
Total input tokens: 256000
Total generated tokens: 32768
Request throughput (req/s): 0.98
Output token throughput (tok/s): 1005.85
Peak output token throughput (tok/s): 1152.00
Peak concurrent requests: 32.00
Total token throughput (tok/s): 8864.01
---------------Time to First Token----------------
Mean TTFT (ms): 308.19
Median TTFT (ms): 287.37
P99 TTFT (ms): 494.26
-----Time per Output Token (excl. 1st token)------
Mean TPOT (ms): 29.54
Median TPOT (ms): 29.62
P99 TPOT (ms): 30.58
---------------Inter-token Latency----------------
Mean ITL (ms): 29.54
Median ITL (ms): 28.52
P99 ITL (ms): 30.89
==================================================

关键指标解读：

指标 含义 测试结果
TTFT Time To First Token，首 token 延迟 平均 308ms
TPOT Time Per Output Token，每个 token 生成时间 平均 29.5ms
吞吐量 Output token throughput 1005 tok/s

7. 小结

本文详细介绍了使用 vLLM 部署 Qwen3.5 模型的完整流程：

  • 模型选择：根据需求，推荐选择 27B、35B-A3B、397B-A17B 几种规格
  • Kubernetes 部署：k8s 中通过 Deployment 配置，支持多 GPU 张量并行
  • 性能表现：INT4 版本在 GB200*4 环境下达到 1005 tok/s 的吞吐量

如果你想在 Claude Code 中使用本地部署的模型，可以参考我的另一篇文章《Claude Code 也能跑本地模型？CCR 多模型智能路由》，了解如何通过 Claude Code Router 实现对接。

另外，如果你对 GLM-5 模型的部署感兴趣，也可以参考《vLLM + GLM-5：打造高性能本地大模型推理服务》。

vLLM 部署 GLM-5 实践指南

2026-03-26 04:00:00

deploy-glm5-by-vllm.jpeg

GLM-5 是智谱 AI 最新发布的大语言模型，具备强大的推理能力和工具调用能力。本文将详细介绍如何使用 vLLM 框架在生产环境中部署 GLM-5 模型。

根据各大榜单排名以及实测表现，GLM-5 在多项评测中表现出色，是当前开源模型中的佼佼者。

glm5-rank.png

本文涵盖以下内容：

  • 模型下载：FP8 和 INT4 两种量化版本
  • 镜像构建：构建支持 GLM-5 的 vLLM 镜像
  • Docker 部署：INT4 版本快速部署
  • 性能测试：INT4 版本基准测试

0.测试环境

本文所有测试均在以下环境完成：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

+-----------------------------------------------------------------------------------------+
| GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |
|=========================================+========================+======================|
| 0 NVIDIA GB200 On | 00000008:01:00.0 Off | 0 |
| N/A 42C P0 395W / 1200W | 175750MiB / 189471MiB | 0% Default |
+-----------------------------------------+------------------------+----------------------+
| 1 NVIDIA GB200 On | 00000009:01:00.0 Off | 0 |
| N/A 42C P0 369W / 1200W | 175366MiB / 189471MiB | 0% Default |
+-----------------------------------------+------------------------+----------------------+
| 2 NVIDIA GB200 On | 00000018:01:00.0 Off | 0 |
| N/A 41C P0 354W / 1200W | 175366MiB / 189471MiB | 0% Default |
+-----------------------------------------+------------------------+----------------------+
| 3 NVIDIA GB200 On | 00000019:01:00.0 Off | 0 |
| N/A 42C P0 375W / 1200W | 179133MiB / 189471MiB | 0% Default |
+-----------------------------------------+------------------------+----------------------+

1. 模型下载

1.1 安装 HuggingFace CLI

首先安装 HuggingFace CLI 工具用于下载模型：

1

curl -LsSf https://hf.co/cli/install.sh | bash

常见问题：安装失败

如果遇到 No module named pip 错误，通常是因为虚拟环境损坏：

1
2
3
4
5

# 删除损坏的虚拟环境
rm -rf /root/.hf-cli/venv

# 重新安装
curl -LsSf https://hf.co/cli/install.sh | bash

1.2 下载模型

GLM-5 提供了多种精度版本，根据你的硬件配置选择：

1
2
3
4
5

# FP8 版本 - 推荐 H200*8 配置
hf download zai-org/GLM-5-FP8 --local-dir /raid/lixd/models/glm5-fp8

# INT4 量化版本 - 推荐 A100/H100*4 配置
hf download Intel/GLM-5-int4-mixed-AutoRound --local-dir /raid/lixd/models/glm5-int4-mixed-autoround

2. vLLM 部署

官方文档：https://github.com/vllm-project/recipes/blob/main/GLM/GLM5.md

2.1 构建自定义镜像

由于 GLM-5 需要最新版 transformers 支持，官方镜像暂未包含，需要构建自定义镜像。

创建 Dockerfile：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

FROM vllm/vllm-openai:v0.17.1-cu130

# 安装 git 用于从源码安装 transformers
RUN apt-get update && apt-get install -y git && \
 rm -rf /var/lib/apt/lists/*

# 安装最新版 transformers（GLM-5 需要）
RUN pip install --no-cache-dir git+https://github.com/huggingface/transformers.git

WORKDIR /app

ENTRYPOINT ["vllm"]

构建镜像：

1

docker build -t vllm/vllm-openai:glm5 .

已推送到公共仓库：lixd96/vllm-openai:v0.17.1-cu130，可直接拉取使用

2.2 Docker 部署 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

docker run -d \
 --name vllm-glm5 \
 --runtime nvidia \
 --gpus '"device=0,1,2,3"' \
 -p 8000:8000 \
 -v /raid/lixd/models/glm5-int4-mixed-autoround:/app/model \
 --shm-size 16g \
 vllm/vllm-openai:glm5 \
 serve /app/model \
 --tensor-parallel-size 4 \
 --tool-call-parser glm47 \
 --reasoning-parser glm45 \
 --enable-auto-tool-choice \
 --served-model-name glm5 \
 --trust-remote-code \
 --gpu-memory-utilization 0.85 \
 --host 0.0.0.0 \
 --port 8000

关键参数说明：

参数 说明
--tensor-parallel-size 张量并行数，通常等于 GPU 数量
--tool-call-parser glm47 使用 GLM 系列工具调用解析器
--reasoning-parser glm45 启用 GLM 推理能力
--enable-auto-tool-choice 启用自动工具选择
--trust-remote-code 信任模型中的远程代码
--gpu-memory-utilization GPU 显存利用率，建议 0.85-0.95

3. 服务验证

3.1 基础验证

部署完成后，验证服务是否正常运行：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# 查看可用模型列表
curl http://localhost:8000/v1/models

# 基础对话测试
curl http://localhost:8000/v1/chat/completions \
 -H "Content-Type: application/json" \
 -d '{
 "model": "glm5",
 "messages": [
 {"role": "user", "content": "你好，请介绍一下你自己"}
 ],
 "max_tokens": 100,
 "temperature": 0.7
 }'

# 流式对话测试
curl http://localhost:8000/v1/chat/completions \
 -H "Content-Type: application/json" \
 -d '{
 "model": "glm5",
 "messages": [
 {"role": "user", "content": "用一句话解释什么是 Kubernetes"}
 ],
 "max_tokens": 200,
 "stream": true
 }'

3.2 思考模式控制

GLM-5 支持开启/关闭思考模式，通过 chat_template_kwargs 参数控制：

开启思考模式（默认）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

curl http://localhost:8000/v1/chat/completions \
 -H "Content-Type: application/json" \
 -d '{
 "model": "glm5",
 "messages": [
 {"role": "system", "content": "You are a helpful assistant."},
 {"role": "user", "content": "Summarize GLM-5 in one sentence."}
 ],
 "temperature": 1,
 "max_tokens": 4096
 }'

关闭思考模式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

curl http://localhost:8000/v1/chat/completions \
 -H "Content-Type: application/json" \
 -d '{
 "model": "glm5",
 "messages": [
 {"role": "system", "content": "You are a helpful assistant."},
 {"role": "user", "content": "Summarize GLM-5 in one sentence."}
 ],
 "temperature": 1,
 "max_tokens": 4096,
 "chat_template_kwargs": {"enable_thinking": false}
 }'

4. 性能基准测试

4.1 测试方法

使用 vLLM 内置的 benchmark 工具进行测试：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Prompt-heavy benchmark (8k input / 1k output)
vllm bench serve \
 --model /app/model \
 --served_model_name glm5 \
 --dataset-name random \
 --random-input 8000 \
 --random-output 1024 \
 --request-rate 10 \
 --num-prompts 32 \
 --trust-remote-code \
 --ignore-eos

4.2 INT4 版本测试结果 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

============ Serving Benchmark Result ============
Successful requests: 32
Failed requests: 0
Request rate configured (RPS): 10.00
Benchmark duration (s): 35.27
Total input tokens: 256000
Total generated tokens: 32768
Request throughput (req/s): 0.91
Output token throughput (tok/s): 929.09
Peak output token throughput (tok/s): 1088.00
Peak concurrent requests: 32.00
Total token throughput (tok/s): 8187.65
---------------Time to First Token----------------
Mean TTFT (ms): 144.10
Median TTFT (ms): 139.03
P99 TTFT (ms): 226.47
-----Time per Output Token (excl. 1st token)------
Mean TPOT (ms): 31.61
Median TPOT (ms): 31.70
P99 TPOT (ms): 31.80
---------------Inter-token Latency----------------
Mean ITL (ms): 31.61
Median ITL (ms): 31.92
P99 ITL (ms): 58.34
==================================================

关键指标解读：

指标 含义 测试结果
TTFT Time To First Token，首 token 延迟，衡量用户等待第一个响应的时间 平均 144ms，响应迅速
TPOT Time Per Output Token，每个 token 的生成时间，反映流式输出的流畅度 平均 31.6ms

5. 小结

本文详细介绍了使用 vLLM 部署 GLM-5 模型的完整流程：

  • 模型下载：提供 FP8 和 INT4 两种版本，按需选择
  • 镜像构建：由于 GLM-5 需要最新 transformers，需自定义镜像
  • Docker 部署：以 INT4 版本为例，快速部署模型服务
  • 性能表现：INT4 版本在 GB200*4 环境下达到 929 tok/s 的吞吐量

如果你想在 Claude Code 中使用本地部署的 GLM-5 模型，可以参考我的另一篇文章《Claude Code 也能跑本地模型？CCR 多模型智能路由》，了解如何通过 Claude Code Router 实现对接。

Claude Code 也能跑本地模型？CCR 多模型 智能路由，成本直降 90%

2026-03-19 04:00:00

claude-code-router.jpeg

Claude Code 是 Anthropic 推出的强大 AI 编程助手，但每月的订阅费用让很多开发者望而却步。

通过 Claude Code Router (CCR)，我们可以：

  • 对接本地模型：部署 GLM5 等开源模型，实现零成本使用
  • 多模型智能路由：根据任务类型自动选择最合适的模型
  • 灵活组合：本地 + 云端混合部署，兼顾隐私、成本和质量

本文将手把手教你搭建这套方案，让你的 AI 编程助手成本降低 90% 以上。

1. 环境准备和工具安装

1.1 安装 Claude Code

首先需要在你的开发机器上安装 Claude Code：

1
2

# 官方安装脚本（需要科学上网）
curl -fsSL https://claude.ai/install.sh | bash

1.2 安装 Claude Code Router

Claude Code Router 是一个 Node.js 包，用于桥接 Claude Code 和本地模型：

1
2

# 需要 Node.js 20+ 版本
npm install -g @musistudio/claude-code-router

1.3 验证安装

安装完成后，验证两个工具是否正常工作：

1
2
3
4
5
6
7

# 检查 Claude Code 版本
❯ claude --version
2.1.51 (Claude Code)

# 检查 CCR 版本
❯ ccr version
claude-code-router version: 2.0.0

2. 模型部署

2.1 模型下载

在服务器上下载 GLM5 模型：

根据硬件配置选择合适的版本

1
2
3
4
5

# 使用 huggingface-cli 下载模型
# FP8 版本 推荐配置：H200*8
hf download zai-org/GLM-5-FP8 --local-dir /raid/lixd/models/glm5-fp8
# INT4 版本
hf download Intel/GLM-5-int4-mixed-AutoRound --local-dir /raid/lixd/models/glm5-int4-mixed-autoround

2.2 vLLM 服务启动

使用 vLLM 框架部署模型服务，确保已安装 GPU 驱动和 NVIDIA Container Toolkit。

由于 GLM5 需要最新版的 transformers 支持，官方镜像暂未包含，需要先构建自定义镜像：

已经推送到 lixd96/vllm-openai:v0.17.1-cu130，直接拉取即可 docker pull lixd96/vllm-openai:v0.17.1-cu130

构建自定义镜像：

创建 Dockerfile：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

FROM vllm/vllm-openai:v0.17.1-cu130

# 安装 git 用于从源码安装 transformers
RUN apt-get update && apt-get install -y git && \
 rm -rf /var/lib/apt/lists/*

# 安装最新版 transformers（GLM5 需要最新版支持）
RUN pip install --no-cache-dir git+https://github.com/huggingface/transformers.git

# 设置工作目录
WORKDIR /app

# 默认启动命令
ENTRYPOINT ["vllm"]

构建并推送镜像：

1
2

# 构建镜像
docker build -t lixd96/vllm-openai:v0.17.1-cu130-ex .

启动服务：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

docker run -d \
 --name vllm-glm5 \
 --runtime nvidia \
 --gpus '"device=0,1,2,3"' \
 -p 8000:8000 \
 -v /raid/lixd/models/glm5-int4-mixed-autoround:/glm5-int4-mixed-autoround \
 --shm-size 16g \
 lixd96/vllm-openai:v0.17.1-cu130 \
 serve /glm5-int4-mixed-autoround \
 --tensor-parallel-size 4 \
 --tool-call-parser glm47 \
 --reasoning-parser glm45 \
 --enable-auto-tool-choice \
 --served-model-name glm5 \
 --trust-remote-code \
 --gpu-memory-utilization 0.85 \
 --api-key "your-api-key" \
 --host 0.0.0.0 \
 --port 8000

关键参数说明：

  • GPU 配置：根据实际 GPU 数量调整 --gpus 和 --tensor-parallel-size 参数
  • 内存共享：--shm-size 16g 确保容器有足够共享内存
  • 工具调用：--enable-auto-tool-choice 启用工具调用功能，--tool-call-parser glm47 使用 GLM 系列的工具调用解析器
  • 推理解析：--reasoning-parser glm45 启用 GLM 的推理能力
  • 信任远程代码：--trust-remote-code 允许加载模型的自定义代码
  • 张量并行：--tensor-parallel-size 4 在多 GPU 上并行处理

2.3 服务验证

部署完成后，验证服务是否正常运行：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# 查看可用模型列表
curl http://localhost:8000/v1/models

# 基础对话测试
curl http://localhost:8000/v1/chat/completions \
 -H "Content-Type: application/json" \
 -d '{
 "model": "glm5",
 "messages": [
 {"role": "user", "content": "你好，请介绍一下你自己"}
 ],
 "max_tokens": 100,
 "temperature": 0.7
 }'

# 流式对话测试
curl http://localhost:8000/v1/chat/completions \
 -H "Content-Type: application/json" \
 -d '{
 "model": "glm5",
 "messages": [
 {"role": "user", "content": "用一句话解释什么是 Kubernetes"}
 ],
 "max_tokens": 200,
 "stream": true
 }'

如果一切正常，你应该能看到模型的响应输出。

2.4 配置 Claude Code Router

配置说明

核心配置文件如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

{
 // LLM 提供商
 "Providers": [
 {
 "name": "openai",
 "baseUrl": "https://api.openai.com/v1",
 "apiKey": "$OPENAI_API_KEY",
 "models": ["gpt-4", "gpt-3.5-turbo"]
 }
 ],

// 路由
{
 "Router": {
 "default": "openai,gpt-4",
 "background": "openai,gpt-3.5-turbo",
 "think": "openai,gpt-4",
 "longContext": "anthropic,claude-3-opus"
 }
}}
  • Providers：对接不同供应商提供的不同模型
  • Router：则是将模型分类 https://musistudio.github.io/claude-code-router/zh-CN/docs/server/config/routing
    • default：默认路由
    • background：后台任务，推荐用轻量级模型
    • think：思考密集型任务，推荐用能力强的模型
    • longContext：长上下文时会使用该模型
    • webSearch：网络搜索任务
    • image：图像任务

完整配置

创建或编辑配置文件 ~/.claude-code-router/config.json：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

{
 "LOG": true,
 "LOG_LEVEL": "debug",
 "CLAUDE_PATH": "",
 "HOST": "127.0.0.1",
 "PORT": 3456,
 "APIKEY": "",
 "API_TIMEOUT_MS": "600000",
 "PROXY_URL": "",
 "transformers": [],
 "Providers": [
 {
 "name": "vllm",
 "api_base_url": "http://your-server-ip:8000/v1/chat/completions",
 "api_key": "your-api-key",
 "models": [
 "glm5"
 ],
 "transformer": {
 "use": [
 "enhancetool",
 [
 "sampling",
 {
 "temperature": "0.7",
 "top_p": "0.8",
 "top_k": "20",
 "repetition_penalty": "1.05"
 }
 ]
 ]
 }
 }
 ],
 "StatusLine": {
 "enabled": true,
 "currentStyle": "default",
 "default": {
 "modules": []
 },
 "powerline": {
 "modules": [
 {
 "type": "workDir",
 "icon": "󰉋",
 "text": "{{workDirName}}",
 "color": "bright_blue"
 },
 {
 "type": "gitBranch",
 "icon": "🌿",
 "text": "{{gitBranch}}",
 "color": "bright_green"
 },
 {
 "type": "model",
 "icon": "🤖",
 "text": "{{model}}",
 "color": "bright_yellow"
 },
 {
 "type": "usage",
 "icon": "📊",
 "text": "{{inputTokens}} → {{outputTokens}}",
 "color": "bright_magenta"
 },
 {
 "type": "script",
 "icon": "📜",
 "text": "Script Module",
 "color": "bright_cyan",
 "scriptPath": ""
 }
 ]
 }
 },
 "Router": {
 "default": "vllm,glm5",
 "background": "vllm,glm5",
 "think": "vllm,glm5",
 "longContext": "vllm,glm5",
 "longContextThreshold": 102400,
 "webSearch": "vllm,glm5",
 "image": ""
 },
 "CUSTOM_ROUTER_PATH": ""
}

配置说明：

  • API 地址：将 your-server-ip 替换为实际的服务器 IP 地址
  • API 密钥：设置与 vLLM 启动时相同的 API 密钥
  • 路由配置：将所有任务类型都指向本地模型
  • 状态栏：启用自定义状态栏显示工作目录、Git 分支、模型信息等
  • 日志级别：调试阶段可设为 debug，生产环境建议改为 info

3. 开始使用

3.1 启动 Claude Code Router

使用 ccr code 替代原来的 claude 命令：

效果如下： ccr-demo.png

启动后，在 claude 界面输入以下命令切换模型

1

/model vllm,glm5

之后就可以正常使用了。

ps: 不切换模型也可以，只是终端会一直显示用的 Claude 的模型。

4. 进阶：多模型智能路由

前面我们介绍了单一模型的配置方式，但在实际使用中，不同类型的任务对模型能力的要求各不相同。
Claude Code Router 的强大之处在于支持对接多个模型，并根据任务类型自动路由到最合适的模型。

4.1 为什么需要多模型路由？

不同任务对模型的需求差异很大：

任务类型 特点 推荐模型策略
日常对话 频率高、响应快 轻量级模型，节省资源
代码生成 需要准确性和逻辑性 中等能力模型
复杂推理 需要深度思考 顶级能力模型
长文本处理 需要大上下文窗口 支持长上下文的模型
图像理解 需要多模态能力 视觉语言模型

通过合理配置，可以实现：

  • 成本优化：简单任务用便宜模型，复杂任务才用昂贵模型
  • 性能平衡：快速响应与高质量输出的权衡
  • 资源利用：充分利用不同模型的优势

4.2 多模型配置示例

以下是一个对接多个模型服务商的完整配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

{
 "LOG": true,
 "LOG_LEVEL": "info",
 "HOST": "127.0.0.1",
 "PORT": 3456,
 "API_TIMEOUT_MS": "600000",
 "Providers": [
 {
 "name": "local-glm5",
 "api_base_url": "http://192.168.1.100:8000/v1/chat/completions",
 "api_key": "your-local-key",
 "models": ["glm5"],
 "transformer": {
 "use": ["enhancetool"]
 }
 },
 {
 "name": "deepseek",
 "api_base_url": "https://api.deepseek.com/v1/chat/completions",
 "api_key": "$DEEPSEEK_API_KEY",
 "models": ["deepseek-chat", "deepseek-reasoner"]
 },
 {
 "name": "openai",
 "api_base_url": "https://api.openai.com/v1/chat/completions",
 "api_key": "$OPENAI_API_KEY",
 "models": ["gpt-4o", "gpt-4o-mini"]
 },
 {
 "name": "zhipu",
 "api_base_url": "https://open.bigmodel.cn/api/paas/v4/chat/completions",
 "api_key": "$ZHIPU_API_KEY",
 "models": ["glm-4-plus", "glm-4-flash"]
 }
 ],
 "Router": {
 "default": "local-glm5,glm5",
 "background": "zhipu,glm-4-flash",
 "think": "deepseek,deepseek-reasoner",
 "longContext": "local-glm5,glm5",
 "longContextThreshold": 64000,
 "webSearch": "openai,gpt-4o-mini",
 "image": "openai,gpt-4o"
 }
}

4.3 路由策略详解

default（默认路由）

  • 用途：常规对话和代码编写
  • 建议：选择性价比高的主力模型
  • 示例：本地 GLM5 或 DeepSeek Chat

background（后台任务）

  • 用途：自动触发的辅助任务，如代码审查、状态检查
  • 特点：频率高、对质量要求相对较低
  • 建议：使用轻量快速模型，如 GLM-4-Flash、GPT-4o-mini
  • 成本优势：可节省 80% 以上的 API 费用

think（思考密集型）

  • 用途：复杂算法设计、架构决策、疑难问题排查
  • 特点：需要深度推理能力
  • 建议：使用最强推理模型，如 DeepSeek Reasoner、Claude Opus
  • 注意：这类模型响应较慢，但输出质量最高

longContext（长上下文）

  • 用途：分析大型代码库、处理长文档
  • 触发条件：当上下文超过 longContextThreshold 时自动切换
  • 建议：选择支持 64K+ 上下文的模型
  • 示例：GLM5（200K）、Claude（200K）

webSearch（网络搜索）

  • 用途：联网查询资料
  • 建议：选择支持工具调用的模型
  • 示例：GPT-4o、DeepSeek Chat

image（图像任务）

  • 用途：截图分析、图表解读
  • 建议：使用多模态模型
  • 示例：GPT-4o、Claude 3.5 Sonnet

4.4 最佳实践建议

工作原理

Claude Code Router 的核心原理是通过启动一个 HTTP 中转服务，在不修改 Claude Code 源码的情况下完成请求的转发和格式转换。

Claude Code 使用 Anthropic API 规范进行通信，而大多数模型服务商（如 OpenAI、DeepSeek 等）使用 OpenAI API 规范。CCR 的作用就是：

  1. 接收请求：CCR 启动一个 HTTP 服务（默认端口 3456），监听 Claude Code 的请求
  2. 格式转换：将 Anthropic API 格式的请求转换为 OpenAI API 格式
  3. 智能路由：根据任务类型将请求分发到不同的模型服务商
  4. 响应转换：将模型的响应转换回 Anthropic API 格式返回给 Claude Code
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

┌─────────────────────────────────────────────────────────────┐
│ Claude Code │
│ (使用 Anthropic API 规范通信) │
└─────────────────────────┬───────────────────────────────────┘
 │ Anthropic API 格式
 ▼
 ┌─────────────────────┐
 │ CCR HTTP 服务 │
 │ (Express.js) │
 │ │
 │ • 格式转换 │
 │ • 智能路由 │
 │ • 请求重写 │
 └──────────┬──────────┘
 │ OpenAI API 格式
 ┌─────────────────┼─────────────────┐
 │ │ │
 ┌────▼────┐ ┌─────▼─────┐ ┌─────▼─────┐
 │ 本地 │ │ 云端 │ │ 云端 │
 │ GLM5 │ │ DeepSeek │ │ OpenAI │
 │ (default)│ │ (think) │ │ (image) │
 └─────────┘ └───────────┘ └───────────┘

按需分配，降低成本

CCR 的核心优势在于可以根据任务特点选择最合适的模型，实现成本与质量的平衡：

任务类型 特点 推荐策略
日常开发 频率高、响应要求快 性价比高的主力模型
复杂推理 需要深度思考 推理能力强的模型
图像理解 需要多模态能力 支持视觉的模型
后台任务 自动触发、频率高 轻量快速模型
长文本 需要大上下文 支持长上下文的模型

成本对比：

1
2
3
4
5
6
7
8

┌────────────────────────────────────────────────┐
│ Claude Max Plan │
│ $200 / 月 │
├────────────────────────────────────────────────┤
│ CCR 多模型路由 │
│ 日常任务用便宜模型 + 复杂任务用强模型 │
│ ~$20 / 月 │
└────────────────────────────────────────────────┘

通过合理配置路由策略，将高频低难度任务分配给低成本模型，仅在必要时调用高端模型，月成本可降低 90% 以上。

5. 常见问题与解决方案

5.1 “Unable to connect to Anthropic services” 错误

如果运行 ccr code 时报错：“Unable to connect to Anthropic services”，可以修改 ~/.claude.json 文件，在最外层添加以下配置：

1
2
3

{
 "hasCompletedOnboarding": true
}

保存后重新运行即可。

6. 小结

本文介绍了如何通过 Claude Code Router 打破 Claude Code 的使用限制：

  • 本地部署：通过 vLLM 部署 GLM5 模型，实现零成本使用
  • 多模型路由：根据任务类型智能分发，高频任务用便宜模型，复杂任务用强模型
  • 成本优化：相比 Claude Max Plan，合理配置后成本可降低 90% 以上

CCR 还支持对接更多 Provider，如 DeepSeek、智谱 AI、OpenAI 等，可根据实际需求灵活组合。如果你也在寻找高性价比的 AI 编程方案，不妨试试这套配置。

Kubernetes教程(五十二)---Velero快速入门：开源备份恢复工具实战

2026-03-11 04:00:00

velero-quickstart.png

在之前的文章《Kubernetes PVC Clone & Snapshot 实战：基于 Csi-Driver-Nfs 的完整示例》中，我们探讨了如何使用 Kubernetes 内置的 PVC 克隆和快照功能进行数据保护。然而，当我们需要对整个 Kubernetes 集群进行全面的备份恢复时，就需要更专业的工具。

Velero（前身 Heptio Ark）正是这样一个专业的 Kubernetes 备份恢复工具，已成为 CNCF 毕业项目。它不仅能够备份持久卷数据，还能备份整个集群的应用配置、服务和资源状态，提供企业级的灾难恢复和集群迁移能力。

你将学到：

  • Velero 架构原理和核心特性
  • 单集群备份恢复完整操作流程
  • 跨集群应用迁移实战演示
  • 生产环境最佳实践和故障排查

1. Velero 简介

1.1 什么是 Velero

在前一篇文章中我们介绍了 PVC 级别的数据保护方案，但当我们需要对整个 Kubernetes 应用栈进行备份恢复时，就需要更全面的解决方案。

Velero（前身 Heptio Ark）正是一个用于备份与恢复 Kubernetes 集群资源和持久卷（PV/PVC）的专业开源工具，提供安全可靠的数据保护解决方案。

Velero 在 Kubernetes 生态中已被广泛视为开源领域事实标准 / 最主流备份恢复工具（CNCF 毕业项目，社区采用率最高）。

1.2 核心特性

  • 集群资源备份恢复：支持 Deployment、Service、ConfigMap、Secret 等 Kubernetes 资源的备份与恢复
  • 持久卷数据保护：通过云快照或文件系统备份工具（Kopia）保护 PVC 数据
  • 定时备份调度：支持自动化定时备份策略
  • 跨集群迁移：实现集群间应用和数据的安全迁移
  • 多存储后端：支持 S3、GCS、Azure Blob 等多种对象存储

1.3 适用场景

  • 灾难恢复：应对集群故障、误删除等意外情况

  • 集群升级迁移：安全地将应用迁移到新版本集群

  • 开发测试：为开发测试环境提供快速数据恢复能力

  • 合规要求：满足数据保护和审计合规需求

  • 开源地址：https://github.com/vmware-tanzu/velero

  • 官方文档：https://velero.io/docs/v1.17/

2. 架构和工作原理

2.1 组件构成

Velero 采用客户端-服务器架构：

  • 服务端：运行在 Kubernetes 集群中的控制器组件
  • 客户端：本地命令行工具，需要配置 kubectl 和集群 kubeconfig

2.2 备份流程

Velero 采用 Operator 模式，通过创建 CRD 对象触发备份操作：

velero-workflow.png

  1. 创建备份任务：Velero 客户端调用 Kubernetes API 创建 Backup CRD
  2. 监听任务：Backup Controller 通过 watch 机制获取备份任务
  3. 收集数据：Controller 通过 kube-apiserver 获取需要备份的资源数据
  4. 存储备份：将数据上传到指定的对象存储后端

2.3 存储后端配置

Velero 通过两种 CRD 管理存储后端：

BackupStorageLocation

定义 Kubernetes 集群资源的存储位置，主要用于存储 YAML 清单文件等元数据。支持 S3 兼容存储（如 MinIO、AWS S3、阿里云 OSS 等）。

VolumeSnapshotLocation

定义持久卷快照的存储位置，需要云提供商插件支持。对于不支持快照的环境，可以使用文件系统备份工具 Restic/Kopia。

Restic 是一款用 Go 语言开发的数据加密备份工具，支持多种存储后端：Local、SFTP、AWS S3、MinIO、Azure Blob Storage、Google Cloud Storage 等。
Kopia 是 Velero 从 v1.10 版本开始引入的新一代 文件级备份工具，用于替代传统的 Restic，相比 Restic 具有更好的性能和可靠性。

3. 安装部署

3.1 准备工作

存储插件选择

Velero 支持多种存储插件，可通过 官方文档 查看完整列表。本教程使用 MinIO 作为 S3 兼容的对象存储。

MinIO 部署

可以参考 MinIO 官方文档部署服务，或使用 Velero 提供的快速部署脚本：

1

kubectl apply -f https://raw.githubusercontent.com/vmware-tanzu/velero/main/examples/minio/00-minio-deployment.yaml

3.2 安装 CLI 工具

到 GitHub release 页面下载最新压缩包：

1
2
3
4
5
6
7
8

wget https://github.com/vmware-tanzu/velero/releases/download/v1.17.2/velero-v1.17.2-linux-amd64.tar.gz

tar -zxvf velero-v1.17.2-linux-amd64.tar.gz

mv velero-v1.17.2-linux-amd64/velero /usr/local/bin/

# 查看版本
velero version

3.3 安装服务端组件

创建认证文件

先创建 S3 配置文件，提供 MinIO 的访问凭证：

1
2
3
4
5

cat > credentials-s3 <<EOF
[default]
aws_access_key_id = your-access-key-id
aws_secret_access_key = your-secret-access-key
EOF

部署 Velero 服务端

开始部署 Velero 服务端组件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

REGISTRY=docker.io
S3URL=http://your-minio-endpoint:port
BUCKET=velero

velero install \
 --namespace velero \
 --provider aws \
 --image $REGISTRY/velero/velero:v1.17.2 \
 --plugins $REGISTRY/velero/velero-plugin-for-aws:v1.13.2 \
 --secret-file ./credentials-s3 \
 --bucket $BUCKET \
 --use-node-agent \
 --use-volume-snapshots=false \
 --backup-location-config region=minio,s3ForcePathStyle="true",s3Url=$S3URL

参数说明：

  • --namespace：指定部署的 namespace 名称，默认为 velero
  • --provider：定义插件提供方，aws 表示 AWS S3 兼容
  • --image：定义运行 velero 的镜像
  • --plugins：指定使用 aws s3 兼容的插件镜像
  • --secret-file：指定对象存储认证文件
  • --bucket：指定对象存储 Bucket 桶名称
  • --use-node-agent：创建 Velero Node Agent 守护进程，用于通过 Kopia 备份 PVC 数据
  • --use-volume-snapshots：是否启用快照功能

注意：从 Velero 1.7 开始，Kopia 成为默认的文件系统备份工具，取代了之前的 Restic。Kopia 提供了更好的性能和可靠性。

  • --backup-location-config：指定对象存储地址信息
    • region：MinIO 本身没有区域概念，但 AWS S3 插件需要 region 参数，因此使用 minio 作为占位符
    • s3ForcePathStyle：路径风格访问，强制使用路径风格的 URL（http://endpoint/bucket/key），这是 MinIO 的推荐访问方式
    • s3Url：MinIO 服务地址

验证安装状态 

1
2
3
4
5
6
7
8
9

# 检查 Pod 状态
kubectl -n velero get pod

# 查看 BackupStorageLocation
kubectl -n velero get BackupStorageLocation

# 示例输出：
# NAME PHASE LAST VALIDATED AGE DEFAULT
# default Available 43s 5m true

3.4 卸载 Velero

如果需要从集群中完全卸载 Velero：

1
2
3
4
5
6

# 使用 velero 命令卸载
velero uninstall

# 或者手动删除相关资源
kubectl delete namespace/velero clusterrolebinding/velero
kubectl delete crds -l component=velero

4. 基础操作

4.1 备份命令详解

备份命令：velero create backup NAME [flags]

4.2 定时备份配置

除了手动备份外，Velero 还支持定时备份，可以通过 Schedule CRD 实现自动化备份：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 创建每天凌晨2点的定时备份
velero create schedule daily-backup \
 --schedule="0 2 * * *" \
 --include-namespaces nginx-example \
 --default-volumes-to-fs-backup \
 --ttl 72h

# 查看定时备份列表
velero get schedules

# 查看定时备份的执行历史
velero get backups --selector velero.io/schedule-name=daily-backup

定时表达式说明：

  • 0 2 * * *：每天凌晨2点执行
  • 0 */6 * * *：每6小时执行一次
  • 0 0 * * 0：每周日午夜执行

常用选项：

  • --exclude-namespaces stringArray：从备份中排除的命名空间
  • --exclude-resources stringArray：从备份中排除的资源类型
  • --include-cluster-resources optionalBool[=true]：是否包含集群级资源
  • --include-namespaces stringArray：要包含的命名空间（默认 ‘*’）
  • --include-resources stringArray：要备份的资源类型
  • --labels mapStringString：为备份添加标签
  • -o, --output string：输出格式（table/json/yaml）
  • -l, --selector labelSelector：按标签筛选资源
  • --snapshot-volumes optionalBool[=true]：是否为 PV 创建快照
  • --storage-location string：指定备份位置
  • --ttl duration：备份数据的过期时间
  • --volume-snapshot-locations strings：指定快照位置

5. 实战演示：单集群备份恢复

5.1 创建测试应用

创建一个 Nginx 应用并挂载 PVC，用于验证备份恢复功能：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

cat > nginx-demo.yaml <<EOF
apiVersion: v1
kind: Namespace
metadata:
 name: nginx-example
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
 name: nginx-html-pvc
 namespace: nginx-example
spec:
 accessModes:
 - ReadWriteOnce
 resources:
 requests:
 storage: 1Gi
 storageClassName: nfs  # 请修改为你的集群中可用的StorageClass
---
apiVersion: apps/v1
kind: Deployment
metadata:
 name: nginx-deployment
 namespace: nginx-example
spec:
 replicas: 1
 selector:
 matchLabels:
 app: nginx
 template:
 metadata:
 labels:
 app: nginx
 spec:
 containers:
 - name: nginx
 image: registry.cn-shanghai.aliyuncs.com/99cloud-sh/nginx:1.20
 ports:
 - containerPort: 80
 volumeMounts:
 - name: html-volume
 mountPath: /usr/share/nginx/html  # Nginx默认的网页根目录
 volumes:
 - name: html-volume
 persistentVolumeClaim:
 claimName: nginx-html-pvc
---
apiVersion: v1
kind: Service
metadata:
 name: nginx-service
 namespace: nginx-example
spec:
 type: NodePort  # 为了方便从集群外部访问，使用NodePort类型
 selector:
 app: nginx
 ports:
 - protocol: TCP
 port: 80
 targetPort: 80
EOF
 
1

kubectl apply -f nginx-demo.yaml

5.2 写入测试数据 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 获取 Nginx Pod 名称
NGINX_POD=$(kubectl get pods -n nginx-example -l app=nginx -o jsonpath='{.items[0].metadata.name}')
echo $NGINX_POD

# 创建测试文件并复制到 Pod
echo '<h1>Hello from Velero Backup Demo!</h1><p>This file was created on '"$(date)"'.</p>' > test-index.html
kubectl cp test-index.html nginx-example/$NGINX_POD:/usr/share/nginx/html/index.html

# 验证数据写入
kubectl get svc nginx-service -n nginx-example
curl http://<cluster-ip>:80

5.3 执行备份 

1

velero backup create nginx-backup-pvc --include-namespaces nginx-example --default-volumes-to-fs-backup

参数说明：

  • --include-namespaces：指定要备份的命名空间
  • --default-volumes-to-fs-backup：使用文件系统备份工具备份 PVC 数据

5.4 监控备份状态 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 查看备份列表
velero backup get

# 示例输出：
# NAME STATUS ERRORS WARNINGS CREATED EXPIRES STORAGE LOCATION SELECTOR
# nginx-backup-pvc Completed 0 0 2026-01-27 08:36:54 +0000 UTC 29d default <none>

# 查看详细备份信息
velero backup describe nginx-backup-pvc

# 查看备份日志
velero backup logs nginx-backup-pvc

5.5 验证备份结果

备份完成后，可以在 MinIO 存储中查看备份内容：

Kubernetes 资源配置备份： velero-save-in-minio-yaml.png

PVC 数据文件备份： velero-save-in-minio-pvc.png

5.5 模拟灾难恢复 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# 删除应用模拟灾难
kubectl delete namespace nginx-example

# 执行恢复
velero restore create --from-backup nginx-backup-pvc

# 监控恢复进度
velero restore get

# 示例输出：
# NAME BACKUP STATUS STARTED COMPLETED ERRORS WARNINGS CREATED SELECTOR
# nginx-backup-pvc-20260127084915 nginx-backup-pvc Completed 2026-01-27 08:49:15 +0000 UTC 2026-01-27 08:49:23 +0000 UTC 0 1 2026-01-27 08:49:15 +0000 UTC <none>

# 验证恢复结果
kubectl -n nginx-example get pod,svc,pvc
curl <nginx-service-cluster-ip>

6. 高级功能：跨集群迁移

只要我们将每个 velero 实例指向相同的对象存储，velero 就能将资源从一个群集迁移到另一个群集。

velero-demo-cross-cluster.png

6.1 环境要求

  • 集群版本一致：建议两个 Kubernetes 集群版本保持一致
  • 存储类匹配：确保目标集群有相同名称的 StorageClass
  • 共享存储后端：两个集群的 Velero 需连接同一对象存储

以下是集群信息：

角色 集群IP 集群版本 部署软件
K8S 集群A 172.16.131.134 v1.34.2 velero、demo-app
K8S 集群B 172.16.131.171 v1.34.2 velero、minio

6.2 源集群操作

在集群 A 部署上应用。

部署测试应用

创建一个 nginx app，并挂载 pvc 用于验证备份恢复功能。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

cat > nginx-demo.yaml <<EOF
apiVersion: v1
kind: Namespace
metadata:
 name: nginx-example
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
 name: nginx-html-pvc
 namespace: nginx-example
spec:
 accessModes:
 - ReadWriteOnce
 resources:
 requests:
 storage: 1Gi
 storageClassName: nfs # 请修改为你的集群中可用的StorageClass
---
apiVersion: apps/v1
kind: Deployment
metadata:
 name: nginx-deployment
 namespace: nginx-example
spec:
 replicas: 1
 selector:
 matchLabels:
 app: nginx
 template:
 metadata:
 labels:
 app: nginx
 spec:
 containers:
 - name: nginx
 image: registry.cn-shanghai.aliyuncs.com/99cloud-sh/nginx:1.20
 ports:
 - containerPort: 80
 volumeMounts:
 - name: html-volume
 mountPath: /usr/share/nginx/html # Nginx默认的网页根目录
 volumes:
 - name: html-volume
 persistentVolumeClaim:
 claimName: nginx-html-pvc
---
apiVersion: v1
kind: Service
metadata:
 name: nginx-service
 namespace: nginx-example
spec:
 type: NodePort # 为了方便从集群外部访问，使用NodePort类型
 selector:
 app: nginx
 ports:
 - protocol: TCP
 port: 80
 targetPort: 80
EOF
 
1

kubectl apply -f nginx-demo.yaml

写入测试 

1
2

NGINX_POD=$(kubectl get pods -n nginx-example -l app=nginx -o jsonpath='{.items[0].metadata.name}')
echo $NGINX_POD

将一个简单的 html 复制到 nginx 数据目录中

1
2
3
4

# 首先在本机创建一个测试文件
echo '<h1>Hello from Velero Backup Demo!</h1><p>This file was created on '"$(date)"'.</p>' > test-index.html
# 将文件拷贝到Pod内的PVC目录
kubectl cp test-index.html nginx-example/$NGINX_POD:/usr/share/nginx/html/index.html

访问 nginx 进行验证

1
2
3
4
5
6

kubectl get svc nginx-service -n nginx-example
# 使用输出的NodePort端口访问，例如节点IP为192.168.1.100，端口为32000
curl http://<cluster-ip>:80

root@lixd-dev-2:~# curl 10.111.66.141
<h1>Hello from Velero Backup Demo!</h1><p>This file was created on Tue Jan 27 07:49:17 UTC 2026.</p>

Velero 备份 

1
2
3

root@lixd-dev-1:~/velero# velero backup create nginx-backup-pvc --include-namespaces nginx-example --default-volumes-to-fs-backup
Backup request "nginx-backup-pvc" submitted successfully.
Run `velero backup describe nginx-backup-pvc` or `velero backup logs nginx-backup-pvc` for more details.

参数：

  • --include-namespaces：指定命名空间，这里测试仅备份 nginx-example 下的内容。
  • --default-volumes-to-fs-backup：使用文件系统备份工具（Kopia）来备份数据。这种方式更通用。

查看状态

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

root@lixd-dev-1:~/velero# velero backup get
NAME STATUS ERRORS WARNINGS CREATED EXPIRES STORAGE LOCATION SELECTOR
nginx-backup-pvc InProgress 0 0 2026-01-28 07:41:25 +0000 UTC 29d default <none>
root@lixd-dev-1:~/velero# velero backup get
NAME STATUS ERRORS WARNINGS CREATED EXPIRES STORAGE LOCATION SELECTOR
nginx-backup-pvc Completed 0 0 2026-01-28 07:41:25 +0000 UTC 29d default <none>

# 查看备份详细信息
$ velero backup describe nginx-backup
 
# 查看备份日志
$ velero backup logs nginx-backup

这样就备份好了。

6.4 集群 B 恢复

恢复

在目标集群查看备份对象（如果连接到同一个 S3 存储，Velero 会自动同步）：

1
2
3

root@lixd-dev-2:~# velero get backup
NAME STATUS ERRORS WARNINGS CREATED EXPIRES STORAGE LOCATION SELECTOR
nginx-backup-pvc Completed 0 0 2026-01-28 07:41:25 +0000 UTC 29d default <none>

恢复数据

1
2
3

root@lixd-dev-2:~# velero restore create --from-backup nginx-backup-pvc
Restore request "nginx-backup-20260127075810" submitted successfully.
Run `velero restore describe nginx-backup-20260127075810` or `velero restore logs nginx-backup-20260127075810` for more details.

查看恢复进度

1
2
3
4
5
6

root@lixd-dev-2:~# velero restore get
NAME BACKUP STATUS STARTED COMPLETED ERRORS WARNINGS CREATED SELECTOR
nginx-backup-pvc-20260128080008 nginx-backup-pvc InProgress 2026-01-28 08:00:08 +0000 UTC <nil> 0 0 2026-01-28 08:00:08 +0000 UTC <none>
root@lixd-dev-2:~# velero restore get
NAME BACKUP STATUS STARTED COMPLETED ERRORS WARNINGS CREATED SELECTOR
nginx-backup-pvc-20260128080008 nginx-backup-pvc Completed 2026-01-28 08:00:08 +0000 UTC 2026-01-28 08:00:17 +0000 UTC 0 1 2026-01-28 08:00:08 +0000 UTC <none>

验证

验证 Nginx 是否完全恢复

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

root@lixd-dev-2:~/velero# kubectl -n nginx-example get po
NAME READY STATUS RESTARTS AGE
nginx-deployment-7cf7667b79-cmjfm 1/1 Running 0 41s
root@lixd-dev-2:~/velero# kubectl -n nginx-example get svc
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
nginx-service NodePort 10.103.125.238 <none> 80:32285/TCP 42s
root@lixd-dev-2:~/velero# kubectl -n nginx-example get pvc
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS VOLUMEATTRIBUTESCLASS AGE
nginx-html-pvc Bound pvc-99f0060d-fd8b-4887-a5e5-cdc6858d3590 1Gi RWO nfs <unset> 45s
root@lixd-dev-2:~# curl 10.111.49.149
<h1>Hello from Velero Backup Demo!</h1><p>This file was created on Wed Jan 28 07:48:15 UTC 2026.</p>

一切正常。

跨集群迁移完成。

小结

Velero 作为一个成熟的 Kubernetes 备份恢复工具，提供了完整的灾难恢复和集群迁移解决方案。通过本文的实战演示，您可以掌握：

  1. Velero 的基本安装和配置
  2. 单集群内应用的备份恢复操作
  3. 跨集群的应用和数据迁移流程
  4. 生产环境的最佳实践建议

KubeClipper 1.5.0 发布：全新工作负载界面与 Kubernetes 1.35 支持

2026-03-04 04:00:00

kubeclipper-release-1.5.0.jpeg

最近，KubeClipper 正式发布了 1.5.0 版本。这次更新带来了多项重要改进，其中最引人注目的是新增的工作负载管理界面，用户现在可以直接在 Web UI 中管理 Deployment、StatefulSet 等 Kubernetes 工作负载。同时，该版本还升级了对 Kubernetes 及其组件的支持，并修复了大量 bug，提升了平台的稳定性和用户体验。

KubeClipper 是一个轻量便捷的 Kubernetes 多集群全生命周期管理工具，旨在提供易使用、易运维、极轻量、生产级的 Kubernetes 多集群管理服务，让运维工程师从繁复的配置和晦涩的命令行中解放出来，实现一站式管理跨区域、跨基础设施的多 K8S 集群。

🚀 5分钟快速体验

如果你是第一次接触 KubeClipper，可以通过以下步骤快速上手：

  1. 一键安装工具：curl -sfL https://oss.kubeclipper.io/get-kubeclipper.sh | KC_REGION=cn bash -
  2. 部署服务：kcctl deploy
  3. 创建集群：kcctl create cluster --name demo --master YOUR_IP --untaint-master
  4. 访问界面：浏览器访问 http://YOUR_IP:8080，账号 admin/Thinkbig1

全程只需5-10分钟，就能拥有一个功能完整的 Kubernetes 环境！

1. KubeClipper 1.5.0 新特性详解

相比于之前的版本，1.5.0 在易用性和功能性方面都有显著提升。最大的变化是新版增加了对 k8s 1.35.0 的支持，另外新增的工作负载管理功能让用户可以完全摆脱命令行操作。

KubeClipper 的核心优势：

  • ✅ 易使用：提供 Web 控制台，通过点点鼠标即可创建和管理 k8s 集群
  • ✅ 极轻量：架构简单，不依赖 Ansible，部署方便快捷
  • ✅ 生产级：支持在线、离线、代理方式部署，提供多版本 K8S、CRI、CNI 选择
  • ✅ 离线友好：提供离线部署方式，对国内用户极为友好

本次更新的主要亮点：

  • 🆕 工作负载 UI 管理：直接在 Web 界面管理 K8s 工作负载
  • 🔄 版本升级：Kubernetes 版本更新至 1.35
  • 🛠️ 技术改进：Go 版本升级、大量依赖库更新、CI/CD 优化
  • 🔧 稳定性提升：节点健康检查、系统服务管理、竞态条件修复
  • 🔒 安全性增强：镜像仓库认证、TLS 配置优化、权限管理改进
  • 🐛 Bug 修复：大量稳定性改进和问题修复

1.1 工作负载管理界面

这是 1.5.0 版本最重要的新功能。之前用户需要通过命令行或第三方工具管理 Kubernetes 工作负载，现在可以直接在 KubeClipper 的 Web UI 中进行可视化操作：

  • Workload 管理：创建、编辑、扩缩容、滚动更新
  • 实时状态查看：Pod 状态、事件日志查看
  • 一键操作：重启、回滚、删除等常用操作

1.2 组件版本升级

1.5.0版本全面升级了支持的组件版本：

  • Kubernetes: 支持最新 v1.35 版本
  • CNI 插件: Calico v1.29.6
  • 容器运行时: containerd 1.7.29
  • 开发工具: Go 语言版本从 1.19 升级到 1.23
  • 其他组件: 同步更新到最新兼容版本

1.3 技术改进和 Bug 修复

1.5.0版本包含了大量的技术改进和稳定性提升：

核心功能改进

  • Kubernetes: 支持最新 v1.35 版本，Calico、Containerd 同步更新
  • 容器运行时优化：修复 SystemdCgroup 配置，改进 containerd 兼容性
  • 证书管理：延长证书有效期至 10 年，避免重复处理证书到期问题

稳定性提升

  • 节点健康检查：使用 kube clientset 检查节点和集群健康状况
  • 错误处理优化：改进命令执行失败时的标准错误输出
  • 系统服务管理：新增 systemctl 工具类，应用于容器运行时和 kubelet
  • 竞态条件修复：解决集群部署和节点添加过程中的并发问题

安全性增强

  • 镜像仓库认证：支持 CRI registry 认证功能
  • TLS 配置：改进证书生成和验证机制
  • 权限管理：优化 kubeconfig 文件生成逻辑

开发工具链升级

  • Go 版本升级：从 1.19 升级到 1.23
  • 依赖库更新：大量第三方库版本升级，包括安全补丁
  • CI/CD 优化：新增代码格式化检查和构建检查

2. 安装部署 KubeClipper 1.5.0

2.1 环境要求

在开始安装之前，确保满足以下要求：

  • 操作系统: CentOS 7+/Ubuntu 18.04+
  • 内核版本: 4.4+
  • 内存: 至少4GB RAM
  • 存储: 至少 20GB 可用空间
  • 网络: 节点间网络互通

2.2 安装 kcctl 工具 

1
2
3
4
5

# 下载最新版本的 kcctl
curl -sfL https://oss.kubeclipper.io/get-kubeclipper.sh | KC_REGION=cn bash -

# 验证安装
kcctl version

正常输出如下：

1
2

root@lixd-dev-1:~# kcctl version
kcctl version: version.Info{Major:"1", Minor:"5", GitVersion:"v1.5.0", GitCommit:"0930af19ab9bddd4883f7a46ac91e67335fc1978", GitTreeState:"clean", BuildDate:"2026-02-26T05:25:31Z", GoVersion:"go1.23.0", Compiler:"gc", Platform:"linux/amd64"}

2.3 部署 KubeClipper 

1
2
3
4
5

# 对于 aio 环境使用 kcctl deploy 即可完成部署
kcctl deploy

# 更多参数参考 kcctl deploy -h
# kcctl deploy --server $IPADDR_SERVER --agent $IPADDR_AGENT --pk-file /root/.ssh/id_rsa --pkg $PKG --ip-detect=interface=ens3 --v 5

在打印出如下的 KubeClipper banner 后即表示安装完成。

1
2
3
4
5
6
7
8

 _ __ _ _____ _ _
| | / / | | / __ \ (_)
| |/ / _ _| |__ ___| / \/ |_ _ __ _ __ ___ _ __
| \| | | | '_ \ / _ \ | | | | '_ \| '_ \ / _ \ '__|
| |\ \ |_| | |_) | __/ \__/\ | | |_) | |_) | __/ |
\_| \_/\__,_|_.__/ \___|\____/_|_| .__/| .__/ \___|_|
 | | | |
 |_| |_|

安装过程中需要去阿里云下载离线安装包，大概 1 分钟即可下载完成。

2.4 访问 Web UI

安装完成后，打开浏览器，访问 http://$IP 即可进入 KubeClipper 控制台。

kc-console-login.jpg

您可以使用默认帐号密码 admin / Thinkbig1 进行登录。

3. 快速上手体验

3.1 创建 K8s 集群

部署成功后可以使用 kcctl 工具或者通过控制台创建 k8s 集群， 这里咱们使用 kcctl 工具进行创建。

查看当前 agent 节点

1
2
3
4
5
6

root@lixd-dev-1:~# kcctl get node
+--------------------------------------+------------------------+---------+----------------+-------------+-----+--------+
| ID | HOSTNAME | REGION | IP | OS/ARCH | CPU | MEM |
+--------------------------------------+------------------------+---------+----------------+-------------+-----+--------+
| bf989745-73c7-4582-ab3a-f8f6c96b9ae7 | lixd-dev-1.taiko.local | default | 172.16.131.134 | linux/amd64 | 4 | 7937Mi |
+--------------------------------------+------------------------+---------+----------------+-------------+-----+--------+

然后使用以下命令创建 k8s 集群:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 其中 IP 为上一步中的 server1 节点 IP
root@lixd-dev-1:~# kcctl create cluster --name demo --master 172.16.131.134 --untaint-master
[2026-03-02T06:33:45Z][INFO] use default containerd version 1.7.29
[2026-03-02T06:33:45Z][INFO] use default calico version v3.29.6
[2026-03-02T06:33:45Z][INFO] use default k8s version v1.35.0
+------+---------+--------------+--------------+------------+----------------------------+-------------------------------+
| NAME | REGION | MASTER COUNT | WORKER COUNT | STATUS | APISERVER CERTS EXPIRATION | CREATE TIMESTAMP |
+------+---------+--------------+--------------+------------+----------------------------+-------------------------------+
| demo | default | 1 | 0 | Installing | | 2026-03-02 06:33:45 +0000 UTC |
+------+---------+--------------+--------------+------------+----------------------------+-------------------------------+

大概两分钟左右即可完成集群创建,可以使用以下命令查看实时日志：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

root@lixd-dev-1:~# kcctl get operation --selector kubeclipper.io/cluster=demo
+--------------------------------------+---------+---------------+------------+---------------------+-------+
| ID | CLUSTER | NAME | STATUS | CREATED AT | STEPS |
+--------------------------------------+---------+---------------+------------+---------------------+-------+
| 118e57ec-c467-4e11-8436-2813ec9e3b51 | demo | CreateCluster | successful | 2026-03-02 06:33:45 | 14 |
+--------------------------------------+---------+---------------+------------+---------------------+-------+

root@lixd-dev-1:~# kcctl logs 118e57ec-c467-4e11-8436-2813ec9e3b51 --summary --follow

===== Step: [2026-03-02 06:33:45] installRuntime (fd8ff5bb-dae1-481f-93a4-bfaeea44b402) [successful]
 Node: lixd-dev-1.taiko.local (172.16.131.134) bf989745-73c7-4582-ab3a-f8f6c96b9ae7 [successful] [4s]

===== Step: [2026-03-02 06:33:49] nodeEnvSetup (355a75de-6e39-44f0-b33b-05067c42e479) [successful]
 Node: lixd-dev-1.taiko.local (172.16.131.134) bf989745-73c7-4582-ab3a-f8f6c96b9ae7 [successful] [1s]

===== Step: [2026-03-02 06:33:49] installExtension (33bba175-5589-4ef6-889a-b99df53c4a6b) [successful]
 Node: lixd-dev-1.taiko.local (172.16.131.134) bf989745-73c7-4582-ab3a-f8f6c96b9ae7 [successful] [34s]

===== Step: [2026-03-02 06:34:23] installPackages (444027ce-66b3-4df6-8435-816bb8985bc7) [successful]
 Node: lixd-dev-1.taiko.local (172.16.131.134) bf989745-73c7-4582-ab3a-f8f6c96b9ae7 [successful] [41s]

===== Step: [2026-03-02 06:35:04] renderKubeadmConfig (d59b27e1-fdd6-4e02-8c63-4e21ee2c2d3d) [successful]
 Node: lixd-dev-1.taiko.local (172.16.131.134) bf989745-73c7-4582-ab3a-f8f6c96b9ae7 [successful] [1s]

===== Step: [2026-03-02 06:35:04] initControlPlane (d7b8db58-9169-420f-b1da-7a4cb80c1dc9) [successful]
 Node: lixd-dev-1.taiko.local (172.16.131.134) bf989745-73c7-4582-ab3a-f8f6c96b9ae7 [successful] [14s]

===== Step: [2026-03-02 06:35:18] cniImageLoader (0b3d3c34-80df-4b36-ac2c-6f007d11d681) [successful]
 Node: lixd-dev-1.taiko.local (172.16.131.134) bf989745-73c7-4582-ab3a-f8f6c96b9ae7 [successful] [44s]

....

或者使用以下命令查看集群状态

1

kcctl get cluster -o yaml|grep status -A5

也可以进入控制台查看实时日志。

进入 Running 状态即表示集群安装完成,您可以使用 kubectl 命令来查看集群健康状况。

1
2
3
4
5
6
7
8

root@lixd-dev-1:~# kubectl get cs
NAME STATUS MESSAGE ERROR
scheduler Healthy ok
controller-manager Healthy ok
etcd-0 Healthy ok
root@lixd-dev-1:~# kubectl get node
NAME STATUS ROLES AGE VERSION
lixd-dev-1.taiko.local Ready control-plane 2m55s v1.35.0

至此，我们的单节点版本就算是结束了，通过几条命令就快速创建出来一个 K8s 集群。

3.2 工作负载体验

进入工作负载界面

登录 Web UI 后，在集群管理界面，点击展开集群后的更多按钮，然后点击 工作负载 按钮跳转到工作负载界面： kc-console-workload1.png

工作负载界面展示

集群节点信息 kc-console-workload2.png

Deployment 管理： kc-console-workload3.png

更多功能就留给大家自行探索了~

4. 小结

KubeClipper 1.5.0 版本的发布标志着该项目在易用性、功能性和技术成熟度方面都达到了新的高度。作为一次重要的里程碑更新，1.5.0 不仅在用户体验上实现了质的飞跃，更在技术架构上为未来的发展奠定了坚实基础。

技术深度升级：

  • ✅ 现代化技术栈: Go 1.23 升级，依赖库全面更新，确保长期维护性
  • ✅ 广泛版本支持: 支持最新的 Kubernetes v1.35，满足不同环境需求
  • ✅ 生产级稳定性: 完善的健康检查、错误处理和系统服务管理
  • ✅ 安全性增强: 镜像仓库认证、TLS 优化等多层次安全防护

用户体验提升：

  • ✅ 简化操作: 工作负载 UI 管理，图形化界面降低学习成本
  • ✅ 全面兼容: 支持最新的 Kubernetes 生态系统和组件
  • ✅ 稳定可靠: 经过充分测试的生产级稳定性
  • ✅ 开源免费: 完全开源，社区活跃

对于正在寻找简单易用的 Kubernetes 管理平台的团队来说，KubeClipper 1.5.0 无疑是一个值得尝试的选择。无论是初学者还是经验丰富的运维人员，都能从这个版本中找到适合自己的价值点。

相关链接：