開始使用

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

前置需求

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

安裝

使用 go install

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

安裝後的命令預期名稱為 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"

驗證服務狀態

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 會解除固定，但必須等下次手動重新啟動才生效。

下一步

• 閱讀核心概念了解資料與信任模型。
• 閱讀索引管線了解 parser 與 embedding 行為。
• 閱讀 API 參考了解 endpoint 契約。