nanobot快速部署：Qwen3-4B模型服务Kubernetes Helm Chart封装指南

1. 引言：为什么需要封装nanobot？

如果你正在寻找一个轻量级、功能强大的个人AI助手，并且希望它能像标准应用一样，在Kubernetes集群中一键部署、轻松管理，那么nanobot的Helm Chart封装方案正是为你准备的。

nanobot是一个灵感来源于OpenClaw的超轻量级AI代理框架。它的核心魅力在于“小而精”——仅用大约4000行代码，就实现了核心的智能代理功能。相比之下，一些同类框架的代码量可能高达数十万行。这种极简设计带来的直接好处就是部署快速、资源占用少、维护简单。

但原生的部署方式往往涉及一系列手动步骤：配置环境、启动服务、检查日志、接入外部应用（如QQ机器人）等。对于需要在生产环境或团队中规模化使用的情况，这种方式就显得不够高效和规范。

本文将带你一步步完成nanobot的Kubernetes Helm Chart封装。通过这个指南，你可以将内置了vLLM推理引擎的Qwen3-4B-Instruct模型服务，以及基于Chainlit的Web交互界面，打包成一个标准的Helm Chart。最终实现的效果是：一行命令，即可在Kubernetes集群中拉起一个功能完整、配置灵活的nanobot服务。

2. 环境与工具准备

在开始封装之前，我们需要确保本地开发环境已经就绪。你不需要是Kubernetes或Helm的专家，但基本的了解会很有帮助。

2.1 核心工具清单

你需要准备以下工具，大部分都可以通过包管理器（如brew、apt或yum）轻松安装：

1. Kubernetes集群：用于最终部署和测试。你可以使用：
   • Minikube（本地单节点集群，适合开发和测试）
   • Kind（Kubernetes in Docker，轻量且快速）
   • 任何一个云服务商（如AWS EKS， Google GKE， Azure AKS）的托管集群
2. kubectl：Kubernetes命令行工具，用于与集群交互。
3. Helm：Kubernetes的包管理器，版本3.0以上。我们将用它来创建和安装Chart。
4. Docker：用于构建nanobot的服务镜像。
5. 基础的YAML/JSON编辑能力：用于编写Chart的模板和配置文件。

2.2 获取nanobot基础部署文件

Helm Chart的本质是一套模板和配置，其基础是应用本身能够运行。因此，我们首先需要理解nanobot服务是如何组成的。

根据提供的描述，nanobot服务主要包含两个核心组件：

• 模型推理服务：基于vLLM部署的Qwen3-4B-Instruct模型，提供AI能力。
• Web交互服务：基于Chainlit框架，提供用户与nanobot对话的Web界面。

此外，还有一个可选的Gateway服务，用于对接像QQ机器人这样的外部消息通道。

我们的目标是将这些组件，以及它们的配置、依赖关系，用Helm Chart清晰地定义出来。

3. 构建nanobot的Docker镜像

在Kubernetes中运行应用，首先需要将其容器化。我们将为nanobot创建一个Docker镜像。

3.1 编写Dockerfile

创建一个名为Dockerfile的文件，内容如下。这个Dockerfile基于一个轻量的Python镜像，并安装了nanobot运行所需的所有依赖。

# 使用一个包含CUDA的Python官方镜像作为基础，确保vLLM能使用GPU
FROM nvidia/cuda:12.1.1-runtime-ubuntu22.04

# 设置非交互式安装，避免apt-get命令提示
ENV DEBIAN_FRONTEND=noninteractive

# 安装系统依赖、Python及pip
RUN apt-get update && apt-get install -y \
    python3.10 \
    python3-pip \
    python3.10-venv \
    curl \
    vim \
    && rm -rf /var/lib/apt/lists/*

# 设置工作目录
WORKDIR /app

# 复制当前目录下的所有文件到容器的/app目录
# 假设你的nanobot代码、requirements.txt等文件都在这里
COPY . .

# 创建并激活虚拟环境（可选但推荐）
RUN python3 -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# 升级pip并安装Python依赖
RUN pip install --upgrade pip
# 根据你的nanobot项目实际需要的包来修改requirements.txt
RUN pip install -r requirements.txt

# 暴露服务端口（Chainlit默认端口是8000，根据你的配置调整）
EXPOSE 8000

# 设置容器启动时执行的命令
# 这里假设启动脚本是 start.sh，你需要根据实际情况创建这个脚本
CMD ["bash", "./start.sh"]

你需要创建一个requirements.txt文件，列出nanobot所需的Python包，至少应包括vllm, chainlit, nanobot（或其源码所需的依赖）等。

同时，创建一个start.sh启动脚本，用于在容器内启动模型服务和Web服务。一个简单的示例可能是先后台启动vLLM服务，再前台启动Chainlit。

3.2 构建并推送镜像

在包含Dockerfile的目录下，执行以下命令构建镜像：

docker build -t your-registry/your-username/nanobot:latest .

将 your-registry/your-username 替换为你自己的容器镜像仓库地址，例如 docker.io/myname 或私有仓库地址。

构建完成后，将其推送到镜像仓库：

docker push your-registry/your-username/nanobot:latest

注意：如果你使用Minikube，可以在Minikube的Docker环境中构建，避免镜像推送步骤：eval $(minikube docker-env)，然后直接构建。

4. 创建nanobot的Helm Chart

Helm Chart是一组文件的集合，它们描述了一个Kubernetes应用。我们现在来创建nanobot的Chart。

4.1 初始化Chart结构

使用Helm命令行工具创建一个标准的Chart骨架：

helm create nanobot-chart
cd nanobot-chart

这个命令会生成一个包含许多文件和目录的nanobot-chart文件夹。其中最关键的是：

• Chart.yaml: Chart的元数据（名称、版本、描述等）。
• values.yaml: Chart的默认配置值，用户可以通过覆盖它来自定义部署。
• templates/: 目录，里面包含了Kubernetes资源清单（如Deployment, Service, ConfigMap等）的模板文件。

4.2 编写核心模板文件

我们需要修改或创建templates/目录下的几个关键文件。首先，清理掉helm create生成的一些我们可能不需要的示例文件，比如templates/hpa.yaml, templates/ingress.yaml（除非你需要），然后专注于核心组件。

1. 部署模型推理服务 (Deployment for vLLM)

创建或编辑 templates/model-deployment.yaml。这个Deployment负责运行vLLM服务。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "nanobot-chart.fullname" . }}-model
  labels:
    {{- include "nanobot-chart.labels" . | nindent 4 }}
    component: model
spec:
  replicas: {{ .Values.model.replicaCount }}
  selector:
    matchLabels:
      {{- include "nanobot-chart.selectorLabels" . | nindent 6 }}
      component: model
  template:
    metadata:
      labels:
        {{- include "nanobot-chart.selectorLabels" . | nindent 8 }}
        component: model
    spec:
      containers:
      - name: {{ .Chart.Name }}-model
        image: "{{ .Values.model.image.repository }}:{{ .Values.model.image.tag | default .Chart.AppVersion }}"
        imagePullPolicy: {{ .Values.model.image.pullPolicy }}
        ports:
        - containerPort: {{ .Values.model.service.port }}
          name: http
        env:
        - name: MODEL_NAME
          value: {{ .Values.model.env.MODEL_NAME | quote }}
        # 添加其他必要的环境变量，例如HUGGINGFACE_HUB_TOKEN等
        {{- with .Values.model.env }}
        {{- toYaml . | nindent 8 }}
        {{- end }}
        resources:
          {{- toYaml .Values.model.resources | nindent 10 }}
        # 如果需要挂载模型文件或配置文件
        volumeMounts:
        - name: config-volume
          mountPath: /root/.nanobot
      volumes:
      - name: config-volume
        configMap:
          name: {{ include "nanobot-chart.fullname" . }}-config

2. 部署Web交互服务 (Deployment for Chainlit)

创建或编辑 templates/web-deployment.yaml。这个Deployment负责运行Chainlit Web界面。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "nanobot-chart.fullname" . }}-web
  labels:
    {{- include "nanobot-chart.labels" . | nindent 4 }}
    component: web
spec:
  replicas: {{ .Values.web.replicaCount }}
  selector:
    matchLabels:
      {{- include "nanobot-chart.selectorLabels" . | nindent 6 }}
      component: web
  template:
    metadata:
      labels:
        {{- include "nanobot-chart.selectorLabels" . | nindent 8 }}
        component: web
    spec:
      containers:
      - name: {{ .Chart.Name }}-web
        image: "{{ .Values.web.image.repository }}:{{ .Values.web.image.tag | default .Chart.AppVersion }}"
        imagePullPolicy: {{ .Values.web.image.pullPolicy }}
        ports:
        - containerPort: {{ .Values.web.service.port }}
          name: http
        env:
        - name: MODEL_API_URL
          value: http://{{ include "nanobot-chart.fullname" . }}-model:{{ .Values.model.service.port }}
        {{- with .Values.web.env }}
        {{- toYaml . | nindent 8 }}
        {{- end }}
        resources:
          {{- toYaml .Values.web.resources | nindent 10 }}
        volumeMounts:
        - name: config-volume
          mountPath: /root/.nanobot
      volumes:
      - name: config-volume
        configMap:
          name: {{ include "nanobot-chart.fullname" . }}-config

3. 创建配置文件 (ConfigMap)

nanobot需要一个配置文件（如config.json）来启用QQ机器人等功能。我们通过ConfigMap来管理这个配置。

创建 templates/configmap.yaml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "nanobot-chart.fullname" . }}-config
data:
  config.json: |
    {
      "channels": {
        "qq": {
          "enabled": {{ .Values.config.qq.enabled }},
          "appId": {{ .Values.config.qq.appId | quote }},
          "secret": {{ .Values.config.qq.secret | quote }},
          "allowFrom": {{ .Values.config.qq.allowFrom | toJson }}
        }
      }
    }

4. 创建服务 (Service)

为模型服务和Web服务分别创建Kubernetes Service，以便在集群内部或外部访问。

创建 templates/model-service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: {{ include "nanobot-chart.fullname" . }}-model
spec:
  type: {{ .Values.model.service.type }}
  ports:
    - port: {{ .Values.model.service.port }}
      targetPort: http
      protocol: TCP
      name: http
  selector:
    {{- include "nanobot-chart.selectorLabels" . | nindent 4 }}
    component: model

创建 templates/web-service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: {{ include "nanobot-chart.fullname" . }}-web
spec:
  type: {{ .Values.web.service.type }}
  ports:
    - port: {{ .Values.web.service.port }}
      targetPort: http
      protocol: TCP
      name: http
  selector:
    {{- include "nanobot-chart.selectorLabels" . | nindent 4 }}
    component: web

5. （可选）创建Gateway服务

如果你需要部署独立的Gateway服务来对接QQ机器人，可以参照Web服务的模板，创建 templates/gateway-deployment.yaml 和 templates/gateway-service.yaml。

4.3 配置Chart的默认值

现在，我们来填充 values.yaml 文件，为用户提供可配置的选项。这个文件定义了所有模板中引用的变量的默认值。

# values.yaml

# 全局配置
global:
  nameOverride: ""
  fullnameOverride: ""

# 模型推理服务配置
model:
  replicaCount: 1
  image:
    repository: your-registry/your-username/nanobot # 替换为你的镜像
    tag: latest
    pullPolicy: IfNotPresent
  service:
    type: ClusterIP
    port: 8001 # vLLM服务端口
  env:
    MODEL_NAME: "Qwen/Qwen2.5-4B-Instruct" # 模型名称
    # HUGGINGFACE_HUB_TOKEN: "" # 如果需要从Hugging Face下载模型
  resources:
    # 根据模型大小和预期负载调整资源请求和限制
    requests:
      memory: "8Gi"
      cpu: "2"
      nvidia.com/gpu: 1 # 申请GPU资源
    limits:
      memory: "16Gi"
      cpu: "4"
      nvidia.com/gpu: 1

# Web交互服务配置
web:
  replicaCount: 1
  image:
    repository: your-registry/your-username/nanobot # 与模型服务使用相同镜像，或专门的前端镜像
    tag: latest
    pullPolicy: IfNotPresent
  service:
    type: LoadBalancer # 或 NodePort， 以便从外部访问Web界面
    port: 8000 # Chainlit默认端口
  env: {}
  resources:
    requests:
      memory: "512Mi"
      cpu: "200m"
    limits:
      memory: "1Gi"
      cpu: "500m"

# 配置文件
config:
  qq:
    enabled: false
    appId: "YOUR_APP_ID"
    secret: "YOUR_APP_SECRET"
    allowFrom: []

4.4 完善Chart元数据

编辑 Chart.yaml，填写必要的信息：

apiVersion: v2
name: nanobot-chart
description: A Helm chart for deploying the nanobot lightweight AI assistant with Qwen3-4B model.
type: application
version: 0.1.0
appVersion: "1.0.0"

5. 打包、安装与测试

Chart创建完成后，就可以进行打包和安装了。

5.1 打包Chart

在nanobot-chart目录的上一级，运行：

helm package nanobot-chart

这会在当前目录生成一个 nanobot-chart-0.1.0.tgz 的压缩包。

5.2 安装到Kubernetes集群

首先，确保你的kubectl上下文指向正确的集群。然后，使用Helm进行安装。

方式一：直接安装本地Chart目录

helm install my-nanobot ./nanobot-chart -n nanobot --create-namespace

这条命令会在名为nanobot的命名空间中（如果不存在则创建），安装我们的Chart，并将这个Release命名为my-nanobot。

方式二：安装打包好的tgz文件

helm install my-nanobot nanobot-chart-0.1.0.tgz -n nanobot --create-namespace

5.3 自定义安装参数

安装时，你可以通过 --set 参数或指定自定义的 values.yaml 文件来覆盖默认配置。

例如，要启用QQ机器人并设置AppID：

helm install my-nanobot ./nanobot-chart -n nanobot \
  --set config.qq.enabled=true \
  --set config.qq.appId="你的AppID" \
  --set config.qq.secret="你的AppSecret"

或者，创建一个 custom-values.yaml 文件，然后使用：

helm install my-nanobot ./nanobot-chart -n nanobot -f custom-values.yaml

5.4 验证部署

安装完成后，使用以下命令检查Pod状态：

kubectl get pods -n nanobot

等待所有Pod的状态变为 Running。

查看Web服务的访问地址：

# 如果Service类型是LoadBalancer，等待EXTERNAL-IP分配
kubectl get svc -n nanobot
# 如果类型是NodePort，使用节点IP和端口访问
minikube service my-nanobot-web -n nanobot --url

通过获取的URL，你就能在浏览器中访问Chainlit界面，与nanobot进行对话了。你也可以查看模型服务的日志，确认vLLM是否成功加载了Qwen3-4B模型。

# 查看模型服务Pod的日志
kubectl logs -f deployment/my-nanobot-model -n nanobot

6. 总结与进阶

通过以上步骤，我们成功地将nanobot这个轻量级AI助手封装成了一个标准的Kubernetes Helm Chart。现在，部署和管理nanobot服务变得异常简单和规范。

回顾一下我们实现的核心价值：

1. 一键部署：从复杂的多步骤手动部署，简化为一条helm install命令。
2. 配置即代码：所有配置（镜像、端口、资源、功能开关）都集中在values.yaml中，易于版本管理和环境差异化（开发、测试、生产）。
3. 标准化与可移植性：Chart可以在任何符合标准的Kubernetes集群上运行，无论是本地环境还是云上。
4. 易于扩展与维护：通过修改Chart模板和值，可以轻松添加健康检查、资源限制、持久化存储、自动伸缩（HPA）等生产级特性。

下一步，你可以考虑：

• 持续集成/持续部署 (CI/CD)：将Chart的打包和发布流程集成到你的CI/CD流水线中。
• 私有Helm仓库：将打包好的nanobot-chart-0.1.0.tgz上传到像ChartMuseum这样的私有Helm仓库，方便团队共享。
• 完善生产配置：为Deployment添加livenessProbe和readinessProbe，配置更精细的资源管理和节点亲和性，设置PodDisruptionBudget等。
• 外部访问优化：通过Ingress控制器来统一管理外部访问，并配置TLS证书实现HTTPS。

封装Helm Chart的过程，是将一个应用“产品化”和“平台化”的关键一步。它不仅提升了部署效率，更重要的是为应用的规模化运维和生命周期管理奠定了坚实的基础。希望这份指南能帮助你顺利地将nanobot带入Kubernetes的世界。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。