macOS 上通过二进制安装 Qdrant 并配置为 launchd 服务

本指南将帮助你在 macOS 系统中下载、安装 Qdrant，并将其配置为 launchd 守护进程，以便随系统启动并在后台运行。

前置条件

• macOS 操作系统
• 终端访问权限
• 已安装 curl、tar、lsof 等基础工具
• 对 ~/Library/LaunchAgents 目录有写入权限（用户级别服务）

1. 下载 Qdrant 二进制

打开终端，执行以下命令以下载最新版本的 Qdrant 二进制包（适用于 Intel 架构的 macOS）：

curl -L https://github.com/qdrant/qdrant/releases/latest/download/qdrant-x86_64-apple-darwin.tar.gz -o qdrant.tar.gz

注意：如果你使用的是 Apple Silicon (M1/M2/M3) Mac，请将 URL 中的 x86_64-apple-darwin 替换为 aarch64-apple-darwin，或者直接访问 Qdrant Releases 选择适合你架构的包。

2. 解压并安装

创建一个目录用于存放 Qdrant 及其配置文件，然后解压并移动可执行文件：

# 创建安装目录
mkdir -p ~/qdrant_cli

# 解压到该目录
tar -xzf qdrant.tar.gz -C ~/qdrant_cli

# 解压后，二进制文件通常名为 qdrant，确保它位于 ~/qdrant_cli 中
# 若解压后直接生成了 qdrant 文件，则无需额外移动；否则请根据实际结构调整

检查可执行文件是否已正确放置：

ls -l ~/qdrant_cli/qdrant

如果文件存在且具有可执行权限，即可继续。

3. 准备配置文件（可选）

Qdrant 默认可以在没有配置文件的情况下运行，但启动命令中指定了 --config-path。你可以先创建一个最小配置文件，或从官方仓库获取示例。

在 ~/qdrant_cli 目录下创建一个 config.yaml 文件，内容可以是最简配置（例如只设置存储路径）：

# ~/qdrant_cli/config.yaml
storage:
  storage_path: ./storage

或使用官方默认配置（可参考 官方文档）。如果没有特殊需求，也可以跳过创建配置文件，直接运行 qdrant（不指定 --config-path），但本教程的后续命令均假设你已创建该文件。

4. 手动启动测试（可选）

在配置 launchd 之前，可以先手动启动 Qdrant，确认二进制文件工作正常：

~/qdrant_cli/qdrant --config-path ~/qdrant_cli/config.yaml

启动后，按 Ctrl+C 停止。如果看到启动日志且无错误，说明二进制正常。

5. 创建 launchd plist 文件

launchd 使用 plist 文件来管理服务。我们需要创建一个 io.qdrant.plist 文件，将其放置在 ~/Library/LaunchAgents/ 目录下（用户级服务）。

使用文本编辑器创建文件：

nano ~/Library/LaunchAgents/io.qdrant.plist

粘贴以下内容（请根据你的实际路径替换 <your-username>）：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>io.qdrant</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/<your-username>/qdrant_cli/qdrant</string>
        <string>--config-path</string>
        <string>/Users/<your-username>/qdrant_cli/config.yaml</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/qdrant.out</string>
    <key>StandardErrorPath</key>
    <string>/tmp/qdrant.err</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/usr/bin:/bin</string>
    </dict>
</dict>
</plist>

• Label：服务标识，应与文件名前缀一致。
• ProgramArguments：启动命令及参数。确保路径正确。
• RunAtLoad：加载 plist 时立即启动服务。
• KeepAlive：服务异常退出时自动重启。
• StandardOutPath / StandardErrorPath：标准输出和错误日志路径。
• EnvironmentVariables：可选，设置环境变量。

保存文件并退出（在 nano 中按 Ctrl+O，回车，再按 Ctrl+X）。

6. 加载并启动服务

首先，卸载可能存在的旧配置（如果之前加载过），然后加载新的 plist：

launchctl unload ~/Library/LaunchAgents/io.qdrant.plist 2>/dev/null
launchctl load ~/Library/LaunchAgents/io.qdrant.plist

加载成功后，Qdrant 将自动在后台运行。

7. 验证服务状态

7.1 检查端口监听

Qdrant 默认监听 6333 端口。使用以下命令查看端口是否被占用：

lsof -i :6333

如果看到类似 qdrant 的进程，说明服务已启动。

7.2 通过 HTTP API 测试

向本地 Qdrant 服务发送请求：

curl http://localhost:6333

正常响应应包含类似 {"title":"qdrant - vector search engine","version":"..."} 的 JSON 数据。

7.3 查看 launchd 服务列表

确认服务已加载：

launchctl list | grep qdrant

输出中应包含 io.qdrant。

8. 查看日志

日志文件位于 /tmp/qdrant.out 和 /tmp/qdrant.err。你可以使用 tail 实时查看：

tail -f /tmp/qdrant.err

检查是否有错误信息。如果一切正常，你会看到 Qdrant 的启动日志。

9. 停止与卸载服务

如需停止服务：

launchctl unload ~/Library/LaunchAgents/io.qdrant.plist

如需完全移除服务，在卸载后删除 plist 文件：

rm ~/Library/LaunchAgents/io.qdrant.plist

10. 常见问题

• 端口被占用：检查是否已有其他进程使用 6333 端口，或修改 Qdrant 配置文件中的端口。
• 权限不足：确保 ~/qdrant_cli 目录及其文件拥有正确的读写权限。
• 启动失败：查看 /tmp/qdrant.err 日志获取具体错误信息。
• Apple Silicon 架构：若下载的包不兼容，请重新下载 aarch64-apple-darwin 版本。

总结

通过以上步骤，你已将 Qdrant 安装为 macOS 上的 launchd 服务，可随系统自启动并稳定运行。后续可通过修改 config.yaml 或更新二进制文件来升级配置与版本。

如需更详细的配置说明，请参考 Qdrant 官方文档。