Qdrant 如何配置 API Key 认证

Qdrant 如何配置 API Key 认证Qdrant 是当下最流行的向量数据库之一广泛应用于 RAG检索增强生成、相似度搜索、AI 应用等场景。生产环境中API Key 认证是保障数据安全的基本手段。本文详细介绍 Qdrant 的 API Key 配置方法涵盖配置文件、环境变量、客户端使用及常见踩坑指南。一、为什么需要 API Key 认证Qdrant 默认不开启认证任何知道服务地址的人都可以访问和操作数据。在生产环境中这意味着未经授权的数据读写任何人只要能连通服务就可以查询、添加、删除向量数据服务被恶意利用可能被用来存储恶意内容或遭受 DDoS 攻击合规风险数据泄露可能导致严重的法律责任开启 API Key 认证后每次 API 请求都必须携带有效的 KeyKey 不匹配则返回 401 未授权错误。二、配置方法2.1 通过配置文件Qdrant 的配置文件通常命名为config.yaml主要配置项如下# 服务绑定地址service:host:0.0.0.0http_port:6333grpc_port:6334# API Key 认证配置api_key:# 启用 API Key 认证默认关闭enabled:true# API Key 列表支持多个 keyapi_key:your-secret-api-key-here# 可选更细粒度的控制区分只读 key 和读写 keyread_only_api_key:your-read-only-key-here# 存储配置storage:storage_path:./storage关键点说明api_key为主 Key拥有读写权限read_only_api_key为可选配置仅允许读取操作GET请求不能执行写入、更新、删除两个 Key 可以同时生效互不冲突简化场景仅一个读写 Keyapi_key:enabled:trueapi_key:my-secret-key-123452.2 通过环境变量不方便修改配置文件时可以直接使用环境变量启动 Qdrant# 启用认证 设置读写 KeyQDRANT_API_KEY_ENABLEDtrueQDRANT_API_KEYmy-secret-key-12345 ./qdrant# 如果需要只读 KeyQDRANT_READ_ONLY_API_KEYmy-readonly-key ./qdrantDocker 方式dockerrun-p6333:6333\-eQDRANT_API_KEY_ENABLEDtrue\-eQDRANT_API_KEYmy-secret-key-12345\qdrant/qdrantDocker Compose 方式version:3.8services:qdrant:image:qdrant/qdrant:latestports:-6333:6333-6334:6334environment:QDRANT_API_KEY_ENABLED:trueQDRANT_API_KEY:my-secret-key-12345QDRANT_READ_ONLY_API_KEY:readonly-key-67890volumes:-./qdrant_storage:/qdrant/storage⚠️注意环境变量QDRANT_API_KEY_ENABLED必须是字符串true而不是布尔值true。三、客户端如何使用 API Key开启认证后所有 API 请求都需要在请求头中携带 Key。3.1 Python 客户端使用官方 Python SDKfromqdrant_clientimportQdrantClient# 方式一初始化时指定clientQdrantClient(urlhttp://localhost:6333,api_keymy-secret-key-12345)# 方式二连接后指定clientQdrantClient(urlhttp://localhost:6333)client.set_api_key(my-secret-key-12345)# 验证连接print(client.get_collections())3.2 REST API 直接调用# 不带 Key会返回 401curlhttp://localhost:6333/collections# 带 Key认证成功curl-Hapi-key: my-secret-key-12345http://localhost:6333/collections# 只读 Key 也能正常读取curl-Hapi-key: readonly-key-67890http://localhost:6333/collections3.3 Java 客户端importio.qdrant.client.QdrantClient;importio.qdrant.client.QdrantClientFactory;QdrantClientclientnewQdrantClientFactory().build(http://localhost:6333,my-secret-key-12345);// 获取所有 collectionvarcollectionsclient.listCollectionsAsync().join();System.out.println(collections);3.4 JavaScript / TypeScriptimport{QdrantClient}fromqdrant/qdrant-js;constclientnewQdrantClient({url:http://localhost:6333,apiKey:my-secret-key-12345,});constcollectionsawaitclient.getCollections();console.log(collections);四、API Key 的安全建议生产环境务必启用本地开发可以用无认证模式生产环境必须开启使用强随机 Key避免使用简单字符串建议使用 32 位以上的随机字符可以用以下方式生成openssl rand-hex32# 输出示例a3f8b2c1d4e5f6789012345678901234567890abcdef1234567890abcdef123456分离读写 Key只读业务用只读 Key避免误操作导致数据被修改或删除定期轮换 Key定期更换 Key尤其是团队人员变动时通过环境变量注入不要把 Key 硬编码在代码或配置文件中通过环境变量或密钥管理服务KMS注入更安全五、常见问题Q1开启了认证但客户端还是报 401常见原因有两个Key 不匹配检查配置文件和环境变量中的 Key 是否完全一致注意前后没有多余空格HTTP vs HTTPS如果通过代理或网关访问确认代理层没有修改请求头# 确认服务是否正确读取了 Key 配置curl-ihttp://localhost:6333/collections# 如果返回 401说明认证已生效Q2开启了只读 Key写入操作返回什么{status:{error:Wrong access rights. Read only access}}Q3服务启动后看不到 Key 配置生效检查 Qdrant 启动日志如果看到类似以下输出说明认证已正确开启[2026-03-27T10:00:00Z INFO qdrant::api_key] API Key authentication enabled [2026-03-27T10:00:00Z INFO qdrant::api_key] Read-only API Key is setQ4Docker 容器中环境变量不生效Docker Compose 中环境变量值必须加引号environment:QDRANT_API_KEY_ENABLED:true# ✅ 字符串 trueQDRANT_API_KEY:my-key# ✅ 引号包裹六、快速验证启动带认证的 Qdrant 后用以下命令快速验证# 1. 不带 Key应当返回 401curl-s-o/dev/null-w%{http_code}http://localhost:6333/collections# 输出401# 2. 带正确 Key应当返回 200curl-s-o/dev/null-w%{http_code}\-Hapi-key: my-secret-key-12345\http://localhost:6333/collections# 输出200# 3. 用只读 Key 尝试写入应当返回 403curl-s-XPUT\-Hapi-key: readonly-key-67890\-HContent-Type: application/json\-d{name: test_collection}\http://localhost:6333/collections/test_collection# 输出403总结Qdrant 的 API Key 认证配置简单直观通过config.yaml或环境变量即可开启。建议开发测试可以先跳过认证快速迭代预生产/灰度开启只读 Key验证客户端兼容性生产环境开启读写 Key 只读 Key严格分离权限配合 HTTPS 使用API Key 认证能有效保护你的向量数据安全。