Hindsight Windows 安裝問題：從鬼打牆到正常運行

前情提要

這篇文章是我實際架設 Hindsight 記憶系統時遇到的問題與解決過程。問題發生在 Windows 環境（已安裝 PostgreSQL 16），最終成功啟動。

---

問題現象

啟動 Hindsight 時看到這個錯誤：

sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:pg0
RuntimeError: Database migration failed
Application startup failed. Exiting.

---

發生經過

第一次嘗試：直接安裝

1. 用 pip 安裝 hindsight-api
2. 建立 hindsight 資料庫
3. 設定 .env 環境變數
4. 執行 hindsight-admin run-db-migration

→ 失敗：pg0://localhost:5433 被 SQLAlchemy 直接當成不支援的資料庫驅動

第二次嘗試：更換 port

因為系統 PostgreSQL 已經佔用 port 5432，pg0 嵌入式 PostgreSQL 綁定失敗。

1. 修改 port 5433
2. 再次執行 migration

→ 同樣的錯誤：pg0:// URL 格式 SQLAlchemy 不認識

第三次嘗試：查看錯誤日誌

Failed to start embedded PostgreSQL after 5 attempts.
Error: could not bind IPv4 address 127.0.0.1: Permission denied

pg0 無法綁定 port，因為系統 PostgreSQL 已經佔用。

第四次嘗試：繞過 CLI

1. 寫 Python 腳本手動解析 pg0 URL
2. 使用 postgresql://hindsight:hindsight@127.0.0.1:5433/hindsight 成功連線
3. 手動執行 migration

→ 成功！pgvector 擴展已就緒

第五次嘗試：直接用 resolved URL

1. 修改 .env 放棄 pg0://，直接寫 postgresql://
2. 啟動 hindsight-api

→ 成功！

---

根本原因

問題	說明
pg0 URL 解析 bug	hindsight-admin run-db-migration 這個指令會把 pg0://localhost:5433 直接傳給 SQLAlchemy，但 SQLAlchemy 不支援 pg0 這個 dialect。正確行為應該是先解析成 postgresql://... 再傳給 SQLAlchemy
Windows port 衝突	系統已有 PostgreSQL 佔用 port 5432，pg0 無法綁定
文件誤導	Hindsight 文件說要用 pg0:// 或 postgresql://，但沒有說明 Windows 環境的限制

---

解決方案

Step 1：確認 pg0 已經啟動

netstat -ano | Select-String "5433.*LISTEN"

找到程序 PID 後確認是 pg0 進程。

Step 2：修改 .env，不要用 pg0://

# 錯誤（Windows 上會失敗）
HINDSIGHT_API_DATABASE_URL=pg0://localhost:5433

# 正確（直接寫 resolved URL）
HINDSIGHT_API_DATABASE_URL=postgresql://hindsight:hindsight@127.0.0.1:5433/hindsight

Step 3：啟動 Hindsight

hindsight-api --port 8888

---

驗證測試

# 健康檢查
curl http://localhost:8888/health
# {"status":"healthy","database":"connected"}

# 寫入記憶
curl -X POST http://localhost:8888/v1/default/banks/default/memories \
  -H "Content-Type: application/json" \
  -d '{"items":[{"content":"這是一個測試記憶"}]}'

# 召回記憶
curl -X POST http://localhost:8888/v1/default/banks/default/memories/recall \
  -H "Content-Type: application/json" \
  -d '{"query":"測試"}'

---

心得

1. 不要相信 pg0:// 能在 Windows 上正常工作 — 至少目前版本有 bug
2. 文件說「使用 Docker」不是推薦 Windows 用戶的路 — 文件是為 macOS/Linux 寫的
3. 先測試 API 而不要一次設定太多 — 確認 health endpoint 是第一步
4. 錯誤訊息很重要 — 這次錯誤訊息直接告訴你是 SQLAlchemy 不認識 pg0 dialect

---

參考資料

• Hindsight 文件
• Hindsight x MiniMax 串接疑難排解：https://esisterebbb.blogspot.com/2026/04/404-hindsight-minimax.html

---

作者：微風（BeeBreeze）

部落格：點點滴滴

https://esisterebbb.blogspot.com/