Ubuntu 22.04 安装 Onyx 4.9.3 指南

目标：在 Ubuntu 22.04 服务器上完成 Onyx 4.9.3（标准版，含 OpenSearch 索引、双模型推理服务与后台任务队列的完整栈）的从零安装、初始化与验证，覆盖官方一键脚本与手动 Docker Compose 两种方案，并沉淀安装过程中的真实排障记录。已在 Ubuntu 22.04 + Docker 29.8.0 + Docker Compose v5.5.1 环境实测通过。

一、环境信息

本文实测环境的关键信息如下，读者在相近环境操作即可复现：

操作系统：Ubuntu 22.04 LTS（x86_64）
Docker：29.8.0（实测 docker version --format "{{.Server.Version}}" 输出 29.8.0）
Docker Compose：v5.5.1（实测 docker compose version 输出 Docker Compose version v5.5.1）
Onyx 版本：4.9.3（Compose 项目名 onyx-4.9.3-stack）
Onyx 标准版共 11 个服务：api_server、web_server、background、indexing_model_server、inference_model_server、relational_db（PostgreSQL 15.2）、opensearch（3.6.0）、cache（Redis 7.4）、minio、code_interpreter、nginx
部署目录：/opt/onyx/deployment/docker_compose（手动方案）；官方脚本方案默认部署目录为 ~/.config/onyx
访问端口：默认 3000（Compose 同时映射 80 → nginx）
演示管理账号：admin@example.com，密码 q1w2e3r4

💡 说明：Onyx 标准版实测空载内存占用约 6.6 GiB，其中 OpenSearch 约 2.8 GiB、后台任务容器约 1.9 GiB、api_server 约 0.64 GiB。建议为标准版准备 8 GB 以上内存；只想快速体验界面可用官方 Lite 模式（官方 README 称其内存占用低于 1 GB，但不含索引能力）。

二、前置条件

安装 Onyx 标准版前，先在 Ubuntu 22.04 服务器上备齐以下依赖：

Docker Engine 与 Docker Compose 插件（Onyx 以 Docker Compose 为官方标准部署形态）。未安装时执行：

# 安装 Docker 官方仓库依赖与 GPG 密钥
apt-get update
apt-get install -y ca-certificates curl
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
# 写入 Docker 软件源
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" > /etc/apt/sources.list.d/docker.list
# 安装 Docker Engine 与 Compose 插件
apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

git（手动方案需要克隆 Onyx 仓库）：

apt-get install -y git

curl（一键脚本与接口验证需要）：

apt-get install -y curl

内存与磁盘：8 GB 以上内存（标准版实测空载约 6.6 GiB）、20 GB 以上可用磁盘（11 个服务镜像合计数 GB，加索引数据预留）。
生成密钥用的 openssl（Ubuntu 22.04 默认自带，用于生成 USER_AUTH_SECRET）。

验证前置条件是否就绪（实测回显）：

docker version --format "Docker {{.Server.Version}}"

Docker 29.8.0

docker compose version

Docker Compose version v5.5.1

git --version

git version 2.34.1

三、版本选型说明

Onyx 发布节奏快，安装前应确认最新稳定版并按需固定版本（本文版本信息查询日期 2026-10-23）：

当前最新稳定版：v4.9.4（来源：GitHub Releases 页面 https://github.com/onyx-dot-app/onyx/releases/latest，查询日期 2026-10-23）。
本文实测版本：4.9.3。v4.9.3 与 v4.9.4 同属 4.x 版线，部署方式与配置结构一致；正文所有命令与回显基于 4.9.3 实测。
镜像标签约定：Onyx 官方 Compose 文件默认使用 IMAGE_TAG 变量（默认 latest）；要固定到具体版本，将 .env 中的 IMAGE_TAG 设为如 v4.9.3 即可。

版本	状态	说明
v4.9.4	最新稳定版（2026-10-23 查询）	生产新装建议；部署流程与 4.9.3 一致
v4.9.3	本文实测版本	全部命令与回显实测于此版本
latest	滚动标签	随最新稳定版变动，重装/升级时镜像层可能变化

选型建议：生产环境用 IMAGE_TAG 钉住具体版本号（如 v4.9.3），保证可重现与可控升级；体验环境用默认 latest 省去改配置。

四、方案 A：官方一键安装脚本（在线安装，推荐）

官方为 Ubuntu 等环境提供了「curl 管道安装脚本」：脚本负责下载并安装官方 onyx-cli 命令行工具（Go 编写，发布在 Onyx 仓库的 cli-latest 标签下），再由 onyx-cli deploy install 引导完成 Docker Compose 部署。这是官方文档「Install Script (Recommended)」推荐的路径。

4.1 执行一键安装

# 下载并执行官方安装脚本（脚本内自动下载 onyx-cli 并进入引导部署）
curl -fsSL https://onyx.app/install_onyx.sh | bash

脚本支持通过参数定制部署（以下帮助文本为实测执行 install_onyx.sh --help 的回显）：

Onyx Installation Script

Installs the Onyx CLI and runs its guided deployment:
  onyx-cli deploy install [OPTIONS]

Usage: /opt/data/quzuo/tmp/onyx/install_onyx.sh [OPTIONS]

Common options (forwarded to the CLI):
  --lite           Deploy Onyx Lite (no OpenSearch, Redis, or model servers)
  --include-craft  Enable Onyx Craft (AI-powered web app building)
  --tag <tag>      Image tag to deploy (default: the latest Onyx release)
  --local          Use existing config files instead of downloading them
  --no-prompt      Run non-interactively with defaults (for CI/automation)
  --dry-run        Show what would be done without making changes
  --verbose        Show detailed output for debugging
  --no-wait        Return as soon as containers are started
  --dir <path>     Deployment directory (default: ~/.config/onyx, or an
                   existing ./onyx_data)
  --help, -h       Show this help message

Run 'onyx-cli deploy install --help' for the full list.

Managing an existing deployment (these replace the retired
--shutdown / --delete-data flags):
  onyx-cli deploy status     Versions, containers, and health
  onyx-cli deploy logs       Logs of the deployment's containers
  onyx-cli deploy stop       Stop the containers, keep the data
  onyx-cli deploy upgrade    Upgrade to a newer version
  onyx-cli deploy uninstall  Remove the deployment and all its data

Environment:
  ONYX_CLI_VERSION  onyx-cli release to install (default: newest)
  ONYX_CLI_BIN_DIR  install location (default: ~/.local/bin, or
                    /usr/local/bin as root)

4.2 常用安装形态

按需选择下列形态（参数由 onyx-cli deploy install 处理）：

# 标准版默认安装（交互式引导，含索引与模型服务）
curl -fsSL https://onyx.app/install_onyx.sh | bash

# 固定部署 4.9.3 版本（--tag 指定镜像标签）
curl -fsSL https://onyx.app/install_onyx.sh | bash -s -- --tag v4.9.3

# 无人值守安装（CI/自动化场景，使用默认值）
curl -fsSL https://onyx.app/install_onyx.sh | bash -s -- --no-prompt

# 轻量 Lite 模式（内存 <1GB，不含 OpenSearch/Redis/模型服务器，不能建索引）
curl -fsSL https://onyx.app/install_onyx.sh | bash -s -- --lite

脚本执行完成后，部署目录默认位于 ~/.config/onyx（或已有的 ./onyx_data），可用 onyx-cli deploy status 查看版本、容器与健康状态。随后跳转第七章完成初始化。

⚠️ 注意：一键脚本是「联网安装」——需要服务器可访问 GitHub 下载 onyx-cli 与 Onyx 镜像。内网隔离环境请改用第五章的手动方案，并提前把镜像同步进内网仓库。

五、方案 B：手动 Docker Compose 部署（可控部署）

适合需要审阅/自定义 Compose 配置、或把部署目录纳入自己运维体系的场景。以下步骤在 Ubuntu 22.04 上从零实测通过。

5.1 克隆 Onyx 仓库

git clone https://github.com/onyxdotapp/onyx.git

输出节选（实测）：

Cloning into 'onyx'...
remote: Enumerating objects: 237, done.
remote: Counting objects: 100% (237/237), done.
remote: Compressing objects: 100% (216/216), done.
Receiving objects: 100% (163759/163759), 223.85 MiB | 10.21 MiB/s, done.
Resolving deltas: 100% (105283/105283), done.
Checking out files: 100% (1648/1648), done.

仓库较大（200 MB+），克隆后进入 Compose 部署目录：

cd onyx/deployment/docker_compose
ls

输出节选（实测，保留关键文件）：

docker-compose.yml   docker-compose.prod.yml   docker-compose.onyx-lite.yml
env.template         install.sh                init-letsencrypt.sh
env.nginx.template   env.prod.template         nginx  ...

5.2 生成 .env 并写入必需密钥

官方 Compose 文件通过 env_file 读取同目录的 .env（可选文件，但生产与标准部署建议提供）。先复制模板：

cp env.template .env

必须先写入 USER_AUTH_SECRET。该密钥用于签署密码重置/邮箱验证令牌、OAuth 登录状态与验证码 Cookie；4.9.x 的 api_server 启动时会强制校验它，为空会直接启动失败（排障实录见第十章问题 1）。生成并写入：

# 生成 64 位十六进制密钥并写入 .env 的 USER_AUTH_SECRET
SECRET=$(openssl rand -hex 32)
sed -i "s|^USER_AUTH_SECRET=.*|USER_AUTH_SECRET=${SECRET}|" .env
grep -c "^USER_AUTH_SECRET=" .env

输出（实测，1 表示已存在且非空）：

⚠️ 注意：不要把 USER_AUTH_SECRET 留成空串 USER_AUTH_SECRET=""，也不要把该值提交到代码仓库或泄露给他人——持有它即可伪造密码重置令牌。

其他常改项先保持模板默认（逐项说明见第八章与《Onyx 4.9.3 配置参数详解》）。

5.3 拉起完整服务栈

docker compose up -d

输出节选（实测首尾，共 11 个服务）：

[+] Running 12/12
 ✔ Network onyx-493-stack_default          Created
 ✔ Container onyx-493-stack-relational_db-1           Started
 ✔ Container onyx-493-stack-cache-1                   Started
 ✔ Container onyx-493-stack-opensearch-1              Started
 ✔ Container onyx-493-stack-minio-1                   Started
 ✔ Container onyx-493-stack-indexing_model_server-1   Started
 ✔ Container onyx-493-stack-inference_model_server-1  Started
 ✔ Container onyx-493-stack-background-1              Started
 ✔ Container onyx-493-stack-code-interpreter-1        Started
 ✔ Container onyx-493-stack-web_server-1              Started
 ✔ Container onyx-493-stack-api_server-1              Started
 ✔ Container onyx-493-stack-nginx-1                   Started

首次启动时 api_server 会自动执行数据库迁移（alembic upgrade head）、创建 OpenSearch 索引、初始化 MinIO 存储桶。观察主服务日志直到出现 Application startup complete（输出节选，实测）：

docker compose logs api_server | tail -n 8

NOTICE:   10/22/2026 09:04:11 PM   setup.py  233: Document index OpenSearchIndexPair setup complete.
INFO:     10/22/2026 09:04:12 PM   utils.py  146: Initialized HuggingFaceTokenizer for: nomic-ai/nomic-embed-text-v1
INFO:     10/22/2026 09:04:12 PM   setup.py  323: No existing docs or connectors found. Checking GPU availability for multipass indexing.
INFO:     10/22/2026 09:04:12 PM   setup.py  327: GPU available: False
INFO:     10/22/2026 09:04:17 PM   h11_impl.py  481: [-] 127.0.0.1:37982 - "GET /health HTTP/1.1" 200
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

5.4 验证部署状态

逐一验证服务状态与 Web 入口（命令与回显均为实测）：

docker compose ps --format "table {{.Name}}\t{{.Status}}"

NAME                                      STATUS
onyx-493-stack-api_server-1               Up 6 minutes (healthy)
onyx-493-stack-background-1               Up 5 hours
onyx-493-stack-cache-1                    Up 6 minutes
onyx-493-stack-code-interpreter-1         Up 5 hours (healthy)
onyx-493-stack-indexing_model_server-1    Up 5 hours (healthy)
onyx-493-stack-inference_model_server-1   Up 6 minutes (healthy)
onyx-493-stack-minio-1                    Up 6 minutes (healthy)
onyx-493-stack-nginx-1                    Up 4 minutes (healthy)
onyx-493-stack-opensearch-1               Up 5 hours
onyx-493-stack-relational_db-1            Up 6 minutes (healthy)
onyx-493-stack-web_server-1               Up 4 minutes (healthy)

curl -sS http://localhost:3000/api/health

{"success":true,"message":"ok","data":null}

curl -sS -o /dev/null -w '%{http_code}\n' http://localhost:3000/

三项全部符合预期（11 个服务运行、健康接口 ok、首页 200），部署完成。

六、方案对比与选择建议

维度	方案 A：官方一键脚本	方案 B：手动 Compose
部署方式	onyx-cli 引导，自动化程度高	git clone + docker compose，全程手动
版本控制	`--tag` 参数指定	`.env` 的 `IMAGE_TAG` 指定
部署目录	`~/.config/onyx`（默认）	自定（仓库 `deployment/docker_compose`）
配置可见性	引导生成	全部配置文件明文可审
升级/卸载	`onyx-cli deploy upgrade/uninstall`	改 IMAGE_TAG + `docker compose` 命令
适用场景	标准服务器快速上生产	内网/定制/需审计 Compose 的团队

选择建议：能联网、想省事选方案 A；需要把 Compose 文件纳入配置管理、内网化部署或按团队规范改造（如接自有 PostgreSQL）选方案 B。两方案产物一致（同一套 Compose 服务栈），后续运维命令通用。

七、安装后初始化与管理员验证

Onyx 采用「首个注册用户即管理员」的机制，部署完成后立即注册管理账号（演示账号 admin@example.com / q1w2e3r4）。

7.1 浏览器初始化

访问 http://<服务器IP>:3000 进入注册页，填写邮箱与密码完成首个账号注册，随后按引导配置 LLM 即可开始使用。

7.2 接口方式验证（可脚本化）

注册首个管理员（实测）：

curl -sS -X POST http://localhost:3000/api/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"q1w2e3r4","username":"admin"}'

{"id":"4f5e8d32-e9a6-449c-ada0-ec9ed1b64ccc","email":"admin@example.com","is_active":true,"is_superuser":false,"is_verified":false,"account_type":"STANDARD"}

登录获取会话 Cookie（登录接口为表单提交，实测返回 204）：

curl -sS -X POST http://localhost:3000/api/auth/login \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=admin@example.com&password=q1w2e3r4' \
  -c /tmp/onyx_cookies.txt -w '%{http_code}\n'

用该 Cookie 核实首个用户的管理员身份（实测 is_admin: true，且已归入 Admin 用户组）：

curl -sS -b /tmp/onyx_cookies.txt http://localhost:3000/api/manage/users

输出节选（实测）：

{"accepted":[{"id":"4f5e8d32-e9a6-449c-ada0-ec9ed1b64ccc","email":"admin@example.com","account_type":"STANDARD","is_admin":true,"is_active":true,"password_configured":true,"personal_name":null,"created_at":"2026-10-22T21:05:37.888487Z",...,"groups":[{"id":1,"name":"Admin"}],...}],"invited":[],...}

⚠️ 注意：首个注册用户自动获得管理员权限，因此标准版部署完成到注册首个账号之间是公开注册窗口，公网部署应尽快注册并按需在管理面板关闭开放注册（或改用 SSO）。

八、配置说明

手动方案的核心配置集中在部署目录的 .env（由 env.template 复制而来，含全部可调项与注释）；一键脚本方案由 onyx-cli 生成同名文件。安装后最常用的配置项：

配置项	默认值	说明
`IMAGE_TAG`	`latest`	Onyx 镜像版本标签，生产建议钉住如 `v4.9.3`
`USER_AUTH_SECRET`	空（必须自填）	签署密码重置/验证令牌、OAuth 状态与验证码 Cookie 的密钥
`POSTGRES_USER` / `POSTGRES_PASSWORD`	`postgres` / 模板随机值	关系库凭据
`MINIO_ROOT_USER` / `MINIO_ROOT_PASSWORD`	`minioadmin` 系	对象存储凭据，生产必须改强口令
`COMPOSE_PROFILES`	`s3-filestore`	启用 MinIO 文件存储形态；改用 Postgres 存文件时移除并设 `FILE_STORE_BACKEND=postgres`
`HOST_PORT` / `HOST_PORT_80`	`3000` / `80`	对外 Web 端口映射
`DOMAIN`	空	nginx 反代与外链域名配置
`LOG_LEVEL`	`info`	服务日志级别

Compose 生产加固清单（官方 docker-compose.yml 头部注释要求，实测摘录）：

除 nginx（80/443）外移除 api_server、relational_db、cache、minio 的端口暴露；
更换 MinIO/S3 强凭据（MINIO_ROOT_* 与 S3_AWS_*，不用 minioadmin）；
需要域名 + HTTPS 时启用 certbot 服务并把 nginx 配置切到 app.conf.template.prod；
SSO（Google/OIDC/SAML）部署后在管理面板配置：Admin Panel > Organization > SSO Providers。

全部参数的逐项详解见《Onyx 4.9.3 配置参数详解》。

九、升级、降级与多版本管理

9.1 升级（手动方案）

# 拉取新版代码（获取对应版本的 compose 模板）
git pull
# 钉住目标版本
sed -i "s|^IMAGE_TAG=.*|IMAGE_TAG=v4.9.4|" .env
# 拉取新镜像并滚动重建
docker compose pull
docker compose up -d

api_server 每次启动都会自动执行 alembic upgrade head 数据库迁移，升级后先看迁移日志再验证服务（命令与回显见 5.4 节）。

⚠️ 注意：升级前备份数据卷（PostgreSQL 与 MinIO 数据目录），并阅读目标版本的 Release Notes 确认有无破坏性变更（版本信息查询日期 2026-10-23）。

9.2 升级与运维（脚本方案）

onyx-cli deploy upgrade     # 升级到新版本
onyx-cli deploy status      # 查看版本、容器与健康状态
onyx-cli deploy stop        # 停止但保留数据
onyx-cli deploy logs        # 查看部署日志
onyx-cli deploy uninstall   # 移除部署及全部数据

9.3 降级与多版本

降级等于把 IMAGE_TAG 换回旧版本号后 pull + up -d，但数据库迁移通常不可自动回滚——降级前务必用 9.1 的备份恢复数据卷。需要并存多版本时，为每个版本准备独立部署目录（各自 .env），并用 Compose 项目名隔离（官方模板默认 name: onyx-<版本>-stack，同机多版本时改出不同项目名避免冲突）。

十、常见问题（含排障实录）

以下问题全部来自本次 4.9.3 实际安装过程，排障记录完整沉淀。

问题 1：api_server 反复重启，容器状态在 Up 与 Restarting 之间循环（排障实录）

现象：docker compose ps 中其余服务正常，唯独 api_server 频繁重启（观察 restartCount 已上千）。docker compose logs api_server 每轮崩溃结尾都是同一段：

  File "/app/onyx/main.py", line 398, in lifespan
    verify_user_auth_secret()
  File "/app/onyx/auth/users.py", line 247, in verify_user_auth_secret
    raise ValueError(message)
ValueError: USER_AUTH_SECRET is empty. It signs password-reset and email-verification tokens, OAuth login state, and captcha cookies, so an empty value lets attackers forge them. Generate one with `openssl rand -hex 32` and set USER_AUTH_SECRET.

ERROR:    Application startup failed. Exiting.

定位：错误信息直接给出原因——.env 中 USER_AUTH_SECRET 为空（模板默认 USER_AUTH_SECRET=""），api_server 启动 lifespan 阶段校验不过，进程退出，restart 策略又拉起，形成崩溃循环。
解决：按错误提示生成密钥并写入 .env，再单独重建该服务：

SECRET=$(openssl rand -hex 32)
sed -i "s|^USER_AUTH_SECRET=.*|USER_AUTH_SECRET=${SECRET}|" .env
docker compose up -d api_server

验证：约 45 秒后服务进入 healthy，日志出现 Application startup complete.（实测回显见 5.3 节）。

问题 2：nginx 服务处于 Created 状态，3000 端口连接被重置（排障实录）

现象：curl http://localhost:3000 报 Recv failure: Connection reset by peer；docker compose ps -a 显示 nginx 为 Created，从未真正启动。
定位：nginx 依赖 web_server 健康检查（condition: service_healthy）；首次 up -d 时若 web_server 未在超时内转 healthy，nginx 会停在 Created 而不启动，其余服务照常。
解决：确认 web_server 已 healthy 后单独补拉：

docker compose up -d nginx

验证：nginx 转为 Up (healthy)，curl -o /dev/null -w '%{http_code}' http://localhost:3000/ 返回 200。

问题 3：标准版内存不足，服务启动慢或被杀

现象：8 GB 以下内存的机器上，OpenSearch 与模型服务器启动缓慢，极端情况下进程被内核杀掉。
定位：标准版实测空载约 6.6 GiB（OpenSearch 2.8 GiB + background 1.9 GiB + 双模型服务 0.7 GiB + 其余约 1.2 GiB），还要为索引与并发预留余量。
解决：内存不足时优先用 Lite 模式（--lite，官方称 <1 GB）体验，或加内存/加 swap 后再跑标准版；生产按官方 Resourcing Guide 分档配置。

问题 4：首次启动耗时数分钟属正常现象

api_server 启动时要依次完成数据库迁移、OpenSearch 索引构建、MinIO 桶创建、分词器初始化（实测日志 Initialized HuggingFaceTokenizer for: nomic-ai/nomic-embed-text-v1）。首次启动 1–3 分钟内转 healthy 为正常，不要在等待期反复重启服务。

问题 5：接口登录返回 422

POST /api/auth/login 接受的是表单（application/x-www-form-urlencoded）而不是 JSON，username 字段填邮箱。用 JSON 体提交会得到 422 Request validation failed.，改为 -d 'username=...&password=...' 即可（实测回显见 7.2 节）。

十一、卸载与清理

手动方案：

cd onyx/deployment/docker_compose
# 停止并删除容器与网络（保留数据卷）
docker compose down
# 连同数据卷一起删除（彻底清除，PostgreSQL/索引/对象存储数据不可恢复）
docker compose down -v

一键脚本方案：

onyx-cli deploy uninstall   # 移除部署及其全部数据

再按需清理镜像与部署目录：

docker rmi onyxdotapp/onyx-backend:v4.9.3 onyxdotapp/onyx-web-server:v4.9.3 onyxdotapp/onyx-model-server:v4.9.3
rm -rf onyx/          # 手动方案的仓库目录

十二、参考链接

Onyx 产品介绍与选型分析：《Onyx 介绍与选型指南》
官方部署文档（Deployment Modes / Quickstart）：https://docs.onyx.app/deployment/overview（查询日期 2026-10-23）
GitHub 仓库与 Releases：https://github.com/onyx-dot-app/onyx/releases（v4.9.4 最新稳定版，查询日期 2026-10-23）
Compose 部署目录官方说明：仓库内 deployment/docker_compose/README.md 与 docker-compose.yml 头部生产清单
配置参数逐项详解：《Onyx 4.9.3 配置参数详解》（本系列配置篇）