pewdiepie-archdaemon/odysseus 源码：https://github.com/pewdiepie-archdaemon/odysseus

Odysseus

─────────────────────────────────────────────── ⊹ ࣪ ˖ ૮( ˶ᴖ ᴗ ᴖ˶ )っ Odysseus 版本 1.0 ───────────────────────────────────────────────

Odysseus 是一个自托管的 AI 工作空间——旨在成为 ChatGPT 和 Claude 那种 UI 体验的自托管版本。但多了些折腾和乐趣。运行在你自己的硬件上，使用你自己的数据——本地优先、隐私优先，没有木马。

功能

• 聊天（Chat） —— 与任何本地模型或 API 聊天；添加它们非常简单。支持 vLLM · llama.cpp · Ollama · OpenRouter · OpenAI
• 智能体（Agent） —— 给它工具，让它自己完成整个任务。基于 opencode (https://github.com/anomalyco/opencode) · MCP · web · files · shell · skills · memory
• 菜谱（Cookbook） —— 扫描你的硬件，推荐模型，点击即可下载并提供服务…… 非常简单！基于 llmfit (https://github.com/AlexsJones/llmfit) · VRAM感知 · GGUF / FP8 / AWQ · 适配评分 · vLLM / llama.cpp 提供
• 深度研究（Deep Research） —— 多步骤运行，收集、阅读并综合来源，形成一份漂亮的视觉报告。改编自 Tongyi DeepResearch (https://github.com/Alibaba-NLP/DeepResearch)
• 比较（Compare） —— 一个有趣的工具，用于并排比较模型。完全盲测，没有偏见！多模型 · 盲测 · 综合
• 文档（Documents） —— 你写文本，AI 辅助，而不是相反。多标签编辑器 · markdown · HTML · CSV · 语法高亮 · AI 编辑 · 建议
• 记忆/技能（Memory / Skills） —— 持久化的记忆和技能，你的智能体随着时间推移不断进化，更好地理解你和你的任务！ChromaDB · fastembed (ONNX) · 向量 + 关键词检索 · 导入/导出
• 电子邮件（Email） —— 内置 AI 分类的 IMAP/SMTP 收件箱：紧急提醒、自动标签、自动摘要、自动回复草稿、自动垃圾邮件。IMAP · SMTP · 每账号路由 · 支持 CalDAV
• 笔记与任务（Notes & Tasks） —— 带提醒的快速笔记、待办列表以及智能体可以执行的定时任务。笔记提醒 · 清单 · cron 风格任务 · ntfy / 浏览器 / 邮件通道
• 日历（Calendar） —— 本地优先的日历，支持 CalDAV 同步到 Radicale / Nextcloud / Apple / Fastmail。CalDAV 拉取 · .ics 导入/导出 · 每日历颜色 · 智能体感知
• 支持移动端（Works on mobile） —— 在手机上也能良好显示和运行，不只是桌面端。响应式 · 可安装（PWA） · 触控手势
• 附加功能（Extras） —— 更多有待探索，如果你愿意尝试，我们会很高兴！图片编辑器 · 主题编辑器 · 文件上传（视觉 + PDF） · 网络搜索 · 预设 · 会话 · 双因子认证

演示

完整的悬停播放导览位于首页（docs/index.html）。一些快照：

聊天与智能体

聊天与智能体

深度研究

深度研究

比较

比较

文档

文档

笔记与任务

笔记与任务

快速开始

默认配置开箱即用——克隆、运行、在应用内配置。首次登录后打开 设置（Settings） 面板，将 Odysseus 指向你的 LLM 服务器、搜索提供商、电子邮件账户等。只有在需要覆盖部署级别的设置（如 AUTH_ENABLED、DATABASE_URL 或预填充 ODYSSEUS_ADMIN_PASSWORD）时才去修改 .env 文件（否则首次启动时会生成一个初始密码并打印出来）。

选项 1：Docker（推荐）

git clone https://github.com/pewdiepie-archdaemon/odysseus
cd odysseus
cp .env.example .env   # 可选，但建议明确默认值
docker compose up -d --build

Compose 会启动 Odysseus、ChromaDB、SearXNG 和 ntfy。首次运行时会进行完整的镜像构建。容器健康后，打开 http://localhost:7000。

菜谱的远程服务器使用 Odysseus 拥有的 SSH 密钥（位于 Docker 内的 ./data/ssh）。在 菜谱 -> 设置 -> 服务器 中，生成/复制公钥并将其添加到远程服务器的 ~/.ssh/authorized_keys。生成密钥后，你也可以从宿主机安装：

ssh-copy-id -i data/ssh/id_ed25519.pub user@server

菜谱的本地下载存储在 ./data/huggingface 中，在 Odysseus 容器内被挂载为 ~/.cache/huggingface。

有用的检查命令：

docker compose ps
docker compose logs --tail=120 odysseus
docker compose logs odysseus | grep -E 'ChromaDB|MemoryVectorStore|DEGRADED'
docker compose exec odysseus python -c "from services.hwfit.models import get_models; print(len(get_models()))"

Docker 中预期的向量记忆启动行：

ChromaDB connected: chromadb:8000
MemoryVectorStore initialized

菜谱模型目录检查应打印一个非零的计数。如果打印 0，请使用 docker compose build --no-cache odysseus 重建 Odysseus 镜像。

选项 2：手动安装——Linux / macOS

要求： Python 3.11+。在 Linux/Termux 上，菜谱还需要 tmux 用于后台模型下载和服务。

首先安装系统包：

# Debian/Ubuntu
sudo apt install tmux
# Arch
sudo pacman -S tmux
# Fedora
sudo dnf install tmux

然后安装 Odysseus：

git clone https://github.com/pewdiepie-archdaemon/odysseus
cd odysseus
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python setup.py   # 创建数据目录并打印初始管理员密码
uvicorn app:app --host 0.0.0.0 --port 7000

选项 3：手动安装——Windows（PowerShell）

git clone https://github.com/pewdiepie-archdaemon/odysseus
cd odysseus
python -m venv venv
venv\Scripts\Activate.ps1
pip install -r requirements.txt
python setup.py
uvicorn app:app --host 0.0.0.0 --port 7000

打开 http://localhost:7000，使用生成的管理员密码登录，然后在 设置 中配置其他所有内容。

安全说明

Odysseus 是一个自托管的工作空间，带有强大的本地工具：shell 访问、文件上传、模型下载、网络研究、邮件/日历集成以及 API 令牌。请将其视为管理控制台。

• 对于任何可访问网络的部署，请保持 AUTH_ENABLED=true。
• 不要在没有 HTTPS 和可信反向代理的情况下直接暴露到公共互联网。
• 确保 data/、.env、日志、数据库以及上传/生成的媒体文件不被纳入 Git。它们默认已被忽略。
• 首次启动后检查 data/auth.json：除非你故意想开放注册，否则禁用开放注册；只将你自己的账户设为管理员，并保持演示/测试账户为非管理员。
• 非管理员用户默认不能使用 shell/Python/文件读写，管理专用路由和工具（如 MCP 管理、API 令牌、webhooks、模型/菜谱服务、备份/保险库、应用设置）受管理员控制。其他功能由每个用户的权限控制，因此在暴露部署前请检查每个用户的权限。
• 轮换任何曾粘贴到共享聊天、演示、截图或日志中的 API 密钥或令牌。
• 如果你启用 API 令牌或 webhooks，请为每个集成创建单独的令牌，并删除未使用的令牌。
• 在手动开发运行时，优先绑定到 127.0.0.1；只有在明确需要局域网/反向代理访问时才绑定到 0.0.0.0。
• 在发布分支之前，运行 git status --short 确认没有来自 .env、data/、logs/、上传文件、备份或本地数据库的私有文件被暂存。

将其置于 HTTPS 后面

Odysseus 在其端口上提供纯 HTTP 服务。这对于 localhost 和可信的局域网 / VPN 使用是可以的，但浏览器会发出警告（“密码字段存在于不安全页面”），并且登录信息 + API 令牌以明文传输。对于任何可以访问你机器以外的地址——包括与其他设备共享的 Tailscale IP——请在其前面放置一个 TLS 终止的反向代理。使用 Caddy (https://caddyserver.com/)（自动续期 Let’s Encrypt 证书）的最短路径：

odysseus.example.com {
    reverse_proxy localhost:7000
}

对于仅限局域网的 Tailscale 部署，Caddy + tailscale-cert (https://caddyserver.com/docs/caddyfile/options#auto-https) 或内置的 MagicDNS HTTPS 功能均可使用。nginx/Traefik 配置类似——代理 localhost:7000，在代理处终止 TLS。一旦设置完成，浏览器警告消失，你的登录信息将被加密。

贡献

欢迎帮助。最好的切入点是新装测试、提供商设置错误、移动端/编辑器打磨、文档以及小型聚焦的重构。请参阅 ROADMAP.md 了解当前需要帮助的列表。

配置

大多数配置在应用内通过 /setup 或 设置 完成。使用 .env 设置部署级别的默认值和希望首次启动前存在的密钥。

关键设置：

捆绑服务

Docker Compose 默认包含以下服务：

• ChromaDB → 语义记忆的向量存储。在 Docker 中，Odysseus 连接到 chromadb:8000；从宿主机暴露为 localhost:8100。
• SearXNG → 用于网络搜索的元搜索引擎。在 Docker 中，Odysseus 连接到 searxng:8080；从宿主机仅暴露在 127.0.0.1:8080。
• ntfy → 本地通知服务，暴露为 localhost:8091。

可选的外部服务

• Ollama → 本地 LLM 服务器 – ollama.ai (https://ollama.ai)

架构

app.py                              # FastAPI 入口
core/                               auth, database, middleware, constants
src/                                llm_core, agent_loop, agent_tools, chat_processor, search/
routes/                             chat, session, document, memory, model ... endpoints
services/                           docs, memory, search, hwfit (Cookbook) ...
static/                             index.html + app.js + style.css + js/ (模块化前端)
docs/                               首页 (index.html) + 预览片段

数据

所有用户数据位于 data/（已 gitignore）：app.db（会话、消息、文档）、memory.json、presets.json、uploads/、personal_docs/、chroma/、settings.json。

许可

MIT —— 参见 LICENSE 和 ACKNOWLEDGMENTS.md。

 |       |||      ||||| | |        |       |||||       )_)   )_)   )_)        ~|~        )___))___))___)\        |         )____)____)_____)\\|      _____|____|____|_____\\\__         \ /       ~^~^~~^~^~~^~^~~^~^~~^~^~~^~^~~^~^~~^~^~          ~^~    all aboard!   ~^~          ~^~^~~^~^~~^~^~~^~^~~^~^~~^~^~~^~^~~^~^~