Onyx 4.9.3 常用 CLI 命令与工具详解

目标：汇总 Onyx 4.9.3 日常运维的全部命令面——Docker Compose 服务管理、onyx-cli 部署管理、容器内 alembic 数据库迁移、curl 接口运维四组工具，每个子命令配实测回显与参数说明，形成一册可查用的命令速查。已在 Ubuntu 22.04 + Onyx 4.9.3 标准版实测通过。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64）
Onyx 版本：4.9.3，标准版 11 服务（Compose 项目名 onyx-4.9.3-stack）
Docker 29.8.0 / Docker Compose v5.5.1（实测 docker compose version → Docker Compose version v5.5.1）
部署目录：onyx/deployment/docker_compose（本文所有 Compose 命令在该目录内执行）
Web 入口：http://localhost:3000；演示管理账号 admin@example.com / q1w2e3r4
安装过程见《Ubuntu 22.04 安装 Onyx 4.9.3 指南》，参数含义见《Onyx 4.9.3 配置参数详解》

二、工具概览

Onyx 4.9.3 没有自研的统一运维 CLI，命令面由四层工具叠加组成，各自覆盖不同运维对象：

工具层	命令族	管理对象	适用方案
Docker Compose	`docker compose <子命令>`	11 个服务的启停、日志、观测、升级	手动方案 / 脚本方案通用
onyx-cli	`onyx-cli deploy <子命令>`	一键脚本部署的整栈生命周期	官方脚本方案专用
alembic（容器内）	`alembic <子命令>`	数据库迁移版本管理	排障/校验迁移状态
curl + REST API	`/api/...` 端点	注册、登录、用户管理等数据面操作	全方案通用

选层逻辑：日常启停看日志用 Compose；一键脚本部署的升级/卸载优先 onyx-cli；升级后核对迁移状态用 alembic；账号与数据面操作用 curl 或管理界面。

💡 技术拓展：「容器编排管理命令」常见三种形态对比：

形态命令示例特点
Compose（单机栈） docker compose up -d 一份 YAML 管多服务，适合单机部署
Swarm 原生 docker service ls 多机编排，学习成本低但生态收缩
Kubernetes kubectl get pods 事实标准，能力最强，运维面最重

Onyx 官方标准部署采用 Compose（另有 Helm/Kubernetes 形态见官方文档），本文以 Compose 为主线。

形态	命令示例	特点
Compose（单机栈）	`docker compose up -d`	一份 YAML 管多服务，适合单机部署
Swarm 原生	`docker service ls`	多机编排，学习成本低但生态收缩
Kubernetes	`kubectl get pods`	事实标准，能力最强，运维面最重

三、前置条件

Onyx 4.9.3 已部署并运行（验证：curl -sS http://localhost:3000/api/health 返回 {"success":true,...}）。
执行机已装 Docker Engine 与 Compose 插件；涉及 docker compose 的命令需在部署目录内执行（含 docker-compose.yml 与 .env）。
一键脚本方案的机器上已装 onyx-cli（onyx-cli --help 可执行）。

四、Docker Compose 服务管理命令详解

4.1 查看状态：ps

列出栈内服务运行状态，是巡检第一条命令：

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)

常用变体：

# 包含已停止/异常退出的服务（排障第一视角）
docker compose ps -a --format "table {{.Name}}\t{{.Status}}"

输出节选（实测）：

NAME                                      STATUS
onyx-493-stack-api_server-1               Up 12 minutes (healthy)
onyx-493-stack-background-1               Up 5 hours
onyx-493-stack-cache-1                    Up 12 minutes

# 只看单个服务（如升级后核对 web_server）
docker compose ps web_server --format "table {{.Name}}\t{{.Status}}"

输出（实测，restart 后随即查看）：

NAME                          STATUS
onyx-493-stack-web_server-1   Up Less than a second (health: starting)

健康解读要点：healthy 表示内置健康检查通过；health: starting 为刚启动还在探活；Restarting / Exited 需立即查日志（见 4.3）。onyc 标准版中 api_server、web_server、nginx、minio、relational_db、双模型服务带健康检查，opensearch 与 background 不带（Up 即正常）。

4.2 启停与重建：up / stop / start / restart

# 启动全栈（改动 .env 后也用它滚动重建）
docker compose up -d

输出节选（实测首尾）：

[+] Running 12/12
 ✔ Network onyx-493-stack_default          Created
 ✔ Container onyx-493-stack-relational_db-1           Started
 ...
 ✔ Container onyx-493-stack-nginx-1                   Started

# 单独重建某服务（.env 中该服务相关参数变更后执行）
docker compose up -d api_server

输出（实测）：

 Container onyx-493-stack-api_server-1 Starting
 Container onyx-493-stack-api_server-1 Started

# 停止某服务（保留容器与数据，可 start 秒回）
docker compose stop web_server
docker compose start web_server

# 重启某服务（配置外问题、内存涨高后的常用恢复手段）
docker compose restart web_server

输出（实测）：

 Container onyx-493-stack-web_server-1 Restarting
 Container onyx-493-stack-web_server-1 Started

⚠️ 注意：restart 不会重新读取 .env——改了参数要用 up -d <服务> 重建；对全栈生效则 up -d。

4.3 日志：logs

# 跟踪主 API 服务日志（排障核心命令）
docker compose logs -f api_server

输出节选（实测，--tail 8 截取启动完成段）：

docker compose logs api_server --tail 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)

# 数据库日志（迁移/连接问题排查）
docker compose logs relational_db --tail 3

输出（实测）：

relational_db-1  | 2026-10-22 21:03:51.832 UTC [1] LOG:  database system is ready to accept connections
relational_db-1  | 2026-10-22 21:08:51.928 UTC [22] LOG:  checkpoint starting: time
relational_db-1  | 2026-10-22 21:08:55.139 UTC [22] LOG:  checkpoint complete: wrote 35 buffers (0.2%); 0 WAL file(s) added, 0 removed, 0 recycled; write=3.208 s, sync=0.001 s, total=3.211 s; sync files=21, longest=0.001 s, average=0.001 s; distance=52 kB, estimate=52 kB

常用参数：-f 持续跟踪、--tail N 只看末尾 N 行、-t 带时间戳、可同时跟多个服务（logs -f api_server background）。

4.4 进入服务内部：exec

# 在 api_server 内执行单条命令（查看容器内生效参数）
docker compose exec -T api_server sh -c "env | grep -E '^(LOG_LEVEL|IMAGE_TAG)' | sort"

输出（实测）：

IMAGE_TAG=latest
LOG_LEVEL=info

# 进入交互式 shell（深度排障）
docker compose exec api_server bash

4.5 观测资源：top / stats

# 查看各服务进程树与 CPU 时间（确认 celery worker 等多进程形态）
docker compose top

输出节选（实测首尾）：

SERVICE                 #   PID     USER  TIME  COMMAND
api_server              1   359908  root  0:00  /bin/sh -c alembic upgrade head && echo "Starting Onyx Api Server" && uvicorn onyx.main:app --host 0.0.0.0 --port 8080
api_server              1   360024  root  0:15  {uvicorn} /usr/local/bin/python /usr/local/bin/uvicorn onyx.main:app --host 0.0.0.0 --port 8080
background              1   1792    root  0:00  /bin/sh -c if [ -f /etc/ssl/certs/custom-ca.crt ]; then update-ca-certificates; fi && /app/scripts/supervisord_entrypoint.sh
background              1   1963    root  1:14  {celery} /usr/local/bin/python /usr/local/bin/celery -A onyx.background.celery.versioned_apps.beat beat
background              1   1964    root  0:28  {celery} /usr/local/bin/python /usr/local/bin/celery -A onyx.background.celery.versioned_apps.docfetching worker --hostname=docfetching@%n -Q connector_doc_fetching
...

# 内存快照（一次采集，不持续）
docker compose stats --no-stream --format "table {{.Name}}\t{{.MemUsage}}"

输出节选（实测）：

NAME                                      MEM USAGE / LIMIT
onyx-493-stack-nginx-1                    13.7MiB / 31.3GiB
onyx-493-stack-web_server-1               75.69MiB / 31.3GiB
onyx-493-stack-api_server-1               648.6MiB / 31.3GiB
onyx-493-stack-inference_model_server-1   364.4MiB / 31.3GiB

实测标准版空载合计约 6.6 GiB（大头：opensearch 约 2.8 GiB、background 约 1.9 GiB），容量规划参考安装篇。

4.6 镜像与配置核查：images / config

# 核对各服务实际使用的镜像与标签
docker compose images

# 校验 compose 配置合法性并列出服务清单（改 .env 后先跑一次防手误）
docker compose config --services

输出（实测）：

inference_model_server opensearch cache minio relational_db api_server web_server nginx indexing_model_server background code-interpreter

4.7 升级与下线：pull / down

# 拉取新版镜像（配合 .env 中的 IMAGE_TAG）
docker compose pull
# 滚动重建使新镜像生效
docker compose up -d

# 停止并删除容器与网络（保留数据卷）
docker compose down
# 彻底清除含数据卷（危险：数据库/索引/文件全删）
docker compose down -v

五、onyx-cli 部署管理命令详解

官方一键脚本方案部署的栈，用 onyx-cli 管理整栈生命周期。以下子命令说明来自官方安装脚本帮助文本（实测执行 install_onyx.sh --help 的回显，参数语义官方原文）：

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

onyx-cli deploy status：输出版本、容器与健康状态，对应手动方案的 docker compose ps。
onyx-cli deploy logs：整栈日志，对应手动方案的 docker compose logs。
onyx-cli deploy stop：停止容器保留数据，重新进入用 deploy install 或 deploy status 观察拉起状态。
onyx-cli deploy upgrade：升级到新版本（内部完成拉镜像、重建与迁移）。
onyx-cli deploy uninstall：移除部署及全部数据（不可逆，先备份）。

⚠️ 注意：两套命令体系不要混用——脚本方案用 onyx-cli 管理（它还维护版本与部署元数据），手动方案用 docker compose；对同一个栈交替使用容易造成状态不一致。

六、容器内 alembic 数据库迁移命令

api_server 每次启动都会执行 alembic upgrade head 自动迁移；运维中常需要「只查不动」地核对迁移状态。命令在部署目录内执行，进入 api_server 容器的 /app 工作目录运行：

docker compose exec -T api_server sh -c "cd /app && alembic current"

输出（实测，25053020dd5a (head) 表示数据库已在最新迁移版本）：

INFO  [alembic.runtime.migration] Will assume transactional DDL.
25053020dd5a (head)

docker compose exec -T api_server sh -c "cd /app && alembic --help"

输出节选（实测，alembic 子命令全集）：

usage: alembic [-h] [--version] [-c CONFIG] [-n NAME] [-x X] [--raiseerr] [-q]
               {branches,check,current,downgrade,edit,ensure_version,heads,history,init,list_templates,merge,revision,show,stamp,upgrade} ...

positional arguments:
  {branches,check,current,downgrade,edit,ensure_version,heads,history,init,list_templates,merge,revision,show,stamp,upgrade}
    branches            Show current branch points.
    check               Check if revision command with autogenerate has
                        pending upgrade ops.
    current             Display the current revision for a database.
    downgrade           Revert to a previous version.
    heads               Show current available heads in the script directory.
    history             List changeset scripts in chronological order.
    upgrade             Upgrade to a later version.
    stamp               'stamp' the revision table with the given revision.

常用组合：升级前 alembic history 看将应用的迁移序列；升级后 alembic current 核对是否到 head；迁移失败时 alembic check 辅助定位。降级操作（downgrade）会改数据结构，仅按官方 Release Notes 指引执行，禁止随意回退。

七、curl 接口运维命令

数据面操作（注册、登录、用户管理）可用 curl 脚本化。以下命令全部实测。

7.1 健康检查

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

输出（实测）：

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

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"}'

输出（实测，返回 201）：

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

7.3 登录并保存会话

登录接口为表单提交（JSON 会报 422），username 字段填邮箱：

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'

输出（实测，204 = 登录成功并写入 Cookie）：

7.4 管理接口：核对用户与管理员身份

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,...,"groups":[{"id":1,"name":"Admin"}],...}],"invited":[],...}

is_admin: true 即确认管理员身份；该接口同时可用于日常核对账号清单。更多管理 API（连接器、Agent、SSO 配置等）在管理界面有对应入口，开启 ENABLE_PUBLIC_DOCS=true 后可在 /docs 查看完整 OpenAPI 文档（参数含义见《Onyx 4.9.3 配置参数详解》）。

八、注意事项

命令的生效层级：restart 不重读 .env，参数变更必须 up -d；stop 后 start 不重建容器，改配置同样要 up -d。
down 的破坏半径：docker compose down 默认保留卷，但加 -v 会连数据库、OpenSearch 索引与 MinIO 文件一起删除——生产环境禁止直接执行，先备份。
执行位置：docker compose 命令依赖当前目录的 docker-compose.yml 与 .env，务必在部署目录内执行；跨目录操作需 -f 显式指定文件。
健康等待：批量重建后 nginx 依赖 web_server 健康检查，整栈就绪有先后顺序，轮询 docker compose ps 直到全部 healthy 再做功能验证。
alembic 只查不改：日常运维用 current/history/check 三个只读子命令足够；downgrade/stamp 属迁移干预，仅在官方文档指引下使用。

九、常见问题

Q1：docker compose ps 报「no configuration file provided」？ 当前目录没有 docker-compose.yml。cd 到部署目录（手动方案 onyx/deployment/docker_compose；脚本方案在 onyx-cli 生成的部署目录下），或用 -f 指定文件路径。

Q2：某服务一直 Restarting 怎么查？ 按顺序三板斧：docker compose logs <服务> --tail 50 看退出原因（本次 4.9.3 实装中 api_server 崩溃循环即由日志中的 ValueError: USER_AUTH_SECRET is empty. 一步定位，完整排障见《Ubuntu 22.04 安装 Onyx 4.9.3 指南》第十章）；docker compose ps -a 确认重启次数与退出码；修复后 up -d <服务> 重建。

Q3：alembic current 显示的版本号和 (head) 不一致？ 说明迁移未跑完或失败。查 api_server 日志中的 alembic upgrade head 段落，修复报错后重启 api_server 会自动续跑迁移；不要手工 stamp 掩盖问题。

Q4：登录接口 422？ /api/auth/login 只接受表单编码（application/x-www-form-urlencoded），且用户名字段是 username（值填邮箱）。用 JSON 体或不带 Content-Type 都会 422。

Q5：compose stats 与宿主 free 的内存数对不上？ 两者口径不同：compose stats 是各容器工作集之和（4.5 节实测约 6.6 GiB），宿主 free 还含页缓存与内核。容量规划以 stats 为准并预留索引增长余量。

十、参考链接

产品全景与选型：《Onyx 介绍与选型指南》
安装与排障实录：《Ubuntu 22.04 安装 Onyx 4.9.3 指南》
配置参数逐项详解：《Onyx 4.9.3 配置参数详解》
Docker Compose 官方命令参考：https://docs.docker.com/compose/reference/（子命令语义，查询日期 2026-10-23）
onyx-cli 与安装脚本：GitHub 仓库 onyx-dot-app/onyx 内 deployment/docker_compose/install.sh（4.9.3 版实查，查询日期 2026-10-23）