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

本教程将指导你完成 Odysseus 的部署——一个集聊天、代理、研究、文档、邮件、笔记和日历于一体的自托管 AI 工作区。

📋 准备工作

1. 硬件与系统要求

操作系统：Linux、macOS 或 Windows（通过 Docker Desktop 或 WSL2）。
Python 版本：3.11 或更高版本（原生安装方式）。
Docker（推荐方式）：Docker Engine 和 Docker Compose。
网络：确保 7000 端口（或 Windows 下的 7400 端口）未被占用。

2. 选择分支

项目有两个主要分支：

main 分支：经过充分测试的稳定分支，推荐生产或日常使用。
dev 分支：包含最新功能，更新频繁但可能不够稳定。

🐳 方式一：使用 Docker 部署（通用推荐）

这是最快捷的部署方式，适用于大多数 Linux 服务器和 Windows/macOS（尽管在 macOS 上 GPU 加速受限）。

1. 克隆并进入项目目录

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

如果你需要使用稳定版 main 分支：

1	git checkout main

2. 配置环境变量

复制示例环境变量文件：

1	cp .env.example .env

默认情况下，无需修改 .env 即可启动。如需启用 GPU 支持等高级功能，可后续编辑此文件。

3. 启动服务

使用 Docker Compose 构建并启动所有容器：

1	docker compose up -d --build

该命令会以后台模式启动 Odysseus 及其依赖服务（如 ChromaDB、SearXNG）。首次启动可能需要几分钟时间下载镜像和构建。

4. 访问与获取密码

访问地址：打开浏览器，访问 http://localhost:7000 。
获取初始管理员密码：
首次启动时，系统会为 admin 账户生成一个随机密码。在终端中执行以下命令查看密码：
1
docker compose logs odysseus | grep "Admin password"
日志中会显示类似 Admin password: YOUR_GENERATED_PASSWORD 的信息。

🍏 方式二：macOS 原生部署（推荐以使用 GPU）

在 Apple Silicon Mac 上，Docker 无法直接访问 Metal GPU，模型将运行在 CPU 上，速度极慢。因此，强烈推荐使用原生安装方式以获得 GPU 加速 。

1. 克隆项目（建议使用稳定分支）

1
2
3

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

2. 运行启动脚本

项目提供了自动化脚本：

1	./start-macos.sh

该脚本会自动创建 Python 虚拟环境、安装依赖并启动服务。如果系统提示 7000 端口被占用（如 AirPlay），服务会自动切换到 http://127.0.0.1:7860。

3. 设置管理员账户

首次访问网页时，系统会引导你为 admin 账户设置一个新密码。

4. 配置本地模型（以 Ollama 为例）

原生安装后，需要连接一个本地模型服务才能开始对话。

安装并启动 Ollama：从 ollama.com 下载安装，然后在终端拉取一个模型（例如 qwen3:30b-a3b）并运行服务：
1
2
ollama pull qwen3:30b-a3b
OLLAMA_HOST=0.0.0.0:11434 ollama serve
在 Odysseus 中添加模型：在 Odysseus 界面中，进入 设置 (Settings) -> 模型提供商 (Model Providers) -> 本地 (Local)，添加 Ollama 的 API 地址：http://localhost:11434/v1。保存后即可在聊天中选择已下载的模型。

方式三：Windows 部署（Docker Desktop）

Windows 使用 Docker Desktop 可能会遇到 CRLF 换行符和端口被 Hyper-V 保留的问题。项目提供了专门的处理方案。

使用自动化脚本（推荐）

在项目目录中，使用 PowerShell 运行启动脚本：

1	.\launch-windows-docker.ps1

该脚本会自动处理端口冲突等问题。服务将在 http://localhost:7400 端口启动。

手动部署

如果希望手动操作，可以使用专用的 Compose 文件：

1	docker compose -f docker-compose.windows.yml up -d --build

🚀 高级配置与故障排除

1. 启用 GPU 支持（Linux Docker）

NVIDIA GPU：
1. 在宿主机上安装 NVIDIA Container Toolkit。
2. 运行诊断脚本并自动启用 GPU 覆盖层：
  1
  scripts/check-docker-gpu.sh --install-nvidia-toolkit --enable-nvidia-overlay
  该脚本会在 .env 文件中自动添加 COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml 。
3. 重新构建并启动容器以应用更改。
AMD GPU：
1. 运行诊断脚本获取配置信息：
  1
  scripts/check-docker-amd-gpu.sh
2. 手动编辑 .env 文件，添加类似以下内容（请替换为实际值）：
  1
  2
  COMPOSE_FILE=docker-compose.yml:docker/gpu.amd.yml
  RENDER_GID=989
3. 重新构建并启动容器。

2. 安全注意事项

Odysseus 拥有强大的本地工具权限。对于任何网络可访问的部署，请确保以下安全设置：

保持 AUTH_ENABLED=true（身份验证启用）。
保持 LOCALHOST_BYPASS=false（禁止绕过本地访问）。
如果通过 HTTPS 提供服务，请在 .env 中设置 SECURE_COOKIES=true。

3. 常见问题

无法找到 chromadb：如果出现与 ChromaDB 相关的错误，尝试卸载轻量版并重装完整版：
1
2
./venv/bin/pip uninstall chromadb-client -y
./venv/bin/pip install --force-reinstall chromadb
GPU 直通成功但模型仍运行在 CPU：nvidia-smi 在容器内成功不代表 llama.cpp 能使用 CUDA。需要在 Cookbook 中重新安装模型服务引擎（如 llama.cpp），以获取支持 GPU 的构建版本。
端口冲突：如果 7000 端口被占用，可以在启动时指定其他端口，或在 .env 中修改 APP_PORT 变量。