qdrant-hybrid-cloud-setup

设置 Qdrant Hybrid Cloud

你已经选择了 Hybrid Cloud（在自己的基础设施上托管控制平面）。如果你还在考虑，请使用 qdrant-deployment-options 技能。大多数设置失败都源于以下两点之一：存储（CSI 驱动程序无法满足 Qdrant 的需求）或连接（Agent 无法连接到 Qdrant Cloud）。请先判断是哪一种，再处理其他问题。

准备 Kubernetes 集群（先做这一步）

适用场景：即将创建环境，或安装／集群配置在存储环节失败。

• Qdrant 需要块存储 CSI 驱动程序。不支持网络存储（NFS）和对象存储（S3）：连接到这些存储的集群会直接失败，而非性能降级 Prerequisites。
• 请提前创建 StorageClass（并设置 allowVolumeExpansion: true）和 VolumeSnapshotClass，不要等到之后再创建。没有卷扩展功能，就无法在之后扩容磁盘；没有 VolumeSnapshotClass 和 CSI 快照控制器，就无法创建备份。
• 任何符合标准的 Kubernetes 集群都可以使用，并且有针对各托管平台的专属设置指南：Akamai（Linode/LKE）、AWS（EKS）、Civo、DigitalOcean（DOKS）、Gcore、GCP（GKE）、Azure（AKS）、Oracle（OKE）、OVHcloud、Red Hat OpenShift、Scaleway、STACKIT 和 Vultr Deployment Platforms。
• 平台会影响存储支持情况：有些平台（例如 Linode/LKE、Vultr）完全不支持 CSI 卷快照，因此无法在这些平台上创建备份。请查看云服务提供商的快照页面，并在确定方案前优先选择其推荐的实例和磁盘类型（例如 EKS 上的 gp3、AKS 上的 Premium SSD v2）。
• 确认出站连接正常：Agent 会通过 443 端口连接到 grpc.cloud.qdrant.io 和 api.cloud.qdrant.io。防火墙／出站代理可能会悄无声息地阻断连接：“安装卡住”通常就是这个原因。
• 你需要 cluster-admin 权限，并且要配置好指向目标集群的 kubectl 和 helm。

创建环境

适用场景：在 Cloud Console 中运行安装向导。

• Kubernetes 命名空间是永久设置：这是唯一一个之后无法更改的选项。其他所有设置（节点选择器、容忍度、注册表 URL、代理）都可以在创建后编辑，因此现在不必过度纠结。
• 向导会生成一次性安装命令，用于创建密钥并通过 Helm 安装 Agent 和运算符。仅初次安装时需要使用此命令；之后可通过 Console 更新 Setup guide。
• 运算符的高级行为（Pod 调度、安全上下文、入口、网络和快照管理）可在环境级别的运算符配置中调整，并且可以在安装后更改 Operator configuration。
• 环境是否隔离网络，或是否限制注册表访问？请将 /qdrant/ 镜像和 /qdrant-charts/ chart 镜像到自己的注册表，并在环境的高级设置中配置容器和 chart 的 URL。请同步所有架构（或正确的架构），否则 ARM／x86 节点将无法拉取镜像。

在环境中创建集群

适用场景：环境已存在，且你正在配置数据库。

• 在此处选择 Database Storage Class 和 Volume Snapshot Class。将 Volume Snapshot Class 设为 None 会禁用备份；将快照卷设为 emptyDir 会使其成为临时卷（在 Pod 重启时丢失）：这些都是需要慎重考虑的选择，不应盲目接受默认值 集群创建。
• 默认情况下，Qdrant Cloud 会为每个 Pod 预留约 20% 的 CPU 和内存，用于操作系统和系统组件。小型节点可能需要预留更多，大型节点则可能需要更少。建议每个节点运行一个数据库 Pod。
• 使用节点选择器／容忍度／拓扑分布约束，让数据库运行在专用节点上，并分散到不同可用区。

暴露和保护集群

适用场景：Kubernetes 集群外的应用需要访问 Qdrant，或有人询问 API 密钥／TLS。

• 默认使用 ClusterIP 服务：仅供内部访问，没有 API 密钥。一旦将其暴露出去（使用 LoadBalancer、NodePort 或 Ingress），就必须配置 API 密钥，并将其作为 Kubernetes Secret 提供，在集群配置中引用 网络与安全。
• 节点间的内部 gRPC 使用端口 6335，且始终不受 API 密钥或 TLS 保护。绝不能将其公开访问；Hybrid Cloud 提供了限制该端口的 NetworkPolicy，不要放宽限制。
• TLS：在 Ingress／LB 处卸载 TLS，或通过 TLS Secret 在 Qdrant 中终止 TLS。不要意外地同时使用两种方式。

日志记录

适用场景：设置日志级别，或将集群日志接入你的技术栈。（如需使用指标／Prometheus／Grafana，请改用 qdrant-monitoring 技能。）

• 日志级别有两处不同的设置位置：数据库级别的日志在 Cluster 详情页设置，而 Agent 和 Operator 的日志级别在 Hybrid Cloud Environment 配置中设置，不是在集群级别设置 网络、日志记录与监控。
• 日志是普通的 Pod 日志，没有 Qdrant 专用格式。将任何支持 Kubernetes 的日志收集器指向 Qdrant 命名空间中的所有 Pod 即可，无需进行 Qdrant 专属配置。

不要做的事

• 不要在 NFS、S3 或任何非块存储上配置资源：这不受支持，会直接失败，而不只是运行缓慢。
• 不要事后才创建 StorageClass／VolumeSnapshotClass（或启用 allowVolumeExpansion），然后才发现无法扩展磁盘或创建备份。必须提前创建。
• 不要假定 Linode 或 Vultr 上的备份“开箱即用”：先确认你的平台支持 CSI 快照。
• 不要在未设置 API 密钥的情况下通过 LoadBalancer／Ingress 暴露集群，也不要让端口 6335 可从公网访问。
• 不要重新生成安装命令（或轮换密钥）后忘记重新应用：在你重新应用之前，Agent 到 Cloud 的连接会悄无声息地中断。
• 删除 Hybrid Cloud 环境前，先删除其中的集群：先拆除集群，再删除环境，最后运行清理脚本，否则集群中会遗留资源。