第17章 Omnigent 共享服务器架构与部署指南

共享服务器

前面几节的内容都在你的笔记本上运行。这是上手最快的方式，但如果你希望在手机端访问 Omnigent、与团队成员共享实例，或让服务在笔记本休眠时继续运行，就需要进行部署。

本节将介绍 Omnigent 的架构，并说明服务器和运行器（Runner）的托管选项。

Omnigent 包含三个组件：服务器、运行器和用户界面（UI）。

服务器

服务器是核心协调者，负责管理：

- 会话历史。所有对话、消息和工具调用均持久化存储于数据库（Postgres 或 SQLite）中。 - 工件（Artifacts）。包括文件、Omnigent 包以及上传内容。 - 目录（Catalog）。已注册及内置的 Omnigent 规范。 - MCP 代理与策略。通过服务端策略执行机制，代理 MCP 工具调用。 - 技能（Skills）。Omnigent 可加载的技能定义。 - 身份验证与账户。用户认证（内置账户或 OIDC/SSO）。

在云端托管服务器有几种方案：

Docker Compose 使用 Docker Compose 部署 Omnigent 服务器。该组合包含服务器和 Postgres 数据库。 ```bash cd deploy/docker ./bootstrap.sh # 生成数据库密码和 Cookie 密钥并写入 .env docker compose up -d # 启动 Omnigent 服务器 + Postgres ```

`.env` 中的关键变量（多用户认证详情参见“Auth & SSO”）：

| 变量 | 用途 | | :--- | :--- | | DATABASE_URL | Postgres 连接字符串 | | OMNIGENT_AUTH_ENABLED | 启用多用户认证（Docker 中默认值为 1） | | OMNIGENT_OIDC_COOKIE_SECRET | 会话 Cookie 密钥 | | OMNIGENT_OIDC_ISSUER | OIDC 颁发者 URL（启用 SSO） | | OMNIGENT_OIDC_CLIENT_ID | OIDC 客户端 ID | | OMNIGENT_OIDC_CLIENT_SECRET | OIDC 客户端密钥（公开的 PKCE 客户端可省略） |

系统不会自动生成管理员密码。首次启动时服务器会报告 `needs_setup`：请打开 Web UI 创建管理员账户，或在 `.env` 中设置 `OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD` 以预设密码，适用于无头部署场景。

云平台 将服务器部署到提供托管基础设施的云平台上。

| 平台 | 数据库 | 部署方式 | | :--- | :--- | :--- | | Railway | 托管 Postgres | 从 GitHub 导入仓库 | | Render | 托管 Postgres | 一键部署 | | Fly.io | 卷上的 SQLite | 通过 CLI 执行 fly deploy | | Hugging Face Spaces | SQLite（临时存储） | Docker Space |

Railway & Render 在 Railway 上，导入仓库并添加 Postgres 插件。仅添加插件不会自动将其 `DATABASE_URL` 关联到应用：打开 Omnigent 服务的“变量”设置，添加一个 `DATABASE_URL` 变量，并将其值设置为对 Postgres 服务的引用（`${{Postgres.DATABASE_URL}}`）。在设置该引用之前，每次启动部署都会因“DATABASE_URL is required”而报错；添加该变量后重新部署即可。Render 通过一键部署提供应用和基于 HTTPS 的托管 Postgres。

两者默认使用内置账户认证，因此多用户功能开箱即用。

Fly.io 使用 `fly deploy` 部署，并在持久卷上使用 SQLite。配置文件位于仓库的 `deploy/fly/` 目录中。 ```bash cd deploy/fly fly deploy ``` 服务器闲置时约占 275 MB RSS 内存。Fly 默认的 256 MB 机器规格会导致内存溢出（OOM）循环。仓库中的 `fly.toml` 已锁定为 1 GB 机器规格。如果你修改过配置，请运行 `fly scale memory 1024`。

Hugging Face Spaces 演示级别的 Docker Space，使用 SQLite。参见仓库中的 `deploy/hf-spaces/`。

警告：在 Hugging Face Spaces 上，磁盘默认是临时存储，持久存储是付费插件。每次重启数据都会重置。仅用于演示用途。

Databricks 在 Databricks 工作区中有两条路径，大多数用户会选择托管方案。

托管（推荐） Databricks 上的 Omnigent（Beta）是一项完全托管服务：Databricks 为你运维 Omnigent 服务器，并预先对接了工作区身份、基础模型、AI Gateway 和 MLflow 追踪。无需维护部署工具、Lakebase 引导程序或打包文件。在工作区设置中启用 Omnigent 预览，并遵循其中的快速入门指南。

自管理 通过 Databricks Asset Bundles 在 Databricks Apps 上自行部署和运维 Omnigent 服务器，底层支持 Lakebase（Postgres）和 Unity Catalog Volumes。配置位于仓库的 `deploy/databricks/` 中。仅在托管服务在你所在区域不可用，或需要托管服务尚未暴露的功能（如自定义 YAML 策略、自带提供商 API 密钥、自定义出口流量控制）时，才选择此方案。

官方 Canvas 扩展默认是禁用的。要为特定的自管理应用启用它，在调用 `deploy/databricks/deploy.py` 时设置环境变量 `OMNIGENT_ENABLE_CANVAS=true`： ```bash OMNIGENT_ENABLE_CANVAS=true uv run python deploy/databricks/deploy.py \ --app-name ... ``` 其他所有应用请保持该变量未设置。带有 `--skip-web-ui` 标志的部署保持纯 API 模式，并忽略 Canvas 选择加入项。要发布额外扩展，请传入可重复的 `--extension-wheel` 参数；所有扩展 wheel 包必须满足 Databricks Apps 源码文件 10 MB 的大小限制。

Kubernetes 使用仓库 `deploy/kubernetes/` 中的 kustomize 清单，将 Omnigent 服务器部署到 Kubernetes 集群。`overlays/sandbox-runners/` 覆盖层额外启用了 Kubernetes 托管沙箱提供商（`sandbox.provider: kubernetes`）：`host_type: managed` 会话会启动一个专用的 Runner Pod，该 Pod 运行 `omni host` 并回调到服务器。 由于该提供商引入了基础服务器镜像省略的 Kubernetes 客户端，因此覆盖层拉取官方 `ghcr.io/omnigent-ai/omnigent-server-kubernetes` 镜像变体——即标准服务器镜像加上 Kubernetes 客户端扩展（`OMNIGENT_EXTRAS=kubernetes`）。无需构建自定义镜像；覆盖层中的 `images:` 块已指向该镜像。

```bash kubectl apply -k deploy/kubernetes/overlays/sandbox-runners # 然后创建 omnigent-creds 工具 Secret（参见覆盖层 README） ```

关于 Pod 启动超时、持久存储、支持轮换的 Secret 挂载，以及针对 `agent_sandbox` 提供商的选择加入的原生热池（在会话到达前保持备用 Pod 就绪），请参阅 Kubernetes 沙箱配置参考。

在子路径下提供服务 默认情况下，服务器和 Web UI 从源站根目录（/）提供服务。若要改为在路径前缀下提供服务——例如位于 code-server 端口代理 `https:///proxy/6767/` 之后，或位于 nginx/Traefik 的 `/omnigent/` 位置块之后——请设置基础路径。环境变量和 CLI 标志等价： ```bash OMNIGENT_WEB_BASE_PATH=/proxy/6767 omni server # 或 omni server --base-path /proxy/6767 ``` Web UI 随后会使用该路径前缀其 API、SSE、WebSocket 和资源 URL。无论代理是否转发该前缀，服务器都会接受请求，因此单个配置值即可覆盖两种代理类型：

- 剥离前缀的代理（如 code-server 的 `/proxy//`）会转发 `/v1/...`——服务器直接原样提供服务。 - 非重写代理（如 code-server 的 `/absproxy//`，或不带 rewrite 的 nginx 位置块）会转发完整的 `/proxy/6767/v1/...`——服务器在路由前会剥离配置的前缀。

服务器发出的重定向也会保持在子路径下：登录和登出、魔术链接登录、`omni login` 使用的设备代码同意页面，以及 GitHub / Databricks 连接回调，都会返回到带前缀的应用，而非源站根目录。

取值规则。使用前导斜杠且无尾部斜杠（如 `/proxy/6767`）；缺少前导斜杠会自动补全，尾部斜杠会被去除。未设置、为空或为 `/` 表示根部署（行为不变）。如果值满足以下任一条件，服务器将拒绝启动：

- 以 `//` 开头； - 包含字母、数字及 `-._~/` 以外的字符（包括百分号编码）； - 包含 `.`、`/` 或 `..` 片段； - 以保留的 API 片段开头——api、assets、auth、docs、health、oauth、openapi.json、redoc、v1、.well-known； - 以 Web UI 自身的顶级路由开头——approve、c、canvas、extensions、inbox、login、members、policies、register、settings、tasks、usage。

子路径后的身份验证。对于内置账户，还需将 `OMNIGENT_ACCOUNTS_BASE_URL` 设置为包含前缀的完整公开 URL（例如 `https:///proxy/6767`），以确保登录和邀请重定向及 Cookie 正确解析。对于 OIDC，将 `OMNIGENT_OIDC_REDIRECT_URI` 设置为包含前缀的完整公开回调 URL（例如 `https:///proxy/6767/auth/callback`）。

本地托管服务器。`omni server --background --base-path /proxy/6767` 会在该前缀下重新生成分离的本地服务器。前缀会被记住：后续未设置基础路径的命令（如普通的 `omni run`、`connect` 等）会直接复用正在运行的服务器，而不会重启并重置为根目录；只有显式传入不同值的命令才会触发重新生成。CLI 为该本地服务器打开或打印的浏览器链接（自动打开的 Web UI 和 `/c/` 会话链接）会包含该前缀；指向远程 `--server` 的链接永远不会被重写。

运行器（Runner）

运行器是执行 Omnigent 循环的按会话进程。它管理执行框架（如 Claude Code、Codex、Claude SDK 等）、运行工具，并通过 WebSocket 将事件流式传输回服务器。服务器在主机上启动运行器：主机是指向服务器注册的一台机器。

默认情况下，主机就是你的笔记本。注册方式如下： ```bash omni login // 如果启用了认证 omni host ``` 这就是为什么你本地的 Claude Code 或 Codex 安装“开箱即用”的原因。在笔记本上启动的运行器可以直接访问你机器上的工具、文件和凭据。

然而，将运行器移至云沙箱主机可以带来以下优势：

- 摆脱笔记本依赖。即使你的机器关闭，Omnigent 也能运行。 - 云原生工具。你的 Omnigent 可以直接访问云资源。 - 隔离性。每个 Omnigent 都在其自己的容器中运行，与本地环境分离。 - 可扩展性。并行运行多个 Omnigent，而不会让你的机器不堪重负。

目前支持 Modal、Daytona 和 Blaxel 平台，更多集成即将推出。查看 Cloud Sandbox Host 页面获取更详细的设置说明。

UI

Web UI、终端 UI 和移动 UI 都与服务器通信。它们从不直接与运行器通信。这意味着：

- 如果服务器在你的笔记本上，UI 访问仅限本地。 - 如果服务器部署到云端，任何设备（包括你的手机）都可以访问它。值得注意的是，云托管服务器还允许你与其他用户在同一服务器上进行协作。

协作

一旦服务器实现云托管，Omnigent 即支持多用户：通过链接共享实时会话、让队友共同驱动你的 Omnigent，或分叉对话让其他人独立继续。相关内容已移至独立页面——请参阅“结对编程”章节了解共同驱动、具有读取/编辑权限的共享以及分叉功能。