odysseus-dev / odysseus

odysseus-dev/odysseus

open_in_new前往仓库

自托管AI工作空间。

项目概览

项目概述

Odysseus 是一个自托管的 AI 工作空间，集成了聊天、智能体、研究、文档、邮件、笔记、日历和本地模型工作流。它旨在提供一个全面的、可本地部署的 AI 助手平台，用户可以在其中管理日常任务和知识。项目使用 Python 编写，采用 AGPL-3.0 许可证。

核心功能

  • 聊天与智能体：支持本地/API 模型、工具、MCP、文件、Shell、技能和记忆。
  • Cookbook：提供硬件感知的模型推荐、下载和服务。
  • 深度研究：多步骤网络研究，包括来源阅读和报告生成。
  • 对比：盲测并排模型测试和综合。
  • 文档：以写作为先的编辑器，支持 AI 编辑、建议、Markdown、HTML、CSV 和语法高亮。
  • 邮件：IMAP/SMTP 收件箱，支持分类、标签、摘要、提醒和回复草稿。
  • 笔记、任务和日历：提醒、待办事项、定时智能体任务和 CalDAV 同步。
  • 其他：图库/图像编辑器、主题、上传、网络搜索、预设、会话和双因素认证。

适用与不适用场景

适用场景：

  • 希望完全掌控数据和 AI 工作流的个人或团队。
  • 需要集成聊天、文档、邮件、日历等多种功能的统一工作空间。
  • 希望使用本地模型或私有 API 进行 AI 任务。
  • 需要深度研究和文档处理能力的用户。

不适用场景：

  • 需要托管式、零维护解决方案的用户。
  • 对 Microsoft Outlook/Office 365 邮件有强依赖的用户（当前不支持 OAuth）。
  • 需要大规模多用户协作和复杂权限管理的企业环境。
  • 希望快速部署且不熟悉 Docker 或 Python 环境的用户。

技术架构与依赖

  • 后端：Python 3.11+，FastAPI 框架。
  • 前端：静态 HTML/CSS/JavaScript，模块化设计。
  • 数据库：SQLite（默认），支持 PostgreSQL 等通过 DATABASE_URL 配置。
  • 向量存储：ChromaDB（用于记忆和 RAG）。
  • 搜索：SearXNG（元搜索）。
  • 通知：ntfy（自托管推送通知）。
  • 模型服务：支持 Ollama、vLLM、SGLang、llama.cpp 等。
  • 部署：Docker Compose 推荐，也支持原生安装（Linux/macOS/Windows）。

安装与快速开始

Docker（推荐）

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
cp .env.example .env
docker compose up -d --build

打开 http://localhost:7000，首次登录密码在 docker compose logs odysseus 中。

原生安装（Linux/macOS）

git clone https://github.com/odysseus-dev/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

Windows

使用 launch-windows.ps1 脚本或手动安装。

典型使用方法

  • 配置模型：在设置中添加 OpenAI 兼容端点或本地模型服务器（如 Ollama）。
  • 创建智能体：使用内置工具（文件、Shell、搜索）和技能。
  • 深度研究：启动多步骤研究任务，生成报告。
  • 文档处理：使用 AI 编辑、建议和格式转换。
  • 邮件管理：连接 IMAP/SMTP 账户，自动分类和摘要。
  • 日历同步：通过 CalDAV 同步日历和任务。

配置与部署要点

  • 环境变量：通过 .env 文件配置端口、认证、数据库等。
  • 安全：保持 AUTH_ENABLED=true，使用 HTTPS 反向代理，不暴露原始服务端口。
  • 备份：使用 scripts/odysseus-backup 工具备份 data/ 目录。
  • GPU 支持：Docker 需要配置 NVIDIA/AMD GPU 覆盖层。
  • HTTPS：使用 mkcert 生成证书，配置反向代理。

限制、风险与许可证

  • 限制：不支持 Microsoft Outlook/Office 365 OAuth；Windows 原生安装未充分测试；Docker 中 ChromaDB 数据不在 data/ 目录内，需单独备份。
  • 风险：自托管包含强大工具（Shell、文件访问），需严格管理认证和权限；备份包含敏感数据，需安全存储。
  • 许可证：AGPL-3.0-or-later。

官方链接

信息来源和分析时间

  • 信息来源：GitHub 仓库 README、CONTRIBUTING.md、docs/setup.md、docs/backup-restore.md、docs/email-outlook.md、docs/agent-migration.md、docs/attachments.md、docs/security-ci.md、docs/pr-blocker-audit.md。
  • 分析时间：2026-05-12（基于仓库内容推断，实际分析时间未提供）。