DataBuff Kubernetes 部署完整指南:从单节点到生产集群
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 命名空间,安装完成后终端会打印当前生效的地址与账号:
| 用途 | 地址 |
|---|---|
| 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 服务已产生调用数、错误率与响应时间:
在 应用性能 → 全局拓扑 中,服务间调用关系会以拓扑图呈现,是验证多服务链路采集是否正常的最佳视图:
启用 AI 诊断(可选)
进入 配置管理 → 模型配置,点击「+ 新增」填入你的大模型 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。
相关文章
- docker安装部署.md — 不想用 K8s?一条命令也能跑起 DataBuff
- 遥测数据流.md — 理解 Ingest → Doris → Web 的数据链路
- opentelemetry-otlp-ingestion.md — 自有应用如何接入 OTLP 上报



