Odysseus 部署实战: 30 分钟搭一套自托管 AI 工作台

一句话简介: 想从 ChatGPT/Claude 网页里"出逃", 把整个 AI 工作台装到自己机器上? 这篇带你跑通 Odysseus — 一个本地优先、隐私优先的 ChatGPT 自托管替代品。

项目简介

Odysseus 是一个 自托管的 AI 工作台 (Self-hosted AI Workspace), 来自 GitHub 用户 pewdiepie-archdaemon, MIT 协议开源。它想做的是: 让你在自己的机器上跑出 ChatGPT / Claude 那种 UI 体验, 但所有数据、所有对话、所有工具调用, 都留在本地。

和传统 ChatGPT 类应用比, 它的差异点很清晰:

• 聊天: 接任意本地或远端模型 (vLLM / llama.cpp / Ollama / OpenRouter / OpenAI / GitHub Copilot)
• Agent: 真正能"动手"的代理, 配 MCP / Web / 文件 / Shell / Skills / 记忆 (基于 opencode)
• Cookbook: 自动扫描你机器的硬件, 推荐能跑的模型, 一键下载 + 启动服务 (基于 llmfit, VRAM-aware)
• Deep Research: 多步研究, 抓取 + 阅读 + 综合, 产出可视化报告 (改造自 Tongyi DeepResearch)
• Compare: 多个模型盲测对比, 不带偏见地挑出真正好用的那个
• Documents: 你写文字, AI 在旁边辅助, 不是反过来
• Memory / Skills: 长期记忆 + 技能系统, 代理越用越懂你 (ChromaDB + fastembed ONNX)
• Email: IMAP/SMTP 收件箱, AI 自动分级、摘要、草稿回复、反垃圾
• Notes & Tasks / Calendar: 笔记 + 任务 + 日历, CalDAV 同步 Radicale / Nextcloud / Apple / Fastmail
• PWA 支持: 手机上访问体验不输桌面, 可以装到主屏

一句话: 它不是一个聊天框, 它是一整个你的 AI 工作环境, 全在你机器上, 不上云。

难度 / 时长 / 收获

• 难度: ⭐⭐⭐ (中等, 需要懂 Docker / Python 基础)
• 时长: 30–45 分钟 (Docker 路径); 1 小时 (原生安装 + 接本地模型)
• 收获:
  • 跑通一套功能完整的自托管 AI 工作台
  • 理解本地优先 AI 应用的典型架构 (FastAPI + ChromaDB + SearXNG + ntfy)
  • 把 Ollama / vLLM / OpenAI 兼容 API 都接进同一个界面
  • 了解 Cookbook 自动选模型、GPU 透传、记忆系统这些"长尾"但很爽的能力

目标读者画像

• 不想再付 ChatGPT Plus / Claude Pro 订阅, 想把 AI 数据留在本地
• 在 8G / 16G / 24G 显存的 NUC / 工作站 / 服务器上跑开源模型, 想有个统一界面
• 全栈/独立开发者, 想把聊天 / 邮件 / 日历 / Agent 任务合到一个面板里
• 对"自托管"感兴趣的运维/平台工程师, 想看一个生产级 FastAPI App 的工程范本
• 已经为云端 LLM 付过费、想找点不那么肉疼的接法的玩家

如果你只是想找个轻量聊天 UI, Odysseus 不一定适合你 — 它功能多, 上手比 Open WebUI 复杂一点, 但换来的是邮件、记忆、Cookbook、Agent 那一整套。

核心依赖与环境

最低配置:

可选 / 增强依赖:

完整项目结构树

odysseus/
├── app.py                    # FastAPI 入口
├── setup.py                  # 初始化脚本 (创建 admin / 数据库 / 目录)
├── requirements.txt          # 核心 Python 依赖
├── requirements-optional.txt # 可选依赖 (PDF/Office/语音/STT)
├── docker-compose.yml        # 默认编排 (CPU)
├── docker-compose.gpu-nvidia.yml  # NVIDIA GPU 覆盖
├── docker-compose.gpu-amd.yml     # AMD ROCm 覆盖
├── Dockerfile
├── core/                     # 基础设施层
│   ├── auth.py               # 认证 / 会话
│   ├── database.py           # SQLAlchemy 初始化
│   ├── middleware.py
│   ├── constants.py
│   └── atomic_io.py
├── src/                      # 业务逻辑层
│   ├── llm_core.py           # 大模型抽象
│   ├── agent_loop.py         # Agent 循环
│   ├── agent_tools.py        # Agent 工具集
│   ├── chat_processor.py     # 聊天处理
│   ├── cookbook_serve_lifecycle.py  # Cookbook 模型服务生命周期
│   ├── memory_vector.py      # ChromaDB 长期记忆
│   ├── deep_research.py      # 深度研究
│   └── ...
├── routes/                   # FastAPI 路由 (40+ 个模块)
│   ├── chat_routes.py
│   ├── agent_routes.py
│   ├── cookbook_routes.py    # 模型推荐/下载
│   ├── memory_routes.py
│   ├── email_routes.py
│   ├── calendar_routes.py
│   └── ...
├── services/                 # 后台服务
│   ├── docs/                 # 文档处理
│   ├── hwfit/                # 硬件扫描 (Cookbook)
│   ├── memory/               # 记忆服务
│   ├── research/             # 研究服务
│   ├── search/               # 搜索
│   ├── stt/ tts/             # 语音转文字 / 文字转语音
│   └── shell/                # Shell 工具
├── static/                   # 前端 (index.html + JS/CSS)
├── docs/                     # 文档站 + 截图 + demo
├── config/                   # SearXNG 等子服务配置
├── companion/                # 桌面伴侣 (macOS)
└── data/                     # 用户数据 (gitignored, 运行时生成)
    ├── app.db                # SQLite
    ├── chroma/               # 向量库
    ├── uploads/
    ├── personal_docs/
    └── huggingface/          # 模型缓存

目录里你只需要关心 app.py / docker-compose.yml / .env 三个文件, 其他都让 Docker 帮你处理。

手把手步骤

步骤 1: 克隆仓库

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

步骤 2: 准备 .env (可选, 但推荐)

cp .env.example .env

最小可用的 .env 长这样:

# === LLM 接入点 ===
LLM_HOST=localhost
# 想用云端 API, 直接在容器里通过 host.docker.internal 访问本地 Ollama
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1

# === 端口与绑定 ===
APP_BIND=127.0.0.1
APP_PORT=7000

# === 安全 (关键!) ===
AUTH_ENABLED=true
LOCALHOST_BYPASS=false
SECURE_COOKIES=false   # 仅当反代 HTTPS 时改成 true
ODYSSEUS_ADMIN_USER=admin
# ODYSSEUS_ADMIN_PASSWORD=  # 不写则首次启动随机生成并打印

# === 搜索 (SearXNG) ===
SEARXNG_INSTANCE=http://searxng:8080

OLLAMA_HOST=0.0.0.0:11434 ollama serve

步骤 3: Docker 一键启动 (推荐路径)

docker compose up -d --build

构建过程会拉基础镜像 + 安装 Python 依赖, 第一次大约 3–5 分钟。看到 odysseus / chromadb / searxng / ntfy 四个容器都 healthy / running 就完事了:

docker compose ps

打开 http://localhost:7000, 第一屏是登录页。初始 admin 密码 在终端日志里:

docker compose logs --tail=200 odysseus | grep -i "temporary\|admin\|password"

你应该看到类似:

[odysseus] Created admin user 'admin' with temporary password: aB3x-9pQz-2vRt

步骤 4: 验证服务都健康

# 1. 容器状态
docker compose ps

# 2. 看 Odysseus 自己的日志 (注意首启动要拉模型会有延迟)
docker compose logs --tail=120 odysseus

# 3. ChromaDB 是否真的起来了 (不是 HTTP 降级)
docker compose logs odysseus | grep -E "ChromaDB|MemoryVectorStore|DEGRADED"

如果看到 DEGRADED, 大概率是 chromadb-client 跟 chromadb 冲突, 排查方法见后文"常见问题"。

步骤 5: 接入你的第一个模型

进入 Settings → Models / Providers, 根据你机器的情况选一条路:

路径 A: 已经有 Ollama 在跑 (最简单)

Base URL:  http://host.docker.internal:11434/v1
API Key:   (留空)
Model:     qwen2.5:7b (或你本地有的任何模型)

路径 B: 想用 Cookbook 自动下载 + 启动

进 Cookbook, 它会扫描你的显存, 推荐能跑的开源模型, 给你打分 (fit score), 点 "Download" 它就走 huggingface-cli 把模型拉到 ./data/huggingface/, 然后用 llama.cpp / vLLM 直接 serve 起来。

路径 C: 接云端 API — 这才是今天想细聊的

Odysseus 的 Provider 配置是协议驱动的, 也就是说, 任何能正确响应 v1/chat/completions 或 v1/messages 这两个端点的服务, 都能直接填 Base URL 接进去 — 不光是 OpenAI、Anthropic 官方, 自建网关、第三方中转, 都走这一套。

我自己的部署里, "日常 Agent 跑代码 / 长文档" 这一档走云端 API, 原因有两个:

1. 本地 24G 显卡跑 70B 量化已经吃力, 再开 Agent 多轮调用经常 OOM
2. Claude / GPT 这类前沿模型在复杂推理上还是比 Qwen2.5-Coder 强一档

但问题就来了 — 官方 API 太贵了。Claude Opus 一周账单轻松破百刀, 个人玩纯属给 Anyscale 打工。

我现在的解法是接 Defapi, 走的是兼容 v1/messages 的端点:

# Odysseus Settings → Custom Anthropic Provider
Base URL:  https://api.defapi.org
API Key:   sk-xxxxx                    # 在 defapi.org 后台拿
Model:     anthropic/claude-sonnet-4.5 # 或 haiku-4.5 / opus-4.6

配置示例: Defapi Claude Sonnet 4.5 (编程/长文档主力), Claude Haiku 4.5 (日常 Agent 调用首选, 便宜)。

实测下来, 同样的对话/任务量, 每月账单比接 Anthropic 官方降了一大半, 而模型能力、Agent 工具调用、prompt 格式这些完全没有差异 — 因为它就是协议层的代理, 模型本身还是同一个, 这一点跟 Odysseus 这种"协议驱动"的设计天然契合。

路径 D: 接 GitHub Copilot / OpenRouter 等

这两个也是 OpenAI 协议兼容, Base URL 分别填 https://api.githubcopilot.com / https://openrouter.ai/api/v1 就行, 不展开了。

步骤 6: 第一次聊天 + 第一次 Agent 任务

回到主界面, 选一个模型, 扔个简单 prompt 测试连通性:

用三句话介绍你自己, 然后给我一个今天能用的 Linux 性能排查清单。

通了就代表 LLM 这条路打通了。

接下来试 Agent 模式: 创建新会话, 切到 "Agent", 输入:

列出当前目录下所有 .py 文件的行数, 然后告诉我哪个文件最值得重构。

Agent 会自己规划:

1. 调 shell 工具跑 find . -name "*.py" | xargs wc -l
2. 拿到结果后做判断
3. 给出建议

这就是本地优先 Agent 跟 ChatGPT 网页的根本区别: 它真的能动手, 你的代码、文件、终端, 它都有权访问。

步骤 7 (可选): 启用 GPU

这一步只在你要用 vLLM / SGLang / llama.cpp CUDA 这种"重型"本地推理时需要。只用 Ollama 或云端 API, 跳过即可。

NVIDIA:

# 一键诊断
scripts/check-docker-gpu.sh

# 装 NVIDIA Container Toolkit (Ubuntu/Debian, 需要 sudo)
scripts/check-docker-gpu.sh --install-nvidia-toolkit

# 验证 GPU 透传成功后才启用 overlay
scripts/check-docker-gpu.sh --enable-nvidia-overlay

# 验证
docker compose exec odysseus nvidia-smi -L

它在 .env 里加了:

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

AMD ROCm:

scripts/check-docker-amd-gpu.sh
# 把输出的 RENDER_GID 写进 .env

COMPOSE_FILE=docker-compose.yml:docker/gpu.amd.yml
RENDER_GID=989

步骤 8 (可选): 启用 Playwright MCP (浏览器代理)

Odysseus 自带几个 MCP server, 但浏览器那个需要先 npx 拉一下:

npx -y @playwright/mcp@latest --version

重启 Odysseus 容器, Agent 里就能用浏览器 MCP 了 (截图、导航、表单填写):

打开 https://news.ycombinator.com, 抓前 10 条标题和链接, 总结成 5 个核心话题。

步骤 9 (可选): 在 Windows 上原生跑

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

脚本会自动创建 venv → 装依赖 → 跑 setup → uvicorn 启动。打开 http://localhost:7000。

步骤 10 (可选): 让手机也能用

在 Tailscale 已连的前提下:

ODYSSEUS_HOST=0.0.0.0 docker compose up -d
# 或在 .env 里写
APP_BIND=0.0.0.0

但裸 HTTP 暴露到 LAN / Tailscale 不安全, 强烈建议加 mkcert HTTPS:

mkcert -install
mkcert -cert-file cert.pem -key-file key.pem 100.x.y.z   # 你的 Tailscale IP

python -m uvicorn app:app --host 0.0.0.0 --port 7000 \
  --ssl-certfile=cert.pem --ssl-keyfile=key.pem

手机上访问 https://<tailscale-ip>:7000, PWA 安装到主屏, 体验跟原生 App 几乎一样。

常见问题排查

Q1: 7000 端口被占 (常见于 macOS)

macOS AirPlay 默认占着 7000。两种解法:

# 方法 1: .env 里改端口
APP_PORT=7001
docker compose up -d
# 浏览器开 http://localhost:7001

# 方法 2: Apple 菜单 → 系统设置 → 通用 → 隔空播放接收器 → 关闭

Q2: ChromaDB 启动但日志里报 DEGRADED

通常是 chromadb-client 跟 chromadb 同时安装, 静默走 HTTP-only 模式, 向量能力挂掉。修复:

# 在运行的容器里 (或本机 venv 里)
./venv/bin/pip uninstall chromadb-client -y
./venv/bin/pip install --force-reinstall chromadb
docker compose restart odysseus

验证修复: docker compose logs odysseus | grep -E "ChromaDB|MemoryVectorStore", 应该看到的是初始化成功, 不再有 DEGRADED。

Q3: Cookbook 看不到我的 GPU, 只看到 iGPU 或 CPU

Docker 默认把宿主机的所有 GPU 都暴露, 但只挂载了 iGPU 或别的卡, 几乎都是 NVIDIA Container Toolkit 没装 / 没 nvidia-ctk runtime configure --runtime=docker:

# 诊断
scripts/check-docker-gpu.sh
# 看输出, 它会告诉你哪一步缺了

# 一键装 + 配 (Ubuntu/Debian)
scripts/check-docker-gpu.sh --install-nvidia-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Q4: GPU 透传成功, 但 llama.cpp 日志里说 Unable to find cudart

设备没问题, 缺的是 CUDA 运行时。这层 Docker 帮不了你, 去 Cookbook → Dependencies 重装 llama-cpp-python 的 CUDA build:

打开 Cookbook → Dependencies → 找到 llama-cpp-python → Reinstall (CUDA build)

它会自己 pip install --no-cache-dir llama-cpp-python[cuda], 大约 2-3 分钟。

Q5: Outlook / Office 365 邮箱连不上

Odysseus 邮件模块现在只支持 IMAP + 用户名密码 认证。微软在 2024 年后基本都禁了普通密码登录, 要 OAuth。这个目前是已知限制。

临时方案: 用 Gmail / Fastmail / 自建邮箱, 或者开一个 Microsoft App Password (有 2FA 的账号) 来模拟密码登录。

Q6: 想公网访问, 怎么搞才安全?

直接 APP_BIND=0.0.0.0 暴露到公网 = 灾难。LOCALHOST_BYPASS 会绕过认证, Agent 还有 shell 工具 — Shodan 上 24 小时就能扫到一堆裸奔实例。

正确姿势:

[Internet] → Cloudflare Access / Tailscale / WireGuard
            → Caddy / Nginx / Traefik (HTTPS 终结)
            → http://127.0.0.1:7000 (Odysseus, 保持 localhost 绑定)

并在 .env 里:

AUTH_ENABLED=true
LOCALHOST_BYPASS=false
SECURE_COOKIES=true

Q7: 云端 API 账单怎么控?

这里展开讲一下步骤 5 路径 C 那个问题。

个人玩下来, 三个思路按成本从高到低排:

1. 接官方 API — 体验最完整, 但账单最贵。Claude Opus + 频繁 Agent 调用, 一周破百刀很正常
2. 接协议兼容的中转层 (我用 Defapi) — 同样的 Claude / GPT / Gemini 模型, 每月账单比接官方低一截 (具体低多少我也没仔细算, 反正从周账单 100 刀变成月账单 100 刀这个量级)。优势是协议层完全兼容, Odysseus 这边配置照旧, 不用改任何 prompt / Agent 代码
3. 本地量化模型 — Cookbook 下个 Q4_K_M 的 GGUF, 16G 显存能跑 30B 级别, 零 API 成本, 但推理速度比云端慢, 复杂任务质量差一档

我的实际组合: 聊天 + Deep Research 走 Defapi Claude Sonnet 4.5, Agent 跑工具调用走 Claude Haiku 4.5 (便宜), 简单分类/摘要任务走本地 Qwen2.5 量化版。三个 Provider 各自计费, 互不干扰, 一个月下来两位数人民币。

扩展阅读 / 进阶方向

• MCP 生态: Odysseus 自动注册的内置 MCP 包括 playwright (浏览器) / filesystem / shell。可以自己写 MCP server, 注册到 mcp_servers/, 就能给 Agent 用
• Skills 系统: routes/skills_routes.py 管理可复用的"技能片段", 跟 OpenClaw 的 Skills 类似 — 写一次, 任何会话都能调
• Tailscale + mkcert HTTPS: 上一节已经演示了基础流程, 进阶可以加自动续期 + DNS-01 挑战
• 反向代理组合: Caddy 配置 HTTPS + Cloudflare 代理, 可以做到零运维公网访问
• CalDAV 同步: 自建 Radicale (一个轻量 CalDAV 服务), Odysseus 日历就能跟手机系统日历双向同步
• Email AI 自动分桶: 接好 IMAP 后, 训练一段时间它会按"紧急 / 一般 / 垃圾"自动分类, 草稿会预先写好, 你只负责点发送
• Cookbook 远程服务器: Cookbook → Settings → Servers 可以配远端 GPU 机器, 推模型/拉模型都走 SSH — 主机小, GPU 远, 配得漂亮
• Deep Research 多步报告: 改造自阿里 Tongyi DeepResearch, 走 SearXNG 抓多源 → 摘要 → 综合, 适合做竞品调研 / 行业研究
• 多 Provider 路由: 在 Odysseus 里给聊天/Agent/Research 配不同的 Provider — 本地 Ollama 处理 80% 日常对话, 复杂问题走云端, 成本和体验都有

GitHub 仓库: pewdiepie-archdaemon/odysseus, 文档在 docs/ 目录, 路线图见 ROADMAP.md, 想参与贡献看 CONTRIBUTING.md。