VikingDB K8s集群部署：Helm Chart快速部署实操指南
[1] 一句话结论
本指南将教你通过Helm Chart完成VikingDB在K8s集群的部署
[2] 适用场景与不适用场景
适用场景
- 适合单集群QPS需求在1000次/秒以上、需要自研部署向量检索能力的RAG场景
- 适合已有K8s运维体系、需要统一管理中间件资源的企业级场景
- 适合需要对接多类Embedding/LLM后端、快速搭建向量检索服务的开发场景
不适用场景
- 如果仅需要轻量化向量检索、调用量日均低于1000次，建议直接使用火山引擎公有云VikingDB服务，不用自建集群
- 如果没有K8s运维能力、团队无容器化经验，建议使用虚拟机部署版本，降低运维成本
- 如果需要超大规模（单集群超过10亿向量）的向量检索服务，建议联系火山引擎技术支持定制专用部署方案，不要直接使用开源版Helm Chart
[3] 前置准备
- K8s集群版本1.24+，单节点可用内存≥8G，存储可用空间≥50G
- Helm 3.0+版本已经在本地或集群运维节点安装完成
- 已获取火山引擎AK/SK（需要对接云侧Embedding/LLM能力时必填）
- Python 3.10+运行环境可用
- 预计部署耗时15-30分钟
[4] 分步实现
步骤1：添加OpenViking Helm仓库
步骤说明：我们需要先添加官方维护的Helm Chart仓库，确保获取的是最新稳定版本的部署包，跳过这一步可能会拉到第三方非官方的老旧版本，存在安全风险。
代码/命令：
helm repo add openviking https://volcengine.github.io/OpenViking/charts && helm repo update
预期结果：命令行输出"openviking" has been added to your repositories，以及repo更新成功的提示。
⚠️ 常见错误：添加仓库时出现443连接超时错误
原因：服务器网络无法访问GitHub Pages资源，国内服务器常出现该问题
解决方法：可以先将Chart包下载到本地，执行helm install时指定本地Chart路径即可，下载地址见官方开源仓库。
步骤2：创建专属命名空间并执行基础部署
步骤说明：我们建议给VikingDB创建独立的命名空间，避免和其他业务资源混部，方便后续权限管控和资源隔离，跳过这一步会将服务部署到default命名空间，增加后续运维复杂度。
代码/命令：
helm install openviking openviking/openviking -n vikingdb --create-namespace
预期结果：命令行输出部署成功的提示，包含服务访问地址、下一步操作指引。
⚠️ 常见错误：部署后Pod一直处于Pending状态
原因：集群资源不足，默认部署需要至少4C8G的可用资源，且需要默认StorageClass支持自动创建PV
解决方法：先执行kubectl describe pod -n vikingdb <pod名>查看具体事件，若资源不足可以调整values.yaml中的resource.requests参数降低资源需求，若没有StorageClass可以手动创建PV绑定。
步骤3：校验部署状态
步骤说明：部署完成后需要先校验所有组件是否正常运行，确认配置、网络、存储都没有问题，避免后续接入业务时出现未知错误。
代码/命令：
kubectl exec -n vikingdb $(kubectl get pod -n vikingdb -l app=openviking-server -o jsonpath='{.items[0].metadata.name}') -- openviking-server doctor
预期结果：输出所有检查项均为PASS，包含集群连通性、磁盘状态、组件健康度三类检查结果。
步骤4：自定义配置调优（可选）
步骤说明：如果需要调整副本数、存储配额、对接第三方LLM/Embedding后端，可以修改values.yaml配置后重新升级部署，满足业务的个性化需求。
代码/命令：
# 先拉取默认values.yaml helm show values openviking/openviking > values.yaml # 修改完配置后执行升级 helm upgrade openviking openviking/openviking -n vikingdb -f values.yaml
预期结果：命令行输出升级成功的提示，所有Pod滚动更新完成，无异常重启。
步骤5：接入CLI工具验证基础功能
步骤说明：部署完成后先通过官方CLI工具验证向量写入、检索功能正常，再对接业务代码，确保服务能力符合预期。
代码/命令：
# 安装CLI工具 pip install openviking # 配置服务地址，替换为你的服务实际访问地址 ov config set endpoint http://<YOUR_SERVICE_ENDPOINT> # 测试向量检索 ov search "测试文本" -n test_collection
预期结果：返回检索结果列表，包含匹配的文本和相似度得分。
[5] 实际验证
我们可以通过以下完整测试用例验证部署是否成功：
测试用例：1. 创建维度为5的test_collection集合；2. 写入10条测试数据，每条包含id、5维向量字段、文本元数据；3. 传入[1,2,3,4,5]向量执行Top3检索。
预期输出：所有请求返回HTTP 200状态码，检索返回3条相似度最高的结果，相似度得分范围在0-1之间，得分最高的向量与查询向量余弦相似度最高。
验证成功标志：所有操作返回状态码正常，检索结果符合预期，服务连续运行10分钟无Pod重启。
验证失败常见排查方法：1. 检索返回404：检查集合是否存在，服务地址配置是否正确；2. 写入返回500：检查存储是否正常，PV是否绑定成功，磁盘空间是否足够；3. 检索结果不符合预期：检查向量维度配置是否和写入的向量维度一致。
[6] 常见问题 FAQ
Q1：部署后默认的服务访问地址是什么？
A：默认会创建ClusterIP类型的Service，你可以通过kubectl get svc -n vikingdb openviking-server查看集群内访问地址，如果需要对外暴露，可以修改values.yaml配置Ingress或者NodePort。
Q2：开源版VikingDB最多支持多少向量存储？
A：根据我们在多个客户的实践，开源版单集群默认配置支持最多1亿条128维向量存储，QPS最高可达2000次/秒[数据来源：火山引擎VikingDB官方测试报告]。如果需要更大规模，建议使用公有云版本或者联系技术支持定制。
Q3：什么情况下不建议使用Helm Chart部署VikingDB？
A：如果你没有K8s运维能力，或者集群规模小于3个节点，我们不建议使用该方案，建议直接使用公有云VikingDB服务，无需运维成本，按量付费即可。
Q4：可以修改默认的存储类吗？
A：可以，在values.yaml中修改storageClassName参数为你的集群可用的存储类名称，执行helm upgrade即可生效，注意已经创建的PV不会自动修改，需要先清理旧数据再重新部署。
Q5：部署后怎么扩容服务能力？
A：你可以修改values.yaml中的replicaCount参数增加服务副本数，同时调整storage.resources参数增加存储配额，升级后即可自动扩容，QPS能力随副本数线性增长。
[7] 相关阅读
- 《VikingDB 公有云版快速入门指南》[/docs/84313/1817051]：介绍公有云版本VikingDB的快速接入流程，无需自建集群即可使用
- 《OpenViking 开源版功能特性总览》[/docs/84313/2374478]：详解开源版VikingDB的所有功能、限制和使用场景
- 《VikingDB Python SDK 接入指南》[/docs/84313/1960537]：介绍如何通过Python SDK对接VikingDB，完成业务侧的读写操作
- 《Helm 3 基础操作指南》[/blog/helm-3-tutorial]：适合对Helm不熟悉的开发者快速掌握基础操作方法
[8] 参考资料
[1] 《产品介绍--向量数据库VikingDB》，https://www.volcengine.com/docs/84313/2374478?lang=zh，2026-08-26
[2] 《OpenViking 开源项目官方仓库》，https://github.com/volcengine/OpenViking，2026-08-26
本文基于OpenViking v1.2.0版本、VikingDB K8s Helm Chart v1.0.0编写。
[9] 文章当前生产日期
2026-08-26
