Odysseus 自托管 AI 工作区详细部署教程

Odysseus 是一个功能强大的自托管 AI 工作区，它将聊天、智能体、研究、文档、邮件、笔记、日历和本地模型工作流整合在一个统一的平台中。您可以通过 Docker 快速部署，获得一个属于自己的、可完全掌控的 AI 生产力中心。

📋 目录

Odysseus 是什么
系统要求与硬件准备
快速部署（Docker Compose）
首次启动与配置
高级部署选项
核心功能与使用场景
配置与安全
更新与卸载
常见问题排查

Odysseus 是什么

Odysseus 是一个自托管的 AI 工作区，旨在为您提供一个统一、私密的 AI 生产力环境。它整合了多种常用工具和 AI 能力，像一个本地的“AI 操作系统”。

核心功能模块：

聊天与智能体：支持本地和云端 AI 模型，集成工具、MCP（模型上下文协议）、文件、Shell、技能和记忆。
深度研究：执行多步骤网络研究，阅读来源并生成报告。
文档编辑器：专为写作优化的编辑器，支持 AI 编辑、建议、Markdown、HTML、CSV 和语法高亮。
邮件客户端：通过 IMAP/SMTP 管理邮箱，支持邮件分类、标签、摘要、提醒和回复草稿生成。
笔记、任务与日历：集成了提醒、待办事项、定时智能体任务，并支持 CalDAV 同步。
模型 Cookbook：提供硬件感知的模型推荐、下载和服务功能。
模型比较：并排盲测不同模型，并支持结果综合。

系统要求与硬件准备

基本要求

操作系统：Linux (推荐)、macOS 或 Windows (需支持 Docker)。
Docker 与 Docker Compose：核心依赖，必须安装。
硬件：
- CPU：至少 2 核心。
- 内存：建议 ≥ 4GB（运行本地模型需要更多）。
- 存储：至少 20GB 可用空间（用于镜像、模型和数据）。
网络：需要能够访问互联网（用于拉取镜像和下载模型）。

可选硬件

GPU (NVIDIA/AMD)：如需运行本地大模型，支持 GPU 加速。项目提供了 docker-compose.gpu-nvidia.yml 和 docker-compose.gpu-amd.yml 文件。

快速部署（Docker Compose）

这是推荐的安装方式，通过 Docker Compose 一键启动所有服务。

1. 克隆项目仓库

1 2	git clone https://github.com/odysseus-dev/odysseus.git cd odysseus

2. 配置环境变量

1	cp .env.example .env

您可以根据需要编辑 .env 文件，配置端口、认证、邮件等参数。默认配置即可工作。

3. 启动服务

1	docker compose up -d --build

该命令会在后台启动所有必要的容器（Odysseus 核心、数据库、可选服务等）。首次启动会下载镜像，可能需要几分钟。

4. 访问工作区
等待容器启动并显示健康状态后，打开浏览器访问 http://localhost:7000。

5. 获取管理员密码
首次启动时，系统会自动生成一个管理员密码。您可以通过以下命令查看：

1	docker compose logs odysseus \| grep "Admin password"

在日志输出中，您会看到类似 Admin password: your-generated-password 的信息。

首次启动与配置

登录：使用用户名 admin 和从日志中获取的密码登录。
设置模型提供商：进入设置页面，配置您想使用的 AI 模型。Odysseus 支持：
- 本地模型：通过 Ollama、LM Studio 等本地运行的服务。
- 云端 API：OpenAI、Anthropic、Google Gemini 等。
- 自托管网关：如 LiteLLM、OpenRouter。
探索工作区：开始创建聊天、文档、研究任务或连接您的邮箱和日历。

高级部署选项

1. 使用 GPU 加速

如果您有 NVIDIA 或 AMD GPU，并希望运行本地模型，可以使用对应的 Compose 文件。

NVIDIA GPU:

1	docker compose -f docker-compose.yml -f docker-compose.gpu-nvidia.yml up -d --build

AMD GPU:

1	docker compose -f docker-compose.yml -f docker-compose.gpu-amd.yml up -d --build

2. 使用稳定分支

项目默认使用 dev 分支（包含最新更新）。如果您更倾向于稳定版，可以在克隆后切换到 main 分支。

1
2
3

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
git checkout main

3. macOS 桌面应用

项目提供了构建 macOS 应用的脚本（build-macos-app.sh），可以生成一个独立的 .app 应用包。

4. Windows 便携版

使用 build-windows-portable.ps1 和 launch-windows.ps1 脚本，可以创建和启动一个 Windows 便携版本。

核心功能与使用场景

个人知识库与写作：使用“文档”模块撰写文章、笔记，并利用 AI 进行润色、摘要或续写。
智能研究助手：使用“深度研究”功能，输入一个主题，AI 会自动搜索、阅读多个网页，并生成一份带引用的综合报告。
统一邮件管理：连接您的邮箱，让 AI 自动为邮件生成摘要、分类（如“重要”、“待办”），并起草回复。
模型评估与对比：使用“比较”功能，让两个不同的模型回答同一个问题，盲测并比较它们的输出质量。
自动化任务：结合“智能体”和“日历/任务”，创建定时任务，例如每天自动抓取特定网站新闻并生成简报。

配置与安全

Odysseus 的配置主要通过 .env 文件和环境变量进行。

关键安全配置：

AUTH_ENABLED：强烈建议保持为 true（默认），以启用身份验证。任何网络可访问的部署都必须开启。
LOCALHOST_BYPASS：本地开发时可设为 true，但生产环境请设为 false，防止绕过认证。
SECRET_KEY：在 .env 中设置一个强随机字符串，用于加密会话。
HTTPS：在生产环境中，应配置反向代理（如 Nginx）提供 HTTPS 支持。具体配置请参考项目的 Setup Guide。

数据存储：

所有数据默认存储在 Docker 卷中，随容器生命周期管理。如需持久化或备份，可查看 docker-compose.yml 中的卷定义。

更新与卸载

更新 Odysseus

进入项目目录：cd odysseus
拉取最新代码：git pull (如果您在 dev 分支)

重新构建并启动容器：

1 2	docker compose down docker compose up -d --build

卸载 Odysseus

停止并删除容器与网络：
1
docker compose down -v
（-v 参数会删除关联的 Docker 卷，这将永久删除所有数据）
删除项目文件夹：cd .. && rm -rf odysseus

常见问题排查

问题：容器无法启动，或一直显示 unhealthy 状态。

解决：检查 Docker 是否分配了足够的内存和 CPU。使用 docker compose logs <服务名> 查看具体错误日志。常见原因有端口冲突（7000 被占用）或环境变量配置错误。

问题：忘记管理员密码。

解决：可以通过 docker compose exec odysseus python -c "from core.auth import reset_admin_password; reset_admin_password()" 命令重置密码（具体命令可能随版本变化，可参考官方文档）。

问题：无法连接本地 Ollama 或 LM Studio。

解决：在 Docker 中，localhost 指向容器自身。您需要使用 host.docker.internal (macOS/Windows) 或主机的真实 IP 地址来访问宿主机上的服务。例如，在 Odysseus 中配置 Ollama 的 Base URL 为 http://host.docker.internal:11434。

问题：部署在远程服务器上，但希望本地访问。

解决：确保服务器防火墙开放了 7000 端口。在 .env 中配置 HOST=0.0.0.0，并考虑配置 Nginx 反向代理和 HTTPS。

通过以上步骤，您应该已经成功部署了 Odysseus 并可以开始探索其丰富的功能。如需深入了解每个模块的详细用法或高级配置，强烈建议查阅项目内的 Setup Guide 和官方文档。