文件 v0.6.0
首頁 GitHub

開始使用

安裝 KuraDB、註冊資料庫、索引檔案，並執行第一次唯讀搜尋。

前置需求

需求 詳細資訊
Go Go 1.25.1 或更新版本
平台 macOS 的 APFS/HFS+，或 Linux 的 ext4/xfs
憑證 OPENAI_API_KEY 存於系統 keychain（service kuradb），或以環境變數作為備援
網路 可連線至 https://api.openai.com/v1/embeddings

KuraDB 依賴 POSIX 目錄修改時間的行為。Windows 與不可靠的 SMB、NFS 或 FUSE 掛載點不在支援的平台契約內。

安裝

使用 go install

go install github.com/pardnchiu/kuradb/cmd/app@latest

go install 會依套件目錄將二進位檔命名為 app，請更名為 kura 以對齊本文其餘指令：

mv "$(go env GOPATH)/bin/app" "$(go env GOPATH)/bin/kura"

從原始碼建置

git clone https://github.com/pardnchiu/KuraDB.git
cd KuraDB
make build

Makefile 會將二進位檔寫入 bin/kura。make app 會停止既有程序、建置二進位檔、安裝到 /usr/local/bin/kura，再啟動服務。

註冊資料庫

kura add my_docs

此命令會：

  1. 將名稱中的空白正規化為底線。
  2. 在 ~/.config/kuradb/db.json 註冊 my_docs。
  3. 建立 ~/.config/kuradb/my_docs/inbox/。
  4. 建立指向 inbox 的符號連結 ~/Kura_my_docs。

Daemon 執行期間新增的資料庫不會熱載入。查詢新資料庫前必須重新啟動 KuraDB。

啟動 daemon

kura

前景 launcher 會啟動分離的 --daemon 程序，並等待 endpoint 檔案最多 10 秒。就緒後會印出類似下列 URL：

http://localhost:43127

Daemon 會載入已註冊資料庫、從 SQLite 還原快取、為每個已載入資料庫啟動 watcher 與 embedding loop，並將唯讀 HTTP API 綁定至 127.0.0.1。

索引檔案

cp document.md ~/Kura_my_docs/

Watcher 每 10 秒輪詢一次。變更的檔案會被解析並寫入 SQLite；embedding scheduler 每 5 秒輪詢一次，每批最多處理 64 個 pending chunk。

執行搜尋

讀取選定的 endpoint，並同時查詢兩種策略：

BASE="$(cat ~/.config/kuradb/endpoint)"
curl "$BASE/api/search?db=my_docs&q=什麼是RAG&limit=5"

使用 target=keyword 或 target=semantic 只執行單一策略：

curl "$BASE/api/search?db=my_docs&q=向量快取&target=semantic"

連接 MCP client

若要用 MCP client 而非 curl 存取 KuraDB，把 client 指向 kura 執行檔：

{
  "mcpServers": {
    "kuradb": { "command": "kura", "args": ["mcp"] }
  }
}

Client 就會看到 list_rag 與 search_rag。執行 kura remote enable 後，daemon 也能在 /mcp 提供同一組 tool；該 endpoint 預設關閉。兩種 transport 見 MCP Server。

驗證服務狀態

curl "$BASE/api/health"
curl "$BASE/api/list"

/api/health 回傳純文字 OK。/api/list 同時回傳目前已載入的資料庫名稱與 registry entry；daemon 重新啟動前，兩者可能不同。

停止或重新設定

kura port set 8080
kura port clear
kura stop

port set 會儲存連接埠並重新啟動 daemon。port clear 會解除固定，但必須等下次手動重新啟動才生效。

下一步

EN