momentry_core_0_1/docs/INSTALL_QDRANT.md

Qdrant 安裝指南 (本地部署)

概述

本文檔說明如何在 macOS 上安裝 Qdrant Vector Database，配置為本地部署，支援遠端訪問。

---

當前狀態

項目	狀態
Qdrant	✅ 已安裝 v1.17.0
數據目錄	/Users/accusys/momentry/var/qdrant/
日誌目錄	/Users/accusys/momentry/log/
Plist	/Library/LaunchDaemons/com.momentry.qdrant.plist

---

安裝步驟

Step 1: 安裝 Qdrant (使用 cargo)

# 安裝 Qdrant 從 GitHub
cargo install --git https://github.com/qdrant/qdrant.git --locked

驗證:

qdrant --version
# qdrant 1.17.0

---

Step 2: 驗證 Qdrant 安裝

# 驗證 Qdrant 安裝
~/.cargo/bin/qdrant --version
# qdrant 1.17.0

---

Step 3: 建立目錄結構

# 建立數據目錄
mkdir -p /Users/accusys/momentry/var/qdrant

# 建立配置目錄
mkdir -p /Users/accusys/momentry/etc/qdrant

# 建立日誌目錄
mkdir -p /Users/accusys/momentry/log

# 建立日誌文件
touch /Users/accusys/momentry/log/qdrant.log
touch /Users/accusys/momentry/log/qdrant.error.log

# 設定權限
chown -R accusys:staff /Users/accusys/momentry/var/qdrant
chown -R accusys:staff /Users/accusys/momentry/etc/qdrant
chown -R accusys:staff /Users/accusys/momentry/log

---

Step 4: 使用 plist 開機自動啟動

# 複製 plist 到 LaunchDaemons 目錄
sudo cp /Users/accusys/momentry_core_0.1/momentry_runtime/plist/com.momentry.qdrant.plist /Library/LaunchDaemons/

# 載入並啟動
sudo launchctl load /Library/LaunchDaemons/com.momentry.qdrant.plist

---

監控配置

添加到監控配置

在 monitor/config/monitor_config.yaml 中添加：

database:
  qdrant:
    enabled: true
    host: "localhost"
    port: 6333

添加健康檢查函數

在 monitor/database/qdrant_monitor.sh 中已包含 Qdrant 監控。

---

卸載步驟

重要: 路徑說明

路徑	類型	說明
/Users/accusys/momentry/var/qdrant/	數據	不要刪除 - Qdrant 數據
/Users/accusys/momentry/etc/qdrant/	配置	不要刪除 - Qdrant 配置
/Users/accusys/momentry/log/	日誌	不要刪除 - 日誌目錄
~/.cargo/bin/qdrant	安裝	刪除 - Qdrant 執行檔

Step 1: 停止 Qdrant

# 找到 Qdrant 進程
ps aux | grep qdrant | grep -v grep

# 停止 Qdrant
pkill qdrant
# 或
kill <PID>

# 確認停止
ps aux | grep qdrant | grep -v grep || echo "Qdrant 已停止"

---

Step 2: 卸載 Qdrant (cargo)

# 移除 cargo 安裝的 Qdrant
cargo uninstall qdrant

# 移除 plist
sudo launchctl unload /Library/LaunchDaemons/com.momentry.qdrant.plist
sudo rm /Library/LaunchDaemons/com.momentry.qdrant.plist

---

Step 3: 刪除專屬檔案

# 刪除數據目錄 (可選)
rm -rf /Users/accusys/momentry/var/qdrant

# 刪除日誌 (可選)
rm -f /Users/accusys/momentry/log/qdrant.log
rm -f /opt/homebrew/var/log/qdrant.error.log

注意: 不要刪除以下共用目錄:

# 這些是共用的，不要刪除!
# /Users/accusys/momentry/var
# /Users/accusys/momentry/log

---

Step 4: 卸載後檢查清單

echo "=== Qdrant 卸載後檢查 ==="

# 1. 檢查 Qdrant 進程
echo "1. Qdrant 進程:"
ps aux | grep qdrant | grep -v grep && echo "   ✗ 仍在運行" || echo "   ✓ 已停止"

# 2. Port 6333
echo "2. Port 6333:"
lsof -i :6333 > /dev/null 2>&1 && echo "   ✗ 仍被佔用" || echo "   ✓ 已釋放"

# 3. Port 6334
echo "3. Port 6334:"
lsof -i :6334 > /dev/null 2>&1 && echo "   ✗ 仍被佔用" || echo "   ✓ 已釋放"

# 4. qdrant 命令
echo "4. qdrant 命令:"
which qdrant > /dev/null 2>&1 && echo "   ✗ 仍存在" || echo "   ✓ 已移除"

# 5. cargo 安裝
echo "5. cargo 安裝:"
cargo install --list | grep qdrant > /dev/null 2>&1 && echo "   ✗ 仍存在" || echo "   ✓ 已移除"

# 6. launchctl 服務
echo "6. launchctl 服務:"
sudo launchctl list | grep qdrant > /dev/null 2>&1 && echo "   ✗ 仍存在" || echo "   ✓ 已移除"

# 7. 數據目錄 (可選刪除)
echo "7. 數據目錄:"
[ -d "/Users/accusys/momentry/var/qdrant" ] && echo "   ✓ 保留" || echo "   ✗ 已刪除"

# 8. 日誌目錄 (可選刪除)
echo "8. 日誌目錄:"
[ -d "/Users/accusys/momentry/log" ] && echo "   ✓ 保留" || echo "   ✗ 已刪除"

預期結果:

=== Qdrant 卸載後檢查 ===
1. Qdrant 進程:
   ✓ 已停止
2. Port 6333:
   ✓ 已釋放
3. Port 6334:
   ✓ 已釋放
4. qdrant 命令:
   ✓ 已移除
5. cargo 安裝:
   ✓ 已移除
6. launchctl 服務:
   ✓ 已移除
7. 數據目錄:
   ✓ 保留 (或 ✗ 已刪除)
8. 日誌目錄:
   ✓ 保留 (或 ✗ 已刪除)

---

手動檢查命令

# 1. 檢查進程
ps aux | grep qdrant | grep -v grep

# 2. 檢查 Port
lsof -i :6333
lsof -i :6334

# 3. 測試連線 (無認證)
curl http://localhost:6333/collections

# 4. 測試連線 (有認證)
curl -H "api-key: Test3200Test3200Test3200" http://localhost:6333/collections

# 5. 查看所有 collections
curl -s -H "api-key: Test3200Test3200Test3200" http://localhost:6333/collections

# 6. 查看日誌
tail -20 /Users/accusys/momentry/log/qdrant.log

---

連線資訊

項目	值
REST API	http://localhost:6333
gRPC	localhost:6334
API Key	Test3200Test3200Test3200
Qdrant UI	http://localhost:6333/dashboard

---

環境變數

在 .env 中:

QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=Test3200Test3200Test3200

---

遠端訪問

• Qdrant 綁定到 0.0.0.0 (所有網路介面)
• 本地網路其他機器可透過 IP 訪問
• 建議設定防火牆規則限制訪問 IP

---

故障排除

Qdrant 無法啟動

# 檢查日誌
tail -f /Users/accusys/momentry/log/qdrant.log

# 檢查目錄權限
ls -la /Users/accusys/momentry/var/qdrant/

# 重新設定權限
chown -R $(whoami):staff /Users/accusys/momentry/var/qdrant

Port 被佔用

# 檢查哪個程序佔用 port 6333
lsof -i :6333

# 終止佔用程序
kill <PID>

需要重新載入 plist

# 卸載舊服務 (如果存在)
sudo launchctl unload /Library/LaunchDaemons/com.momentry.qdrant.plist 2>/dev/null

# 載入新服務
sudo launchctl load /Library/LaunchDaemons/com.momentry.qdrant.plist

---

檔案位置

類型	路徑	說明
/Users/accusys/.cargo/bin/qdrant	二進制	cargo 安裝位置 (直接使用)
/opt/homebrew/bin/qdrant	符號連結	已棄用 - 不再需要
數據目錄	/Users/accusys/momentry/var/qdrant/	數據儲存
日誌	/Users/accusys/momentry/log/qdrant.log	執行日誌
錯誤日誌	/opt/homebrew/var/log/qdrant.error.log	錯誤日誌
plist	/Library/LaunchDaemons/com.momentry.qdrant.plist	開機啟動
備份	/Users/accusys/momentry/var/qdrant_backup/	數據備份

---

備份與恢復

備份

Qdrant 提供兩種備份方式：Snapshots (推薦) 和手動複製。

方式一：使用 Snapshots API (推薦)

# 創建備份目錄
mkdir -p /Users/accusys/momentry/var/qdrant_backup

# 獲取所有 collections
curl -s -H "api-key: Test3200Test3200Test3200" \
  http://localhost:6333/collections | jq -r '.result[].name'

# 為每個 collection 創建 snapshot
# 假設 collection 名稱為 "chunks"
curl -X POST -H "api-key: Test3200Test3200Test3200" \
  http://localhost:6333/collections/chunks/snapshots \
  -o /Users/accusys/momentry/var/qdrant_backup/chunks_snapshot_$(date +%Y%m%d).tar.gz

方式二：手動複製數據目錄 (停機備份)

# 停止 Qdrant
pkill qdrant

# 等待停止
sleep 2

# 複製數據目錄
TIMESTAMP=$(date +%Y%m%d)
mkdir -p /Users/accusys/momentry/var/qdrant_backup
tar -czf /Users/accusys/momentry/var/qdrant_backup/qdrant_data_${TIMESTAMP}.tar.gz \
  -C /Users/accusys/momentry/var qdrant/

# 啟動 Qdrant
launchctl load /Library/LaunchDaemons/com.momentry.qdrant.plist

自動備份腳本

#!/bin/bash
# backup_qdrant.sh
set -e

QDRANT_HOST="localhost"
QDRANT_PORT="6333"
QDRANT_API_KEY="Test3200Test3200Test3200"
BACKUP_DIR="/Users/accusys/momentry/var/qdrant_backup"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

mkdir -p "$BACKUP_DIR"

echo "開始 Qdrant 備份..."

# 獲取所有 collections
COLLECTIONS=$(curl -s -H "api-key: $QDRANT_API_KEY" \
  http://${QDRANT_HOST}:${QDRANT_PORT}/collections | \
  jq -r '.result[].name')

if [ -z "$COLLECTIONS" ]; then
    echo "警告: 沒有找到任何 collections"
else
    for COLLECTION in $COLLECTIONS; do
        echo "備份 collection: $COLLECTION"
        curl -X POST -H "api-key: $QDRANT_API_KEY" \
          "http://${QDRANT_HOST}:${QDRANT_PORT}/collections/${COLLECTION}/snapshots" \
          -o "${BACKUP_DIR}/${COLLECTION}_${TIMESTAMP}.tar.gz" 2>/dev/null || \
          echo "警告: $COLLECTION 備份失敗"
    done
fi

# 壓縮所有 snapshot
cd "$BACKUP_DIR"
tar -czf qdrant_snapshots_${TIMESTAMP}.tar.gz *.tar.gz 2>/dev/null || true
rm -f *.tar.gz

# 清理 30 天前的備份
find "$BACKUP_DIR" -name "qdrant_snapshots_*.tar.gz" -mtime +30 -delete

echo "Qdrant 備份完成: ${BACKUP_DIR}/qdrant_snapshots_${TIMESTAMP}.tar.gz"

恢復

# 停止 Qdrant
pkill qdrant
sleep 2

# 解壓縮備份
TIMESTAMP="20260315"
tar -xzf /Users/accusys/momentry/var/qdrant_backup/qdrant_snapshots_${TIMESTAMP}.tar.gz \
  -C /Users/accusys/momentry/var/qdrant_backup/

# 恢復數據目錄 (方式二備份)
# rm -rf /Users/accusys/momentry/var/qdrant/*
# tar -xzf /Users/accusys/momentry/var/qdrant_backup/qdrant_data_${TIMESTAMP}.tar.gz \
#   -C /Users/accusys/momentry/var/

# 啟動 Qdrant
launchctl load /Library/LaunchDaemons/com.momentry.qdrant.plist

排程備份

# 編輯 crontab
crontab -e

# 添加每天凌晨 3 點執行備份
0 3 * * * /Users/accusys/momentry/scripts/backup_qdrant.sh >> /Users/accusys/momentry/log/backup.log 2>&1

---

版本資訊

• 版本: 1.17.0
• API Key: Test3200Test3200Test3200
• 數據目錄: /Users/accusys/momentry/var/qdrant/
• 日誌目錄: /Users/accusys/momentry/log/