6.2 安全与访问控制

6.2 安全与访问控制

当 Qdrant 服务暴露在网络中时，安全防护是不可忽视的环节。无论是内部服务调用还是对外提供 API，都需要建立完善的安全体系来防止未授权访问、数据泄露和恶意攻击。本章将详细介绍 Qdrant 的 API Key 认证、RBAC 权限模型、TLS 加密通信以及生产环境的安全最佳实践。

API Key 认证

API Key 是 Qdrant 最基础也是最常用的认证方式，适用于服务间的调用场景。

创建 API Key

通过 REST API 创建 API Key：

POST /api-keys
{
  "description": "search-service-key",
  "expires_at": "2027-01-01T00:00:00Z"
}
​

创建成功后返回完整的 API Key 字符串和 Key 的元信息。注意：完整的 API Key 只在创建时返回一次，后续无法再次查看。请务必在创建时妥善保存。

API Key 支持设置过期时间。对于长期使用的服务，建议设置较长的过期时间或不过期，但配合权限最小化原则使用。对于临时用途（如数据迁移），设置短期过期时间。

使用 API Key

在 HTTP 请求中通过 api-key Header 传递：

GET /collections HTTP/1.1
Host: qdrant.example.com
api-key: your-secret-api-key-here
​

Python 客户端中同样支持：

from qdrant_client import QdrantClient

client = QdrantClient(
    host="qdrant.example.com",
    port=6333,
    api_key="your-secret-api-key-here"
)
​

API Key 管理

Qdrant 提供了完整的 API Key 生命周期管理：

# 列出所有 API Key
GET /api-keys

# 删除指定 API Key
DELETE /api-keys/{api_key}
​

在生产环境中，建议建立以下管理流程：

1. 为每个调用服务创建独立的 API Key
2. 在 Key 的描述中标注服务名称和负责人
3. 定期审计 API Key 的使用情况
4. 离线服务或废弃项目的 Key 应及时删除
5. 怀疑 Key 泄露时立即删除并重新创建

RBAC 权限模型

Qdrant 从 v1.7 开始支持基于角色的访问控制（Role-Based Access Control），提供了更精细的权限管理能力。

核心概念

RBAC 模型包含三个核心概念：

角色（Role）：定义一组权限的集合。Qdrant 预定义了以下角色：

• read_only：只读权限，可以查询集合和搜索向量
• editor：读写权限，在只读基础上可以创建/更新/删除向量
• administrator：管理权限，在编辑基础上可以创建/删除集合和管理配置

权限（Permission）：定义对特定资源的操作权限：

• collections/{collection_name}/read
• collections/{collection_name}/write
• collections/*（通配符匹配所有集合）
• snapshots/read
• cluster/read
• cluster/write

主体（Subject）：权限的载体，可以是 API Key 或特定访问令牌。

创建和管理角色

# 创建自定义角色
PUT /roles/{role_name}
{
  "permissions": [
    {"collection": "product_vectors", "access": "read"},
    {"collection": "user_profiles", "access": "write"},
    {"collection": "*", "access": "read"}
  ]
}
​

这个角色允许：只读访问所有集合、读写访问 product_vectors 集合、读写访问 user_profiles 集合。

绑定角色到 API Key

创建 API Key 时指定其角色：

POST /api-keys
{
  "description": "search-service",
  "roles": ["search_only"],
  "expires_at": null
}
​

也可以为已有 API Key 添加或修改角色：

PUT /api-keys/{api_key}/roles
{
  "roles": ["read_only", "search_only"]
}
​

一个 API Key 可以绑定多个角色，最终的权限是所有角色权限的并集。

实际权限设计案例

场景一：搜索微服务

搜索服务只需要读取特定集合的数据：

角色: search_service
权限: collections/product_vectors/read, collections/user_profiles/read
绑定: 搜索服务的 API Key
​

场景二：数据导入管道

ETL 管道需要写入数据但不能删除：

角色: data_writer
权限: collections/product_vectors/write
绑定: 数据导入服务的 API Key
​

场景三：运维管理

运维人员需要完整的管理权限：

角色: ops_admin
权限: collections/*/write, snapshots/read, cluster/read, cluster/write
绑定: 运维团队的 API Key
​

场景四：多租户隔离

在多租户场景中，每个租户只能访问自己的集合：

角色: tenant_a
权限: collections/tenant_a_*/write
角色: tenant_b
权限: collections/tenant_b_*/write
​

TLS 加密通信

启用 HTTPS

在生产环境中，Qdrant 的所有 API 通信都应该通过 HTTPS 加密，防止数据在传输过程中被窃听或篡改。

在 Docker 中启用 TLS：

docker run -d \
  -p 6333:6333 \
  -v ./certs:/qdrant/certs \
  qdrant/qdrant \
  ./qdrant --tls-cert /qdrant/certs/server.crt --tls-key /qdrant/certs/server.key
​

配置文件方式：

tls:
  cert: /etc/ssl/qdrant/server.crt
  key: /etc/ssl/qdrant/server.key
  ca_cert: /etc/ssl/qdrant/ca.crt  # 用于客户端证书认证（mTLS）
​

客户端证书认证（mTLS）

对于安全要求更高的场景，可以启用双向 TLS（mTLS），要求客户端也提供有效证书：

tls:
  cert: /etc/ssl/qdrant/server.crt
  key: /etc/ssl/qdrant/server.key
  client_ca: /etc/ssl/qdrant/client-ca.crt
  client_cert: /etc/ssl/qdrant/client.crt
  client_key: /etc/ssl/qdrant/client.key
​

启用 mTLS 后，只有持有受信任客户端证书的请求才能通过认证。这种方式比 API Key 更安全，因为证书无法在请求中直接传递。

证书管理建议

• 使用 Let's Encrypt 或内部 CA 签发证书
• 设置证书自动续期机制
• 定期轮换证书（建议 90 天周期）
• 监控证书过期时间，提前续期

网络层安全

防火墙配置

即使启用了应用层认证，网络层防护仍然是重要的防线：

• Qdrant 的 gRPC 端口（6334）和 HTTP 端口（6333）只对必要的网络段开放
• 管理接口（如 API Key 管理）应限制为内网访问
• 在 Kubernetes 中使用 NetworkPolicy 限制 Pod 间通信

反向代理

在生产环境中，建议在 Qdrant 前面部署反向代理（如 Nginx、Envoy），提供以下能力：

• TLS 终端和证书管理
• 请求速率限制
• IP 黑名单/白名单
• 请求日志记录
• WAF（Web 应用防火墙）防护

Nginx 配置示例：

server {
    listen 443 ssl;
    server_name qdrant.example.com;

    ssl_certificate /etc/ssl/qdrant/server.crt;
    ssl_certificate_key /etc/ssl/qdrant/server.key;

    # 速率限制
    limit_req_zone $binary_remote_addr zone=qdrant:10m rate=100r/s;

    location / {
        limit_req zone=qdrant burst=50 nodelay;
        proxy_pass http://qdrant_backend:6333;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 管理接口限制内网访问
    location /api-keys {
        allow 10.0.0.0/8;
        deny all;
        proxy_pass http://qdrant_backend:6333;
    }
}
​

数据安全

Payload 加密

对于存储在 Qdrant 中的敏感 Payload 数据，建议在写入前由应用层进行加密。Qdrant 本身不提供字段级别的加密功能，但可以在应用层实现：

from cryptography.fernet import Fernet

fernet = Fernet(encryption_key)

# 写入前加密敏感字段
encrypted_data = fernet.encrypt(sensitive_payload.encode())

client.upsert(
    collection_name="user_data",
    points=[{
        "id": user_id,
        "vector": embedding,
        "payload": {
            "encrypted_profile": encrypted_data.decode(),
            "public_name": display_name  # 非敏感字段明文存储
        }
    }]
)

# 读取后解密
results = client.search(collection_name="user_data", query_vector=...)
for result in results:
    decrypted = fernet.decrypt(result.payload["encrypted_profile"].encode()).decode()
​

数据脱敏

对于日志和监控中可能暴露的数据，需要在应用层进行脱敏处理。避免将原始的向量数据或敏感 Payload 记录到日志中。

审计日志

启用 Qdrant 的结构化日志，记录所有操作请求。关键审计信息包括：

• 操作时间
• 调用方身份（API Key 或 IP）
• 操作类型（读/写/删除）
• 目标集合
• 操作结果（成功/失败）

将审计日志发送到独立的日志系统（如 Splunk、ELK），设置保留策略和合规审查流程。

安全检查清单

在部署 Qdrant 到生产环境前，逐项检查以下安全措施：

• API Key 认证已启用，默认空密码已禁用
• RBAC 角色已按最小权限原则配置
• TLS 加密通信已启用
• 管理接口仅限内网访问
• 防火墙规则已配置
• 反向代理已部署并配置速率限制
• 敏感数据在应用层加密
• 审计日志已启用并集中存储
• 证书自动续期机制已配置
• 安全事件告警已设置

总结

Qdrant 提供了多层安全防护能力，从 API Key 认证到 RBAC 权限控制，从 TLS 加密到网络层防护。在生产环境中，需要综合运用这些安全机制，建立纵深防御体系。记住：安全不是一次性的配置，而是持续的过程——定期审查权限、轮换密钥、更新证书，才能保障数据的长期安全。