Odysseus 完整教學 — Self-Hosted AI Workspace

1. 專案定位

Odysseus 是一個 self-hosted (自建) AI workspace (工作空間)，目標是成為 ChatGPT 和 Claude 的自建替代品。它運行在使用者自己的硬體上，所有資料本地儲存，不外送任何內容至第三方服務（除非使用者主動設定 API provider）。

為什麼需要 Odysseus？

需求	Odysseus 的解答
隱私控制	所有資料留在本地，不經過任何中間服務
模型自由	接入任何 LLM：本地 Ollama / vLLM / llama.cpp 或遠端 OpenAI / OpenRouter
功能整合	不只是聊天——agent / deep research / email / calendar / memory 一站式
硬體適配	Cookbook 自動掃描 GPU，推薦最合適的模型並一鍵部署
多用戶	支援多帳號、權限管理、2FA

專案規模與活躍度

Stars: 46,095（建立僅 5 天即達，爆炸性成長）
Forks: 5,313
建立日期: 2026-05-31
檔案數: 837 檔案
測試數: 300+ 個測試檔案
社群: 2,400+ Issues，極活躍的開發節奏

2. 安裝指南

2.1 Docker 安裝（推薦）

1git clone https://github.com/pewdiepie-archdaemon/odysseus.git
2cd odysseus
3cp .env.example .env       # 建議：明確設定預設值
4docker compose up -d --build

開啟 http://localhost:7000。Docker Compose 預設將 web UI bind 到 127.0.0.1。

首次登入：Odysseus 自動建立 admin 帳號，臨時密碼印在 terminal 中。Docker 安裝查看 docker compose logs odysseus。

Docker 內建服務：Compose 啟動 4 個服務——Odysseus + ChromaDB + SearXNG + ntfy。

2.2 Native Linux / macOS

1git clone https://github.com/pewdiepie-archdaemon/odysseus.git
2cd odysseus
3python3 -m venv venv
4source venv/bin/activate
5pip install -r requirements.txt
6python setup.py
7python -m uvicorn app:app --host 127.0.0.1 --port 7000

系統需求: Python 3.11+。Cookbook 需要 tmux。

2.3 Apple Silicon (M 系列 Mac)

Docker 無法使用 Metal GPU。要用 GPU 加速的 Cookbook，需原生安裝：

1git clone https://github.com/pewdiepie-archdaemon/odysseus.git
2cd odysseus
3./start-macos.sh

啟動在 http://127.0.0.1:7860（macOS 用 7860 是因為 AirPlay 常佔 7000）。

2.4 Windows

1git clone https://github.com/pewdiepie-archdaemon/odysseus.git
2cd odysseus
3powershell -ExecutionPolicy Bypass -File .\launch-windows.ps1

或手動：py -3.11 -m venv venv → pip install -r requirements.txt → python setup.py → uvicorn。

2.5 GPU 設定

NVIDIA：

1scripts/check-docker-gpu.sh                          # 診斷
2scripts/check-docker-gpu.sh --install-nvidia-toolkit  # 安裝 NVIDIA Container Toolkit
3scripts/check-docker-gpu.sh --enable-nvidia-overlay   # 啟用 GPU overlay

AMD / ROCm：

1scripts/check-docker-amd-gpu.sh
2# 然後在 .env 加入：
3# COMPOSE_FILE=docker-compose.yml:docker/gpu.amd.yml
4# RENDER_GID=989

3. 核心架構解析

Odysseus 採用經典的 FastAPI monolith (單體) 架構，前端使用原生 JavaScript（無 React / Vue），後端模組化設計，各功能以 routes + services 分層。


flowchart TD
    subgraph Frontend["前端 — 原生 JS + CSS"]
        UI[index.html + app.js]
        CHAT_JS[chat.js / chatStream.js]
        DOC_JS[document.js / editor/]
        RSCH_JS[research/ / researchSynapse.js]
        COOK_JS[cookbook.js / cookbookServe.js]
    end

    subgraph Backend["後端 — FastAPI / Python"]
        APP[app.py
FastAPI 入口]
        AUTH[core/auth.py
多用戶 + 2FA]
        LLM[src/llm_core.py
多 Provider LLM 呼叫]
        AGENT[src/agent_loop.py
Agent 工具執行迴圈]
        RESEARCH[services/research/
Deep Research]
        MEM[services/memory/
向量記憶]
        SEARCH[services/search/
SearXNG 整合]
        HWFIT[services/hwfit/
Cookbook 硬體適配]
    end

    subgraph Storage["儲存層"]
        SQLITE[(SQLite
app.db)]
        CHROMA[(ChromaDB
向量記憶)]
        FILES[data/
uploads / settings]
    end

    subgraph External["外部服務"]
        OLLAMA[Ollama / vLLM]
        OPENAI[OpenAI / OpenRouter]
        SEARX[SearXNG]
        IMAP[IMAP/SMTP]
        CALDAV[CalDAV Server]
    end

    UI --> APP
    CHAT_JS --> APP
    APP --> AUTH
    APP --> LLM
    APP --> AGENT
    APP --> RESEARCH
    APP --> MEM
    LLM --> OLLAMA & OPENAI
    SEARCH --> SEARX
    MEM --> CHROMA
    APP --> SQLITE & FILES

3.1 後端模組分層

層級	目錄	職責
入口	`app.py`	FastAPI app 初始化、middleware 註冊、auth 中間層
核心	`core/`	auth（bcrypt + 2FA）、database（SQLAlchemy）、middleware、constants
業務邏輯	`src/`	llm_core、agent_loop、agent_tools、chat_processor、deep_research、memory、embeddings
路由	`routes/`	40+ endpoint 檔案（chat / session / document / memory / model / email / calendar…）
服務	`services/`	docs / memory / research / search / hwfit / shell / stt / tts / youtube
MCP	`mcp_servers/`	email / image_gen / memory / rag 四個 MCP server
CLI	`scripts/`	20+ CLI 工具（odysseus / odysseus-mail / odysseus-memory / odysseus-research…）

3.2 Agent 架構

Agent loop (src/agent_loop.py) 是 streaming agent loop，包裝 stream_llm() 加上多輪 tool execution (工具執行)。LLM 透過寫 fenced code block 決定使用哪些工具。支援的工具包括：

bash — shell 命令執行（admin-only）
python — Python 腳本執行（admin-only）
read_file / write_file — 檔案讀寫（admin-only）
search_web — SearXNG 網頁搜尋
manage_memory — 記憶管理
MCP tools — 透過 MCP protocol 連接外部工具

工具安全由 src/tool_security.py 管控，非 admin 使用者無法存取 bash / python / file 工具。

3.3 Deep Research

基於 Alibaba NLP 的 Tongyi DeepResearch 改造，執行多步驟研究：

分解研究問題為子查詢
透過 SearXNG 搜尋多個來源
抓取並閱讀相關頁面
綜合產出結構化的視覺報告

3.4 Cookbook — 硬體適配模型推薦

services/hwfit/ 模組掃描本機硬體（GPU 型號、VRAM、RAM），根據 hardware fitting (硬體適配) 算法推薦合適的模型格式（GGUF / FP8 / AWQ），支援一鍵下載和 serving（透過 vLLM / llama.cpp）。

4. CLI 工具詳解

Odysseus 提供 20+ 個 CLI 工具，位於 scripts/ 目錄，涵蓋所有功能模組：

CLI 工具	功能
`odysseus`	主 CLI（啟動 / 設定 / 狀態）
`odysseus-mail`	Email 管理（收件匣 / 寄信 / 設定帳號）
`odysseus-memory`	記憶管理（列出 / 搜尋 / 匯出 / 匯入）
`odysseus-research`	Deep Research（啟動 / 列出 / 查看報告）
`odysseus-docs`	文件管理（列出 / 搜尋 / 匯出）
`odysseus-sessions`	Session 管理（列出 / 刪除 / 匯出）
`odysseus-tasks`	排程任務管理
`odysseus-calendar`	Calendar 同步管理
`odysseus-notes`	筆記管理
`odysseus-gallery`	圖片庫管理
`odysseus-cookbook`	Cookbook 模型管理
`odysseus-mcp`	MCP server 管理
`odysseus-skills`	Skills 管理
`odysseus-preset`	Preset 管理
`odysseus-theme`	主題設定
`odysseus-webhook`	Webhook 管理
`odysseus-backup`	備份 / 還原
`odysseus-personal`	個人文件管理
`odysseus-signature`	Email 簽名檔管理
`odysseus-logs`	Log 查看

所有 CLI 支援 bash/zsh completion（scripts/_completion/）。

5. 應用場景

5.1 個人 AI 助手

最典型的用途。部署在家中伺服器或 NAS 上，作為日常 AI 聊天、寫作、研究的私人助手。所有對話記錄、記憶、文件都留在本地。

5.2 小型團隊 AI 工作站

多用戶支援 + 權限管理 + 2FA，適合小型團隊共用一台 GPU 伺服器。每個使用者有獨立的 session、memory、documents，admin 可控制工具權限。

5.3 本地模型評測

Compare 功能提供多模型盲測比較，適合在選擇部署哪個模型時做 A/B testing。Cookbook 的 hardware fitting 功能幫助找到本機硬體能跑的最佳模型。

5.4 自動化研究

Deep Research 功能自動執行多步驟研究流程，從問題分解到來源蒐集到報告綜合，適合需要頻繁做市場調查或技術調研的場景。

5.5 Email + Calendar AI 整合

IMAP/SMTP inbox 整合 AI triage——自動分類緊急度、標記、摘要、產生回覆草稿、識別垃圾郵件。CalDAV 同步支援 Radicale / Nextcloud / Apple / Fastmail。

5.6 Claude Code / Codex 整合

integrations/ 目錄提供 Claude Code 和 Codex 的整合設定，讓 coding agent 可以存取 Odysseus 的記憶和技能。

6. 資安掃描報告

6.1 整體評級：🟡 中風險

Odysseus 作為一個功能豐富的自建平台，攻擊面較廣。專案有明確的安全意識（prompt injection hardening、tool security、SSRF protection），但某些設計本質上需要謹慎部署。

6.2 發現項目

🔴 高風險：Shell 命令執行（shell=True）

src/builtin_actions.py 中有 3 處使用 shell=True 執行使用者提供的命令：

1# Line 311 — 單行命令
2return await _run_subprocess(command, shell=True, timeout=120, label="Command")
3# Line 326, 336 — 多行腳本
4return await _run_subprocess(script, shell=True, timeout=300, label="Script")

雖然受 tool_security.py 限制為 admin-only，但 admin 帳號的 shell 存取是完整的 OS-level 存取。Issue #2401 報告了「取得其他使用者的 session responses and instructions」的問題，表示存在 owner scope 隔離不完全的風險。

🟡 中風險：多處 Owner Scope 不一致

多個 Issue 指出 endpoint 缺少 owner scope 保護：

Issue #2413：model-assisted route helpers 不帶 owner scope
Issue #2409：research spinoff endpoint fallback 不帶 owner scope
Issue #2401：可取得其他使用者的 session 資料

這在多用戶部署中構成 data isolation (資料隔離) 風險。

🟡 中風險：API Key 明文存儲

Issue #eee2167（已修復）：save() 將其他 provider 的 API key 以 plaintext (明文) 寫入。修復已合併，但反映出 secret management (密鑰管理) 需持續關注。

🟡 中風險：Prompt Injection Hardening

src/prompt_security.py 實作了 untrusted context 標記系統，將外部內容標記為 UNTRUSTED_SOURCE_DATA。這是好的防禦措施，但最終仍依賴 LLM 遵守指令，非技術性保證。

🟢 低風險：SSRF 防護

src/url_safety.py 實作了 outbound URL 檢查：

阻擋非 HTTP(S) scheme（file:// / gopher:// / ftp://）
阻擋 link-local range（169.254.0.0/16）防止雲端 metadata 竊取
EMBEDDING_BLOCK_PRIVATE_IPS=true 可啟用完整 SSRF lockdown

設計合理——預設允許 loopback/LAN（因為這是正常使用情境），但提供嚴格模式。

🟢 低風險：認證系統

bcrypt 密碼雜湊 + pyotp 2FA + session token + API token，實作合理。LOCALHOST_BYPASS 預設為 false，AUTH_ENABLED 預設為 true。

6.3 安全建議

部署：絕對不要直接暴露到公網，務必透過 reverse proxy + HTTPS
多用戶：在 owner scope 問題全部修復前，謹慎評估多用戶部署的風險
Admin 權限：僅授予信任的使用者 admin 權限（含 shell / file 存取）
API Keys：定期輪換所有 API key，特別是曾在聊天或截圖中出現過的
Auth 設定：AUTH_ENABLED=true + LOCALHOST_BYPASS=false + SECURE_COOKIES=true
監控：定期檢查 data/auth.json 的帳號設定

7. FAQ

Q1: Odysseus 跟 Open WebUI 有什麼差別？

Odysseus 的定位更接近「個人 AI 工作站」而非純聊天介面。除了 chat 外，還整合了 agent（tool execution）、deep research、email/calendar、document editor、memory/skills 等，是更完整的 workspace 概念。

Q2: 需要什麼硬體？

核心 app 很輕量（FastAPI + SQLite），任何能跑 Python 3.11 的機器都行。資源消耗主要來自本地模型 serving——這取決於你選的模型、runtime (vLLM / llama.cpp / Ollama) 和 GPU。沒有 GPU 的機器可以只用遠端 API（OpenAI / OpenRouter）。

Q3: 支援哪些 LLM provider？

本地: Ollama、vLLM、llama.cpp、SGLang
遠端: OpenAI、OpenRouter、Anthropic（透過 OpenAI-compatible API）
自訂: 任何 OpenAI-compatible endpoint

Q4: 資料存在哪裡？

所有使用者資料在 data/ 目錄（gitignored）：app.db（SQLite）、memory.json、presets.json、uploads/、personal_docs/、chroma/、settings.json。

Q5: 可以同時給多人用嗎？

可以。多用戶帳號 + 權限管理 + 2FA。但目前有若干 owner scope 隔離不完全的 Issue（見資安掃描），在完全修復前應謹慎評估。

Q6: Mobile 支援如何？

響應式設計 + PWA (Progressive Web App)，在手機瀏覽器安裝後有接近 native app 的體驗。

8. 進階技巧

8.1 環境變數設定

變數	預設值	說明
`LLM_HOST`	`localhost`	LLM server 位址
`LLM_HOSTS`	—	多個 LLM server（逗號分隔）
`APP_BIND`	`127.0.0.1`	Web UI bind 位址
`APP_PORT`	`7000`	Web UI port
`AUTH_ENABLED`	`true`	啟用登入
`LOCALHOST_BYPASS`	`false`	Loopback auth bypass（開發用）
`SECURE_COOKIES`	`false`	HTTPS cookie
`DATABASE_URL`	`sqlite:///./data/app.db`	資料庫連線字串
`CHROMADB_HOST`	`localhost`	ChromaDB host
`EMBEDDING_URL`	—	自訂 embedding endpoint
`SEARXNG_INSTANCE`	`http://localhost:8080`	SearXNG URL

8.2 MCP Server 設定

Odysseus 內建 4 個 MCP server（mcp_servers/）：

Server	功能
`email_server.py`	Email 收發與搜尋
`image_gen_server.py`	圖片生成
`memory_server.py`	記憶讀寫
`rag_server.py`	RAG 檢索

另外自動註冊 Playwright MCP（需先 npx -y @playwright/mcp@latest --version）。

8.3 Ollama 整合（Docker 部署）

若 Ollama 在 host 上運行：

1# 在 Settings 中加入 endpoint：
2http://host.docker.internal:11434/v1
3
4# Ollama 需要 listen 在 0.0.0.0：
5OLLAMA_HOST=0.0.0.0:11434 ollama serve

8.4 HTTPS + Tailscale / LAN 暴露

1mkcert -install
2mkcert -cert-file cert.pem -key-file key.pem 192.168.1.100 tailscale-ip
3python -m uvicorn app:app --host 0.0.0.0 --port 7000 \
4  --ssl-certfile=cert.pem --ssl-keyfile=key.pem

8.5 可選依賴

套件	啟用功能
`faster-whisper`	本地 speech-to-text (語音轉文字)
`duckduckgo-search`	DuckDuckGo 搜尋
`PyMuPDF`	PDF 頁面渲染 + 表單填寫（注意：AGPL-3.0）
`markitdown`	Office/EPUB 文件轉 Markdown

9. 整合進其他工作流

9.1 與 Claude Code 整合

integrations/claude/ 目錄提供 Claude Code 的 skills 和 README，讓 Claude Code 可以存取 Odysseus 的 memory 和 skill 系統。

9.2 與 Codex 整合

integrations/codex/ 目錄提供 Codex 的 plugin 設定和 scripts，整合 Odysseus 的功能到 Codex 工作流中。

9.3 作為研究工具

Deep Research 功能可以取代或補充手動研究流程。透過 CLI odysseus-research，可以自動化研究任務的觸發和報告取得。

9.4 部署為團隊服務

1# docker-compose.yml 已內建：
2services:
3  odysseus:    # 主應用，port 7000
4  chromadb:    # 向量記憶，port 8100
5  searxng:     # 搜尋引擎，port 8080
6  ntfy:        # 通知服務，port 8091

加上 reverse proxy（Caddy / nginx / Traefik）+ HTTPS，即可供團隊使用。

10. 重點摘要 Checklist

安裝：docker compose up -d --build → http://localhost:7000
首次登入：查看 terminal / docker compose logs odysseus 取得臨時 admin 密碼
設定 LLM：Settings 頁面加入 Ollama / OpenAI / OpenRouter endpoint
設定搜尋：SearXNG 預設已在 Docker Compose 內啟動
GPU 加速：執行 scripts/check-docker-gpu.sh 設定 NVIDIA overlay
記憶系統：ChromaDB + fastembed 預設啟用，agent 自動學習
Deep Research：點擊 Research tab 或使用 odysseus-research CLI
Email：Settings → Email 設定 IMAP/SMTP 帳號
Calendar：Settings → Calendar 設定 CalDAV sync
安全：AUTH_ENABLED=true + 不暴露到公網 + reverse proxy + HTTPS
備份：odysseus-backup CLI 或 Settings → Backup
已知風險：多用戶 owner scope 隔離尚有若干 Issue 待修復

11. 進一步閱讀

官方 Landing Page: https://pewdiepie-archdaemon.github.io/odysseus/
CONTRIBUTING.md: https://github.com/pewdiepie-archdaemon/odysseus/blob/main/CONTRIBUTING.md
ROADMAP.md: https://github.com/pewdiepie-archdaemon/odysseus/blob/main/ROADMAP.md
SECURITY.md: https://github.com/pewdiepie-archdaemon/odysseus/blob/main/SECURITY.md
THREAT_MODEL.md: https://github.com/pewdiepie-archdaemon/odysseus/blob/main/THREAT_MODEL.md
ACKNOWLEDGMENTS.md: https://github.com/pewdiepie-archdaemon/odysseus/blob/main/ACKNOWLEDGMENTS.md
Docker GPU 設定: scripts/check-docker-gpu.sh --help
CLI Completion: scripts/_completion/odysseus.bash / odysseus.zsh

Odysseus 完整教學 — Self-Hosted AI Workspace

Contents

Odysseus 完整教學 — Self-Hosted AI Workspace

1. 專案定位

為什麼需要 Odysseus？

專案規模與活躍度

2. 安裝指南

2.1 Docker 安裝（推薦）

2.2 Native Linux / macOS

2.3 Apple Silicon (M 系列 Mac)

2.4 Windows

2.5 GPU 設定

3. 核心架構解析

3.1 後端模組分層

3.2 Agent 架構

3.3 Deep Research

3.4 Cookbook — 硬體適配模型推薦

4. CLI 工具詳解

5. 應用場景

5.1 個人 AI 助手

5.2 小型團隊 AI 工作站

5.3 本地模型評測

5.4 自動化研究

5.5 Email + Calendar AI 整合

5.6 Claude Code / Codex 整合

6. 資安掃描報告

6.1 整體評級：🟡 中風險

6.2 發現項目

🔴 高風險：Shell 命令執行（shell=True）

🟡 中風險：多處 Owner Scope 不一致

🟡 中風險：API Key 明文存儲

🟡 中風險：Prompt Injection Hardening

🟢 低風險：SSRF 防護

🟢 低風險：認證系統

6.3 安全建議

7. FAQ

Q1: Odysseus 跟 Open WebUI 有什麼差別？

Q2: 需要什麼硬體？

Q3: 支援哪些 LLM provider？

Q4: 資料存在哪裡？

Q5: 可以同時給多人用嗎？

Q6: Mobile 支援如何？

8. 進階技巧

8.1 環境變數設定

8.2 MCP Server 設定

8.3 Ollama 整合（Docker 部署）

8.4 HTTPS + Tailscale / LAN 暴露

8.5 可選依賴

9. 整合進其他工作流

9.1 與 Claude Code 整合

9.2 與 Codex 整合

9.3 作為研究工具

9.4 部署為團隊服務

10. 重點摘要 Checklist

11. 進一步閱讀

Related Posts

Comments