設定
設定 KuraDB 的憑證、本機狀態、HTTP 綁定與編譯期服務行為。
憑證
KuraDB 需要一項外部憑證：
| 名稱 | 必要 | 使用者 | 用途 |
|---|---|---|---|
OPENAI_API_KEY |
是 | internal/openai.New |
授權 text-embedding-3-small request |
Daemon 會初始化 KuraDB keychain context，並透過 go-pkg/filesystem/keychain 取得 OPENAI_API_KEY。KuraDB 的 application source 未定義其他 runtime environment variable。
請勿將憑證寫入 config.json、command argument、log 或文件。啟動 daemon 前必須透過 keychain integration 提供此值；若無法取得，啟動程序會結束。
設定目錄
所有 runtime state 都位於 ~/.config/kuradb/。
| 路徑 | 類型 | 用途 |
|---|---|---|
config.json |
持久 JSON | 可選的固定 HTTP port |
db.json |
持久 JSON | 已註冊資料庫名稱與建立時間 |
global.db |
持久 SQLite | 持久化 query embedding cache |
{name}/data.db |
持久 SQLite | 權威 chunk、dismissal state 與 embedding |
{name}/inbox/ |
監控目錄 | Ingestion pipeline 接受的檔案 |
{name}/record.json |
持久 JSON | 檔案 metadata 的 watcher snapshot |
runtime.uid |
暫時 JSON | Daemon UID、PID 與啟動時間 |
endpoint |
暫時文字 | 目前本機 HTTP base URL |
daemon.log |
Log | 分離 daemon 的 stdout 與 stderr |
每個資料庫另有便利的符號連結 ~/Kura_{name}，指向其 inbox。
HTTP port
config.json 目前支援一個 property：
{
"port": 8080
}
| Property | 型別 | 預設 | 規則 |
|---|---|---|---|
port |
integer | 0／省略 |
透過 CLI 設定時必須介於 1–65535 |
請透過 KuraDB 管理此值，不要手動編輯 JSON：
kura port set 8080
kura port clear
port set 會持久化設定並重新啟動 daemon。port clear 會寫入未固定的設定，於下次手動啟動後生效。
未固定 port 時，KuraDB 會在 10000 到 65535 之間隨機嘗試最多 10 個 port。固定與隨機 listener 都只綁定 127.0.0.1；發布的 URL 使用 localhost。
固定服務常數
下列行為編譯在目前 binary 中，並未開放為設定：
| 設定 | 值 | 來源 |
|---|---|---|
| 檔案輪詢間隔 | 10 秒 | cmd/app/main.go |
| Embedding 輪詢間隔 | 5 秒 | cmd/app/main.go |
| Embedding batch size | 64 chunks | cmd/app/main.go |
| OpenAI model | text-embedding-3-small |
internal/openai/openai.go |
| Embedding dimensions | 512 | internal/openai/openai.go |
| OpenAI request timeout | 1 分鐘 | internal/openai/openai.go |
| HTTP read-header timeout | 5 秒 | cmd/app/http.go |
| HTTP shutdown timeout | 5 秒 | cmd/app/http.go |
| 預設 search limit | 10 | internal/api/handler/keyword.go |
| 最大 search limit | 100 | internal/api/handler/keyword.go |
| Semantic score cutoff | 0.3 | internal/api/handler/semantic.go |
Endpoint discovery
Listener 就緒後，KuraDB 會將 URL 寫入 ~/.config/kuradb/endpoint：
BASE="$(cat ~/.config/kuradb/endpoint)"
curl "$BASE/api/health"
Launcher 會等待此檔案最多 10 秒。Graceful shutdown 會將它移除，因此 consumer 應在每次重啟後重新讀取。
資料庫可用性
Registry 變更會立即持久化，但 daemon 只在啟動時建立 loaded database map。執行 kura add 後，必須先重新啟動 KuraDB，才能對新名稱送出搜尋。/api/list 會分別暴露 registered 與 loaded，讓 client 偵測此狀態。
平台限制
請使用 macOS 的本機 APFS/HFS+ filesystem，或 Linux 的 ext4/xfs。Watcher 依賴可靠的 POSIX directory mtime 語義，不支援 Windows、SMB、NFS 或 FUSE mount。