DBX 中的 Qdrant 1.8 本地测试环境：冒烟数据、Compose 配方与 API Key 认证验证

数据库客户端数据库桌面应用CLI后端MCP 服务AI 应用【免费下载链接】dbx25 MB lightweight cross-platform database client for 90 databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90 数据库提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。项目地址https://gitcode.com/gh_mirrors/dbx7/dbx点击查看免费下载本篇指南以 deploy/database/qdrant/1.8/init/README.md 为核心结合仓库内的 Compose 配方、冒烟测试定义与驱动实现系统讲解 DBX 项目如何为 Qdrant 1.8.3 搭建可重复创建的本地测试环境。读完你将掌握Qdrant 配方目录的完整结构、data命名卷与向量数据持久化的关系、verify冒烟验证如何携带api-key头执行带认证的 HTTP 请求以及如何用make db*系列目标一键启动、验证、停机和重置这一环境并直接在 DBX 桌面端建立 Qdrant 连接。一、配方概览一份冒烟数据说明文件背后的完整环境deploy/database/qdrant/1.8/init/README.md是 Qdrant 1.8 配方目录中的说明文件全文虽然简短却精确概括了该测试环境的三个核心事实Qdrant stores its vectors in the nameddatavolume. Theverifycommand sends an authenticated HTTP request using the configured admin API key (123456by default).翻译过来即Qdrant 将向量数据保存在名为data的命名卷中verify命令使用配方中配置的管理员 API Key默认123456发送带认证的 HTTP 请求来完成冒烟验证。这三点分别对应仓库中三个实际文件构成一个完整的测试环境配方。依据 deploy/database/README.zh-CN.md 的配方结构说明每个带版本的配方目录遵循统一约定product/version/ ├── recipe.json # 连接字段和冒烟命令 ├── compose.yaml # Docker Compose 环境 └── init/ # 环境初始化数据Qdrant 1.8 的目录结构如下deploy/database/qdrant/1.8/recipe.json声明数据库类型、镜像、平台、连接字段、宿主端口与冒烟步骤deploy/database/qdrant/1.8/compose.yaml定义容器、端口映射、环境变量、健康检查与data命名卷deploy/database/qdrant/1.8/init/README.md本指南的主体文档说明冒烟数据与验证方式。配方以qdrant1.8作为选择器make db-list会按产品归并展示所有配方见 scripts/database-env.mjs 中的discoverRecipes与databaseListRows。二、Compose 配方逐项拆解命名卷、端口映射与 API Key 注入compose.yaml 是整个环境的运行定义全文如下services: database: image: docker.cnb.cool/znb/images/qdrant:v1.8.3 container_name: dbx-qdrant-1.8 restart: always ports: - ${DB_BIND_ADDRESS:-127.0.0.1}:${DB_PORT:-11200}:6333 - ${DB_BIND_ADDRESS:-127.0.0.1}:${QDRANT_GRPC_PORT:-11201}:6334 environment: QDRANT__SERVICE__API_KEY: ${DB_PASSWORD:-123456} volumes: - data:/qdrant/storage healthcheck: test: [CMD-SHELL, bash -c /dev/tcp/127.0.0.1/6333] interval: 5s timeout: 5s retries: 30 start_period: 10s volumes: data:结合 init/README.md 的说明逐项解读1. 命名卷data向量持久化的位置Qdrant 服务端把数据目录挂在/qdrant/storage下宿主侧使用名为data的Docker 命名卷volumes: data:块声明。这正是 README 第一句Qdrant stores its vectors in the nameddatavolume的出处——容器重启后向量、集合与索引仍然保留而不是像匿名卷或容器层那样随生命周期丢失。命名卷是 scripts/database-env.mjs 中配方校验的硬性要求validateRecipe会检查 compose.yaml 必须声明命名卷且目标服务必须挂载命名卷serviceHasNamedVolume渲染后的 Compose 配置也必须包含type volume的挂载validateRenderedCompose。make db-reset DBqdrant1.8 CONFIRM1会执行docker compose down --volumes --remove-orphans即删除该命名卷及其中的全部向量数据因此必须显式传入CONFIRM1确认见 Makefile 与assertResetConfirmed。2. 端口映射HTTP 与 gRPC 双协议Qdrant 同时暴露两种协议端口协议容器端口默认宿主端口覆盖变量HTTP REST API633311200DB_PORTgRPC API633411201QDRANT_GRPC_PORT所有映射默认绑定127.0.0.1通过${DB_BIND_ADDRESS:-127.0.0.1}仅本机可访问如需远程访问必须显式设置DB_BIND_ADDRESS0.0.0.0同时配合强密码与防火墙限制。11200/11201落在 scripts/database-env.mjs 为 qdrant 分配专属的11200–11299宿主端口段内保证与其他已提交配方mysql 101xx、redis 105xx 等同时启动也不会冲突validateHostPortAllocation会进一步校验端口段内的分配不与其他配方重复。3. API Key 注入默认管理员密钥123456environment: QDRANT__SERVICE__API_KEY: ${DB_PASSWORD:-123456}环境变量QDRANT__SERVICE__API_KEY是 Qdrant 官方的双层下划线配置约定等价于Qdrant.Service.ApiKey由 Compose 的环境变量展开语法从DB_PASSWORD注入默认回退到123456。这正是 init/README.md 第二句admin API key (123456by default)的机制来源。统一默认密码123456是全部数据库配方的约定见 scripts/database-env.mjs 中的DEFAULT_PASSWORD生产环境务必通过DB_PASSWORD覆盖。4. 健康检查healthcheck: test: [CMD-SHELL, bash -c /dev/tcp/127.0.0.1/6333] interval: 5s timeout: 5s retries: 30 start_period: 10s健康检查用 Bash 的/dev/tcp探测容器内 6333 端口可达性每 5 秒一次、最多重试 30 次、启动宽限期 10 秒。配方校验要求每个 compose.yaml 必须定义健康检查docker compose up -d --wait会等健康检查通过后才返回冒烟验证也因此建立在服务已就绪的前提上。三、recipe.json 中的冒烟步骤verify如何发送带认证的 HTTP 请求init/README.md 提到的verify命令定义在 recipe.json 的smoke.steps中包含两条按序执行的断言smoke: { steps: [ { name: reject an unauthenticated collection request, command: [ bash, -c, exec 3/dev/tcp/127.0.0.1/6333; printf GET /collections HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n 3; cat 3 ], expect: 403 Forbidden }, { name: query collections with the configured API key, command: [ bash, -c, exec 3/dev/tcp/127.0.0.1/6333; printf GET /collections HTTP/1.1\\r\\nHost: localhost\\r\\napi-key: %s\\r\\nConnection: close\\r\\n\\r\\n \$1\ 3; cat 3, bash, ${DB_PASSWORD} ], expect: collections } ] }两个步骤都用 Bash 的/dev/tcp打开到容器内127.0.0.1:6333的 TCP 连接手工构造原始 HTTP/1.1 请求并读取响应——无需额外安装 curl 等工具从而保证配方在任何镜像内可执行。第一步拒绝未认证请求期望403 Forbidden构造的请求为GET /collections不携带任何认证头。Qdrant 在配置了QDRANT__SERVICE__API_KEY后未认证访问 REST API 会返回 HTTP 403。这一步验证的是没有密钥就进不来的访问控制底线确认 API Key 确实生效。第二步携带配置的 API Key 查询集合期望响应包含collectionsprintf GET /collections HTTP/1.1\r\nHost: localhost\r\napi-key: %s\r\nConnection: close\r\n\r\n $1 3$1接收脚本参数即${DB_PASSWORD}。Qdrant 的 REST API 认证约定是将管理员 API Key 放入名为api-key的 HTTP 请求头文档 docs/content/docs/database-lab.mdx 也确认了 DBX 驱动通过 HTTP 请求头api-key发送该密钥。携带正确密钥后GET /collections应返回 200 及 JSON 集合列表响应正文必然包含collections字段名因此以collections作为期望文本。底层执行链路make db-verify做了什么make db-verify DBqdrant1.8实际调用pnpm db:env -- verify见 Makefile底层实现在 scripts/database-env.mjs 的main的verify分支runCompose(recipe, [up, -d, --wait])启动容器并等待健康检查通过ensureBootstrap(recipe)执行可选的引导步骤Qdrant 配方未定义bootstrap直接跳过遍历recipe.smoke.steps对每条命令先调用expandSmokeCommand把${DB_PASSWORD}、${DB_PORT}占位符替换为实际值优先取进程环境变量回退到recipe.connection中的默认值再通过docker compose exec -T database ...在容器内执行用output.includes(step.expect)断言输出包含期望文本不匹配即抛出错误并以非零退出码失败全部通过则依次打印OK step name。因此verify的全过程验证的是端到端的认证链路Compose 注入的 API Key → Qdrant 服务端强制校验 → 手工 HTTP 请求携带api-key头 → 正确返回集合列表。init/README.md 中theverifycommand sends an authenticated HTTP request using the configured admin API key描述的正是这条链路。四、快速上手从启动到验证的完整操作流程Qdrant 1.8 配方遵循 deploy/database/README.zh-CN.md 描述的统一 Make 目标约定在仓库根目录执行# 1. 查看所有可用配方确认 qdrant1.8 的端口、镜像、平台 make db-list # 2. 启动 Qdrant 1.8 并输出连接字段含 dbx:// 深链 make db DBqdrant1.8 # 3. 启动并运行冒烟验证未认证 403、带 api-key 返回 collections make db-verify DBqdrant1.8 # 4. 停止环境保留 data 卷数据 make db-down DBqdrant1.8 # 5. 删除容器与 data 命名卷必须显式确认 make db-reset DBqdrant1.8 CONFIRM1执行make db DBqdrant1.8后脚本会输出类似下面的连接字段依据 scripts/database-env.mjs 的printConnectionQdrant (1.8.3) host: 127.0.0.1 port: 11200 password: 123456 database: dbx grpcPort: 11201 DBX connection link: dbx://connection/new?typeqdrant...其中dbx://connection/new深链可在已安装 DBX 桌面端的 macOS 上通过open 链接直接打开新建连接窗口链接含密码勿写入共享终端历史、日志或工单。在 DBX 中建立 Qdrant 连接的要点依据 docs/content/docs/database-lab.mdx 与 plugins/connection-types/qdrant.yaml 的定义用户名留空把管理员 API Key123456填入密码字段驱动会通过 HTTP 请求头api-key发送主连接端口为11200HTTPgRPC 端口11201Qdrant 连接类型dbType: qdrantdefaultPort: 6333支持queryExecution查询执行与metadataBrowse元数据浏览其余如对象浏览器、表编辑、数据导出、SQL 文件执行、用户管理等能力均为关闭状态supportLevel: browseruntimeMode: native、mcpMode: bridge表示该连接类型由 Rust 侧原生实现并通过桥接方式支持 MCP 场景。常用诊断命令底层pnpm db:env还提供面向诊断的子命令见 scripts/database-env.mjspnpm db:env -- info qdrant 1.8 # 查看连接字段与深链 pnpm db:env -- status qdrant 1.8 # docker compose ps 查看容器状态 pnpm db:env -- logs qdrant 1.8 # 查看容器日志FOLLOW1 时持续跟随 pnpm db:env -- shell qdrant 1.8 # 进入容器 bash pnpm db:env -- check # 校验全部配方与 Compose 文件make db-check会对每个配方执行静态校验镜像必须固定版本标签、禁止latest、必须声明健康检查与命名卷、端口映射默认回环、容器名必须为dbx-qdrant-1.8等见 scripts/database-env.mjs 的validateRecipe并用docker compose config校验渲染后的 Compose 配置。五、小结一份仅两行的 init/README.md浓缩了 Qdrant 1.8 测试环境配方最核心的三条事实而它们都在仓库中拥有可验证的实现依据init/README.md 中的陈述实现依据Qdrant 将向量存储在命名卷data中compose.yaml 的volumes: - data:/qdrant/storage与顶层volumes: data:verify发送带认证的 HTTP 请求recipe.json 的smoke.steps手工构造携带api-key头的GET /collections请求管理员 API Key 默认123456compose.yaml 的QDRANT__SERVICE__API_KEY: ${DB_PASSWORD:-123456}与 scripts/database-env.mjs 的DEFAULT_PASSWORD需要自定义时只需覆盖环境变量DB_PASSWORD修改 API Key、DB_PORT/QDRANT_GRPC_PORT修改宿主端口、DB_BIND_ADDRESS0.0.0.0开放远程访问务必同步使用强密码。整个配方可以在 Windows PowerShell、Git Bash 或 WSL 中通过 GNU Make 直接使用make db-completion还会输出 Bash、Zsh、PowerShell 的配方选择器补全配置让DBqdrant1.8这类参数也能自动补全从而把启动一个带认证的 Qdrant 本地环境收敛为一条可重复、可验证、可清理的命令。赞分享数据库客户端数据库桌面应用CLI后端MCP 服务AI 应用【免费下载链接】dbx25 MB lightweight cross-platform database client for 90 databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90 数据库提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。项目地址https://gitcode.com/gh_mirrors/dbx7/dbx点击查看免费下载相关推荐DBX 中的 Pulsar 4.2 测试环境standalone 部署与 DBX smoke 冒烟验证指南DBX 中的 Pulsar 4.2 测试环境standalone 部署与 DBX smoke 冒烟验证指南 DBX 仓库在 deploy/database/数据库客户端数据库桌面应用CLI后端MCP 服务AI 应用dbx 仓库中 Elasticsearch 6.8 冒烟测试环境make db-verify 与 dbx-smoke 索引验证实战dbx 仓库中 Elasticsearch 6.8 冒烟测试环境make db verify 与 dbx smoke 索引验证实战 导读 deploy/dat数据库开发者工具桌面应用CLIMCP 服务AI 应用DBX 数据库测试环境Kafka 4.3 单节点 KRaft 部署与冒烟验证指南DBX 数据库测试环境Kafka 4.3 单节点 KRaft 部署与冒烟验证指南 导读 本文聚焦 DBX 开源项目轻量级跨平台数据库客户端内置的数据库测试数据库客户端数据库桌面应用CLI后端MCP 服务AI 应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考