DataBuff Kubernetes 部署完整指南:从单节点到生产集群

原创2026-11-01 09:04:541,686 阅读

DataBuff Kubernetes 部署完整指南:从单节点到生产集群

DataBuff Kubernetes 部署并不复杂:一条命令即可在 K8s 集群中自动拉起 ZooKeeper、Apache Doris、Ingest 与 Web 四个组件,并完成建库建表。本文面向新手和普通用户,讲清楚如何从零开始在 Kubernetes 上部署 DataBuff 这套基于 OpenTelemetry 的 AI 原生 APM 平台,以及如何从单节点演示扩展到多副本生产集群。

📖 本文内容对应仓库文档:k8s安装部署.md、K8s运维.md,全部部署脚本与清单位于 deploy/k8s/ 目录。

一、部署前准备:3 项环境要求

在执行 DataBuff K8s 一键安装之前,请确认以下三项:

要求 说明
Kubernetes 集群 任意发行版均可,k3s / kubeadm / 云厂商托管集群都行
kubectl 可访问集群 安装脚本会自动探测 KUBECONFIG、/etc/rancher/k3s/k3s.yaml、~/.kube/config、/etc/kubernetes/admin.conf 等常见路径
推荐资源 8C16G(8 核 CPU / 16GB 内存)

各组件默认资源限制如下(详见 manifests/doris.yaml、manifests/ingest.yaml、manifests/web.yaml):

组件 CPU limit 内存 limit
Doris FE + BE 1 + 2 2Gi + 6Gi
ingest 2 5Gi
web 1 2Gi
ZooKeeper 0.5 512Mi

二、一键安装 DataBuff:单条命令完成部署

确认 kubectl 可用后,执行安装脚本 ai-apm-k8s-install.sh:

curl -fsSL https://databuff.ai/databuff/ai-apm-k8s-install.sh | bash

脚本全自动执行 5 个阶段:检查环境 → 清理旧版本 → 下载部署包 → 解压到 /opt/databuff-ai-apm-k8s → 按顺序部署(ZooKeeper + Doris → 等待就绪并执行初始化 SQL → ingest + web),全程无需人工输入。

如果想固定版本安装:

curl -fsSL https://databuff.ai/databuff/ai-apm-k8s-install.sh | bash -s -- --version 0.1.8

DataBuff Kubernetes 部署一键安装成功后的终端输出,显示服务已就绪及访问地址

记住这组访问地址

所有组件默认部署在 databuff 命名空间,安装完成后终端会打印当前生效的地址与账号:

用途 地址
Web UI(NodePort) http://<节点IP>:32703
OTLP gRPC(集群外) <节点IP>:30417
OTLP HTTP(集群外) http://<节点IP>:30418
OTLP HTTP(集群内 Agent 上报) http://ai-apm-ingest:4318

默认登录账号:admin / Databuff@123。集群内的应用只要把 OTLP endpoint 指向 ai-apm-ingest:4318 即可接入,无需 NodePort。

三、安装 Demo 造数:快速验证部署成功

平台装好后,最直观的体验方式是在同一集群里跑一个 Demo 应用持续上报 Trace:

curl -fsSL https://databuff.ai/databuff/ai-apm-demo-k8s-install.sh | bash

该脚本部署 demo-seeder.yaml 中的 ai-apm-demo Deployment,每隔 30 秒向 http://ai-apm-ingest:4318/v1/traces 发送模拟调用链数据。

打开 http://<节点IP>:32703 登录后,进入 应用性能 → 服务,即可看到 Demo 服务已产生调用数、错误率与响应时间:

DataBuff Kubernetes 部署后服务列表页面,展示 demo 服务的调用数与响应时间指标

在 应用性能 → 全局拓扑 中,服务间调用关系会以拓扑图呈现,是验证多服务链路采集是否正常的最佳视图:

DataBuff Kubernetes 部署后的全局拓扑图,展示 demo 服务间调用关系

启用 AI 诊断(可选)

进入 配置管理 → 模型配置,点击「+ 新增」填入你的大模型 API Key 即可启用 AI 对话与智能巡检:

DataBuff 模型配置页面,在 Provider 弹窗中填入 API Key 启用 AI 诊断

配置完成后到 AI 平台 → AI 对话 试一句:「查询最近1小时的服务列表」。

四、从单节点到生产集群:Ingest 多副本扩展

默认单副本 ingest 以 standalone 模式运行,满足单节点演示。生产环境流量上来后,可以把 ingest 扩展为多副本——ai-apm-config 中已默认开启集群协调(INGEST_CLUSTER_ENABLED=true,见 configmap.yaml),依赖 ZooKeeper 做成员发现与选主:

kubectl scale deploy/ai-apm-ingest -n databuff --replicas=4
kubectl rollout status deploy/ai-apm-ingest -n databuff

多副本时的关键机制:

  • 每个 Pod 通过 Downward API 注入 POD_IP,启动时向 ZooKeeper 注册 <POD_IP>:18112 的 gRPC endpoint;
  • 跨节点的 partial 数据转发由 GrpcClusterPartialForwarder 完成,实现 Trace 二次聚合;
  • Pod 重启后 IP 变化会自动重新注册 ephemeral 节点,无需人工干预;
  • 单副本时自动按 standalone 运行,缩回 1 副本同样无缝。

⚠️ 生产注意事项:演示版 Doris 清单使用 emptyDir 存储,Pod 重建后数据丢失,需重新执行初始化 SQL(databuff.sql)。生产集群请为 Doris 挂载持久化存储卷(PVC)后再启用多副本。

五、离线集群:K8s 镜像离线加载

节点无法直接拉取镜像时,在每个节点上执行(自动识别 amd64 / arm64):

curl -fsSL https://databuff.ai/databuff/ai-apm-k8s-download-images.sh | bash

k3s / containerd 节点需指定加载命令:

export IMAGE_LOAD_CMD=ctr
curl -fsSL https://databuff.ai/databuff/ai-apm-k8s-download-images.sh | bash

仅升级 ingest / web 镜像(不更新 Doris / ZooKeeper)时使用 ai-apm-k8s-download-apm-images.sh;离线镜像细节见 K8s运维.md 的「离线镜像」一节。

六、日常运维速查

操作 命令
停止服务(缩容至 0,保留 Service/ConfigMap) ./stop.sh(stop.sh)
仅启动不卸载 ./start.sh
查看 ingest 日志 kubectl logs -n databuff deploy/ai-apm-ingest -f
Web 健康检查 kubectl exec -n databuff deploy/ai-apm-web -- wget -qO- http://127.0.0.1:27403/health
Ingest 健康检查 kubectl exec -n databuff deploy/ai-apm-ingest -- wget -qO- http://127.0.0.1:4318/health

常见问题:

现象 排查
服务列表为空 确认 Agent OTLP endpoint 指向 http://ai-apm-ingest:4318(集群外用 NodePort)
Pod 启动失败 kubectl describe pod -n databuff <pod> 查看 Events,检查节点内存
无法连接 API 先配置 kubeconfig 再执行安装脚本

更多场景(参数配置、启停细节、故障定位)请参考 K8s运维.md 与 常见问题.md。

相关文章

登录后查看全文
databuff