pewdiepie-archdaemon/odysseus · 上手攻略

  • 仓库：pewdiepie-archdaemon/odysseus
  • 链接：https://github.com/pewdiepie-archdaemon/odysseus
  • 分类：AI · 自托管工作台（AI Workspace）
  • 作者：Jay
  • 更新：2026-07-05

这是什么

Odysseus 是一个自托管 AI 全功能工作台，集成了聊天/Agent、深度研究、文档编辑、邮件、笔记/日历/任务、模型评测对比、本地模型服务等模块，用 Docker 一键部署，数据全留本地。

它的定位类似"本地版的 ChatGPT + Notion + Gmail + 深度研究工具"的合体，但完全自托管，支持接入本地运行的 LLM（Ollama / vLLM）或任意 OpenAI 兼容 API。适合对数据隐私有要求、不想把日常工作数据发给第三方云服务的用户或团队。

技术栈 - 后端：Python 3.11+，Uvicorn - 前端：React（具体版本见源码） - 容器：Docker + Docker Compose - 向量数据库：ChromaDB（bundled） - 搜索：SearXNG（bundled） - 通知：ntfy（bundled） - 本地模型服务：llama.cpp / Ollama / vLLM - 协议：Web UI、REST API、SSH（远程服务器管理） - License：AGPL-3.0

数据来源 README：README，Setup Guide

解决什么问题

  1. 数据隐私：所有聊天记录、邮件、文档、笔记全部存在自己的服务器上，不经过任何第三方云服务。
  2. 本地模型：内置 Cookbook 模块，支持下载并本地 serving HuggingFace 模型，用自己的 GPU 跑 LLM，不消耗 API 额度。
  3. 一站式工作流：不用在多个工具之间切换——聊天、邮件、笔记、日历、研究、写文档，全部在一个界面内完成。
  4. MCP 工具支持：内置 MCP 协议，可以给 AI Agent 扩展工具（文件系统、Shell、代码执行等）。
  5. 深度研究：多步骤网页研究，自动抓取来源并生成报告，比单次 API 调用更有深度。

快速安装

方式一：Docker Compose（推荐，最简单）

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
cp .env.example .env        # 可选，defaults 开箱即用
docker compose up -d --build

首次启动后，admin 初始密码在 docker compose logs odysseus 中打印。

打开 http://localhost:7000 ，用 admin 账户登录后修改密码。

方式二：macOS 原生（含 GPU 支持）

Docker Desktop on M-series Mac 无法访问 Metal GPU，如需 GPU 加速本地模型，用原生脚本：

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

默认启动在 http://127.0.0.1:7860。绑定到 LAN/VPN 供手机访问：

ODYSSEUS_HOST=0.0.0.0 ./start-macos.sh
# 然后打开 http://<tailscale-ip>:7860

方式三：Linux/macOS 原生（无 Docker）

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

要求：Python 3.11+。Cookbook 模块还需要 tmux。

GPU 加速（NVIDIA）

# 诊断 GPU 是否正确暴露给 Docker
./scripts/check-docker-gpu.sh

# 安装 NVIDIA Container Toolkit（Ubuntu/Debian）
./scripts/check-docker-gpu.sh --install-nvidia-toolkit

# 自动写入 COMPOSE_FILE 到 .env
./scripts/check-docker-gpu.sh --enable-nvidia-overlay

或在 .env 中手动加：

COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml

验证：

docker compose exec odysseus nvidia-smi -L

AMD GPU（ROCm）

./scripts/check-docker-amd-gpu.sh
# 会输出需要在 .env 中添加的内容

自定义配置（可选）

.env 中常用配置项：

APP_PORT=7000              # 端口
APP_BIND=127.0.0.1         # 绑定地址（改为 0.0.0.0 允许 LAN 访问）
AUTH_ENABLED=true          # 认证开关
ODYSSEUS_ADMIN_USER=admin  # 管理员用户名

⚠️ AUTH_ENABLED=false 会关闭登录验证，仅在你完全信任网络时使用。

核心用法

Chat + Agents

启动后点击左侧 "Chat" 新建对话，可选： - API 模型：接入 OpenAI / Anthropic / Ollama 等 - 本地模型：通过 Cookbook 下载并 serving 的 HuggingFace 模型 - 工具：MCP 工具（文件系统、Shell、代码执行等）

Cookbook（本地模型管理）

  1. 进入 Settings → Servers 添加远程 Ollama / vLLM 服务器
  2. 进入 Cookbook，浏览推荐的模型（按你的硬件推荐）
  3. 点击下载，llama.cpp 在后台 serving
  4. 返回 Chat，切换到对应模型开始对话

M-series Mac 用 Docker 时 Cookbook 只能跑 CPU；建议用 ./start-macos.sh 原生运行以获得 GPU 加速。

Deep Research（深度研究）

  1. 输入研究主题
  2. 系统自动规划多步骤搜索：SearXNG 搜索 → 读取来源网页 → 汇总
  3. 生成带引用来源的研究报告

SearXNG 为 bundled 服务，不需要额外配置。

Compare（模型对比）

盲测：同时对两个模型/配置输入相同 prompt，返回两者回答后可对比效果，用于做模型选型决策。

Email（邮件）

  • IMAP/SMTP 配置：Settings → Email 填入邮箱账号
  • 支持：收件箱分类、标签、摘要、回复草稿生成、提醒

Notes + Tasks + Calendar

  • 笔记：Markdown 编写，支持 AI 润色/建议
  • 任务：待办清单
  • 日历：CalDAV 同步（需配置 CalDAV 服务器）
  • 支持设置定时 Agent 任务

Documents（文档编辑）

内置写作编辑器，支持： - Markdown / HTML / CSV 预览 - AI 编辑和润色建议 - 语法高亮

远程服务器管理

在 Settings → Servers 添加远程机器的 SSH Key，Cookbook 可以管理远程服务器上的模型：

# 手动添加 SSH 公钥到远程服务器
ssh-copy-id -i data/ssh/id_ed25519.pub user@your-server

典型适用场景

  1. 隐私敏感团队：所有数据存在本地，适合医疗、法律、金融等数据合规要求严格的场景。
  2. 开发者本地调试：在本地跑各种模型，对比不同模型的效果，不需要每次都调 API。
  3. 深度研究需求：需要 AI 进行多轮搜索、阅读大量网页并汇总报告，Compose 里内置了 SearXNG。
  4. 个人 AI 工作台：把邮件、笔记、日历、聊天统一到一个界面，减少工具切换成本。
  5. 离线/内网使用：在完全没有外网访问权限的内网服务器上部署，所有功能仍可使用（本地模型 + 向量数据库）。

坑与注意

问题 说明
Docker on M-series Mac 无 Metal GPU 这是 Docker 桌面版的限制，不是 Odysseus 的 bug。解决：使用 ./start-macos.sh 原生运行。
首次 admin 密码需要从日志获取 docker compose logs odysseus 中搜索密码，登录后立刻改掉。
端口 7000 被占用 在 .env 中设置 APP_PORT=7001 后重建容器。
Docker Socket 默认未挂载 docker compose.yml 默认不挂载 /var/run/docker.sock，远程 Docker 管理需要 COMPOSE_FILE=docker-compose.yml:docker/host-docker.yml 并设置 DOCKER_GID。
nvidia-smi 通过 ≠ llama.cpp 能用 CUDA GPU 通过 Docker 暴露只是第一步；llama.cpp 还需要 cudart 库。如果看到 "Unable to find cudart library"，需要通过 Cookbook → Dependencies 重新安装 CUDA 版 llama.cpp。
macOS Docker 容器内 SearXNG / ChromaDB 这些 bundled 服务在容器内运行，macOS 上需要确保 Docker 有足够内存分配（建议 ≥ 4GB）。
AGPL-3.0 License 如果你要 fork 并商业使用，需要注意 AGPL 的传染性——修改服务端代码需要开源。

与同类对比

维度 Odysseus Jan Open WebUI Flowise
定位 全功能工作台 本地 ChatGPT ChatGPT 前端 No-code LLM 编排
邮件/日历/笔记 ✅ ❌ ❌ ❌
Deep Research ✅ ❌ ❌ ❌
Cookbook（本地模型管理） ✅ ✅ ❌ ❌
模型对比 ✅ ⚠️ ❌ ❌
Docker 一键部署 ✅ ✅ ✅ ✅
License AGPL-3.0 AGPL-3.0 Apache 2.0 Apache 2.0

Odysseus 的核心差异化：唯一同时内置邮件+日历+笔记+深度研究+模型对比的全栈工作台，且完全 Docker 化部署。如果你只需要 Chat UI，Jan 或 Open WebUI 更轻量；如果需要统一所有日常工作流到 AI，Odysseus 是最完整的开源选项。

一句话推荐结论

如果你想要一个"数据全留本地"的 AI 工作台，Odysseus 是目前开源生态中功能最完整的一体化方案——邮件、笔记、研究、模型对比，一套 docker compose 全搞定，值得在内网或私有部署场景中认真评估。