docker-compose 重點#

核心就是「把本機 repo mount 進容器」+「讓容器能連到 Ollama」。

1
services:
2
  deepwiki:
3
    build:
4
      context: .
5
      dockerfile: Dockerfile
6
    ports:
7
      - "8001:8001"   # API
8
      - "3000:3000"   # UI (Next.js)
9
    environment:
10
      - DEEPWIKI_AUTH_MODE=false
11
      - OLLAMA_HOST=http://host.docker.internal:11434
12
      - DEEPWIKI_EMBEDDER_TYPE=ollama
13
      - DEEPWIKI_GENERATOR_TYPE=ollama
14
      - EMBEDDING_MODEL=nomic-embed-text
15
      - LLM_MODEL=minimax-m2:cloud
16
      # 有些版本仍會硬檢查 OpenAI key（下文會講）
17
      - OPENAI_API_KEY=sk-fake-dummy
18
      - OPENAI_BASE_URL=http://host.docker.internal:11434/v1
19
    volumes:
20
      - ~/.adalflow:/root/.adalflow
21
      - /Users/yourname/Projects:/mnt/local-repos:rw
22
      - ./api/config:/app/api/config:ro

啟動：

1
docker compose up -d

症狀#

UI 填本機路徑會噴：

1
Local repository API error (404): {"error":"Directory not found: /Users/yourname/Projects/"}

原因#

DeepWiki 後端跑在容器內，容器看不到 host 的 /Users/...，所以必定 404。這是 常見的 local repo 掛載問題。

解法#

把 host 路徑 mount 到容器內，並在 UI 改用容器路徑：

• Host：/Users/yourname/Projects
• Container：/mnt/local-repos

UI 輸入：

1
/mnt/local-repos/my-project

症狀#

改 compose 時遇到：

1
services.deepwiki additional properties 'services' not allowed

原因#

YAML 結構錯，把 services: 又寫到 services.deepwiki: 底下（巢狀 services）。這是 Docker Compose 常見的 schema 驗證錯誤。

解法#

把 services: 放回頂層，確保縮排正確，用以下指令檢查：

1
docker compose config

症狀#

UI 顯示：

1
Failed to validate the authorization code

原因#

服務啟用了 auth 模式，UI 需要 auth code 才能產生文件。

解法#

本地自用直接關掉：

1
- DEEPWIKI_AUTH_MODE=false

症狀 A（初始階段）#

1
OPENAI_API_KEY environment variable is not set...

症狀 B（更關鍵）#

後端 log 在 retriever 階段直接掛掉：

1
ValueError preparing retriever: Environment variable OPENAI_API_KEY must be set

為什麼會這樣#

某些版本的 DeepWiki-Open / 其底層依賴（常見是 OpenAI SDK 相容層）會在建立 embedding/retriever 時先硬檢查 OpenAI key，即使你要用的是 Ollama。這是 issue 上常見的抱怨。

我一開始還想說「那就填一個過期的真實 OpenAI key 吧」— 結果一樣驗證失敗。因為有些檢查不只看 key 有沒有設，還會實際打 OpenAI API 驗證，過期 key 自然過不了。這才逼出了後面整套改用 Ollama 相容端點的做法。

最終處理方式#

用「OpenAI 相容模式」— 讓 DeepWiki 以為自己在呼叫 OpenAI，但其實全部打到 Ollama 的 /v1 相容端點：

1
# 設一個假的 key，只為了通過檢查
2
- OPENAI_API_KEY=sk-fake-dummy
3
# 把 base URL 指向 Ollama 的 OpenAI 相容端點
4
- OPENAI_BASE_URL=http://host.docker.internal:11434/v1

Ollama 的 OpenAI 相容端點是已知可用的解法，很多 OpenAI-only 的 client 都靠這招跑起來。

如果設了環境變數還是報錯#

有些版本光靠環境變數不夠，embedding 仍然會走錯 client。這時候需要建立 api/config/embedder.json，直接強制指定用 OllamaClient：

1
{
2
  "embedder": {
3
    "client_class": "OllamaClient",
4
    "model_kwargs": { "model": "nomic-embed-text" }
5
  }
6
}

這個設定檔會覆蓋底層的 client 選擇邏輯，確保 embedding 一定走 Ollama 而不是 OpenAI。

症狀#

跑到最後一刻才爆：

1
POST http://host.docker.internal:11434/api/chat "HTTP/1.1 404 Not Found"
2
Error: model 'qwen3:1.7b' not found (status code: 404)
3
No valid XML found in response

原因#

DeepWiki 的模型名稱可以在三個地方指定：api/config/generator.json 設定檔、docker-compose 環境變數（LLM_MODEL）、以及 UI 前端的模型選擇器。不管在哪裡設定，模型名稱都必須跟 Ollama 裡實際 pull 過的完全一致，否則 Ollama 找不到模型就會回 404。

後端拿不到預期的回應格式時，前端會顯示 “No valid XML found…” — 這個錯誤訊息很誤導，容易讓人以為是 repo 格式問題，實際上只是模型不存在。

解法#

確保你要用的模型已下載，名稱要和設定完全一樣：

1
# 例如你想用 qwen3:1.7b
2
ollama pull qwen3:1.7b
3

4
# 或者用本文的 minimax-m2:cloud
5
ollama pull minimax-m2:cloud

然後在 docker-compose 中固定指定：

1
- LLM_MODEL=minimax-m2:cloud

UI 的模型選擇器也能切換模型，但如果環境變數已經設定了 LLM_MODEL，實際行為以 server config 為準。建議統一在 docker-compose 管理，避免混淆。

症狀#

nomic-embed-text embedding 時，log 會出現一堆：

1
Failed to get embedding for document '...babel-polyfill.min.js', skipping
2
Failed to get embedding for document '...vuetify.min.js', skipping
3
Failed to get embedding for document '...firebase-app.js', skipping

或 Ollama 回 500：

1
the input length exceeds the context length (status code: 500)

第一次看到 log 裡整片 Failed to get embedding 會很緊張，但其實不影響最終結果 — DeepWiki 會自動跳過這些檔案，其餘正常的原始碼照樣能被 index。

原因#

minified/vendor 檔案 token 數超大，embedding 模型的 context length 不夠就會爆。DeepWiki 會自動跳過或 backoff retry。

處理方式#

DeepWiki 預設的 api/config/repo.json 已經排除了 node_modules/、*.min.js、dist/ 等常見目錄。但如果你的專案有其他大型 vendor 檔案（例如直接放在 src/ 裡的第三方 JS），可以手動編輯 repo.json 加入排除規則：

1
{
2
  "excluded_dirs": ["node_modules/", "vendor/", "dist/", "build/"],
3
  "excluded_files": ["*.min.js", "*.min.css", "*.bundle.js"]
4
}

建議在第一次跑之前就先確認排除清單，讓 ingestion 更乾淨、速度更快。

症狀#

換另一個老專案後，大量出現：

1
'utf-8' codec can't decode byte 0xa5 ... invalid start byte

原因#

那些 .js 檔不是 UTF-8（可能是 Big5、CP950 或 Windows-1252），DeepWiki ingestion 用 UTF-8 讀取就會失敗。

處理方式#

兩種策略：

1. 轉碼成 UTF-8（最佳做法）
2. 直接排除這些歷史檔案路徑（如果本來就不重要）

RAG/索引已完成的關鍵 log#

看到以下代表 embeddings + retriever 完成：

1
Loaded XXX documents from existing database
2
Embedding validation complete: XXX/XXX
3
Index built with XXX chunks
4
FAISS retriever created successfully
5
Retriever prepared for /mnt/local-repos/...

UI 卡在「驗證 Wiki 結構…」怎麼辦#

這通常是前端狀態沒有更新，或快取/專案列表顯示邏輯的問題。最務實的做法是：

1. 先確認後端 Retriever prepared 有出現
2. 再確保 LLM model 真的存在、可呼叫
3. 必要時用 OpenAI 相容模式（fake key + base_url）讓流程不會卡在 retriever 初始化