pewdiepie-archdaemon/odysseus

# 奥德修斯  ## 功能 ## 演示

屏幕截图 / 录像

## 快速开始 首次设置时，Odysseus 会创建一个管理员账户（除非设置了 `ODYSSEUS_ADMIN_USER`，否则为 `admin`）并在终端打印一个临时密码。 对于 Docker 安装，相同的行在 `docker compose logs odysseus` 中。 首次登录时使用该行，然后在 **设置** 中更改它。 ### Docker（推荐） 要在镜像中包含可选的额外功能（PDF 查看器、Office 提取；包括 AGPL PyMuPDF），在 `up` 之前使用 `docker compose build --build-arg INSTALL_OPTIONAL=true` 构建。 ### 原生 Linux / macOS 要求：Python 3.11+。Cookbook 还需要 `tmux` 以在后台模型下载和提供服务。应用程序本身很轻量级；本地模型提供是重头戏，取决于模型、运行时、GPU 和 VRAM，因此小型主机可以连接到 API 或远程模型服务器。仅当您有意想访问 LAN/reverse-proxy 时才使用 `--host 0.0.0.0`。 **远程服务器。** 在 **Cookbook -> 设置 -> 服务器** 中生成 Odysseus SSH 密钥并将公钥添加到远程服务器的 `~/.ssh/authorized_keys`。从主机您还可以运行： **Docker GPU 窗口覆盖。** 仅 CPU 用户可以跳过此部分。Cookbook 只能检测 Docker 向容器公开的 GPU — 如果主机运行时或设备透传未配置，Cookbook 将看到 iGPU、另一张卡或 CPU 而不是您想要的 GPU。 ``` # 只读诊断（默认 — 不安装任何内容，永不编辑 .env）: scripts/check-docker-gpu.sh # 打印不运行的特定于操作系统的安装命令： scripts/check-docker-gpu.sh --print-install-commands # 在 Ubuntu/Debian 上安装 NVIDIA 容器工具包（需要 sudo）: scripts/check-docker-gpu.sh --install-nvidia-toolkit # 将 COMPOSE_FILE 写入 .env（仅在确认 GPU 直通工作后）: scripts/check-docker-gpu.sh --enable-nvidia-overlay # 完整辅助设置 — 安装工具包，然后启用覆盖（如果直通工作）： scripts/check-docker-gpu.sh --install-nvidia-toolkit --enable-nvidia-overlay ``` - 应用程序永远不会自动安装主机 GPU 运行时。 - 应用程序永远不会自动编辑 `.env`。 - 只有在明确传递 `--enable-nvidia-overlay` 时，`.env` 才会修改，并且仅在 GPU 透传成功后。`--yes` 跳过提示但不会绕过透传门。 - `--enable-nvidia-overlay` 创建的 `.env.bak.*` 备份被 Git 和 Docker 构建上下文忽略。 ``` COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml ``` ``` scripts/check-docker-amd-gpu.sh ``` ``` COMPOSE_FILE=docker-compose.yml:docker/gpu.amd.yml RENDER_GID=989 ``` **堆栈管理 UI（Portainer、Coolify、Dockhand 等）。** 这些工具通常只接受单个 Compose 文件，并且不能可靠地遵守 `COMPOSE_FILE` 或多个 `-f` 突出显示。CLI 用户应继续使用上面的 `COMPOSE_FILE` 突出显示工作流程。对于堆栈 UI，将堆栈指向一个独立的文件，这些文件捆绑了基本堆栈以及 GPU 设置： 基本的 `docker-compose.yml` 加上 `docker/gpu.*.yml` 突出显示是真相的来源；独立的文件将它们镜像化以进行单文件部署。 ``` docker compose exec odysseus nvidia-smi -L # NVIDIA docker compose exec odysseus sh -lc 'test -e /dev/kfd && test -d /dev/dri && ls -l /dev/kfd /dev/dri/renderD*' # AMD ``` **Ollama 与 Docker。** 如果 Ollama 在主机上运行，请在设置中添加此端点： Ollama 必须监听其自身的回环接口： 这连接 Docker 中的 Odysseus 到已在您的主机机器上运行的 Ollama 服务器；它不会在容器内启动 Ollama。 `host.docker.internal` 是容器内主机机器的 Docker 主机名。Cookbook **Serve** 是通过 Odysseus/llama.cpp 提供下载模型的单独工作流程，因此拥有现有 Ollama 安装的 Windows 用户通常只需在设置中添加端点。 ``` docker compose ps docker compose logs --tail=120 odysseus docker compose logs odysseus | grep -E 'ChromaDB|MemoryVectorStore|DEGRADED' ```

### `chromadb-client` 与嵌入式 ChromaDB 冲突 **修复：** 卸载 `chromadb-client` 并强制重新安装完整包： ### HTTPS + LAN/Tailscale 暴露 1. 在 `.env` 中将绑定地址更改为 `0.0.0.0`（`APP_BIND=0.0.0.0` 或 `ODYSSEUS_HOST=0.0.0.0`）。 2. 使用 [mkcert](https://github.com/FiloSottile/mkcert) 为您的 LAN/Tailscale IP 生成本地受信任的证书： mkcert -install mkcert -cert-file cert.pem -key-file key.pem 192.168.1.100 tailscale-ip 3. 使用生成的证书运行 `uvicorn`： python -m uvicorn app:app --host 0.0.0.0 --port 7000 --ssl-certfile=cert.pem --ssl-keyfile=key.pem 4. 在您想要从其访问 Odysseus 的任何其他设备上安装 `mkcert` CA（例如，对于 iOS，将 `rootCA.pem` 发送给自己，安装配置文件，并在证书信任设置中信任它）。 ## 安全注意事项 - 对于任何可网络访问的部署，请保持 `AUTH_ENABLED=true`。 - 在本地开发之外，请保持 `LOCALHOST_BYPASS=false`。 - 当 Odysseus 通过受信任的代理或私有访问网关通过 HTTPS 提供服务时，请使用 `SECURE_COOKIES=true`。 - 不要在没有 HTTPS 和受信任的代理或私有访问层的情况下直接将其暴露给公共互联网。 - 请将 `.env`、`data/`、`logs/`、数据库、上传、生成的媒体、备份、认证/会话文件、API 密钥和模型/提供者令牌保留在 Git 和私有共享之外。默认情况下，它们被忽略。 - 在首次启动后审查 `data/auth.json`：除非您有意想启用它，否则请禁用公开注册，仅将您自己的账户设置为管理员，并保持演示/测试账户非管理员。 - 默认情况下，非管理员用户不会获得 shell/Python/文件读写权限，并且只有管理员才能访问的管理路由/工具（如 MCP 管理、API 令牌、webhooks、模型/cookbook 提供、备份/保险库以及应用程序设置）受管理员门控。其他功能受每个用户的权限控制，因此在暴露部署之前，请审查每个用户的权限。 - 旋转任何曾经粘贴到共享聊天、演示、屏幕截图或日志中的 API 密钥或令牌。 - 如果您启用了 API 令牌或 webhooks，为每个集成创建单独的令牌并删除未使用的令牌。 - 将手动开发运行绑定到 `127.0.0.1`；仅当您有意想访问 LAN/reverse-proxy 时才绑定到 `0.0.0.0`。 - 请将 ChromaDB、SearXNG、ntfy、Ollama、vLLM、llama.cpp、数据库和原始模型/提供者 API 保持为内部使用。仅通过您信任的代理或私有访问层公开认证的 Odysseus Web/API 入口点。 - 在发布分支之前，运行 `git status --short` 并确认没有从 `.env`、`data/`、`logs/`、上传、备份或本地数据库中暂存的私有文件。 ## 配置 大多数设置都在应用程序内部通过 `/setup` 或 **设置** 完成。使用 `.env` 来设置部署级别的默认值和您希望在首次启动之前存在的机密信息。 关键设置： | 变量 | 默认值 | 描述 | |---|---|---| | `LLM_HOST` | `localhost` | 您的 LLM 服务器（例如 `llm-host.local:8000`） | | `LLM_HOSTS` | -- | 模型发现的逗号分隔列表 | | `OPENAI_API_KEY` | -- | 可选的 OpenAI 密钥。除非预先播种，否则请优先在应用程序中添加提供者。 | | `SEARXNG_INSTANCE` | `http://localhost:8080` | SearXNG URL。Docker 覆盖此为 `http://searxng:8080`。 | | `SEARXNG_SECRET` | 第一次 Docker 启动时生成 | 可选的 SearXNG cookie/CSRF 密钥。除非您需要将其固定，否则请留空。 | | `APP_BIND` | `127.0.0.1` | Docker Compose 为主机 Web UI 绑定地址。仅当您有意想访问 LAN/reverse-proxy 时才使用 `0.0.0.0`。 | | `APP_PORT` | `7000` | Docker Compose 为主机 Web UI 绑定端口。 | | `AUTH_ENABLED` | `true` | 启用/禁用登录 | | `LOCALHOST_BYPASS` | `false` | 仅用于本地开发的回环请求认证绕过。对于共享/网络部署请保持为 false。 | | `SECURE_COOKIES` | `false` | 当 Odysseus 通过 HTTPS 在受信任的代理或私有访问网关提供服务时设置 true。 | | `DATABASE_URL` | `sqlite:///./data/app.db` | 数据库连接字符串 | | `CHROMADB_HOST` | `localhost` | 向量内存的 ChromaDB 主机。Docker 覆盖此为 `chromadb`。 | | `CHROMADB_PORT` | `8100` | 手动主机运行的 ChromaDB 端口。Docker 覆盖此为 `8000`。 | | `EMBEDDING_URL` | -- | 兼容 OpenAI 的嵌入端点 | ### 内置 MCP 服务器（可选设置） Odysseus 在启动时自动注册几个内置 MCP 服务器。基于 npx 的服务器（目前是浏览器服务器，`@playwright/mcp`）仅在它们的 npm 包已经在本地 npx 缓存中时启动。如果包未缓存，则该服务器将跳过，并在启动日志消息中解释要做什么，因此全新安装不会因为多分钟的 npm 下载而阻塞，也不会在 Playwright 系统依赖项缺失时挂起。 要启用浏览器 MCP（页面导航、截图、视觉），运行一次： ``` npx -y @playwright/mcp@latest --version ``` 这会安装 `@playwright/mcp` 加上 Playwright (~300MB 总计)。重新启动 Odysseus，服务器将在启动时注册。 ## 架构 ``` app.py # FastAPI entry point 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/ (modular front-end) docs/ landing page (index.html) + preview clips ``` ## 数据 所有用户数据都位于 `data/`（git 忽略）：`app.db`（会话、消息、文档）、`memory.json`、`presets.json`、`uploads/`、`personal_docs/`、`chroma/`、`settings.json`。 ## 星星历史 ## 许可证 MIT -- 查看 [LICENSE](LICENSE) 和 [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md). ``` | ||| ||||| | | | ||||||| )_) )_) )_) ~|~ )___))___))___)\ | )____)____)_____)\\| _____|____|____|_____\\\__ \ / ~^~^~~^~^~~^~^~~^~^~~^~^~~^~^~~^~^~~^~^~ ~^~ all aboard! ~^~ ~^~^~~^~^~~^~^~~^~^~~^~^~~^~^~~^~^~~^~^~ ```

标签：Docker, GPU, GPU passthrough, GPU检测, NIDS, NVIDIA Container Toolkit, Odysseus, Python, SSH, SSH密钥, 临时密码, 人工智能, 全辅助设置, 反向代理, 后台服务, 安全认证, 安全设置, 安全配置, 安全防御评估, 安装命令, 安装脚本, 容器化, 工作空间, 工具安装, 快速入门, 性能优化, 截图, 授权管理, 无后门, 检测绕过, 模型下载, 模型服务, 演示, 环境变量, 环境变量写入, 环境变量配置, 环境搭建, 用户模式Hook绕过, 用户界面, 系统要求, 系统诊断, 网络配置, 自托管, 虚拟化, 视频剪辑, 设置管理, 请求拦截, 账户管理, 轻量级应用, 远程服务器, 逆向工具